82a358f18d
ontoref-derive: #[onto_mcp_tool] attribute macro registers MCP tool unit-structs in
the catalog at link time via inventory::submit!; annotated item is emitted unchanged,
ToolBase/AsyncTool impls stay on the struct. All 34 tools migrated from manual wiring
(net +5: ontoref_list_projects, ontoref_search, ontoref_describe,
ontoref_list_ontology_extensions, ontoref_get_ontology_extension).
validate modes (ADR-018): reads level_hierarchy from workflow.ncl and checks every
.ncl mode for level declared, strategy declared, delegate chain coherent, compose
extends valid. mode resolve <id> shows which hierarchy level handles a mode and why.
--self-test generates synthetic fixtures in a temp dir for CI smoke-testing.
validate run-cargo: two-step Cargo.toml resolution — workspace layout first
(crates/<check.crate>/Cargo.toml), single-crate fallback by package name or repo
basename. Lets the same ADR constraint shape apply to workspace and single-crate repos.
ontology/schemas/manifest.ncl: registry_topology_type contract — multi-registry
coordination, push targets, participant scopes, per-namespace capability.
reflection/requirements/base.ncl: oras ≥1.2.0, cosign ≥2.0.0, sops ≥3.9.0, age
≥1.1.0, restic declared as Hard/Soft requirements with version_min, check_cmd, and
install_hint (ADR-017 toolchain surface).
ADR-019: per-file recipient routing for tenant isolation without multi-vault. Schema
additions: sops.recipient_groups + sops.recipient_rules in ontoref-project.ncl.
secrets-bootstrap generates .sops.yaml from project.ncl in declarative mode. Three
new secrets-audit checks: recipient-routing-coherent, recipient-routing-coverage,
no-multi-vault. Adoption templates: single-team/, multi-tenant/, agent-first/.
Integration templates: domain-producer/, mode-producer/, mode-consumer/.
UI: project_picker surfaces registry badge (⟳ participant) and vault badge
(⛁ vault_id · N, green=declarative / amber=legacy) per project card. Expanded panel
adds collapsible Registry section with namespace, endpoint, and push/pull capability.
manage.html gains Runtime Services card — MCP and GraphQL toggleable without restart
via HTMX POST /ui/manage/services/{service}/toggle.
describe.nu: capabilities JSON includes registry_topology and vault_state per project.
sync.nu: drift check extended to detect //! absence on newly registered crates.
qa.ncl: six entries — credential-vault-best-practice (layered data-flow diagram),
credential-vault-templates (paths A/B/C), credential-vault-troubleshooting (15 named
errors), integration-what-and-why (ADR-042 OCI federation), integration-how-to-implement,
integration-troubleshooting.
on+re: core.ncl + manifest.ncl updated to reflect OCI, MCP, and mode-hierarchy nodes.
Deleted stale presentation assets (2026-02 slides + voice notes).
65 lines
2.3 KiB
Markdown
65 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.
|