{ "slug": "safe/storage-modes", "title": "Safe Storage Modes", "description": "Compare local vaults, inline encrypted text, Persist-backed Safes, and 1Password pass-through.", "url": "https://cuitty.com/docs/safe/storage-modes", "markdown_url": "https://cuitty.com/docs/safe/storage-modes.md", "json_url": "https://cuitty.com/docs/safe/storage-modes.json", "frontmatter": { "title": "Safe Storage Modes", "description": "Compare local vaults, inline encrypted text, Persist-backed Safes, and 1Password pass-through.", "order": 3, "section": "Safe", "updatedAt": "2026-06-09" }, "headings": [ { "depth": 1, "slug": "safe-storage-modes", "text": "Safe Storage Modes" }, { "depth": 2, "slug": "local-vault", "text": "Local vault" }, { "depth": 2, "slug": "inline-encrypted-text", "text": "Inline encrypted text" }, { "depth": 2, "slug": "persist-adapter", "text": "Persist adapter" }, { "depth": 2, "slug": "1password-pass-through", "text": "1Password pass-through" } ], "body_markdown": "# Safe Storage Modes\n\nEach Safe chooses one source of truth. The reference path stays stable even when the backing provider changes.\n\n| Mode | Source of truth | Best fit |\n| --- | --- | --- |\n| Local vault | Encrypted local Safe database | First-run development, locked workstations, local CI workers |\n| Inline encrypted text | Ciphertext in the referencing file | Portable fixtures and small local-only handoffs |\n| Persist adapter | Cuitty Persist `secret` storage class with E2EE | Local or remote sync experiments that accept alpha guardrails |\n| 1Password | 1Password vault/item/field | Team production credentials and headless CI service accounts |\n\n## Local vault\n\nLocal vaults are the default for first-run development.\n\n```text\n~/.cuitty/safe/vaults///safe.db\n~/.cuitty/safe/vaults///safe.audit.jsonl\n```\n\nKey material should live in the OS credential store when available: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Headless passphrase-derived keys require explicit opt-in.\n\n## Inline encrypted text\n\nInline mode stores authenticated ciphertext next to the config that needs it:\n\n```dotenv\nSTRIPE_SECRET=csafe:v1:aes-256-gcm:kid_localdev:base64url-nonce:base64url-ciphertext\n```\n\nInline values must use authenticated encryption, include versioned envelope metadata, and keep decryption keys outside the file.\n\n## Persist adapter\n\nPersist mode stores Safe records as E2EE payloads in Cuitty Persist.\n\n```ts\nimport { createSafePersistAdapter } from \"@cuitty/safe/server\";\n\nconst adapter = createSafePersistAdapter({\n profile: \"local-first-laptop\",\n account: \"acme\",\n safe: \"dev\",\n namespace: \"safe/acme/dev\",\n storageClass: \"secret\",\n syncMode: \"manual\",\n alpha: true,\n acknowledgeE2eeRisk: true,\n});\n```\n\nThe Persist adapter is alpha until Persist's E2EE profile runtime reaches GA security review, recovery testing, and multi-device revocation testing. For high-value production CI/CD credentials, prefer 1Password service accounts or a locked local vault until that review is complete.\n\n## 1Password pass-through\n\n1Password mode keeps 1Password as the source of truth. Cuitty Safe stores metadata that maps a Cuitty ref to a 1Password object.\n\n```text\nacme/dev/database-url -> op://Development/Database/url\n```\n\nUsers do not need to commit `op://...` references unless they choose the advanced escape hatch.", "body_html": "

Safe Storage Modes

\n

Each Safe chooses one source of truth. The reference path stays stable even when the backing provider changes.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ModeSource of truthBest fit
Local vaultEncrypted local Safe databaseFirst-run development, locked workstations, local CI workers
Inline encrypted textCiphertext in the referencing filePortable fixtures and small local-only handoffs
Persist adapterCuitty Persist secret storage class with E2EELocal or remote sync experiments that accept alpha guardrails
1Password1Password vault/item/fieldTeam production credentials and headless CI service accounts
\n

Local vault

\n

Local vaults are the default for first-run development.

\n
~/.cuitty/safe/vaults/<account>/<safe>/safe.db\n~/.cuitty/safe/vaults/<account>/<safe>/safe.audit.jsonl
\n

Key material should live in the OS credential store when available: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Headless passphrase-derived keys require explicit opt-in.

\n

Inline encrypted text

\n

Inline mode stores authenticated ciphertext next to the config that needs it:

\n
STRIPE_SECRET=csafe:v1:aes-256-gcm:kid_localdev:base64url-nonce:base64url-ciphertext
\n

Inline values must use authenticated encryption, include versioned envelope metadata, and keep decryption keys outside the file.

\n

Persist adapter

\n

Persist mode stores Safe records as E2EE payloads in Cuitty Persist.

\n
import { createSafePersistAdapter } from \"@cuitty/safe/server\";\n\nconst adapter = createSafePersistAdapter({\n  profile: \"local-first-laptop\",\n  account: \"acme\",\n  safe: \"dev\",\n  namespace: \"safe/acme/dev\",\n  storageClass: \"secret\",\n  syncMode: \"manual\",\n  alpha: true,\n  acknowledgeE2eeRisk: true,\n});
\n

The Persist adapter is alpha until Persist’s E2EE profile runtime reaches GA security review, recovery testing, and multi-device revocation testing. For high-value production CI/CD credentials, prefer 1Password service accounts or a locked local vault until that review is complete.

\n

1Password pass-through

\n

1Password mode keeps 1Password as the source of truth. Cuitty Safe stores metadata that maps a Cuitty ref to a 1Password object.

\n
acme/dev/database-url -> op://Development/Database/url
\n

Users do not need to commit op://... references unless they choose the advanced escape hatch.

", "links_out": [] }