Skip to main content
sovseal is threat-model-first about identity. This page states, without hedging, how you are authenticated, where key material lives, and what happens if you lose it.

​
Local / MCP tier — no account required

The local MCP server needs no signup, email, or password. On first run it writes ~/.sovseal/config.json containing a self-asserting project token:
Treat sov_proj_… like an SSH key: anyone holding it can write snapshots under your project namespace. It is a bearer credential — keep it out of shared dotfiles and CI logs.

​
Key custody (where the encryption keys live)

sovseal never stores your raw encryption key in a plaintext file. The master key lives in the OS keychain:
  • macOS Keychain · Windows Credential Manager · Linux libsecret (@napi-rs/keyring).
  • Two subkeys are derived with HKDF-SHA256 for domain separation: k_rest = HKDF(master, "sovseal/at-rest/v1") encrypts memory text on disk; k_sync = HKDF(master, "sovseal/sync/v1") seals ciphertext before replication.
  • Legacy config.json encryption_key_b64 values are migrated once into the keychain and then tombstoned.
File fallback fails closed. If the keychain is unavailable, sovseal aborts rather than silently writing keys to disk. An opt-in 0600 file fallback exists only behind SOVSEAL_KEY_FALLBACK=file — set it deliberately, or not at all.

​
Platform / dashboard account

The managed dashboard authenticates through WorkOS AuthKit:
  • Magic Auth, Google OAuth, and GitHub OAuth — the backend verifies your session JWT against WorkOS AuthKit’s remote JWKS (jose.createRemoteJWKSet + jose.jwtVerify); there is no locally-configured signing secret. The verified sub claim resolves to your account via public.users.workos_user_id.
  • API keys — sov_live_… keys are issued, listed, and revoked from API Keys. Revoke immediately on suspected exposure — there is no scheduled auto-rotation today (see Authentication & Tokens); revocation of a team-scoped sub-key does not itself trigger a DEK rotation, but revoking a full team member does.
  • Enterprise SSO + SCIM — SAML 2.0 single sign-on and SCIM 2.0 directory provisioning are available on the Enterprise plan (see SSO & SCIM).

​
Recovery — what each plan actually guarantees

sovseal is sovereign by default: your keys, your responsibility. Managed recovery is a paid entitlement, gated by planHasManagedRecovery().
On the local/MCP and Hobby/Starter tiers there is no reset and no recovery. This is a deliberate property of the zero-knowledge design, not a limitation we can waive for you.

​
Best practices

  1. Prefer Google or GitHub OAuth over Magic Auth links where your organization already enforces MFA on those accounts.
  2. Back up your OS-keychain master key material somewhere offline before you depend on sync.
  3. Scope sov_proj_ and sov_live_ tokens narrowly and rotate them; revoke on exposure.
  4. For teams that cannot accept total-loss risk, adopt Growth or above for Managed Key Recovery.