> ## Documentation Index > Fetch the complete documentation index at: https://capy.sc/docs/llms.txt > Use this file to discover all available pages before exploring further. # Capy Cryptography: BIP-39 to AES-256-GCM > End-to-end Capy cryptography: BIP-39 seed → PBKDF2 master key → HKDF project key → AES-256-GCM ciphertext. Invite, deploy, and revocation primitives explained. Capy is zero-trust: the service stores your encrypted secrets but can never decrypt them on its own. Every decryption requires two independent shares - one held by you, one held by the service. This page walks through the complete client-side cryptography, from the root seed phrase down to the exact bytes your app decrypts at runtime. Service-internal constructions (how the outer wrap is stored, how the service gates co-decrypt requests) are intentionally out of scope here. The guarantee you should rely on is that the service holds only ciphertext and membership records, never key material in recoverable form. ## Trust model Neither side can read plaintext alone. * **Share 1 - your machine.** Holds the inner wrapping key, any derived project keys, and (for owners) the BIP-39 seed phrase. None of these ever leave your machine. * **Share 2 - Capy service.** Holds the outer encryption layer and the membership records that gate every decrypt request. The service never sees plaintext and cannot derive any user key on its own. Trust model: your machine holds the seed phrase, master key, project keys, and an inner wrap key. Capy's service holds identities, memberships, the ciphertext, and an outer wrap. Both halves are needed to co-decrypt. Trust model: your machine holds the seed phrase, master key, project keys, and an inner wrap key. Capy's service holds identities, memberships, the ciphertext, and an outer wrap. Both halves are needed to co-decrypt. If the service is fully compromised, an attacker can strip the outer layer off every `key.enc` file but still cannot recover any master key - the inner layer is AES-encrypted with a value bound to each user's identity and never stored server-side. ## Key hierarchy One root, everything else derived. Key hierarchy: BIP-39 seed phrase derives master key M via PBKDF2-SHA512. Master key M derives project key PK via HKDF-SHA256. The project key AES-256-GCM encrypts each value into a capy:... snippet. Key hierarchy: BIP-39 seed phrase derives master key M via PBKDF2-SHA512. Master key M derives project key PK via HKDF-SHA256. The project key AES-256-GCM encrypts each value into a capy:... snippet. The seed phrase is the only long-lived secret the system relies on. Every other key is either derived from it on demand or generated fresh for a single purpose and then discarded. | Key | Size | Scope | Origin | | ------------------- | -------- | ----------------- | -------------- | | BIP-39 seed phrase | 24 words | Organization root | User-generated | | Master key **M** | 32 bytes | Organization | PBKDF2-SHA512 | | Project key **PK** | 32 bytes | Project | HKDF-SHA256 | | Inner wrapping key | 32 bytes | Local storage | SHA-256 | | Invite token **T** | 32 bytes | One-time invite | Random | | Deploy token **DT** | 32 bytes | One deployment | Random | Full derivations: ``` M = PBKDF2-SHA512( seed, salt = "capy-mnemonic", iter = 2048, keylen = 32) PK = HKDF-SHA256( M, salt = orgId, info = "capy:project:{projectId}", length = 32) inner_wrap = SHA-256(userId + ":" + orgId) T = randomBytes(32) DT = randomBytes(32) ``` Each `capy:…` snippet also includes a 5-character `resourceId` - a stable per-project identifier for the variable that lets Capy diff ciphertext without leaking plaintext or revealing that two projects share a value. ## Inviting a new member Capy's invite flow is "double-wrapped": the master key is encrypted first by a client-side key derived from a one-time token, then again by the service. The token travels out-of-band to the invitee. The service never sees it. Invite flow: Alice generates token T, computes inner = AES(M, HKDF(T, email)), sends inner to the service. The service produces an outer-wrapped blob and returns it. Alice builds code = b64(T, orgId, outer) and sends it out-of-band to Bob. Bob sends outer with his auth to the service co-decrypt endpoint; the service verifies membership, strips the outer wrap, and returns inner to Bob. Bob derives M by inverting the AES step using HKDF(T, email). Invite flow: Alice generates token T, computes inner = AES(M, HKDF(T, email)), sends inner to the service. The service produces an outer-wrapped blob and returns it. Alice builds code = b64(T, orgId, outer) and sends it out-of-band to Bob. Bob sends outer with his auth to the service co-decrypt endpoint; the service verifies membership, strips the outer wrap, and returns inner to Bob. Bob derives M by inverting the AES step using HKDF(T, email). Your CLI generates `T = randomBytes(32)` and derives an inner key bound to the recipient's email: ``` innerKey = HKDF-SHA256( T, salt = "{orgId}:{email}", info = "capy:invite") innerBlob = AES-256-GCM(M, innerKey) ``` Binding the email into the HKDF salt means only the intended recipient can later derive the key that decrypts the blob. Your CLI sends `innerBlob` to `POST /orgs/{orgId}/wrap`. The service adds its outer wrap and returns an opaque `outerBlob`. The service never sees the inner key or `M`. Your CLI concatenates `T`, the org ID, and `outerBlob` into a single base64 string. You deliver this code to the invitee out-of-band (Signal, paper, QR). **The service never sees the redeem code.** The invitee runs `capy redeem ` and authenticates, receiving an auth token bound to their email. The invitee sends `outerBlob` to `POST /orgs/{orgId}/co-decrypt` with their auth. The service verifies org membership - **if the user is not an active member, the request fails here, and they cannot proceed**. Otherwise, the service returns `innerBlob`. The invitee derives the inner key locally using the token `T` and the email claim from their auth token. AES-GCM decrypts `innerBlob` and produces `M`. If the auth email doesn't match the salt the inviter used, decryption fails cryptographically - not by policy. The invitee re-wraps `M` with the same double-wrap scheme (`SHA256(userId:orgId)` inner, service-added outer) and saves it to `~/.capy/orgs/{orgId}/users/{userId}/key.enc`. The one-time token `T` is discarded. The redeem code contains the token `T`. Anyone who intercepts it **plus** the separately-delivered `outerBlob` could recover `M`. In practice the service holds `outerBlob` behind authentication, so `T` alone is useless - but treat the redeem code like a password and deliver it over a channel you trust. ## Sync: pushing and pulling secrets When you run `capy`, the CLI unlocks your master key, pulls the latest encrypted secrets from the service, diffs them against your local `.env`, and writes any changes back. Every secret is encrypted with AES-256-GCM under the project key. Sync flow: CLI posts to the service co-decrypt endpoint to get the master key M. CLI derives the project key PK. CLI fetches the current ciphertext blob from the service, decrypts per-variable, diffs against local, re-encrypts merged values, and sends the new blob back. Sync flow: CLI posts to the service co-decrypt endpoint to get the master key M. CLI derives the project key PK. CLI fetches the current ciphertext blob from the service, decrypts per-variable, diffs against local, re-encrypts merged values, and sends the new blob back. The service only ever sees opaque `capy:{resourceId}:{iv||ciphertext||tag}` snippets. Identical variable sets produce identical content-addressed blobs, so uploads are deduplicated. Your `.env` on disk never contains plaintext. Capy rewrites it in place with `capy:{...}` snippets after every sync. The plaintext only exists in memory, briefly, during the diff. ## Deploying to production Deploying an app adds a second zero-trust flow. You can't just ship your master key to CI - that would collapse the two-share property. Instead, `capy deploy` mints a deploy token `DT` that is itself double-wrapped: you keep one half as a CI secret, the service keeps the other half, and at build time your CI runner presents its half to the service to get the second half back. **Mint time** (on the developer machine): Deploy mint flow: capy deploy CLI generates DT, wraps the project key under HKDF(DT, projectId), and POSTs the inner blob to the service. The service returns deployId plus an opaque outer blob. The CLI builds the deploy code for the user to paste into their CI secret store. Deploy mint flow: capy deploy CLI generates DT, wraps the project key under HKDF(DT, projectId), and POSTs the inner blob to the service. The service returns deployId plus an opaque outer blob. The CLI builds the deploy code for the user to paste into their CI secret store. **Build time** (inside the CI runner): Deploy build flow: the build step parses the deploy code, posts the outer blob to the service deploy decrypt endpoint. The service checks the token has not been revoked and returns enough material for the runner to reconstruct the project key locally. The runner writes it to .capy/decrypt and discards the deploy token. Deploy build flow: the build step parses the deploy code, posts the outer blob to the service deploy decrypt endpoint. The service checks the token has not been revoked and returns enough material for the runner to reconstruct the project key locally. The runner writes it to .capy/decrypt and discards the deploy token. The crucial detail is that the service never learns the project key. It only ever holds the outer-wrapped form, which is useless without the customer-held `DT` half. Run `capy deploy`. Your CLI generates `DT`, wraps `PK` with `HKDF(DT, salt=projectId, info="capy:deploy")`, sends the inner blob to the service for outer-wrapping, and receives a `deployId`. Your CLI prints the deploy code. You paste it into your CI secret store (GitHub Actions secrets, Vercel env vars, etc.). Your build step reads the deploy code, posts the outer portion to `POST /deploy/{deployId}/decrypt`, and receives the material it needs to reconstruct `PK` locally using its own `DT`-derived key. The runner derives `PK` locally, writes `.capy/decrypt` (hex of `PK`), and discards `DT`. From here on the app reads decrypted values the usual way. ## Revocation Removing a member is O(1) - a membership deletion on the service side. No key rotation, no re-encryption of secrets. Revocation flow: Owner runs capy kick bob; the service deletes the user's membership and returns ok. Later the kicked user runs any capy command and posts to the co-decrypt endpoint; the service checks membership, fails, returns 403. The user's key.enc remains on disk but is cryptographically inert because the outer wrap needs the service and the service now refuses. Revocation flow: Owner runs capy kick bob; the service deletes the user's membership and returns ok. Later the kicked user runs any capy command and posts to the co-decrypt endpoint; the service checks membership, fails, returns 403. The user's key.enc remains on disk but is cryptographically inert because the outer wrap needs the service and the service now refuses. Why it's safe to skip re-encryption: the kicked user's `key.enc` on disk is outer-wrapped. To use it, they need the service to strip the outer layer, and the service now refuses them. Their bytes are still on disk but cryptographically inert. If the kicked user had already decrypted some values and kept plaintext copies elsewhere, those copies are outside Capy's control. Rotate the specific secrets they had access to through your normal secret rotation process - the revocation above only prevents *new* decryption. **The one case that does require full rotation: seed phrase compromise.** A user who copied their BIP-39 seed phrase can derive `M` offline, bypassing the service's co-decrypt gate entirely. If you suspect seed-phrase exfiltration, generate a new seed, derive a new `M`, re-encrypt every secret, and re-invite every member. ## Cryptographic primitives A single reference for every client-side algorithm used on the data path. | Purpose | Algorithm | Parameters | | ------------------------- | ------------- | ------------------------------------------------ | | Symmetric encryption | AES-256-GCM | IV = 12 random bytes, tag = 16 bytes | | Key derivation | HKDF-SHA256 | Per-use `salt` and `info` - see key hierarchy | | Seed → master key | PBKDF2-SHA512 | `salt="capy-mnemonic"`, `iter=2048`, `keylen=32` | | Inner wrap + resource IDs | SHA-256 | Deterministic hashing | There is no asymmetric cryptography on the data path. All confidentiality and authentication comes from AES-256-GCM. All key derivations are HKDF-SHA256 except the one-shot seed-to-master conversion, which uses PBKDF2 to slow down brute force against the BIP-39 wordlist.