Safe References

Every Cuitty Safe reference normalizes to:

account/safe/secret

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

Accepted syntaxes

# Bare path, valid when Cuitty Safe is the active resolver.
DATABASE_URL=acme/dev/database-url

# Explicit scheme, preferred for mixed env files.
DATABASE_URL=cuitty-safe:acme/dev/database-url

# URL-style scheme for tools that require URI-looking values.
DATABASE_URL=cuitty-safe://acme/dev/database-url

# Inline encrypted literal. This is ciphertext, not a pointer.
DATABASE_URL=csafe:v1:aes-256-gcm:kid_localdev:base64url-nonce:base64url-ciphertext

Parsing rules

• account and safe are required and cannot contain /.
• secret is required and may contain additional / characters.
• References are case-sensitive.
• Tools should URL-encode reserved characters.
• The resolver should warn when a configured backend is case-insensitive.
• Decrypted values must not appear in URLs, logs, trace spans, crash reports, docs examples, or generated fixtures.

Resolver strictness

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

Defaults:

• .env and .env.* use explicit-only, plus known-env-vars when a cuittySafe.env map exists.
• package.json resolves only cuittySafe.env and explicit cuitty-safe: values.
• Shell scripts resolve only explicit CLI calls or explicit cuitty-safe: values.
• CI/CD resolves explicit references only.

Source-of-truth index

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

~/.cuitty/safe/index.json
.cuitty/safe/index.json

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