66 lines
2.3 KiB
Markdown
66 lines
2.3 KiB
Markdown
|
# Credential Vault Templates (ADR-017)
|
||
|
|
|
||
|
|
Three starting templates for adopting the credential vault model. Copy the snippet
|
||
|
|
that matches your tenancy needs into your project's `.ontoref/project.ncl` and
|
||
|
|
`.ontology/manifest.ncl`. None is mandatory — the schema fields are optional and
|
||
|
|
projects can declare them ad-hoc.
|
||
|
|
|
||
|
|
## Pick one
|
||
|
|
|
||
|
|
| Template | When to use |
|
||
|
|
|---|---|
|
||
|
|
| **single-team** | One team, no tenant separation. CI uses same credentials as developers. |
|
||
|
|
| **multi-tenant** | Multiple clients/projects share the same vault but must not see each other's credentials. |
|
||
|
|
| **agent-first** | AI agents (MCP) consume credentials with strict RO scope; humans operate normally. |
|
||
|
|
|
||
|
|
## Layout
|
||
|
|
|
||
|
|
```text
|
||
|
|
single-team/
|
||
|
|
project.ncl.snippet ← paste into <your-project>/.ontoref/project.ncl
|
||
|
|
manifest.ncl.snippet ← paste into <your-project>/.ontology/manifest.ncl
|
||
|
|
multi-tenant/
|
||
|
|
project.ncl.snippet
|
||
|
|
manifest.ncl.snippet
|
||
|
|
agent-first/
|
||
|
|
project.ncl.snippet
|
||
|
|
manifest.ncl.snippet
|
||
|
|
```
|
||
|
|
|
||
|
|
## Snippet conventions
|
||
|
|
|
||
|
|
- `<placeholder>` — replace with project-specific value
|
||
|
|
- `age1...` — generate via `age-keygen -o ~/.age/keys/<name>.key.txt`, copy
|
||
|
|
the public key from the line `# public key: ...`
|
||
|
|
- All paths in `credential_sops` / `credential_sops_rw` are relative to the
|
||
|
|
src-vault root (i.e. `~/.config/ontoref/vaults/<vault_id>/src-vault/`)
|
||
|
|
|
||
|
|
## Migration from one template to another
|
||
|
|
|
||
|
|
Templates only differ in `recipient_groups` + `recipient_rules` and the
|
||
|
|
`credential_sops` paths. To switch:
|
||
|
|
|
||
|
|
1. Edit `project.ncl::sops.recipient_groups` + `recipient_rules`
|
||
|
|
2. Edit `manifest.ncl::registry_provides.registries[].credential_sops*`
|
||
|
|
3. `ore secrets rekey` — regenerates `<vault>/.sops.yaml` and re-encrypts
|
||
|
|
4. `ore secrets close` — pushes the updated state
|
||
|
|
|
||
|
|
## No template: legacy minimal
|
||
|
|
|
||
|
|
If none of the templates fits, the minimal viable path is:
|
||
|
|
|
||
|
|
```ncl
|
||
|
|
sops = {
|
||
|
|
enabled = true,
|
||
|
|
vault_id = "<your-slug>",
|
||
|
|
master_key_path = "/path/to/.kage",
|
||
|
|
vault_backend = 'restic,
|
||
|
|
registry_endpoint = "<your-zot-host>",
|
||
|
|
actor_key_bindings = { developer = "developer" },
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
`recipient_groups` + `recipient_rules` left absent. The bootstrap will require
|
||
|
|
`SOPS_AGE_RECIPIENTS` env var listing all recipient public keys. Same recipients
|
||
|
|
across all encrypted files. Path A in the FAQ.
|