Cloud references

A reference is a vault entry that holds a pointer to a value living in a cloud secret manager — not the value itself. kovra resolves it at runtime, under your own cloud identity, and never copies the plaintext into the vault. Two providers ship today:

• Azure Key Vault — azure-kv://<vault-name>/<secret-name>
• AWS Secrets Manager — aws-sm://<region>/<secret-name> (the name may contain /)

Add a reference

kovra add --reference stores the pointer. There’s no value to prompt for:

zsh

~ % kovra add secret:dev/db/url --reference 'azure-kv://my-keyvault/db-url'
Added dev/db/url (Medium).

In a listing, a reference shows a mode of reference and its pointer in place of a fingerprint — so you can see exactly where it resolves, with no value on screen:

zsh

~ % kovra list
┌────────┬──────────────┬─────────────┬───────────┬───────────────────────────────────────────────┐
│ ORIGIN ┆ COORDINATE   ┆ SENSITIVITY ┆ MODE      ┆ FINGERPRINT                                   │
╞════════╪══════════════╪═════════════╪═══════════╪═══════════════════════════════════════════════╡
│ global ┆ dev/db/url   ┆ medium      ┆ reference ┆ → azure-kv://my-keyvault/db-url               │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ global ┆ prod/app/jwt ┆ high        ┆ reference ┆ → aws-sm://us-east-1/prod/app/jwt-signing-key │
└────────┴──────────────┴─────────────┴───────────┴───────────────────────────────────────────────┘

A prod reference is still born high — the environment floor applies to the pointer just as it would to a literal.

Checked when you save it

kovra checks the pointer’s form before it saves it — with kovra add --reference, kovra edit --reference and an agent’s edit_metadata. A pointer that kovra run would refuse (no <scheme>://, a provider kovra doesn’t have, a malformed vault, region or name) is refused right away, with the same message run would give, and nothing is written:

zsh

~ % kovra add secret:dev/db/url --reference 'my-keyvault/db-url'
Error: provider error: reference `my-keyvault/db-url` is malformed: expected `<scheme>://…`

When you repoint a high reference, the check comes before the approval prompt, so you’re never asked to approve a repoint that would then fail. Only the form is checked — kovra doesn’t call your cloud to do it — so a secret that doesn’t exist, or that you can’t read, still shows up when the reference resolves. Names AWS generates itself, such as the RDS-managed rds!db-<uuid> and rds!cluster-<uuid>, are valid.

How a reference resolves

When a referenced coordinate is injected (via kovra run or an agent), kovra calls the provider with your credentials and streams the value straight into the child process — it is never written to the vault, a file, or your context. The same policy decision governs the delivery; the only difference from a literal is where the bytes come from.

A reference resolves at the strictest sensitivity any reference to the same provider secret has, in any vault: a low reference created next to a high one can’t read its value without the approval the high one needs. Provider URIs compare the way the provider does — the scheme and Azure names regardless of case, the AWS region in lowercase.

Your cloud login is not governed by kovra

A reference resolves with your own provider login (az, aws). An agent running as you, with that CLI signed in, can read the provider secret directly. high on a reference governs what kovra delivers, not what your cloud session allows.

This keeps the source of truth in your cloud secret manager while still giving you one coordinate namespace, one policy, and one audit trail across literal and cloud-backed secrets.

Reference vs. import

A reference stays live — it always resolves the current cloud value. If you instead want a one-time copy captured into the vault (no ongoing link to the source), see Import from 1Password.