---
title: Safe References
description: The canonical account/safe/secret model and accepted reference syntaxes for Cuitty Safe.
section: Safe
order: 2
updatedAt: 2026-06-09
slug: safe/references
---
# Safe References

Every Cuitty Safe reference normalizes to:

```text
account/safe/secret
```

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

## Accepted syntaxes

```dotenv
# 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

```ts
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:

```text
~/.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.