boxel: Skill for Claude Code

Secrets at rest (operators)

Stored secrets are sealed by the application before they reach the database, with AES-256-GCM from Node's crypto, by SecretsKeyring in packages/realm-server/lib/secrets-at-rest/envelope.ts. Each sealed value is four things a table stores: keyId (which data key sealed it), nonce (12 bytes), ciphertext and tag (16 bytes).

Envelope

• A 32-byte data key seals every secret. KMS wraps it; the wrapped blob lives in SSM as /<env>/boxel/SECRETS_WRAPPED_DATA_KEY and reaches the task as SECRETS_WRAPPED_DATA_KEY, with the key's ARN as SECRETS_KMS_KEY_ARN.
• The realm server and the worker manager each call kms:Decrypt once, at startup, then seal and open locally. Each worker the manager starts or respawns asks the manager for the keys over their IPC channel instead of calling KMS. A KMS outage stops new tasks from starting but never a running one, a worker respawn included, and no request makes a KMS call.
• The KMS client takes its region from the key ARN and gives up on a call after 5 s to connect or 10 s to answer, with 3 attempts.
• The unwrap uses the encryption context {"purpose": "boxel-secrets-data-key"}. The key policy lets only the realm-server and worker task roles decrypt, and only under that context. CloudTrail records each unwrap.

Binding

Each value is bound, as GCM additional authenticated data, to the field it is stored in (<table>.<column>, required), the owner, the row id and the destination the secret is sent to. A value moved to another column, row, owner or destination by a database writer doesn't open: the caller gets SecretDecryptionError, whose message names none of the inputs. Naming the field is what keeps two secrets on one row, such as an OAuth client secret and its refresh token sent to the same token endpoint, from being swapped.

• A secret with no destination yet (a key added before its first approval) is sealed under field, owner and id only. keyring.reseal(sealed, from, to) binds it to its destination; after that it opens only with that destination.
• secretEncryptionContext(binding) is the context a value is bound to: field, owner, id and destination_sha256. The destination appears only as its SHA-256, so the context is safe to log or to hand to a service that records it.
• Destinations are compared exactly as given. A caller passes the same normalized form when sealing and opening.