vta_keyspaces/lib.rs
1//! Central registry of the VTA's keyspace names.
2//!
3//! Every `store.keyspace(..)` call in the VTA (`vta-service` server, offline
4//! CLIs, backup, tests) names its keyspace through a `const` here rather than a
5//! bare string literal. This is the single source of truth that killed the
6//! `"imported"` / `"imported_secrets"` test-vs-production divergence (a test
7//! opened a *different*, empty keyspace than the one production writes). The
8//! `no_bare_keyspace_literals` guard in `vta-service` keeps it that way by
9//! scanning that crate's source for bare `.keyspace("…")` literals.
10//!
11//! Keyspace *names* live here; per-keyspace *key formats* (the `key:`, `seed:`,
12//! `path_counter:` … record families inside a keyspace) are a separate concern
13//! and are not yet centralised.
14//!
15//! A near-leaf crate: it holds the shared keyspace vocabulary (the name
16//! constants) plus the [`Keyspaces`] handle bundle, so that every VTA subsystem
17//! crate can name and pass keyspaces without depending on `vta-service`. Its
18//! only dependency is `vti-common` (for `KeyspaceHandle`).
19
20use vti_common::store::KeyspaceHandle;
21
22/// Shared bundle of borrowed keyspace handles passed to operations that need
23/// several keyspaces at once.
24///
25/// The struct is a pure field bundle — the constructors that borrow it from a
26/// concrete `AppState` / `VtaState` live in `vta-service` (they know those
27/// types), so this stays free of any `vta-service` dependency.
28pub struct Keyspaces<'a> {
29 pub keys: &'a KeyspaceHandle,
30 pub acl: &'a KeyspaceHandle,
31 pub contexts: &'a KeyspaceHandle,
32 pub did_templates: &'a KeyspaceHandle,
33 pub audit: &'a KeyspaceHandle,
34 pub imported: &'a KeyspaceHandle,
35 #[cfg(feature = "webvh")]
36 pub webvh: &'a KeyspaceHandle,
37}
38
39/// Master seed + key records (`key:`, `seed:`, `path_counter:`,
40/// `active_seed_id`, `imported_kek_salt`, …) and the backup import sentinel.
41pub const KEYS: &str = "keys";
42/// Auth sessions + challenges.
43pub const SESSIONS: &str = "sessions";
44/// ACL entries + the seal record + the integrity-anchor root.
45pub const ACL: &str = "acl";
46/// Trust contexts (the BIP-32 key hierarchy roots).
47pub const CONTEXTS: &str = "contexts";
48/// Stored DID templates (global + context-scoped).
49pub const DID_TEMPLATES: &str = "did_templates";
50/// Audit log.
51pub const AUDIT: &str = "audit";
52/// Imported secret material (KEK-wrapped). Named `imported_secrets`, **not**
53/// `imported` — the latter was a long-standing test-only typo that operated on
54/// an empty keyspace disjoint from production. Always reference this const.
55pub const IMPORTED_SECRETS: &str = "imported_secrets";
56/// Ephemeral cache (resolver/auth caches).
57pub const CACHE: &str = "cache";
58/// Holder credential vault (third-party secrets stored on this VTA).
59pub const VAULT: &str = "vault";
60/// Persistent runtime service-enable state (`operations::protocol::runtime_state`).
61pub const SERVICE_STATE: &str = "service_state";
62/// Sealed-bootstrap anti-replay nonce log.
63pub const SEALED_NONCES: &str = "sealed_nonces";
64/// In-flight backup-bundle control-plane records.
65pub const BACKUP_BUNDLES: &str = "backup_bundles";
66/// WebVH DID records + `did.jsonl` state.
67pub const WEBVH: &str = "webvh";
68/// In-flight passkey-as-verificationMethod enrolment state.
69pub const PASSKEY_VMS: &str = "passkey_vms";
70/// Persisted protocol-management drain set.
71pub const DRAINS: &str = "drains";
72/// Per-kind previous-config snapshots for fail-forward rollback.
73/// (Historically `operations::protocol::snapshot::KEYSPACE_NAME`.)
74pub const SNAPSHOT: &str = "service_prev_config";
75/// KMS-protected, unencrypted boot keyspace (TEE integrity manifest, etc.).
76pub const BOOTSTRAP: &str = "bootstrap";
77/// Inbound-messaging consent: durable grants + TTL'd pending requests
78/// (`vti_common::consent`). The VTA is the first gate for bridged conversations.
79pub const CONSENT: &str = "consent";
80/// Per-(platform, context) approver bindings — who decides consent and how the
81/// prompt routes (`vti_common::consent::ApproverBinding`).
82pub const CONSENT_APPROVERS: &str = "consent_approvers";
83/// VTA-issued credentials (minted by `vta/credentials/issue/0.1`, revoked by
84/// `vta/credentials/revoke/0.1`). One record per credential keyed `cred:<id>`;
85/// revocation is a tombstone (`revokedAt` set in place), not a delete. Distinct
86/// from [`VAULT`] (which stores credentials the holder *holds*).
87pub const ISSUED_CREDENTIALS: &str = "issued_credentials";
88
89/// Per-context key/value store for AI-agent memory (`vta/memory/{put,list,
90/// delete}/0.1`). One record per `(contextId, key)` pair, keyed
91/// `mem:<contextId>:<key>`; `list` is a `mem:<contextId>:` prefix scan. Durable
92/// user data → in [`BACKED_UP`].
93pub const MEMORY: &str = "memory";
94
95/// Rego policy modules for the Policy Decision Point (`policy/{upsert,list,
96/// delete,evaluate}`). One `policy::PolicyModule` per id, keyed `policy:<id>`;
97/// the active set is every enabled row, priority-ordered. Durable operator
98/// security config → in [`BACKED_UP`] (a lost policy set would silently drop
99/// enforcement on restore).
100pub const POLICY: &str = "policy";
101
102/// Task-execution consent for the PDP's `requireConsent` disposition: pending
103/// approvals keyed by payload digest, and granted consents a re-submitted task
104/// consumes. Distinct from [`CONSENT`] (messaging-bridge conversation consent).
105/// One `policy::consent::PendingTaskConsent` per `pending:<digest>` and
106/// `policy::consent::TaskConsentGrant` per `grant:<digest>:<requester>`.
107/// Durable operator-facing security state → [`BACKED_UP`].
108pub const TASK_CONSENT: &str = "task_consent";
109
110/// Durable reliable-messaging outbox backing `vti_common::outbox_store::`
111/// `VtiOutboxStore` for the delivery-layer `MessagingService` (D2 P2a
112/// cut-over). Holds `Guaranteed`-delivery outbox entries; dormant in P2a (all
113/// current sends are `BestEffort`) but wired so the drain/confirmation loops
114/// persist across restarts once P2b adds guaranteed VTA pushes. Runtime state,
115/// not backed up.
116pub const OUTBOX: &str = "outbox";
117
118/// Every production keyspace. Partitioned by [`BACKED_UP`] +
119/// [`EXCLUDED_FROM_BACKUP`]; the [`tests::backup_partition_is_total`] guard
120/// asserts the partition stays exhaustive so a newly-added keyspace can't be
121/// silently omitted from the backup decision.
122pub const ALL: &[&str] = &[
123 KEYS,
124 SESSIONS,
125 ACL,
126 CONTEXTS,
127 DID_TEMPLATES,
128 AUDIT,
129 IMPORTED_SECRETS,
130 CACHE,
131 VAULT,
132 SERVICE_STATE,
133 SEALED_NONCES,
134 BACKUP_BUNDLES,
135 WEBVH,
136 PASSKEY_VMS,
137 DRAINS,
138 SNAPSHOT,
139 BOOTSTRAP,
140 CONSENT,
141 CONSENT_APPROVERS,
142 ISSUED_CREDENTIALS,
143 MEMORY,
144 POLICY,
145 TASK_CONSENT,
146 OUTBOX,
147];
148
149/// Keyspaces whose contents a full `export_backup` captures (as typed
150/// collections — see `operations::backup`).
151pub const BACKED_UP: &[&str] = &[
152 KEYS,
153 ACL,
154 CONTEXTS,
155 AUDIT,
156 IMPORTED_SECRETS,
157 WEBVH,
158 CONSENT,
159 CONSENT_APPROVERS,
160 // Durable agent memory is user data and must survive a restore.
161 MEMORY,
162 // Operator security policy — must survive a restore, else enforcement
163 // silently reverts to whatever defaults boot-install provides.
164 POLICY,
165 // Task-consent grants are durable authorizations a re-submitted task
166 // consumes; losing them on restore would strand in-flight approvals.
167 TASK_CONSENT,
168];
169
170/// Keyspaces deliberately **not** in a backup.
171///
172/// Most are ephemeral / runtime / re-derivable: [`SESSIONS`], [`CACHE`],
173/// [`SEALED_NONCES`], [`SERVICE_STATE`], [`BACKUP_BUNDLES`], [`PASSKEY_VMS`],
174/// [`DRAINS`], [`SNAPSHOT`], [`BOOTSTRAP`]. [`DID_TEMPLATES`] and [`VAULT`]
175/// hold durable operator/holder state and are **known backup gaps** — a
176/// backup-fidelity follow-up should move them into [`BACKED_UP`], not leave
177/// them silently dropped.
178pub const EXCLUDED_FROM_BACKUP: &[&str] = &[
179 SESSIONS,
180 DID_TEMPLATES,
181 CACHE,
182 VAULT,
183 SERVICE_STATE,
184 SEALED_NONCES,
185 BACKUP_BUNDLES,
186 PASSKEY_VMS,
187 DRAINS,
188 SNAPSHOT,
189 BOOTSTRAP,
190 // Durable VTA-issued holder credentials. Like [`VAULT`], a known backup
191 // gap — a backup-fidelity follow-up should move it into [`BACKED_UP`].
192 ISSUED_CREDENTIALS,
193 // Reliable-messaging outbox: runtime delivery state, re-driven from live
194 // sends, not part of a state backup.
195 OUTBOX,
196];
197
198#[cfg(test)]
199mod tests {
200 use super::*;
201 use std::collections::BTreeSet;
202
203 /// The backup partition must be total and disjoint: every production
204 /// keyspace is either backed up or explicitly excluded. Adding a keyspace
205 /// to [`ALL`] without classifying it fails here — that's the point.
206 #[test]
207 fn backup_partition_is_total() {
208 let all: BTreeSet<&str> = ALL.iter().copied().collect();
209 let backed: BTreeSet<&str> = BACKED_UP.iter().copied().collect();
210 let excluded: BTreeSet<&str> = EXCLUDED_FROM_BACKUP.iter().copied().collect();
211
212 assert_eq!(all.len(), ALL.len(), "ALL has a duplicate");
213 assert!(
214 backed.is_disjoint(&excluded),
215 "a keyspace is both backed up and excluded: {:?}",
216 backed.intersection(&excluded).collect::<Vec<_>>()
217 );
218 let union: BTreeSet<&str> = backed.union(&excluded).copied().collect();
219 assert_eq!(
220 union, all,
221 "backup partition is not exhaustive — every keyspace in ALL must be in \
222 exactly one of BACKED_UP / EXCLUDED_FROM_BACKUP"
223 );
224 }
225}