{
  "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.",
  "links_out": []
}