> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Account & Device Security

> How sovseal authenticates you, where your keys live, and exactly what recovery is — and isn't — available on each plan.

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:

```json theme={null}
{ "project_id": "sov_proj_<uuid-v4>", "api_key": "sov_proj_...", "endpoint": "https://…/v2-agent-state" }
```

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.

<Warning>
  **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.
</Warning>

## 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](/platform/console/api-keys). Revoke immediately on suspected exposure — there is no scheduled auto-rotation today (see [Authentication & Tokens](/platform/features/auth-and-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](/platform/features/sso-and-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()`.

| Plan                | Recovery model                                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hobby / Starter** | **Sovereign, no escrow.** Lose the keychain master key (or the fallback key file) and every snapshot is permanently undecryptable. Back up your key material. |
| **Growth / Pro**    | **Managed Key Recovery** — Shamir-split DEK escrow, restorable from the dashboard.                                                                            |
| **Enterprise**      | Managed recovery **plus HSM-backed** key custody.                                                                                                             |

<Warning>
  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.
</Warning>

## 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.