eleven / ocho Public

Clone
git clone https://amadan.net/eleven/ocho

Plain git — no account needed to clone.

Download

Download this file

1{
2 "description": "πŸ€– Vault fold vectors β€” the cross-implementation contract for the Vault app's reducer, INCLUDING the lock layer (docs/locked-vaults.md). The web reducer (web/static/apps/vault.js) and the Go fold (internal/vault) must fold every event_sequence from an empty state to exactly expected_state. States are compared in CANONICAL form: every item/log/keyring field present, \"\" / 0 defaults for absent strings/numbers, keyring null when the vault is unlocked. Access follows THREAD MEMBERSHIP: a lock hands the vault key to each member (`handoffs`, each a `member` wrap sealed to their roster key); a member self-enrols a durable wrap (`vault.enroll`, which drops their `member` handoff by uid); an insider gives a latecomer a handoff (`vault.give`). There is no request/grant. Vectors are the spec: if one side disagrees, fix the implementation, never the vector.",
3 "app": "vault",
4 "source": "web/static/apps/vault.js (events reducer) + internal/vault/vault.go (Fold)",
5 "state_shape": {
6 "items": [{ "id": "", "name": "", "value": "", "sealed": "", "kind": "text", "by": "", "byName": "", "at": 0, "updatedBy": "", "updatedByName": "", "updatedAt": 0 }],
7 "log": [{ "id": "", "ref": "", "action": "add|change|remove|lock|enroll|give|revoke", "name": "", "by": "", "byName": "", "at": 0 }],
8 "keyring": { "v": 1, "pub": "", "wraps": [{ "id": "", "kind": "passkey|keychain|member", "label": "", "uid": "", "credId": "", "wrapped": "" }] }
9 },
10 "vectors": [
11 {
12 "name": "plain add, change, remove β€” items and audit log",
13 "event_sequence": [
14 { "type": "vault.add", "id": "s1", "aid": "a1", "label": "WiFi", "value": "hunter2", "uid": "u1", "name": "Paul", "ts": 1000 },
15 { "type": "vault.change", "id": "s1", "aid": "a2", "value": "hunter3", "uid": "u2", "name": "James", "ts": 2000 },
16 { "type": "vault.add", "id": "s2", "aid": "a3", "label": "Door", "value": "0000", "uid": "u1", "name": "Paul", "ts": 3000 },
17 { "type": "vault.remove", "id": "s1", "aid": "a4", "uid": "u1", "name": "Paul", "ts": 4000 }
18 ],
19 "expected_state": {
20 "items": [
21 { "id": "s2", "name": "Door", "value": "0000", "sealed": "", "kind": "text", "by": "u1", "byName": "Paul", "at": 3000, "updatedBy": "", "updatedByName": "", "updatedAt": 0 }
22 ],
23 "log": [
24 { "id": "a1", "ref": "s1", "action": "add", "name": "WiFi", "by": "u1", "byName": "Paul", "at": 1000 },
25 { "id": "a2", "ref": "s1", "action": "change", "name": "WiFi", "by": "u2", "byName": "James", "at": 2000 },
26 { "id": "a3", "ref": "s2", "action": "add", "name": "Door", "by": "u1", "byName": "Paul", "at": 3000 },
27 { "id": "a4", "ref": "s1", "action": "remove", "name": "WiFi", "by": "u1", "byName": "Paul", "at": 4000 }
28 ],
29 "keyring": null
30 }
31 },
32 {
33 "name": "replays dedupe β€” a re-folded add changes nothing",
34 "note": "addItem keys items by id and log entries by aid, so folding the same event twice (a reconnect catch-up overlapping a snapshot) is a no-op.",
35 "event_sequence": [
36 { "type": "vault.add", "id": "s1", "aid": "a1", "label": "WiFi", "value": "hunter2", "uid": "u1", "name": "Paul", "ts": 1000 },
37 { "type": "vault.add", "id": "s1", "aid": "a1", "label": "WiFi", "value": "hunter2", "uid": "u1", "name": "Paul", "ts": 1000 }
38 ],
39 "expected_state": {
40 "items": [
41 { "id": "s1", "name": "WiFi", "value": "hunter2", "sealed": "", "kind": "text", "by": "u1", "byName": "Paul", "at": 1000, "updatedBy": "", "updatedByName": "", "updatedAt": 0 }
42 ],
43 "log": [
44 { "id": "a1", "ref": "s1", "action": "add", "name": "WiFi", "by": "u1", "byName": "Paul", "at": 1000 }
45 ],
46 "keyring": null
47 }
48 },
49 {
50 "name": "malformed adds fold to no-ops",
51 "note": "missing id/aid/label, both value+sealed, neither, and empty sealed are all rejected; a remove of an unknown id still logs (the item may have raced away) but touches no items.",
52 "event_sequence": [
53 { "type": "vault.add", "id": "", "aid": "a1", "label": "X", "value": "v" },
54 { "type": "vault.add", "id": "s1", "aid": "", "label": "X", "value": "v" },
55 { "type": "vault.add", "id": "s1", "aid": "a1", "label": " ", "value": "v" },
56 { "type": "vault.add", "id": "s1", "aid": "a1", "label": "X", "value": "v", "sealed": "s" },
57 { "type": "vault.add", "id": "s1", "aid": "a1", "label": "X" },
58 { "type": "vault.add", "id": "s1", "aid": "a1", "label": "X", "sealed": "" },
59 { "type": "vault.change", "id": "ghost", "aid": "a2", "value": "v" },
60 { "type": "vault.remove", "id": "ghost", "aid": "a3", "uid": "u1", "name": "Paul", "ts": 500 }
61 ],
62 "expected_state": {
63 "items": [],
64 "log": [
65 { "id": "a3", "ref": "ghost", "action": "remove", "name": "", "by": "u1", "byName": "Paul", "at": 500 }
66 ],
67 "keyring": null
68 }
69 },
70 {
71 "name": "lock seals covered items, keeps uncovered plaintext, hands the key to members, installs the keyring",
72 "note": "vault.lock carries the locker's own durable wrap PLUS a `member` handoff per other member (the vault key sealed to their roster key). Both fold into the keyring; the handoff is dropped once that member self-enrols.",
73 "event_sequence": [
74 { "type": "vault.add", "id": "s1", "aid": "a1", "label": "WiFi", "value": "hunter2", "uid": "u1", "name": "Paul", "ts": 1000 },
75 { "type": "vault.add", "id": "s2", "aid": "a2", "label": "Door", "value": "0000", "uid": "u1", "name": "Paul", "ts": 2000 },
76 { "type": "vault.lock", "aid": "a3", "pub": "vault-pub", "wrap": { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }, "handoffs": [{ "id": "h2", "kind": "member", "uid": "u2", "label": "James", "wrapped": "handoff-james" }], "sealed": { "s1": "sealed-s1" }, "uid": "u1", "name": "Paul", "ts": 3000 }
77 ],
78 "expected_state": {
79 "items": [
80 { "id": "s1", "name": "WiFi", "value": "", "sealed": "sealed-s1", "kind": "text", "by": "u1", "byName": "Paul", "at": 1000, "updatedBy": "", "updatedByName": "", "updatedAt": 0 },
81 { "id": "s2", "name": "Door", "value": "0000", "sealed": "", "kind": "text", "by": "u1", "byName": "Paul", "at": 2000, "updatedBy": "", "updatedByName": "", "updatedAt": 0 }
82 ],
83 "log": [
84 { "id": "a1", "ref": "s1", "action": "add", "name": "WiFi", "by": "u1", "byName": "Paul", "at": 1000 },
85 { "id": "a2", "ref": "s2", "action": "add", "name": "Door", "by": "u1", "byName": "Paul", "at": 2000 },
86 { "id": "a3", "ref": "", "action": "lock", "name": "", "by": "u1", "byName": "Paul", "at": 3000 }
87 ],
88 "keyring": {
89 "v": 1,
90 "pub": "vault-pub",
91 "wraps": [
92 { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" },
93 { "id": "h2", "kind": "member", "uid": "u2", "label": "James", "credId": "", "wrapped": "handoff-james" }
94 ]
95 }
96 }
97 },
98 {
99 "name": "lock is one-way; malformed locks fold to no-ops; junk wrap fields and non-member handoffs are dropped",
100 "note": "a handoff must be a well-formed `member` wrap β€” a passkey-kind entry in `handoffs` is dropped, and spare wrap fields never fold in.",
101 "event_sequence": [
102 { "type": "vault.lock", "aid": "b1", "pub": "", "wrap": { "id": "w0", "kind": "passkey", "wrapped": "x" } },
103 { "type": "vault.lock", "aid": "b2", "pub": "p", "wrap": { "id": "w0", "kind": "usb-fob", "wrapped": "x" } },
104 { "type": "vault.lock", "aid": "b3", "pub": "p", "wrap": { "id": "w0", "kind": "passkey", "wrapped": "" } },
105 { "type": "vault.lock", "aid": "a1", "pub": "first-pub", "wrap": { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1", "evil": "extra" }, "handoffs": [{ "id": "hbad", "kind": "passkey", "uid": "u2", "wrapped": "x" }, { "id": "h2", "kind": "member", "uid": "u2", "label": "James", "wrapped": "handoff-james" }], "sealed": {}, "uid": "u1", "name": "Paul", "ts": 1000 },
106 { "type": "vault.lock", "aid": "a2", "pub": "second-pub", "wrap": { "id": "w2", "kind": "passkey", "label": "Mallory", "credId": "cred-2", "wrapped": "wrap-2" }, "sealed": {}, "uid": "u9", "name": "Mallory", "ts": 2000 }
107 ],
108 "expected_state": {
109 "items": [],
110 "log": [
111 { "id": "a1", "ref": "", "action": "lock", "name": "", "by": "u1", "byName": "Paul", "at": 1000 }
112 ],
113 "keyring": {
114 "v": 1,
115 "pub": "first-pub",
116 "wraps": [
117 { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" },
118 { "id": "h2", "kind": "member", "uid": "u2", "label": "James", "credId": "", "wrapped": "handoff-james" }
119 ]
120 }
121 }
122 },
123 {
124 "name": "membership: a member self-enrols from their handoff (dropping it), an insider gives a newcomer access, they self-enrol too",
125 "note": "the whole no-request flow β€” lock hands James a key, James turns it into a durable keychain wrap (his `member` handoff drops), Paul gives Carol (who joined later) a handoff, Carol self-enrols a passkey (her handoff drops). enroll drops the enroller's `member` handoff by uid.",
126 "event_sequence": [
127 { "type": "vault.lock", "aid": "a1", "pub": "vault-pub", "wrap": { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }, "handoffs": [{ "id": "h2", "kind": "member", "uid": "u2", "label": "James", "wrapped": "handoff-james" }], "sealed": {}, "uid": "u1", "name": "Paul", "ts": 1000 },
128 { "type": "vault.enroll", "aid": "a2", "wrap": { "id": "w2", "kind": "keychain", "uid": "u2", "label": "James β€” CLI", "wrapped": "wrap-2" }, "uid": "u2", "name": "James", "ts": 2000 },
129 { "type": "vault.give", "aid": "a3", "wrap": { "id": "h3", "kind": "member", "uid": "u3", "label": "Carol", "wrapped": "handoff-carol" }, "uid": "u1", "name": "Paul", "ts": 3000 },
130 { "type": "vault.enroll", "aid": "a4", "wrap": { "id": "w3", "kind": "passkey", "uid": "u3", "label": "Carol", "credId": "cred-3", "wrapped": "wrap-3" }, "uid": "u3", "name": "Carol", "ts": 4000 }
131 ],
132 "expected_state": {
133 "items": [],
134 "log": [
135 { "id": "a1", "ref": "", "action": "lock", "name": "", "by": "u1", "byName": "Paul", "at": 1000 },
136 { "id": "a2", "ref": "", "action": "enroll", "name": "James β€” CLI", "by": "u2", "byName": "James", "at": 2000 },
137 { "id": "a3", "ref": "", "action": "give", "name": "Carol", "by": "u1", "byName": "Paul", "at": 3000 },
138 { "id": "a4", "ref": "", "action": "enroll", "name": "Carol", "by": "u3", "byName": "Carol", "at": 4000 }
139 ],
140 "keyring": {
141 "v": 1,
142 "pub": "vault-pub",
143 "wraps": [
144 { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" },
145 { "id": "w2", "kind": "keychain", "uid": "u2", "label": "James β€” CLI", "credId": "", "wrapped": "wrap-2" },
146 { "id": "w3", "kind": "passkey", "uid": "u3", "label": "Carol", "credId": "cred-3", "wrapped": "wrap-3" }
147 ]
148 }
149 }
150 },
151 {
152 "name": "enroll drops only the enroller's own handoff, never another member's",
153 "note": "lock hands James (u2) and Carol (u3) a key each; James enrolling drops h2 only β€” Carol's h3 stays until she enrols.",
154 "event_sequence": [
155 { "type": "vault.lock", "aid": "a1", "pub": "vault-pub", "wrap": { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }, "handoffs": [{ "id": "h2", "kind": "member", "uid": "u2", "label": "James", "wrapped": "hj" }, { "id": "h3", "kind": "member", "uid": "u3", "label": "Carol", "wrapped": "hc" }], "sealed": {}, "uid": "u1", "name": "Paul", "ts": 1000 },
156 { "type": "vault.enroll", "aid": "a2", "wrap": { "id": "w2", "kind": "passkey", "uid": "u2", "label": "James", "credId": "cred-2", "wrapped": "wrap-2" }, "uid": "u2", "name": "James", "ts": 2000 }
157 ],
158 "expected_state": {
159 "items": [],
160 "log": [
161 { "id": "a1", "ref": "", "action": "lock", "name": "", "by": "u1", "byName": "Paul", "at": 1000 },
162 { "id": "a2", "ref": "", "action": "enroll", "name": "James", "by": "u2", "byName": "James", "at": 2000 }
163 ],
164 "keyring": {
165 "v": 1,
166 "pub": "vault-pub",
167 "wraps": [
168 { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" },
169 { "id": "h3", "kind": "member", "uid": "u3", "label": "Carol", "credId": "", "wrapped": "hc" },
170 { "id": "w2", "kind": "passkey", "uid": "u2", "label": "James", "credId": "cred-2", "wrapped": "wrap-2" }
171 ]
172 }
173 }
174 },
175 {
176 "name": "revoke drops a wrap but never the last one",
177 "event_sequence": [
178 { "type": "vault.lock", "aid": "a1", "pub": "vault-pub", "wrap": { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }, "sealed": {}, "uid": "u1", "name": "Paul", "ts": 1000 },
179 { "type": "vault.revoke", "aid": "a2", "wrapId": "w1", "uid": "u1", "name": "Paul", "ts": 2000 },
180 { "type": "vault.enroll", "aid": "a3", "wrap": { "id": "w2", "kind": "keychain", "uid": "u1", "label": "Paul β€” CLI", "wrapped": "wrap-2" }, "uid": "u1", "name": "Paul", "ts": 3000 },
181 { "type": "vault.revoke", "aid": "a4", "wrapId": "w1", "uid": "u1", "name": "Paul", "ts": 4000 }
182 ],
183 "expected_state": {
184 "items": [],
185 "log": [
186 { "id": "a1", "ref": "", "action": "lock", "name": "", "by": "u1", "byName": "Paul", "at": 1000 },
187 { "id": "a3", "ref": "", "action": "enroll", "name": "Paul β€” CLI", "by": "u1", "byName": "Paul", "at": 3000 },
188 { "id": "a4", "ref": "", "action": "revoke", "name": "Paul", "by": "u1", "byName": "Paul", "at": 4000 }
189 ],
190 "keyring": {
191 "v": 1,
192 "pub": "vault-pub",
193 "wraps": [{ "id": "w2", "kind": "keychain", "uid": "u1", "label": "Paul β€” CLI", "credId": "", "wrapped": "wrap-2" }]
194 }
195 }
196 },
197 {
198 "name": "a legacy recovery wrap folds to a no-op",
199 "note": "the passphrase-derived kind:recovery break-glass (#995) was removed 2026-07-25 β€” recovery is a passkey, never a passphrase. wrapShape rejects the kind, so a historical (or hostile) recovery enroll leaves the keyring untouched.",
200 "event_sequence": [
201 { "type": "vault.lock", "aid": "a1", "pub": "vault-pub", "wrap": { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }, "sealed": {}, "uid": "u1", "name": "Paul", "ts": 1000 },
202 { "type": "vault.enroll", "aid": "a2", "wrap": { "id": "rec", "kind": "recovery", "label": "Recovery key (1Password)", "wrapped": "recov-blob" }, "uid": "u1", "name": "Paul", "ts": 2000 }
203 ],
204 "expected_state": {
205 "items": [],
206 "log": [
207 { "id": "a1", "ref": "", "action": "lock", "name": "", "by": "u1", "byName": "Paul", "at": 1000 }
208 ],
209 "keyring": {
210 "v": 1,
211 "pub": "vault-pub",
212 "wraps": [{ "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }]
213 }
214 }
215 },
216 {
217 "name": "junk gives/enrolls fold to no-ops on a locked vault",
218 "note": "a give must be a well-formed `member` wrap WITH a uid; an enroll wrap must be durable (never `member`); malformed wraps are rejected by wrapShape.",
219 "event_sequence": [
220 { "type": "vault.lock", "aid": "a1", "pub": "vault-pub", "wrap": { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }, "sealed": {}, "uid": "u1", "name": "Paul", "ts": 1000 },
221 { "type": "vault.give", "aid": "b1", "wrap": { "id": "g1", "kind": "member", "wrapped": "x" } },
222 { "type": "vault.give", "aid": "b2", "wrap": { "id": "g2", "kind": "passkey", "uid": "u2", "wrapped": "x" } },
223 { "type": "vault.give", "aid": "b3", "wrap": { "id": "", "kind": "member", "uid": "u2", "wrapped": "x" } },
224 { "type": "vault.enroll", "aid": "b4", "wrap": { "id": "", "kind": "passkey", "wrapped": "x" } },
225 { "type": "vault.enroll", "aid": "b5", "wrap": { "id": "w9", "kind": "member", "uid": "u2", "wrapped": "x" } }
226 ],
227 "expected_state": {
228 "items": [],
229 "log": [
230 { "id": "a1", "ref": "", "action": "lock", "name": "", "by": "u1", "byName": "Paul", "at": 1000 }
231 ],
232 "keyring": {
233 "v": 1,
234 "pub": "vault-pub",
235 "wraps": [{ "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }]
236 }
237 }
238 },
239 {
240 "name": "keyring events before any lock fold to no-ops",
241 "event_sequence": [
242 { "type": "vault.enroll", "aid": "a1", "wrap": { "id": "w1", "kind": "passkey", "wrapped": "x" } },
243 { "type": "vault.give", "aid": "a2", "wrap": { "id": "g1", "kind": "member", "uid": "u2", "wrapped": "x" } },
244 { "type": "vault.revoke", "aid": "a3", "wrapId": "w1" }
245 ],
246 "expected_state": { "items": [], "log": [], "keyring": null }
247 },
248 {
249 "name": "sealed add on a locked vault; a change carrying sealed replaces stale plaintext",
250 "event_sequence": [
251 { "type": "vault.add", "id": "s1", "aid": "a1", "label": "WiFi", "value": "hunter2", "uid": "u1", "name": "Paul", "ts": 1000 },
252 { "type": "vault.lock", "aid": "a2", "pub": "vault-pub", "wrap": { "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }, "sealed": {}, "uid": "u1", "name": "Paul", "ts": 2000 },
253 { "type": "vault.add", "id": "s2", "aid": "a3", "label": "Token", "sealed": "sealed-s2", "uid": "u2", "name": "James", "ts": 3000 },
254 { "type": "vault.change", "id": "s1", "aid": "a4", "sealed": "sealed-s1-now", "uid": "u2", "name": "James", "ts": 4000 }
255 ],
256 "expected_state": {
257 "items": [
258 { "id": "s1", "name": "WiFi", "value": "", "sealed": "sealed-s1-now", "kind": "text", "by": "u1", "byName": "Paul", "at": 1000, "updatedBy": "u2", "updatedByName": "James", "updatedAt": 4000 },
259 { "id": "s2", "name": "Token", "value": "", "sealed": "sealed-s2", "kind": "text", "by": "u2", "byName": "James", "at": 3000, "updatedBy": "", "updatedByName": "", "updatedAt": 0 }
260 ],
261 "log": [
262 { "id": "a1", "ref": "s1", "action": "add", "name": "WiFi", "by": "u1", "byName": "Paul", "at": 1000 },
263 { "id": "a2", "ref": "", "action": "lock", "name": "", "by": "u1", "byName": "Paul", "at": 2000 },
264 { "id": "a3", "ref": "s2", "action": "add", "name": "Token", "by": "u2", "byName": "James", "at": 3000 },
265 { "id": "a4", "ref": "s1", "action": "change", "name": "WiFi", "by": "u2", "byName": "James", "at": 4000 }
266 ],
267 "keyring": {
268 "v": 1,
269 "pub": "vault-pub",
270 "wraps": [{ "id": "w1", "kind": "passkey", "uid": "u1", "label": "Paul", "credId": "cred-1", "wrapped": "wrap-1" }]
271 }
272 }
273 }
274 ]
275}
276