{ "slug": "safe/references", "title": "Safe References", "description": "The canonical account/safe/secret model and accepted reference syntaxes for Cuitty Safe.", "url": "https://cuitty.com/docs/safe/references", "markdown_url": "https://cuitty.com/docs/safe/references.md", "json_url": "https://cuitty.com/docs/safe/references.json", "frontmatter": { "title": "Safe References", "description": "The canonical account/safe/secret model and accepted reference syntaxes for Cuitty Safe.", "order": 2, "section": "Safe", "updatedAt": "2026-06-09" }, "headings": [ { "depth": 1, "slug": "safe-references", "text": "Safe References" }, { "depth": 2, "slug": "accepted-syntaxes", "text": "Accepted syntaxes" }, { "depth": 2, "slug": "parsing-rules", "text": "Parsing rules" }, { "depth": 2, "slug": "resolver-strictness", "text": "Resolver strictness" }, { "depth": 2, "slug": "source-of-truth-index", "text": "Source-of-truth index" } ], "body_markdown": "# Safe References\n\nEvery Cuitty Safe reference normalizes to:\n\n```text\naccount/safe/secret\n```\n\n`account` is the namespace, `safe` is the Safe name, and `secret` is the remaining logical key path.\n\n## Accepted syntaxes\n\n```dotenv\n# Bare path, valid when Cuitty Safe is the active resolver.\nDATABASE_URL=acme/dev/database-url\n\n# Explicit scheme, preferred for mixed env files.\nDATABASE_URL=cuitty-safe:acme/dev/database-url\n\n# URL-style scheme for tools that require URI-looking values.\nDATABASE_URL=cuitty-safe://acme/dev/database-url\n\n# Inline encrypted literal. This is ciphertext, not a pointer.\nDATABASE_URL=csafe:v1:aes-256-gcm:kid_localdev:base64url-nonce:base64url-ciphertext\n```\n\n## Parsing rules\n\n- `account` and `safe` are required and cannot contain `/`.\n- `secret` is required and may contain additional `/` characters.\n- References are case-sensitive.\n- Tools should URL-encode reserved characters.\n- The resolver should warn when a configured backend is case-insensitive.\n- Decrypted values must not appear in URLs, logs, trace spans, crash reports, docs examples, or generated fixtures.\n\n## Resolver strictness\n\n```ts\ntype SafeReferenceMode = \"explicit-only\" | \"known-env-vars\" | \"all-values\";\n```\n\nDefaults:\n\n- `.env` and `.env.*` use `explicit-only`, plus `known-env-vars` when a `cuittySafe.env` map exists.\n- `package.json` resolves only `cuittySafe.env` and explicit `cuitty-safe:` values.\n- Shell scripts resolve only explicit CLI calls or explicit `cuitty-safe:` values.\n- CI/CD resolves explicit references only.\n\n## Source-of-truth index\n\nCuitty Safe tracks where each Safe lives in metadata-only indexes:\n\n```text\n~/.cuitty/safe/index.json\n.cuitty/safe/index.json\n```\n\nThe index stores provider, status, key fingerprint, connector version, source pointer, and sharing stub metadata. It never stores secret values.", "body_html": "

Safe References

\n

Every Cuitty Safe reference normalizes to:

\n
account/safe/secret
\n

account is the namespace, safe is the Safe name, and secret is the remaining logical key path.

\n

Accepted syntaxes

\n
# Bare path, valid when Cuitty Safe is the active resolver.\nDATABASE_URL=acme/dev/database-url\n\n# Explicit scheme, preferred for mixed env files.\nDATABASE_URL=cuitty-safe:acme/dev/database-url\n\n# URL-style scheme for tools that require URI-looking values.\nDATABASE_URL=cuitty-safe://acme/dev/database-url\n\n# Inline encrypted literal. This is ciphertext, not a pointer.\nDATABASE_URL=csafe:v1:aes-256-gcm:kid_localdev:base64url-nonce:base64url-ciphertext
\n

Parsing rules

\n\n

Resolver strictness

\n
type SafeReferenceMode = \"explicit-only\" | \"known-env-vars\" | \"all-values\";
\n

Defaults:

\n\n

Source-of-truth index

\n

Cuitty Safe tracks where each Safe lives in metadata-only indexes:

\n
~/.cuitty/safe/index.json\n.cuitty/safe/index.json
\n

The index stores provider, status, key fingerprint, connector version, source pointer, and sharing stub metadata. It never stores secret values.

", "links_out": [] }