@coffre/core 0.14.7 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +1 -1
  2. package/dist/{access-BrdZKp1d.js → access-CF8UG59J.js} +70 -8
  3. package/dist/{access-qkMZa-6Z.d.ts → access-ERdGGHG7.d.ts} +45 -3
  4. package/dist/access.d.ts +2 -2
  5. package/dist/access.js +2 -2
  6. package/dist/envelope.d.ts +28 -9
  7. package/dist/envelope.js +25 -8
  8. package/dist/identity.d.ts +2 -917
  9. package/dist/identity.js +1036 -525
  10. package/dist/index-DuG9p3GH.d.ts +1233 -0
  11. package/dist/kek.d.ts +10 -16
  12. package/dist/kek.js +26 -41
  13. package/dist/log.d.ts +114 -0
  14. package/dist/log.js +291 -0
  15. package/dist/mcp.d.ts +25 -1
  16. package/dist/mcp.js +29 -4
  17. package/dist/recipe-BgJpmJum.d.ts +128 -0
  18. package/dist/recipe.d.ts +2 -127
  19. package/dist/{registry-D7X-x202.d.ts → registry-B7_LUDsJ.d.ts} +30 -5
  20. package/dist/schemas.d.ts +14 -4
  21. package/dist/schemas.js +16 -4
  22. package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
  23. package/dist/vault.d.ts +1800 -299
  24. package/dist/vault.js +99 -32
  25. package/package.json +8 -3
  26. package/src/access.ts +63 -8
  27. package/src/changes/access.ts +140 -0
  28. package/src/changes/freezes.ts +40 -0
  29. package/src/changes/mcp.ts +150 -0
  30. package/src/changes/places.ts +219 -0
  31. package/src/changes/secrets.ts +235 -0
  32. package/src/changes/signin.ts +197 -0
  33. package/src/changes/workloads.ts +166 -0
  34. package/src/context.ts +18 -2
  35. package/src/envelope.ts +35 -12
  36. package/src/identity/auth.ts +11 -3
  37. package/src/identity/aws.ts +62 -0
  38. package/src/identity/github-app.ts +45 -24
  39. package/src/identity/index.ts +3 -0
  40. package/src/identity/profiles.ts +139 -0
  41. package/src/identity/proofs.ts +306 -0
  42. package/src/identity/signin/config.ts +1 -1
  43. package/src/identity/tokens.ts +10 -3
  44. package/src/identity/verifier.ts +73 -14
  45. package/src/identity/workload-token.ts +4 -0
  46. package/src/kek/aws-kms.ts +18 -13
  47. package/src/kek/check.ts +16 -46
  48. package/src/kek/index.ts +2 -2
  49. package/src/kek/types.ts +15 -3
  50. package/src/log/index.ts +7 -0
  51. package/src/log/tiles.ts +166 -0
  52. package/src/log/tree.ts +163 -0
  53. package/src/mcp.ts +34 -3
  54. package/src/schemas.ts +16 -2
  55. package/src/vault.ts +308 -276
  56. package/src/checkpoint.ts +0 -22
package/dist/vault.d.ts CHANGED
@@ -1,4 +1,1491 @@
1
- import { A as RoleDefinition, P as ServiceSetting, T as Policy, _ as InstanceRole, f as GrantPlace, i as CredentialScope, j as Scope, k as Role, n as CallerKind } from "./access-qkMZa-6Z.js";
1
+ import { A as RoleDefinition, P as ServiceSetting, T as Policy, _ as InstanceRole, d as Filter, f as GrantPlace, i as CredentialScope, j as Scope, k as Role, m as Holdings, n as CallerKind } from "./access-ERdGGHG7.js";
2
+ import { Z as VerifiedUnder, z as CallerIdentity } from "./index-DuG9p3GH.js";
3
+ import { a as BindingPolicy, rt as Constraints } from "./workloads-CW2dK4AW.js";
4
+ import { McpScope } from "./mcp.js";
5
+ import { l as Generation } from "./recipe-BgJpmJum.js";
6
+ //#region src/changes/access.d.ts
7
+ /**
8
+ * The changes of members, grants, roles and the instance's policy
9
+ * (`packages/vault/src/ops/access.ts`). A workload's session makes none of
10
+ * them, whatever its scope holds (`workload_cannot_issue`), as 0.14 refused.
11
+ */
12
+ type AccessChanges = MemberPut | MemberRemove | AccessGrant | RoleEdit | SettingsEdit;
13
+ type AccessAnswers = {
14
+ /** The role and scope they hold now, the scope's projects by id as the row holds them (null is everywhere), and whether they were admitted or brought back. */
15
+ 'member.put': Standing & {
16
+ created: boolean;
17
+ };
18
+ /**
19
+ * How many grants went with them (`revoked`), and how many ways in the
20
+ * removal ended, as they stood when it was made: sign-in accounts it
21
+ * revoked, and, of their generation, live sessions (browser and CLI),
22
+ * tokens (every other credential but an MCP connection's) and connected
23
+ * apps (an MCP connection its client redeemed), which the generation's
24
+ * move ends; and whether the caller runs the instance (`runs`), as the
25
+ * change found them: the leaver's report is theirs to read.
26
+ */
27
+ 'member.remove': {
28
+ revoked: number;
29
+ sessions: number;
30
+ tokens: number;
31
+ identities: number;
32
+ apps: number;
33
+ runs: boolean;
34
+ };
35
+ /** What became of each place, in the order asked; with `admit`, whether this change admitted the service account. */
36
+ 'access.grant': {
37
+ changes: AccessChange[];
38
+ created?: boolean;
39
+ };
40
+ /** The role as it is now: null once deleted. */
41
+ 'policy.change': {
42
+ role: RoleDefinition | null;
43
+ };
44
+ /** The setting as the row holds it, projects by id. */
45
+ 'settings.change': {
46
+ serviceAccounts: Scope;
47
+ };
48
+ };
49
+ type Standing = {
50
+ role: InstanceRole;
51
+ scope: Scope | null;
52
+ };
53
+ /**
54
+ * Where a person's instance role applies, as the app names it: projects by
55
+ * slug, which the vault keeps by id, so a rename keeps them; environments by
56
+ * slug, those of every project. Each list holds 1,000 slugs at most. Null is
57
+ * everywhere.
58
+ */
59
+ type ScopeInput = {
60
+ projects: Filter;
61
+ environments: Filter;
62
+ };
63
+ /**
64
+ * A member admitted, brought back or given an instance role
65
+ * (`member.put`), whichever their row calls for, as 0.14.7's `admit` did:
66
+ * the app cannot know which without reading the row, and only the vault's
67
+ * read can. Its entry is the action that happened:
68
+ *
69
+ * no row `member.add`, as `role`, or `member` when null
70
+ * removed `member.restore`, the same, in the generation their removal moved on to, with no grant
71
+ * active `member.role`, `unchanged` when nothing moves; a null role keeps their role and scope
72
+ *
73
+ * Whoever runs the instance puts a member; only an Owner of the whole
74
+ * instance makes an Owner, changes one, or changes their own role; the last
75
+ * Owner of the whole instance stays one (`last_owner`), and one the
76
+ * deployment names comes in and stays as one (`configured_owner`). A
77
+ * service account holds no instance role but `member`: asked one, refused
78
+ * `invalid`. A person who does not run the instance, on a session, sets up
79
+ * a service account, as `member`, where they could give it something
80
+ * (`setsUpServices`), and brings back one they removed. A refused put is
81
+ * logged as `member.add`, as 0.14.7 logged it.
82
+ *
83
+ * A member, by principal: a person, `user:<email>` in lowercase, or a
84
+ * service account, `token:<name>`, 256 characters at most. `scope` is where
85
+ * the role applies, given only with a role but `member`, which holds
86
+ * nothing. Past these the call is a fault, not a refusal: the app checks
87
+ * them first.
88
+ */
89
+ type MemberPut = {
90
+ op: 'member.put';
91
+ principal: string;
92
+ role: InstanceRole | null;
93
+ scope: ScopeInput | null;
94
+ };
95
+ /**
96
+ * Remove a member: their grants go, their sign-in accounts are revoked, and
97
+ * their generation moves on, which ends every session, token and binding
98
+ * issued before. Whoever runs the instance removes a member; a person on a
99
+ * session, a service account they manage (`managesService`).
100
+ */
101
+ type MemberRemove = {
102
+ op: 'member.remove';
103
+ principal: string;
104
+ };
105
+ /**
106
+ * A person's roles at projects and environments, set, changed, given an end
107
+ * or taken away: all of the places or none, each once. A place is a
108
+ * project's slug, or one of its environments' too, which takes a role that
109
+ * holds nothing only a project has (`PROJECT_ONLY_PERMISSIONS`). A role is
110
+ * a project role's id, or null to revoke; `expiresAt` an ISO 8601 time
111
+ * after the change, or null for no end. Whoever manages access at each
112
+ * place (`grant.manage`) gives anything there but to themselves; they may
113
+ * give up their own. A grant is of the member's generation: one left from
114
+ * before a removal is replaced in place. Refused `no_access` where a place
115
+ * is not there or not theirs; to whoever manages every place asked,
116
+ * `not_a_member`, `removed`, and `invalid` for a role there is not, a
117
+ * project's on an environment or an end gone.
118
+ *
119
+ * A service account's grants, where the caller does not manage access: a
120
+ * person on a session gives it what they could give it (`givesService`),
121
+ * and takes away what it holds, if they manage it (`managesService`): they
122
+ * could give it all it holds. `admit` admits it in the same change when
123
+ * it is not a member, or brings it back, all or none, as 0.14.7's
124
+ * `setAccess` did: by someone who could set one up (`setsUpServices`), it
125
+ * holds nothing before and is theirs; one removed, only its remover or
126
+ * whoever runs the instance brings back. A row these weigh that the vault
127
+ * did not write refuses, `tampered`. 1 to 1,000 places; past the shapes
128
+ * above, or `admit` of a person, the call is a fault, not a refusal: the
129
+ * app checks them first. `was`, given, is the grant the member holds at
130
+ * the place as an approval page showed it, or null for none: a live grant
131
+ * of their generation, as the member list has it. One that differs when
132
+ * the vault writes refuses `stale`, and nothing is changed.
133
+ */
134
+ type AccessGrant = {
135
+ op: 'access.grant';
136
+ principal: string;
137
+ changes: {
138
+ project: string;
139
+ environment: string | null;
140
+ role: Role | null;
141
+ expiresAt: string | null;
142
+ was?: {
143
+ role: Role;
144
+ expiresAt: string | null;
145
+ } | null;
146
+ }[];
147
+ admit?: boolean;
148
+ };
149
+ /**
150
+ * A role defined, edited, put back or deleted (`policy.change`), by an
151
+ * Owner of the whole instance on a session, as 0.14 allowed: a project role
152
+ * (`instance` false), one that ships or one an Owner makes, or one of the
153
+ * instance's that ships (Admin, Auditor). Owner, and the instance's Member,
154
+ * are never edited. `definition` null puts a role that ships back as it
155
+ * ships, and deletes one an Owner made, refused `role_granted` while a
156
+ * grant names it, as is defining one that does not ship and is not there.
157
+ * A project role that holds what only a project has
158
+ * (`PROJECT_ONLY_PERMISSIONS`) is refused `invalid` while a grant on an
159
+ * environment names it, as is deleting a role that is not there.
160
+ * `revision` is the role as its preview weighed it (`roleRevision`), none
161
+ * included: one that changed since is refused `policy_changed`, so that a
162
+ * change is made from the role its preview was. Left out, the change is
163
+ * made from the role as it is. An id is a role's as `ROLE_ID` has it; a
164
+ * definition one `definitionProblem` passes; a revision one
165
+ * `ROLE_REVISION` matches: past those the call is a fault, not a refusal:
166
+ * the app checks them first.
167
+ */
168
+ type RoleEdit = {
169
+ op: 'policy.change';
170
+ instance: boolean;
171
+ role: Role;
172
+ definition: RoleDefinition | null;
173
+ revision?: string;
174
+ };
175
+ /**
176
+ * Where people set up service accounts themselves (`settings.change`,
177
+ * `ServiceSetting`): projects and environments by slug, 1,000 a list at
178
+ * most. Whoever runs the instance sets it, as 0.14 allowed.
179
+ */
180
+ type SettingsEdit = {
181
+ op: 'settings.change';
182
+ serviceAccounts: ScopeInput;
183
+ };
184
+ //#endregion
185
+ //#region src/changes/freezes.d.ts
186
+ /**
187
+ * A workload's use stopped at its next request, and let go again
188
+ * (`packages/vault/src/ops/freezes.ts`, docs/design/workload-access.md,
189
+ * 8.2): a freeze is a field of the row it stops, and keeps the sessions,
190
+ * codes and bindings under it, so lifting it restores service with no new
191
+ * sign-in. An upstream credential's is its environment's
192
+ * (`upstream.freeze`, `upstream.thaw`).
193
+ */
194
+ type FreezeChanges = WorkloadFreeze | WorkloadUnfreeze;
195
+ type FreezeAnswers = {
196
+ /** The target in its one spelling, and since when it is frozen: a freeze already there is kept, with its time. */
197
+ 'workload.freeze': Frozen;
198
+ /** The target in its one spelling, and null: it is not frozen now. */
199
+ 'workload.unfreeze': Frozen;
200
+ };
201
+ type Frozen = {
202
+ target: string;
203
+ frozenAt: string | null;
204
+ };
205
+ /**
206
+ * What a freeze names, as `freezeTarget` spells it, and who freezes and
207
+ * lifts it:
208
+ *
209
+ * instance every workload's use an Owner of the whole instance, on a session
210
+ * token:<name> one service account's whoever manages it (`managesService`)
211
+ * binding:<uuid> one of its trust bindings the same
212
+ * session:<uuid> one workload's session the same
213
+ *
214
+ * Refused `no_access` where the target is not there (a service account
215
+ * removed, a binding revoked, a session ended or of another generation)
216
+ * or not theirs, one answer; `tampered` where a row the decision weighs
217
+ * was written behind the vault; `workload_cannot_issue` to a workload's
218
+ * session. A target in another spelling, or `credential:…`, is a fault:
219
+ * the app canonicalizes it first. `reason` is why, 1 to 400 characters,
220
+ * which the entry keeps.
221
+ */
222
+ type WorkloadFreeze = {
223
+ op: 'workload.freeze';
224
+ target: string;
225
+ reason: string;
226
+ };
227
+ /** A freeze lifted: by whoever may make it, as `WorkloadFreeze` says. */
228
+ type WorkloadUnfreeze = {
229
+ op: 'workload.unfreeze';
230
+ target: string;
231
+ };
232
+ //#endregion
233
+ //#region src/changes/mcp.d.ts
234
+ /**
235
+ * The changes of MCP connections and of the OAuth clients that make them
236
+ * (`packages/vault/src/ops/mcp.ts`, docs/design/0.16.md, "MCP
237
+ * connections"). A connection is a credential of kind `mcp` of the person
238
+ * who approved it: its row holds the code until the client redeems it, then
239
+ * the refresh token. Each access token is a credential of its own, of an
240
+ * hour, under it (`ancestors`): it stands while its connection does, so
241
+ * ending the connection ends them all, with no write of theirs.
242
+ */
243
+ type McpChanges = McpConnect | McpToken | McpRevoke | OauthRegister | McpAsk | McpDecide;
244
+ type McpAnswers = {
245
+ /** The connection, and when its code stops being good, ISO 8601. */
246
+ 'mcp.connect': {
247
+ connection: string;
248
+ expiresAt: string;
249
+ };
250
+ /**
251
+ * The tokens made: the access token's credential, its member, when it
252
+ * ends (ISO 8601), and the scopes it holds. Or, for a code or a refresh
253
+ * token presented again, the connection it ended (`ended`), which the
254
+ * app answers `invalid_grant`.
255
+ */
256
+ 'mcp.token': {
257
+ ended: false;
258
+ principal: string;
259
+ connection: string;
260
+ credential: string;
261
+ expiresAt: string;
262
+ scopes: McpScope[];
263
+ } | {
264
+ ended: true;
265
+ connection: string;
266
+ };
267
+ /** The connection ended. */
268
+ 'mcp.revoke': {
269
+ connection: string;
270
+ };
271
+ /** The client registered, and when, ISO 8601. */
272
+ 'oauth.register': {
273
+ client: string;
274
+ createdAt: string;
275
+ };
276
+ /** The approval opened, and when it expires, ISO 8601. */
277
+ 'mcp.ask': {
278
+ approval: string;
279
+ expiresAt: string;
280
+ };
281
+ /** The approval decided. */
282
+ 'mcp.decide': {
283
+ approval: string;
284
+ };
285
+ };
286
+ /**
287
+ * The changes nobody asks: a client redeems or gives back what it holds (a
288
+ * code with its PKCE verifier, a refresh token, an access token), and anyone
289
+ * may register a client.
290
+ */
291
+ type McpUnasked = 'mcp.token' | 'mcp.revoke' | 'oauth.register';
292
+ /**
293
+ * A client as the person approved it: its id (a metadata document's URL,
294
+ * or a registration's id), its name and host as the consent page showed
295
+ * them, how it is known (`cimd`, a document the app fetched; `dcr`, a
296
+ * registration, whose row the vault reads and holds the redirect and the
297
+ * name to), and the redirect the code goes to.
298
+ */
299
+ type McpClient = {
300
+ id: string;
301
+ name: string;
302
+ host: string | null;
303
+ registration: 'cimd' | 'dcr';
304
+ redirectUri: string;
305
+ };
306
+ /**
307
+ * A person, on a session of theirs, approves an MCP client
308
+ * (`POST /oauth/authorizations`): a connection, whose code the client
309
+ * redeems within a minute (`CODE_SECONDS`) with its PKCE verifier. The app
310
+ * draws the code and sends its SHA-256 (`code`), with the S256 challenge
311
+ * the client sent (`challenge`, RFC 7636) and the scopes the person ticked
312
+ * (`read` always among them).
313
+ *
314
+ * A token, a workload's session or an MCP connection is refused
315
+ * `no_access`: a personal token connecting one would make a connection
316
+ * with all its person holds. A person with `MAX_CONNECTIONS` connections
317
+ * that stand, codes waiting included, is refused `too_many_connections`.
318
+ * A registered client (`dcr`) is its row's: refused `unknown_client` for
319
+ * one not there, or revoked, and `wrong_redirect` for a redirect it did not
320
+ * register; its name is the row's, whatever the app says.
321
+ */
322
+ type McpConnect = {
323
+ op: 'mcp.connect';
324
+ client: McpClient;
325
+ scopes: McpScope[];
326
+ code: string;
327
+ challenge: string;
328
+ };
329
+ /**
330
+ * A client redeems what it holds for an access token and the next refresh
331
+ * token (`POST /api/oauth/token`). The app draws both and sends their
332
+ * SHA-256 (`tokens`). The access token lasts an hour
333
+ * (`ACCESS_TOKEN_MINUTES`), never past its connection.
334
+ *
335
+ * - `authorization_code`: the code's SHA-256, its PKCE verifier and the
336
+ * redirect it was sent to, within its minute. The connection then lasts
337
+ * `minutes` (365 days at most), and the person's earlier connections of
338
+ * the same client that it grants all of and more end (`supersedes` in
339
+ * @coffre/core/mcp).
340
+ * - `refresh_token`: the refresh token's SHA-256, and the scopes the client
341
+ * narrows the access token to, or null for all the connection holds.
342
+ *
343
+ * Refused, writing nothing: `unknown_grant` for a code or a refresh token
344
+ * that is not there, or whose connection ended; `expired`, a code past its
345
+ * minute or a connection past its end; `wrong_client`, `wrong_redirect`,
346
+ * `wrong_verifier`; `invalid_scope` for a refresh that widens; `deactivated`
347
+ * for a person removed since they connected it; `tampered` for a row
348
+ * written behind the vault; `adopting` before the vault adopted the
349
+ * database. A code or a refresh token presented after it was replaced is a
350
+ * copy someone else holds: the connection ends, in a change that is made
351
+ * (`ended: true`), since a refusal writes nothing.
352
+ */
353
+ type McpToken = {
354
+ op: 'mcp.token';
355
+ client: string;
356
+ tokens: {
357
+ access: string;
358
+ refresh: string;
359
+ };
360
+ } & ({
361
+ grant: 'authorization_code';
362
+ code: string;
363
+ verifier: string;
364
+ redirectUri: string;
365
+ minutes: number;
366
+ } | {
367
+ grant: 'refresh_token';
368
+ refresh: string;
369
+ scopes: McpScope[] | null;
370
+ });
371
+ /**
372
+ * A client gives back a token it holds (RFC 7009, `POST /api/oauth/revoke`):
373
+ * its refresh token or one of its access tokens, by its SHA-256 (`token`),
374
+ * and its `client_id` when it sent one (`client`). Its connection ends, and
375
+ * every access token under it, as a disconnect does. Nobody asks it but
376
+ * whoever holds the token.
377
+ *
378
+ * Refused, writing nothing, which the endpoint answers as a success, as
379
+ * RFC 7009 has it: `unknown_grant` for a token that is no connection's
380
+ * refresh token nor an access token that stands, whose connection ended
381
+ * already, or that is another client's; `tampered` for a row written
382
+ * behind the vault; `adopting` before the vault adopted the database.
383
+ */
384
+ type McpRevoke = {
385
+ op: 'mcp.revoke';
386
+ token: string;
387
+ client: string | null;
388
+ };
389
+ /**
390
+ * Anyone registers a client (RFC 7591, `POST /api/oauth/register`): a
391
+ * public one, its name as it claims it and the redirects the app kept
392
+ * (`registrationRedirects` in @coffre/core/mcp). The app's limiter counts
393
+ * who asks; the table holds `MAX_CLIENTS` rows at most, refused `full`
394
+ * past that, and the vault's upkeep deletes those no connection names a
395
+ * week after they were made. Its entry ages out.
396
+ */
397
+ type OauthRegister = {
398
+ op: 'oauth.register';
399
+ name: string;
400
+ redirectUris: string[];
401
+ };
402
+ /**
403
+ * An MCP client asks for a change, on its access token (`tools/call`): an
404
+ * approval, pending for `APPROVAL_SECONDS`, which its person decides on
405
+ * coffre's page. `arguments` is the tool's, as canonical JSON (keys
406
+ * sorted); the vault keeps them in the row, and the SHA-256 of
407
+ * `[tool, arguments]` beside them (`digest`), which the page sends back.
408
+ * The entry names the tool, the `place` it is about
409
+ * (`project/environment/KEY`, or less) and the digest, never the
410
+ * arguments: they are the client's text. Nothing changes until the person
411
+ * approves it, as theirs (`ForConnection`).
412
+ *
413
+ * Refused, writing nothing: `unauthenticated` for a token that is no MCP
414
+ * access token that stands; `full` for a connection with `MAX_PENDING`
415
+ * approvals waiting, which only their person's decision or their expiry
416
+ * frees; `pending` for one waiting already for the same call, which the
417
+ * app joins.
418
+ */
419
+ type McpAsk = {
420
+ op: 'mcp.ask';
421
+ tool: string;
422
+ arguments: string;
423
+ place: string | null;
424
+ };
425
+ /**
426
+ * A person, on their browser session, denies an approval, or approves one
427
+ * whose tool changes nothing (`MCP_SHOWS`): the page showed them the value
428
+ * first. `digest` is the one the page rendered. Every other approval is
429
+ * approved by its change (`ForConnection`). Refused `unknown_approval` for
430
+ * one that is not pending (decided, or expired by the time its write
431
+ * starts), not of this digest, or not theirs; `disconnected` for one whose
432
+ * connection no longer stands.
433
+ */
434
+ type McpDecide = {
435
+ op: 'mcp.decide';
436
+ approval: string;
437
+ approve: boolean;
438
+ digest: string;
439
+ };
440
+ //#endregion
441
+ //#region src/changes/places.d.ts
442
+ /** The changes of projects and environments (`packages/vault/src/ops/places.ts`). */
443
+ type PlacesChanges = ProjectCreate | EnvironmentCreate | ProjectEdit | EnvironmentEdit | FolderRefile | PlaceDelete;
444
+ /**
445
+ * An edit answers the place as it leaves it, `archivedAt` in ISO 8601;
446
+ * asked for what is so already, it changes nothing, and is logged all the
447
+ * same.
448
+ */
449
+ type ProjectEdited = {
450
+ id: string;
451
+ slug: string;
452
+ archivedAt: string | null;
453
+ folder: string | null;
454
+ };
455
+ type EnvironmentEdited = {
456
+ id: string;
457
+ slug: string;
458
+ archivedAt: string | null;
459
+ protected: boolean;
460
+ };
461
+ type PlacesAnswers = {
462
+ 'project.create': {
463
+ id: string;
464
+ };
465
+ /**
466
+ * Its slug is the one asked for, or, for a personal config, the one made
467
+ * for it, which only a list for deletion shows. A personal config is
468
+ * `protected` as the environment it is a config of is.
469
+ */
470
+ 'environment.create': {
471
+ id: string;
472
+ slug: string;
473
+ protected: boolean;
474
+ forked?: Forked;
475
+ };
476
+ /** The projects it filed, by slug. */
477
+ 'folder.refile': {
478
+ moved: string[];
479
+ };
480
+ 'project.delete': PlaceDeleted;
481
+ 'environment.delete': PlaceDeleted;
482
+ } & { [K in ProjectEdit['op']]: ProjectEdited; } & { [K in EnvironmentEdit['op']]: EnvironmentEdited; };
483
+ /**
484
+ * Make a project, as an Admin or Owner of the instance whose scope takes in
485
+ * new projects, on a session's credential. Its slug is free: no project has
486
+ * it, archived ones included. A slug is 1 to 63 of `a-z`, `0-9` and `-`,
487
+ * starting with a letter or digit; past that the call is a fault, not a
488
+ * refusal: the app checks it first.
489
+ */
490
+ type ProjectCreate = {
491
+ op: 'project.create';
492
+ project: string;
493
+ };
494
+ /**
495
+ * Make an environment in a live project, as one who manages its
496
+ * environments (`environment.manage`): its slug free in the project,
497
+ * shaped as a project's and none of a project's pages (`PROJECT_PAGES`).
498
+ * With `parent`, a fork that inherits from that environment, live, never
499
+ * a personal config, which the caller reads, and which inherits from two
500
+ * at most, so that the fork inherits from three; with `copy`, a fork that
501
+ * copies one (`EnvironmentCopy`). A fork of a protected environment is
502
+ * protected, whatever `protected` says.
503
+ *
504
+ * With `mine`, the caller's personal config of `environment` instead: a
505
+ * person's, who reads or uses it, live, never a personal config itself,
506
+ * with two parents at most. One per person per environment. Its slug is
507
+ * made here, and it is protected as its environment is, through it.
508
+ */
509
+ type EnvironmentCreate = {
510
+ op: 'environment.create';
511
+ project: string;
512
+ environment: string;
513
+ } & ({
514
+ mine: false;
515
+ parent: string | null;
516
+ protected: boolean;
517
+ copy?: EnvironmentCopy;
518
+ } | {
519
+ mine: true;
520
+ });
521
+ /**
522
+ * A fork that copies (docs/design/forking.md, "Forks"): with `copy`, the
523
+ * new environment inherits from nothing (`parent` null) and holds, made in
524
+ * the same change, each key `from` reads now, as a use of it finds them:
525
+ * its own and those it inherits, each from the nearest environment that
526
+ * holds it or dismissed it, with the folder it is filed in there, and none
527
+ * of its history. A key with no value, a reference broken, is left out.
528
+ * Who forks manages the project's environments and reads `from`, and each
529
+ * environment above it a key comes from (`parent_unreadable`); `from` is a
530
+ * live environment of the project, no personal config, whose chain stands
531
+ * (`broken_chain`).
532
+ *
533
+ * Each key is a copy of its value by default: the vault opens the version
534
+ * and seals it again as the new key's first version, and nobody else holds
535
+ * it. It is kept as it was, plain, a secret or sensitive, and its first
536
+ * date is its source's; it has no recipe and is in no pair, as one typed.
537
+ * With `references`, each key is a reference instead, one hop, to where its
538
+ * value is held: the parent's key, a key it inherits, or a reference's
539
+ * source. That is a reference made, as `secret.write` makes one: its
540
+ * forker reads the source where it is held, by their own grants, and uses
541
+ * it there too if it is sensitive. A key whose source they do not is
542
+ * copied, and named in `copied`. A sensitive value reached through a
543
+ * reference is never copied, whatever is asked: a copy would hold it under
544
+ * this project, which another project's value is not. It stays a reference
545
+ * to its source, which its forker must be able to make, or the fork is
546
+ * refused, `no_access`. A workload copies or refers to no value it only
547
+ * uses where it is held (`use_only`).
548
+ *
549
+ * One change opens and seals again 2,000 values at most (`too_many_keys`),
550
+ * and 8 MiB of them as stored (`too_much_to_copy`, the vault's
551
+ * `MOST_COPIED`, which a mark shares): past either, nothing is made, and
552
+ * the fork is made by references or inherits instead. Either is weighed
553
+ * before any value is read: one that copies by default, by every value it
554
+ * copies; one by references, by every value it may copy (each sensitive
555
+ * value its chain holds, and each a reference reads that is not), so past
556
+ * the bound it is refused even where the forker uses most of them, and is
557
+ * made inheriting instead (docs/design/0.16.md, the paragraph on
558
+ * `MOST_COPIED`).
559
+ */
560
+ type EnvironmentCopy = {
561
+ from: string;
562
+ references: boolean;
563
+ };
564
+ /** What a fork that copies made: how many keys, how many of them references, and those copied where references were asked for. */
565
+ type Forked = {
566
+ keys: number;
567
+ references: number;
568
+ copied: string[];
569
+ };
570
+ /**
571
+ * A project edited, archived or not, by whoever manages it
572
+ * (`project.manage`), on a project there or archived: a deleted one's
573
+ * tombstone is no project.
574
+ *
575
+ * - `project.update`: its slug, to one free as a new project's is.
576
+ * - `project.archive`: refused, `referenced`, while a reference held
577
+ * outside it reads a value in it (D41): archiving would stop that read.
578
+ * - `project.restore`.
579
+ * - `project.move`: filed in a folder, 1 to 64 characters with no `/`, no
580
+ * control character and no space at either end, or in none.
581
+ */
582
+ type ProjectEdit = {
583
+ project: string;
584
+ } & ({
585
+ op: 'project.update';
586
+ slug: string;
587
+ } | {
588
+ op: 'project.archive';
589
+ } | {
590
+ op: 'project.restore';
591
+ } | {
592
+ op: 'project.move';
593
+ folder: string | null;
594
+ });
595
+ /**
596
+ * An environment edited, there or archived, by whoever manages its
597
+ * project's environments (`environment.manage`), unless said otherwise. A
598
+ * personal config is edited by none of these: it is archived and restored
599
+ * with its environment, and protected through it.
600
+ *
601
+ * - `environment.update`: its slug, to one free in the project and none of
602
+ * a project's pages. Scopes name environments by slug, so this moves who
603
+ * an instance role reaches there.
604
+ * - `environment.archive`, with its personal configs: refused while a live
605
+ * fork inherits from it (`inherited`), or a reference held outside it
606
+ * reads a value in it (`referenced`).
607
+ * - `environment.restore`, with its personal configs: refused while an
608
+ * environment it inherits from is archived or deleted (`parent_archived`),
609
+ * or one is not there to say (`broken_chain`).
610
+ * - `environment.protect`: each role holds there what its protected column
611
+ * says, for people (docs/design/roles.md). Never by a workload's session
612
+ * (`workload_cannot_issue`), which changes no one's access.
613
+ * - `environment.unprotect`: as protecting, and by an Owner of its project
614
+ * alone, by a grant on it or an instance role whose scope takes in all
615
+ * of it, on no credential's scope (`ownsProject`, R30).
616
+ * - `upstream.freeze`: the deployment's upstream credential of that name,
617
+ * `stripe`, used by nobody in this live environment, by whoever writes
618
+ * there (`secret.write`); `upstream.thaw` lifts it, by an Owner of the
619
+ * project (docs/design/workload-access.md, section 8.2).
620
+ */
621
+ type EnvironmentEdit = {
622
+ project: string;
623
+ environment: string;
624
+ } & ({
625
+ op: 'environment.update';
626
+ slug: string;
627
+ } | {
628
+ op: 'environment.archive';
629
+ } | {
630
+ op: 'environment.restore';
631
+ } | {
632
+ op: 'environment.protect';
633
+ } | {
634
+ op: 'environment.unprotect';
635
+ } | {
636
+ op: 'upstream.freeze';
637
+ upstream: string;
638
+ } | {
639
+ op: 'upstream.thaw';
640
+ upstream: string;
641
+ });
642
+ /**
643
+ * A folder of projects renamed, `to` a name shaped as `project.move`
644
+ * takes one, or emptied, `to` null: every project filed there, archived
645
+ * ones included, in one change, by whoever manages each of them
646
+ * (`project.manage`). A folder is a label, so renaming onto one that is
647
+ * there merges the two. A folder none of whose projects the caller may
648
+ * file is no folder of theirs: refused as one with no project.
649
+ */
650
+ type FolderRefile = {
651
+ op: 'folder.refile';
652
+ folder: string;
653
+ to: string | null;
654
+ };
655
+ /**
656
+ * A place deleted for good, as 0.14.7 deleted one (`deletePlace`), in one
657
+ * change: every version under it erased, its ciphertext and wrapped data
658
+ * key emptied, and a plain one's copy cleared; every grant on it revoked;
659
+ * every reference into it or out of it ended, its holder reading nothing
660
+ * since (a reference holds no value of its own); and its slug made a
661
+ * tombstone, `market~deleted-2026-10-05` (`tombstoneOf`), which frees the
662
+ * slug and is never mistaken for what takes it next. Its rows stay, names
663
+ * and dates only, because the log names them. A copy made of one of its
664
+ * values elsewhere, a fork's, is a value of its own and stays. Weighed
665
+ * (`weigh`), it says what it would take, and changes nothing.
666
+ *
667
+ * - `project.delete`: an archived project, with every environment and
668
+ * personal config in it.
669
+ * - `environment.delete`: an archived environment itself, whatever its
670
+ * project is, with its personal configs; refused, `inherited`, while a
671
+ * fork inherits from it, archived or not: deleted, it would leave the
672
+ * fork naming a tombstone.
673
+ *
674
+ * Both by an Admin or Owner of the whole instance, on no credential's
675
+ * scope (`runsInstance`); a place there but live is `not_archived`. A
676
+ * personal config is deleted by its owner, or by whoever manages its
677
+ * project's environments (`environment.manage`), archived or not, never
678
+ * on a personal token (deleting for good stays with people):
679
+ * `environment` names it by its own slug, which only a list for deletion
680
+ * shows, or, with `mine`, the environment it is the caller's config of.
681
+ * A place that holds more versions with a value than one change erases
682
+ * (`MOST_ERASED` in the vault) is refused, `too_large`, and nothing is
683
+ * erased: its environments are deleted one at a time first.
684
+ */
685
+ type PlaceDelete = {
686
+ op: 'project.delete';
687
+ project: string;
688
+ } | {
689
+ op: 'environment.delete';
690
+ project: string;
691
+ environment: string;
692
+ mine: boolean;
693
+ };
694
+ /** What deleting a place takes, or took. */
695
+ type PlaceDeleted = {
696
+ /** `market`, `market/prod`, or a personal config's `market/dev@ada@acme.example`. */
697
+ path: string;
698
+ /** The slug its tombstone keeps: `market~deleted-2026-10-05`. */
699
+ tombstone: string;
700
+ /** The environments it takes, personal configs too, these by their environment and owner (`dev@ada@acme.example`): a project's every one, or the one with its configs. */
701
+ environments: string[];
702
+ /** The keys named there, which the tombstone keeps, never their values. */
703
+ keys: number;
704
+ /** The versions whose values it erases. */
705
+ versions: number;
706
+ /** The grants on it, lapsed ones too, which it revokes. */
707
+ grants: {
708
+ member: string;
709
+ place: string;
710
+ role: string;
711
+ }[];
712
+ /** The references into it and out of it, which it ends: each holder, and the source it read (`(gone)` for one not found). */
713
+ references: {
714
+ holder: string;
715
+ source: string;
716
+ }[];
717
+ /** Members who hold nothing anywhere afterwards, with no instance role: a service among them may be offboarded. */
718
+ stranded: string[];
719
+ };
720
+ //#endregion
721
+ //#region src/changes/secrets.d.ts
722
+ /** The changes of keys and their values (`packages/vault/src/ops/secrets.ts`). */
723
+ type SecretsChanges = SecretWrite | SecretRename | SecretRefile | ReferenceBreak | MissingDismiss;
724
+ type SecretsAnswers = {
725
+ /**
726
+ * Each key given a value, written or restored: the version it is at now, and the nature it was written as. A key made a
727
+ * reference is given none. And what the write does to each key asked (`outcomes`), which a dry run tells (`weigh`).
728
+ */
729
+ 'secret.write': {
730
+ keys: Record<string, {
731
+ version: number;
732
+ nature: Nature;
733
+ }>;
734
+ outcomes: Record<string, KeyOutcome>;
735
+ };
736
+ /** Where the reference read, as its source's rows say: null when the vault does not see them. */
737
+ 'reference.break': {
738
+ source: SecretPath | null;
739
+ };
740
+ /** The key renamed, by its id. */
741
+ 'secret.rename': {
742
+ id: string;
743
+ };
744
+ /** The keys filed there, by name, in order. */
745
+ 'secret.refile': {
746
+ moved: string[];
747
+ };
748
+ /** What the change did to each key it named: dismissed, restored, or nothing, as it was already. */
749
+ 'missing.dismiss': {
750
+ keys: Record<string, 'dismissed' | 'restored' | 'unchanged'>;
751
+ };
752
+ };
753
+ /**
754
+ * What a write does to one key, as 0.14's dry run said it (`DryRunOutcome`):
755
+ * `added`, a key made, by a value or a reference; `archived`; `unchanged`,
756
+ * nothing at all, a key archived already, filed where it is, or made a
757
+ * reference to the source it reads; `changed`, anything else. Or, for a
758
+ * value written over the key's own, live, of the nature it is written as,
759
+ * typed and no reference (`compare`): the same or not only by opening that
760
+ * version, which a decision never does. A dry run asks a use to compare
761
+ * (purpose `compare`), which opens and logs the value as a read: the version
762
+ * named is the one a use must hand back for the answer to stand. The write
763
+ * itself never compares: it writes the value as a new version.
764
+ */
765
+ type KeyOutcome = 'added' | 'changed' | 'archived' | 'unchanged' | {
766
+ compare: {
767
+ secret: string;
768
+ version: number;
769
+ };
770
+ };
771
+ /** A key by where it is held: `market/prod/STRIPE_KEY`. */
772
+ type SecretPath = {
773
+ project: string;
774
+ environment: string;
775
+ key: string;
776
+ };
777
+ /** How a value is kept: a secret, a sensitive one that no person is handed back, or a plain one that whoever lists its environment sees. */
778
+ type Nature = 'secret' | 'sensitive' | 'plain';
779
+ /**
780
+ * What a write does to one key of its environment, one thing or several:
781
+ *
782
+ * - `value`: the key's next version, the key made if the environment has
783
+ * none by that name. Its `nature` as given, or, given none, the key's
784
+ * own kept, or, where the environment holds none, the one it inherits,
785
+ * and both for an archived key brought back: sensitive stays sensitive, and anything else is written a secret, a
786
+ * plain one's and one inherited from nowhere included. A reference's is
787
+ * its source's.
788
+ * `generated`: a client made it, by that recipe, which Regenerate makes
789
+ * the next one by (`@coffre/core/recipe`), as `formatRecipe` writes it.
790
+ * Never plain. A key pair's recipe writes its two keys together, each
791
+ * naming both, `{ private, public }`, with the same recipe: the two
792
+ * halves of one pair. A value typed, restored or referred to makes none.
793
+ * - `restore`: the key's next version, the value of that version of its
794
+ * own, opened and sealed again by the vault, which never hands it out.
795
+ * The value comes back as it was kept, plain, a secret or sensitive, and
796
+ * sensitive while the key is, as a write with no nature says (above), or
797
+ * while the key's newest value was. Its first date is its source's (the
798
+ * member report's). Made by a recipe or in a pair, it comes back as typed:
799
+ * Regenerate makes a new value, and it pairs with nothing. Whoever restores
800
+ * reads the key there (`secret.read`): the value serves again. And never
801
+ * looser than the newest copy of the same value, by its first date: a
802
+ * value marked sensitive comes back sensitive from a version before the
803
+ * mark, and one marked a secret from its plain version.
804
+ * - `nature` alone (`coffre mark`): the key's value kept, made of that
805
+ * nature, as the key's next version, which the vault opens and seals
806
+ * again: nature and version are in what its encryption names. Its first
807
+ * date, recipe and pair are kept: the value is the same. Stricter only,
808
+ * plain to a secret or sensitive, a secret to sensitive, by whoever
809
+ * writes keys there (`secret.write`); a sensitive value made a secret by
810
+ * an Owner of the project alone, as a person on no credential's scope
811
+ * (`not_owner` to anyone else), and plain never: that takes the value
812
+ * written again (`looser`). The nature it has already writes nothing
813
+ * (`unchanged`). The key is the environment's own, live and holding a
814
+ * value: `archived`, `is_reference` (mark its source), `inherited_key`
815
+ * (mark it where it is held), `no_value`, or `unknown_key`. A change
816
+ * that makes any key looser is logged `secret.loosen`, with every key's
817
+ * line, and `secret.write` otherwise.
818
+ * - `ref`: the key made a reference to that key, which whoever reads this
819
+ * environment then reads through it, value and nature, as it changes. Its
820
+ * own value, if any, is history. The source is a key of a live project and
821
+ * environment, no personal config's, that the writer reads there (and
822
+ * uses, a sensitive one), and that is no reference itself; nor is a key
823
+ * other references read made one: one hop only. A workload refers only to
824
+ * a value it is handed back where it is held, a plain one or one its
825
+ * binding lists.
826
+ * - `archived`: true archives the key, false brings it back. A key is
827
+ * archived with no value written.
828
+ * - `folder`: the folder it is listed in, null for none.
829
+ * - `inherit`, alone: in a fork, true resets the key to what a parent
830
+ * passes down, its own row archived with its history, and false makes
831
+ * its own value serve over that again. Either takes `secret.write`, as
832
+ * writing over a parent's does, and false `secret.read` too: the value
833
+ * serves again. A key no parent passes down is `not_inherited`.
834
+ *
835
+ * Any of these but `inherit` may say what the key read when its author
836
+ * looked (`replaces`): the version the key's value is now, by its id, as a
837
+ * listing gave it (`versionId`), its own live one or, in a fork that holds
838
+ * none live, the one it inherits; `{ source }`, a reference, here or
839
+ * inherited, to that secret, by its id (a listing's `reference.sourceId`);
840
+ * or `null`, a key that reads no value now and is no reference, here or
841
+ * inherited (new, archived with none passed down, or a reference broken).
842
+ * Anything else, a key renamed, archived, made a reference or written
843
+ * since, refuses the write, `stale`: a regenerate, or an MCP approval's
844
+ * change, addresses keys by name, and would otherwise change a key that no
845
+ * longer holds what its person read.
846
+ *
847
+ * A key that gets neither a value nor a reference is one the environment
848
+ * holds. In a fork, a key reset to what it inherits is written over as if
849
+ * it were live: it overrides its parent's again, as 0.14's did.
850
+ */
851
+ type KeyWrite = {
852
+ key: string;
853
+ archived?: boolean;
854
+ folder?: string | null;
855
+ replaces?: Replaces;
856
+ inherit?: undefined;
857
+ } & ({
858
+ value: string;
859
+ nature?: Nature;
860
+ generated?: Generation;
861
+ ref?: undefined;
862
+ restore?: undefined;
863
+ } | {
864
+ restore: number;
865
+ value?: undefined;
866
+ nature?: undefined;
867
+ generated?: undefined;
868
+ ref?: undefined;
869
+ } | {
870
+ ref: SecretPath;
871
+ value?: undefined;
872
+ nature?: undefined;
873
+ generated?: undefined;
874
+ restore?: undefined;
875
+ } | {
876
+ value?: undefined;
877
+ nature?: undefined;
878
+ generated?: undefined;
879
+ ref?: undefined;
880
+ restore?: undefined;
881
+ }) | {
882
+ key: string;
883
+ nature: Nature;
884
+ replaces?: Replaces;
885
+ archived?: undefined;
886
+ folder?: undefined;
887
+ inherit?: undefined;
888
+ value?: undefined;
889
+ generated?: undefined;
890
+ ref?: undefined;
891
+ restore?: undefined;
892
+ } | {
893
+ key: string;
894
+ inherit: boolean;
895
+ archived?: undefined;
896
+ folder?: undefined;
897
+ value?: undefined;
898
+ nature?: undefined;
899
+ generated?: undefined;
900
+ replaces?: undefined;
901
+ ref?: undefined;
902
+ restore?: undefined;
903
+ };
904
+ /** What a key read when its author looked (`KeyWrite`'s): a version by its id, a reference to a secret by its id, or nothing. */
905
+ type Replaces = string | null | {
906
+ source: string;
907
+ };
908
+ /**
909
+ * Write keys in one environment, all of them or none. 1 to 2,000 keys,
910
+ * each once and named as a key is (`[A-Za-z_][A-Za-z0-9_]{0,127}`); a value
911
+ * is well-formed text with no NUL, 64 Ki characters at most, generated by a recipe as `formatRecipe` writes it, a key pair's two halves both in the write, and replacing a version named by a UUID, and the values
912
+ * of one write 1 MiB of UTF-8 in all, each version restored counted as the most a value weighs, 192 KiB (so 5 at most), since its size is known only once the vault reads it; a version restored a positive integer; a reference's source named by slugs and its key's name; a folder 1 to 64 UTF-16 units, with no slash or control character
913
+ * and nothing `trim` removes at either end (`folderName`); a mark one of the three natures, alone. Past any of these
914
+ * the call is a fault, not a refusal: the app checks them first.
915
+ *
916
+ * In a personal config (`mine`), its owner alone writes, a person
917
+ * (`not_a_person` to a service account), while they read or use the
918
+ * environment it is a config of, and as far as their credential's scope
919
+ * does there; no grant or role reaches it. It holds no reference, and a
920
+ * value written there with no nature over a plain one stays plain: nobody
921
+ * but its owner lists it. A write that gives a key a value makes the
922
+ * config where they have none, as an environment of three parents at most
923
+ * (`too_deep`); anything else asked of a config not there is asked of a
924
+ * key not there.
925
+ */
926
+ type SecretWrite = {
927
+ op: 'secret.write';
928
+ project: string;
929
+ environment: string;
930
+ /** In the caller's personal config of `environment` (`dev@me`), made by this write if they have none and it gives a key a value. */
931
+ mine?: boolean;
932
+ keys: KeyWrite[];
933
+ };
934
+ /**
935
+ * A key renamed (`to`), with its history, by whoever writes keys there. A
936
+ * live key, named as `SecretWrite`'s: an archived one is brought back
937
+ * first (`archived`), and a name the environment holds already, archived
938
+ * or not, is `duplicate_key`. Its references read it still, by its id.
939
+ *
940
+ * The name carries down to every environment that inherits from it, forks
941
+ * of forks, archived ones and personal configs included: each one's own
942
+ * row of the key, its override, takes the new name, and so does its
943
+ * dismissal, so each goes on overriding or doing without the key it did.
944
+ * Where one already holds a key of the new name of its own, a shared fork
945
+ * refuses the rename, `duplicate_key_below`; a personal config, named to
946
+ * nobody but its owner, has its own moved out of the way, `NEW_2` (or
947
+ * `_3`, and on). No value moves, so the renamer needs nothing in the
948
+ * forks. Renamed onto its own name, nothing changes. In the caller's
949
+ * personal config (`mine`), as `SecretWrite`'s: a config has no forks.
950
+ */
951
+ type SecretRename = {
952
+ op: 'secret.rename';
953
+ project: string;
954
+ environment: string;
955
+ /** In the caller's personal config of `environment` (`dev@me`). */
956
+ mine?: boolean;
957
+ key: string;
958
+ to: string;
959
+ /** What the key read when its author looked, as a write's (`KeyWrite`): anything else now, `stale`. */
960
+ replaces?: Replaces;
961
+ };
962
+ /**
963
+ * A folder of one environment's keys renamed (`to`), or emptied (`to`
964
+ * null): every key filed there, archived ones too, all of them or none, by
965
+ * whoever writes keys there. A folder is a label, so renaming onto one
966
+ * that is there merges the two. A folder no key is filed in is no folder:
967
+ * refused `no_folder`. Folders are named as `SecretWrite`'s; past that, a
968
+ * fault.
969
+ */
970
+ type SecretRefile = {
971
+ op: 'secret.refile';
972
+ project: string;
973
+ environment: string;
974
+ /** In the caller's personal config of `environment` (`dev@me`). */
975
+ mine?: boolean;
976
+ folder: string;
977
+ to: string | null;
978
+ };
979
+ /**
980
+ * End the reference a key is: whoever read through it reads nothing there,
981
+ * until the key is given a value or made a reference again. Whoever writes
982
+ * the key may, and whoever manages access in its source's project, who
983
+ * need not see the key's environment at all.
984
+ */
985
+ type ReferenceBreak = {
986
+ op: 'reference.break';
987
+ project: string;
988
+ environment: string;
989
+ key: string;
990
+ };
991
+ /**
992
+ * Keys an environment does without (`dismissed: true`), or does again
993
+ * (`false`), 0.14's `setDismissals`, by whoever writes keys there: the
994
+ * team's decision, which its missing keys list leaves out until someone
995
+ * restores it. A key named twice, or a key past 2,000 in one change, is a
996
+ * fault and a refusal (`too_many_keys`) respectively.
997
+ *
998
+ * In a fork, or a personal config (`mine`), a dismissal is also a removal:
999
+ * the environment no longer inherits the key, and a use there reads
1000
+ * nothing of it. One it holds a live row of, a value or a reference, would
1001
+ * serve whatever is dismissed, so dismissing it is refused, `held_here`:
1002
+ * reset it to what it inherits first, or archive it. Outside a fork, such a
1003
+ * dismissal is moot, and allowed, as in 0.14.7. A personal config is
1004
+ * dismissed in only by its owner, and only once they have one: a
1005
+ * dismissal makes none, `no_config`.
1006
+ */
1007
+ type MissingDismiss = {
1008
+ op: 'missing.dismiss';
1009
+ project: string;
1010
+ environment: string;
1011
+ /** In the caller's personal config of `environment` (`dev@me`). */
1012
+ mine?: boolean;
1013
+ keys: {
1014
+ key: string;
1015
+ dismissed: boolean;
1016
+ }[];
1017
+ };
1018
+ //#endregion
1019
+ //#region src/changes/signin.d.ts
1020
+ /**
1021
+ * The changes of sign-in and of credentials (`packages/vault/src/ops/signin.ts`,
1022
+ * docs/design/0.16.md, "Signing in").
1023
+ */
1024
+ type SigninChanges = Signin | CredentialEnd | AccountLink | AccountUnlink | TokenCreate | DeviceStart | DeviceDecide | DeviceRedeem;
1025
+ type SigninAnswers = {
1026
+ signin: Issued;
1027
+ /** The credential ended. */
1028
+ 'credential.end': {
1029
+ credential: string;
1030
+ };
1031
+ /** The identity the account is bound by. */
1032
+ 'account.link': {
1033
+ identity: string;
1034
+ };
1035
+ 'account.unlink': {
1036
+ identity: string;
1037
+ };
1038
+ /**
1039
+ * The token made, and what it reaches, each place by its path and the
1040
+ * role there; a service's, the places of those whose sensitive values it
1041
+ * will not read (`withheld`, R32), as `token.bind` answers them.
1042
+ */
1043
+ 'token.create': Issued & {
1044
+ scope: Record<string, string>;
1045
+ withheld?: string[];
1046
+ };
1047
+ /** The device login, and when its codes stop being good, ISO 8601. */
1048
+ 'device.start': {
1049
+ deviceLogin: string;
1050
+ expiresAt: string;
1051
+ };
1052
+ /** The device login decided. */
1053
+ 'device.decide': {
1054
+ deviceLogin: string;
1055
+ };
1056
+ /** The CLI's session. */
1057
+ 'device.redeem': Issued;
1058
+ };
1059
+ /**
1060
+ * The operations nobody asks: no credential comes with them, only where
1061
+ * their request came from (`Trace`). Each rests on what the app verified,
1062
+ * or on a secret of its own (a device code).
1063
+ */
1064
+ type Unasked = 'signin' | 'device.start' | 'device.redeem';
1065
+ /**
1066
+ * An account at a sign-in provider, as the app verified it with the
1067
+ * provider: the vault takes it on the app's word, and its entry says so.
1068
+ * `issuer` is the hash the app keeps a provider's issuer by; `emails` are
1069
+ * the addresses the provider verified, lowercase, its primary one first, 20
1070
+ * at most.
1071
+ */
1072
+ type Account = {
1073
+ provider: string;
1074
+ issuer: string;
1075
+ subject: string;
1076
+ emails: string[];
1077
+ };
1078
+ /**
1079
+ * A credential to make. The app draws its token and sends the SHA-256,
1080
+ * lowercase hex: the vault never sees a token. `minutes` is how long it
1081
+ * lasts, within what its kind may.
1082
+ */
1083
+ type NewCredential = {
1084
+ token: string;
1085
+ minutes: number;
1086
+ label: string | null;
1087
+ };
1088
+ /** A credential made: whose it is, its id, and when it ends, ISO 8601. */
1089
+ type Issued = {
1090
+ principal: string;
1091
+ credential: string;
1092
+ expiresAt: string;
1093
+ };
1094
+ /**
1095
+ * A person signs in to a browser with an account the app verified.
1096
+ *
1097
+ * - The account is bound, its identity not revoked: its member signs in,
1098
+ * if they are active and of the generation it was bound in
1099
+ * (`deactivated` otherwise).
1100
+ * - The account is new: the first of its emails that names a member names
1101
+ * who it is (`not_registered` for none). They must be active
1102
+ * (`deactivated`) and have no account yet (`account_mismatch`: they sign
1103
+ * in with the one they have, and link this one). It is bound to them.
1104
+ * - An email the vault's configuration names an Owner is a member whatever
1105
+ * the rows say: made one, or made an active Owner of the whole instance
1106
+ * again, in the same change.
1107
+ * - Before the vault has adopted the database nobody signs in
1108
+ * (`adopting`, for the app to answer 503). A row the decision would read
1109
+ * that is there and not the vault's refuses it (`tampered`).
1110
+ *
1111
+ * `replaces` is the SHA-256 of the session token the browser showed, if it
1112
+ * showed one: that session ends in the same change, whoever's it was.
1113
+ */
1114
+ type Signin = {
1115
+ op: 'signin';
1116
+ account: Account;
1117
+ session: NewCredential;
1118
+ replaces: string | null;
1119
+ };
1120
+ /**
1121
+ * End a credential: write its row revoked. Ending one that is already
1122
+ * ended, expired, not there or not the caller's to end is one refusal,
1123
+ * `unknown_credential`, which does not say which.
1124
+ *
1125
+ * - `credential` null: the one the request came in on, signing out
1126
+ * (`sign_out`). Any credential that stands signs itself out but a
1127
+ * handle, which is the proxy's; one that does not is told
1128
+ * `unauthenticated`, which the app answers as signed out all the same.
1129
+ * - `credential` an id (`token.revoke`), by what the route named it as
1130
+ * (`of`), and by the callers 0.14.7's route reached: no personal token
1131
+ * but on the handles route. A credential with a scope holds nothing of
1132
+ * the instance's own (`runsInstance` in @coffre/core/access), so a
1133
+ * service's token ends its own service's alone, or one of a service it
1134
+ * manages:
1135
+ * - `of` null: one of the caller's own, any kind, or anyone's for whoever
1136
+ * runs the instance (`DELETE /sessions/:id`, which a workload's session
1137
+ * does not reach);
1138
+ * - `of` `'handle'`: a handle of the caller's own, and nothing else, on
1139
+ * a personal token too (`DELETE /handles/:id`, `coffre run` ending its
1140
+ * own);
1141
+ * - `of` a member: a token or a workload's session of that member
1142
+ * (`DELETE /members/:member/tokens/:id`): theirs, for a person who
1143
+ * manages the service account (`managesService`), or for whoever runs
1144
+ * the instance.
1145
+ */
1146
+ type CredentialEnd = {
1147
+ op: 'credential.end';
1148
+ } & ({
1149
+ credential: null;
1150
+ of: null;
1151
+ } | {
1152
+ credential: string;
1153
+ of: null | 'handle' | {
1154
+ member: string;
1155
+ };
1156
+ });
1157
+ /**
1158
+ * A person, on a browser session, binds a second account the app verified
1159
+ * to themselves. Refused `already_linked` if the account is bound to
1160
+ * anyone, themselves included.
1161
+ */
1162
+ type AccountLink = {
1163
+ op: 'account.link';
1164
+ account: Account;
1165
+ };
1166
+ /**
1167
+ * The caller revokes one of their own accounts, by its identity's id
1168
+ * (`unknown_identity` for one that is not theirs, or not bound). The
1169
+ * sessions it opened end with it, with no write: the rule that reads them
1170
+ * refuses a session whose account is revoked. Their last account too: they
1171
+ * sign in again with any account a verified email of theirs names, as the
1172
+ * first time.
1173
+ */
1174
+ type AccountUnlink = {
1175
+ op: 'account.unlink';
1176
+ identity: string;
1177
+ };
1178
+ /**
1179
+ * Make a token (`token.create`), one of three kinds. The app draws it and
1180
+ * sends its SHA-256 (`credential`), and its hint as the token's list shows it,
1181
+ * its kind's prefix and its last four characters (`coffre_pat_…x7Qd`). Its
1182
+ * scope is sealed on its row, each place by id with what its role held
1183
+ * there as it was made, and never changes after: a request made with it
1184
+ * holds what both that and its member hold then. A credential with a
1185
+ * scope never makes one, but a personal token a handle; a personal token
1186
+ * asking for a personal token is told what it is (`personal_token`), whoever
1187
+ * it names; a workload's session makes none (`workload_cannot_issue`).
1188
+ *
1189
+ * - `personal`: a person, on a session, for themselves (`member`, the route's
1190
+ * `user:<email>`: anyone else's is `no_access`, as 0.14.7 refused a person
1191
+ * making another's); a label, a week at most, and a scope by path (`{ "market/dev": "viewer" }`), each role one
1192
+ * that manages no access and that they hold all of at its place now, in
1193
+ * a project's protected environments too (0.14.7's `personalScope`).
1194
+ * - `handle`: a person, on a session or a personal token of theirs, for
1195
+ * the proxy (docs/design/credential-proxy.md); a label, a week at most
1196
+ * and never past the token it is made on, and the environments it stands
1197
+ * in for by path, `@me` for the person's personal config of one. It
1198
+ * reaches each, and each parent it inherits from that they read or use,
1199
+ * reading where they read and using where they only use.
1200
+ * - `service`: a token of the service account `member`, for whoever
1201
+ * manages it (`issuesCredential`); a label or none, 366 days at most, and
1202
+ * the scope asked or, `scope` null, every grant it holds. Each place
1203
+ * reads the sensitive values there only if the caller is an Owner of its
1204
+ * project (`ownsProject`, R32). Refused `use_only` on an instance whose
1205
+ * services sign in with a key only.
1206
+ *
1207
+ * A place that is not there and one beyond the caller are one refusal,
1208
+ * `no_access`; a role there is not, or one its place does not take,
1209
+ * `invalid`; a service's token with nothing to reach, `no_grants`.
1210
+ */
1211
+ type TokenCreate = {
1212
+ op: 'token.create';
1213
+ credential: NewCredential;
1214
+ hint: string;
1215
+ } & ({
1216
+ kind: 'personal';
1217
+ member: string;
1218
+ scope: Record<string, string>;
1219
+ } | {
1220
+ kind: 'handle';
1221
+ paths: string[];
1222
+ } | {
1223
+ kind: 'service';
1224
+ member: string;
1225
+ scope: Record<string, string> | null;
1226
+ });
1227
+ /**
1228
+ * A CLI asks to be signed in from a browser (RFC 8628, `coffre login`).
1229
+ * The app draws both codes: the device code, which only the CLI holds and
1230
+ * the vault has by its SHA-256 (`code`, lowercase hex), and the user code
1231
+ * a person types in their browser (`USER_CODE` in @coffre/core/access).
1232
+ * `label` is what the CLI calls itself, as the person approving it sees
1233
+ * it. It waits 10 minutes for a decision (`DEVICE_TTL_SECONDS`).
1234
+ *
1235
+ * Refused `taken` when a row holds either code already, expired or not:
1236
+ * the app draws again. Before the vault has adopted the database,
1237
+ * `adopting`; with an instance's row that is not the vault's, `tampered`.
1238
+ * How many wait at once is the app's to cap, before it asks.
1239
+ */
1240
+ type DeviceStart = {
1241
+ op: 'device.start';
1242
+ code: string;
1243
+ userCode: string;
1244
+ label: string | null;
1245
+ };
1246
+ /**
1247
+ * A person, on a session of theirs, approves or denies a device login by
1248
+ * the user code it shows (`device.approve`, `device.deny`): approved, the
1249
+ * CLI that holds its device code collects a session of theirs. One that is
1250
+ * not there, decided, or past its 10 minutes is refused `unknown_code`;
1251
+ * a token, a service account's or a person's, `no_access`.
1252
+ */
1253
+ type DeviceDecide = {
1254
+ op: 'device.decide';
1255
+ userCode: string;
1256
+ approve: boolean;
1257
+ };
1258
+ /**
1259
+ * The CLI collects its session, by its device code's SHA-256 (`code`): once
1260
+ * a person approved its device login, within its 10 minutes, and once. The
1261
+ * session is the approver's, of the generation they approved it in, for
1262
+ * `minutes` (365 days at most), labelled as the CLI called itself.
1263
+ *
1264
+ * The CLI polls until then. Refused, writing nothing (RFC 8628's errors):
1265
+ * `pending` while nobody has decided; `denied` once someone denied it, or
1266
+ * when its approver is no longer an active member of the generation they
1267
+ * approved it in; `expired` for one that is past its 10 minutes, collected
1268
+ * already, or not there. `adopting` and `tampered` as for a sign-in, and
1269
+ * `tampered` for a device login or its approver written behind the vault.
1270
+ */
1271
+ type DeviceRedeem = {
1272
+ op: 'device.redeem';
1273
+ code: string;
1274
+ session: {
1275
+ token: string;
1276
+ minutes: number;
1277
+ };
1278
+ };
1279
+ //#endregion
1280
+ //#region src/changes/workloads.d.ts
1281
+ /**
1282
+ * The changes of workloads signing in (`packages/vault/src/ops/workloads.ts`,
1283
+ * docs/design/0.16.md, "A workload signing in").
1284
+ */
1285
+ type WorkloadChanges = TokenExchange | WorkloadSignin | WorkloadRenew | TokenBind | TokenUnbind;
1286
+ type WorkloadAnswers = {
1287
+ 'token.exchange': Exchanged;
1288
+ 'workload.signin': Session;
1289
+ 'workload.renew': Renewed;
1290
+ 'token.bind': Bound;
1291
+ 'token.unbind': {
1292
+ binding: string;
1293
+ };
1294
+ };
1295
+ /** The workloads' changes nobody asks: a CI run, or a workload signing in, has no credential yet, only its platform's proof. */
1296
+ type WorkloadsUnasked = 'token.exchange' | 'workload.signin';
1297
+ /**
1298
+ * A CI run trades its platform's ID token for a service token of five
1299
+ * minutes, issued by the oldest of the service's bindings with no policy
1300
+ * that takes it.
1301
+ *
1302
+ * - `token` is the ID token itself, which the vault reads its claims
1303
+ * from: the app verified its signature under `under`, the issuer and
1304
+ * the address of its keys, and the vault takes that on its word. For a
1305
+ * binding that carries its keys, `under.jwksUri` is theirs,
1306
+ * `sha256:<hex>`, and the vault verifies the signature itself, under the
1307
+ * keys on its own row.
1308
+ * - `publicUrl` is the app's own, which a CI run's token names as its
1309
+ * audience.
1310
+ * - `credential` is the SHA-256 of the token the app drew, lowercase hex.
1311
+ *
1312
+ * Refused (docs/design/0.16.md, "A refusal"): `no_match`, `audience`,
1313
+ * `expired`, `too_old`, `malformed`, `replayed`, `unknown_signer`, and
1314
+ * `tampered` for a binding or the service's row written behind the vault.
1315
+ * A refusal writes nothing and is not logged.
1316
+ */
1317
+ type TokenExchange = {
1318
+ op: 'token.exchange';
1319
+ service: string;
1320
+ token: string;
1321
+ under: VerifiedUnder;
1322
+ publicUrl: string;
1323
+ credential: string;
1324
+ };
1325
+ /** The token made, and the binding that issued it, by which the app counts a binding's rate. */
1326
+ type Exchanged = Issued & {
1327
+ binding: string;
1328
+ };
1329
+ /**
1330
+ * A workload's proof, by its kind: a platform's ID token, with the keys the
1331
+ * app verified it under (`token.exchange`'s `token` and `under`), or STS's
1332
+ * answer to the `GetCallerIdentity` request the workload signed, which the
1333
+ * app checked whole and sent.
1334
+ */
1335
+ type WorkloadProof = {
1336
+ oidc: {
1337
+ token: string;
1338
+ under: VerifiedUnder;
1339
+ };
1340
+ } | {
1341
+ aws: CallerIdentity;
1342
+ };
1343
+ /**
1344
+ * A workload trades its proof for a session bound to a key it holds,
1345
+ * issued by the oldest of the service's bindings with a policy, of that
1346
+ * proof's profiles, that takes it.
1347
+ *
1348
+ * - `key` is the thumbprint of the key the request's own proof (RFC 9449)
1349
+ * named, which the app held to the request: the session is that key's
1350
+ * alone, and a token whose audience names a key names this one.
1351
+ * - `publicUrl` and `credential` as for `token.exchange`.
1352
+ *
1353
+ * Refused as `token.exchange` is, and `frozen` for a service, a binding or
1354
+ * every workload a manager froze, as 0.14 refused it. A binding whose
1355
+ * sources the request comes from outside, or that lists reads where the
1356
+ * deployment lets none (`noReads`), is `no_match`. A refusal writes nothing
1357
+ * and is not logged.
1358
+ */
1359
+ type WorkloadSignin = {
1360
+ op: 'workload.signin';
1361
+ service: string;
1362
+ proof: WorkloadProof;
1363
+ key: string;
1364
+ publicUrl: string;
1365
+ credential: string;
1366
+ };
1367
+ /**
1368
+ * The session made: its token's expiry, an hour on or its hard end, and
1369
+ * that hard end; the environments it reaches as of now, by id, as its row
1370
+ * lists them, which the app names by path; and the binding that issued it,
1371
+ * by which the app counts a binding's rate.
1372
+ */
1373
+ type Session = Issued & {
1374
+ binding: string;
1375
+ notAfter: string;
1376
+ places: string[];
1377
+ };
1378
+ /**
1379
+ * A workload's session moves its own expiry on, by its key's proof: an
1380
+ * hour from now, never past its hard end. A frozen session renews, so that
1381
+ * lifting the freeze restores it; one stopped for any other reason, or
1382
+ * narrowed from another, does not. Refused `expired` within five seconds of
1383
+ * its expiry, so that a renewal that comes late revives nothing.
1384
+ */
1385
+ type WorkloadRenew = {
1386
+ op: 'workload.renew';
1387
+ };
1388
+ /** The session's expiry, moved on, or as it was at its hard end. */
1389
+ type Renewed = {
1390
+ expiresAt: string;
1391
+ };
1392
+ /**
1393
+ * A binding to make, as 0.14's `POST /members/:m/bindings` took it, and
1394
+ * checked as it did (`checkBinding`, `checkPolicy`, the profile's rule):
1395
+ *
1396
+ * - `keys`: where its issuer's keys are, the address the app's discovery
1397
+ * found (a URN profile's, its issuer), which the vault takes on the
1398
+ * app's word and seals; or the keys themselves, uploaded, a JWKS the
1399
+ * vault checks and keeps (`uploadedKeys`).
1400
+ * - `policy`: a workload's binding's, null for one a CI run's exchange
1401
+ * takes (a bearer profile's; under `useOnly`, every binding is a
1402
+ * workload's). Its `reads` name each environment by path, and its keys
1403
+ * by name or `"*"`, which the vault finds and seals by id.
1404
+ * - `scope`: what its credentials reach, by path, as a service token's
1405
+ * (`token.create`); null for what the bindings it replaces reached, of
1406
+ * what the service still holds, or else all the service holds.
1407
+ * - `replaces`: the live bindings it takes the place of, by id. Those of
1408
+ * its issuer whose keys are elsewhere go too (`keys_moved`).
1409
+ * - `only`: true when `replaces` is all it may end, as an approval page
1410
+ * listed them: one of its issuer's whose keys are elsewhere and that it
1411
+ * does not name refuses `stale`, and nothing is made.
1412
+ */
1413
+ type NewBinding = {
1414
+ profile: string;
1415
+ issuer: string | null;
1416
+ claims: Record<string, unknown>;
1417
+ keys: {
1418
+ uri: string;
1419
+ } | {
1420
+ jwks: unknown;
1421
+ };
1422
+ policy: Record<string, unknown> | null;
1423
+ scope: Record<string, string> | null;
1424
+ label: string | null;
1425
+ replaces: string[];
1426
+ only?: boolean;
1427
+ };
1428
+ /**
1429
+ * Trust a workload as a service (`binding`), or give its bindings on an
1430
+ * issuer new keys, uploaded (`keys`): each is replaced by one the same but
1431
+ * for its keys, reaching what it did of what the service still holds.
1432
+ * Whoever manages the service (`managesService`), each grant of the scope
1433
+ * one they could give it and it holds (`issuesCredential`); its sensitive
1434
+ * values only where an Owner of the project binds it (`ownsProject`). A
1435
+ * binding is never edited: a replaced one is revoked, and the credentials
1436
+ * it issued end with it.
1437
+ *
1438
+ * Refused: `unauthenticated` and a stopped caller's words; `no_access`,
1439
+ * for one who does not manage the service, or a place not found or beyond
1440
+ * them; `unknown_principal`, a service that is not active; `tampered`, any
1441
+ * row read that is not the vault's; `invalid`, a role that is none there, a
1442
+ * read outside the scope or of a key the environment does not hold, a
1443
+ * policy its reads break, uploaded keys that are no JWKS, or replaced
1444
+ * bindings that reach nothing the service still holds or a place with two
1445
+ * roles; `no_grants`, a scope with nothing to reach; `not_owner_issued`, a
1446
+ * sensitive key read where no Owner of its project binds; `no_reads`, reads
1447
+ * where the deployment lets none; `unknown_binding`, a binding replaced
1448
+ * that is not live, or no binding on the issuer whose keys are replaced;
1449
+ * `keys_differ`, other bindings on the issuer whose keys are elsewhere,
1450
+ * uploaded on one side; `same_keys`, keys the bindings carry already;
1451
+ * `too_many_bindings`, past `MAX_BINDINGS` live.
1452
+ */
1453
+ type TokenBind = {
1454
+ op: 'token.bind';
1455
+ member: string;
1456
+ } & ({
1457
+ binding: NewBinding;
1458
+ } | {
1459
+ keys: {
1460
+ issuer: string;
1461
+ jwks: unknown;
1462
+ };
1463
+ });
1464
+ /**
1465
+ * The bindings made, each with what it reaches by path and role and the
1466
+ * places of those whose sensitive values it will not read (`withheld`:
1467
+ * each holds one of a project no Owner of which binds it, R32), and the
1468
+ * bindings revoked, by id.
1469
+ */
1470
+ type Bound = {
1471
+ bindings: {
1472
+ id: string;
1473
+ scope: Record<string, string>;
1474
+ withheld: string[];
1475
+ }[];
1476
+ replaced: string[];
1477
+ };
1478
+ /**
1479
+ * Remove a binding: whoever manages its service. Its row is revoked, and
1480
+ * the credentials it issued end with it. Refused `unknown_binding` for
1481
+ * one that is not a live binding of the service, and as `token.bind` is.
1482
+ */
1483
+ type TokenUnbind = {
1484
+ op: 'token.unbind';
1485
+ member: string;
1486
+ binding: string;
1487
+ };
1488
+ //#endregion
2
1489
  //#region src/access-fault.d.ts
3
1490
  /**
4
1491
  * Why the vault's members and grants do not follow from its log, as facts
@@ -63,220 +1550,309 @@ type FaultNames = {
63
1550
  /** The fault in a sentence, with whatever names the caller can give. */
64
1551
  export declare function describeAccessFault(fault: AccessFault, names?: FaultNames): string;
65
1552
  //#endregion
66
- //#region src/checkpoint.d.ts
67
- /** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
68
- export declare function checkpointMessage(checkpoint: Omit<Checkpoint, 'signature' | 'keyId'>): Uint8Array<ArrayBuffer>;
69
- /** Whether `checkpoint` was signed by the key whose raw public half is `publicKey`. */
70
- export declare function verifyCheckpoint(checkpoint: Checkpoint, publicKey: string): Promise<boolean>;
71
- /**
72
- * `verifyCheckpoint` for many checkpoints signed by one key, the key
73
- * imported once: a full verification checks every checkpoint, one every
74
- * five minutes.
75
- */
76
- export declare function checkpointVerifier(publicKey: string): Promise<(checkpoint: Checkpoint) => Promise<boolean>>;
77
- //#endregion
78
1553
  //#region src/vault.d.ts
79
1554
  /**
80
- * The vault as the app sees it: the contract between `@coffre/server` and
81
- * `@coffre/vault`, kept in core so that neither side owns it. Every argument
82
- * and result is plain JSON: strings, numbers, booleans, arrays and objects,
83
- * never a Buffer, a Date, a class or a function. So it crosses a Workers RPC
84
- * boundary, or a process boundary later, as it is, and the in-process
85
- * transport proves it by round-tripping everything through JSON.
1555
+ * The vault as the app sees it (docs/design/0.16.md, "The contract"): the
1556
+ * contract between `@coffre/server` and `@coffre/vault`, kept in core so
1557
+ * that neither side owns it. Every argument and answer is plain JSON:
1558
+ * strings, numbers, booleans, arrays and objects, never a Buffer, a Date, a
1559
+ * class or a function. So it crosses a Workers RPC boundary, or a process
1560
+ * boundary, as it is, and the in-process transport proves it by
1561
+ * round-tripping everything through JSON.
86
1562
  *
87
- * The app says who is asking and the vault decides. The app never holds a
88
- * key: it encrypts a value under a fresh data key, has the vault wrap that
89
- * key, and stores the result; to read, it names stored versions and the
90
- * vault loads their keys itself.
1563
+ * The app says what a request showed and the vault decides: it finds the
1564
+ * credential by its token, reads what it holds and opens the values
1565
+ * itself. The app holds no key, no ciphertext it can open and no grant it
1566
+ * decides on.
91
1567
  *
92
- * Decisions come back as values: `{ ok: false, refusal }` for a refusal, which
93
- * the vault has already logged. Only a fault (a bug, the store down) throws.
1568
+ * A decision comes back as a value: `{ refused }` for a refusal, which
1569
+ * wrote nothing of what was asked. A refused use writes nothing at all; a
1570
+ * change refused to a caller who stands, one log entry that says so, once
1571
+ * a minute in each instance for that caller and what they asked. Only a
1572
+ * fault throws: a bug, or the database down.
94
1573
  */
95
1574
  export interface Vault {
1575
+ /** Open values for whoever presented a token: a reveal, `coffre run`, an export, a proxied request, a signature. */
1576
+ use(input: UseInput): Promise<Used | Refused>;
96
1577
  /**
97
- * Unwrap data keys for `principal`: all of them, or none. Given the
98
- * revision of an answer of `access` the app decided the read on
99
- * (`accessRevision`), only while the principal's access is still that
100
- * one, under their row and the head the decision holds: otherwise it
101
- * refuses `access_changed` and logs no read, and says, by naming it back,
102
- * that it checked. A vault older than 0.14.1 names none: it checked none.
103
- */
104
- unwrap(input: UnwrapInput): Promise<Outcome<Unwrapped>>;
105
- /**
106
- * Wrap fresh data keys for new versions `principal` writes: all, or none.
107
- * `seqs` are the `key.wrap` entries, one per key, which the app's
108
- * `secret.write` entries name as related. `sensitive` says, per key,
109
- * whether its wrap binds it as sensitive: a vault older than 0.10 answers
110
- * none, binding none, and the app stores no sensitive version it wrapped.
1578
+ * What `use` would give, as of now, without opening or writing anything:
1579
+ * each key's secret and version, or why it is refused. What a watch
1580
+ * compares before it reads (`GET …/version`).
111
1581
  */
112
- wrap(input: WrapInput): Promise<Outcome<Wrapped>>;
1582
+ peek(input: UseInput): Promise<Peeked | Refused>;
113
1583
  /**
114
- * Wrap existing data keys again for new versions of the same secrets,
115
- * under the current key: restoring an old value, or making one stricter.
116
- * It needs a write grant, not a read one, since the key never leaves the
117
- * vault. A new version is never less sensitive than the one it is made
118
- * from, or than its secret's newest: a value is made looser only by
119
- * being written again (`invalid`). Except one: a key's current sensitive
120
- * value made a secret, in place, by an Owner of its project, or of the
121
- * whole instance, on no credential's scope (`ownsProject`; `not_allowed`
122
- * for anyone else), its entry saying `was: 'sensitive'`.
1584
+ * Who a request's credential is and all it holds, for the app to scope a
1585
+ * page's queries with. Nothing is opened or changed on the answer: a use
1586
+ * and a change read their caller themselves.
123
1587
  */
124
- rewrap(input: RewrapInput): Promise<Outcome<Wrapped>>;
1588
+ caller(input: Presented & {
1589
+ head?: boolean;
1590
+ }): Promise<Called | Refused>;
125
1591
  /**
126
- * Make secrets references to others: whoever can read the holder's
127
- * environment reads the source through it (docs/design/environments.md).
128
- * The vault checks that `principal` reads each source and writes each
129
- * holder, by their own grants, and logs a `reference.create` per item:
130
- * that entry, under the vault's MAC, is the reference. `seqs` are the
131
- * entries, which the app stores beside each reference and names when it
132
- * reads through one (`UnwrapInput`'s `via`). All, or none.
1592
+ * Make a change: one operation, named as its log entry's action is, with
1593
+ * its input. All of it, or none.
133
1594
  */
134
- reference(input: ReferenceInput): Promise<Outcome<{
135
- seqs: number[];
136
- }>>;
1595
+ change<O extends Change['op']>(input: Asked<O>): Promise<{
1596
+ answer: Answers[O];
1597
+ } | Refused>;
137
1598
  /**
138
- * End references, each with a `reference.end` naming its creation:
139
- * `replaced` when the holder gets a value of its own, which takes write on
140
- * the holder; `broken` otherwise, which takes write on the holder, or
141
- * managing the source's project's access. An ended reference reads no
142
- * more, whatever any row says. All, or none.
1599
+ * What `change` would answer, as of now, with nothing written: the same
1600
+ * read and the same decision, so a dry run (`?dryRun=1`) is no second
1601
+ * copy of a rule. The change made after reads and decides again, and
1602
+ * alone tells a version it opens that does not open (`unreadable`). One
1603
+ * refused is logged as the change refused is; one that would be made
1604
+ * leaves nothing. Only what a caller asks is weighed: a sign-in or an
1605
+ * exchange rests on a proof, which this would try without spending.
143
1606
  */
144
- endReferences(input: EndReferencesInput): Promise<Outcome<{
145
- seqs: number[];
146
- }>>;
1607
+ weigh<O extends Exclude<Change['op'], Unasked | WorkloadsUnasked | McpUnasked>>(input: Asked<O>): Promise<{
1608
+ answer: Answers[O];
1609
+ } | Refused>;
147
1610
  /**
148
- * What one principal holds right now: the app asks once per request,
149
- * unless the request reads values on an answer it kept (`accessRevision`),
150
- * and at sign-in for each verified email. A decision, its rows checked:
151
- * lists of who holds what read the rows themselves, and need not ask.
152
- * A person the vault's `owners` names who is no Owner of all of it
153
- * becomes one here, logged (`reason: 'owners'`).
1611
+ * The vault's configuration that is no secret: its vault keys and its
1612
+ * signing keys' checks. It asks no caller, reads nothing, writes no
1613
+ * entry and opens no connection: it answers what the vault was started
1614
+ * with, the same to anyone, so whoever may see it is the app's to say.
154
1615
  */
155
- access(principal: string): Promise<Access>;
156
- /**
157
- * Set roles at several places for one principal: all of it, or none.
158
- * With `admit`, a service account that is not a member is admitted
159
- * first, in the same decision, as `admit` would: `admitted` says so.
160
- */
161
- setAccess(input: SetAccessInput): Promise<Outcome<{
162
- changes: AccessChange[];
163
- admitted?: Admitted;
164
- }>>;
165
- /**
166
- * Add a member, bring back a removed one, or change a person's instance
167
- * role and its scope. `generation` is theirs now: sessions and tokens of
168
- * an earlier one are dead.
169
- */
170
- admit(input: AdmitInput): Promise<Outcome<Admitted>>;
1616
+ about(): Promise<About>;
1617
+ }
1618
+ /** Where a request came from, which every call carries. */
1619
+ export type Trace = {
1620
+ /** The app's id for the request, for the log. */
1621
+ request: string | null;
1622
+ /** The address it came from, for the log, and for a workload's binding that names its sources. */
1623
+ ip: string | null;
1624
+ };
1625
+ /**
1626
+ * What a request showed, which every call but a change nobody asks starts
1627
+ * with. The app never says who is asking: the vault finds the credential
1628
+ * by its token.
1629
+ */
1630
+ export type Presented = Trace & {
1631
+ /** The SHA-256 of the token the request presented, in lowercase hex. */
1632
+ token: string;
171
1633
  /**
172
- * Remove a member: revoke every grant and refuse them until admitted
173
- * again, from `generation` on. An Owner, only an Owner of the whole
174
- * instance removes, and never the last.
1634
+ * The thumbprint of the key that signed the request's proof (RFC 9449),
1635
+ * once the app has held the proof to the request: a workload's session
1636
+ * is its key's alone. Null with no proof.
175
1637
  */
176
- remove(input: RemoveInput): Promise<Outcome<{
177
- revoked: Grant[];
178
- generation: number;
179
- }>>;
1638
+ proof: string | null;
1639
+ };
1640
+ /**
1641
+ * A change as the app sends it: its operation's input, with what the
1642
+ * request showed, or for one nobody asks (`Unasked`), where it came from
1643
+ * alone.
1644
+ */
1645
+ export type Asked<O extends Change['op']> = O extends Change['op'] ? (O extends Unasked | WorkloadsUnasked | McpUnasked ? Trace : Presented & ForConnection) & Extract<Change, {
1646
+ op: O;
1647
+ }> : never;
1648
+ /**
1649
+ * The approval a person makes a change for, on coffre's page
1650
+ * (docs/design/0.16.md, "An MCP client's changes"): the change is theirs,
1651
+ * made on their browser session, and its entry names the app that asked.
1652
+ * The vault reads the connection and the approval with the change's other
1653
+ * rows. The connection must stand, be of the caller's own member and
1654
+ * generation, and the caller be on a browser session, or the change is
1655
+ * refused `disconnected`. The approval must be the connection's, pending,
1656
+ * unexpired by the time the write starts, and of the `digest` the page
1657
+ * rendered, or it is refused `unknown_approval`. Made, the change marks the
1658
+ * approval approved in its own write: no approval is approved without its
1659
+ * change, nor a change made twice under one. It decides nothing else: what
1660
+ * the change may do is the person's.
1661
+ */
1662
+ export type ForConnection = {
1663
+ via?: {
1664
+ connection: string;
1665
+ approval: string;
1666
+ digest: string;
1667
+ };
1668
+ };
1669
+ export type UseInput = Presented & {
1670
+ /** The place, by its slugs. */
1671
+ project: string;
1672
+ environment: string;
1673
+ /** The caller's personal config of that environment, `@me`, where they have one. */
1674
+ mine: boolean;
1675
+ /** The keys asked for, by name, 1,000 at most: null is every key the environment has. */
1676
+ keys: string[] | null;
1677
+ /** `use`: the value is used for the caller, by the credential proxy, and never handed back. Any other hands it back. */
1678
+ purpose: Purpose;
1679
+ /** What the values are used for (`Upstream`): null for none. */
1680
+ upstream: Upstream | null;
180
1681
  /**
181
- * The instance's settings, as the vault's newest `settings.change` entry
182
- * says, by its MAC: an entry is where they live, so each change is logged
183
- * by being made. Everywhere, until someone narrows it.
1682
+ * Read the rows now, never from the vault's memory (`memorySeconds`): an
1683
+ * answer that must see a change just made (`coffre run`'s plan after the
1684
+ * values it generated were written). Any read may ask it; the rows read are
1685
+ * remembered all the same.
184
1686
  */
185
- settings(): Promise<Settings>;
186
- /** Change the instance's settings: those who run it, never anyone else. */
187
- setSettings(input: SetSettingsInput): Promise<Outcome<{
188
- settings: Settings;
189
- }>>;
1687
+ fresh?: boolean;
1688
+ };
1689
+ /**
1690
+ * The upstream credential a use is for, by its name in the deployment's
1691
+ * configuration (`stripe`), and where the proxy sends the values, which the
1692
+ * use's entry keeps on the app's word, as 0.14.7's app logged it: the host
1693
+ * (`api.stripe.com`, a presigned URL's), and `egress` when the request
1694
+ * leaves through the deployment's egress. Signing, verifying, a cipher and
1695
+ * a tunnel name no host: they send nothing anywhere, or the host is in the
1696
+ * value.
1697
+ */
1698
+ export type Upstream = {
1699
+ credential: string;
1700
+ host?: string;
1701
+ egress?: true;
1702
+ };
1703
+ /**
1704
+ * Why someone reads, which the log shows. `use`: the credential proxy
1705
+ * injects the value into a request and never hands it back. Every other
1706
+ * hands the value back: `reveal` of one key, `run` of an environment,
1707
+ * `compare` of a guess in a dry run, `expose` by the proxy to a person's
1708
+ * own app.
1709
+ */
1710
+ export declare const PURPOSES: readonly ["reveal", "run", "compare", "expose", "use"];
1711
+ export type Purpose = (typeof PURPOSES)[number];
1712
+ /**
1713
+ * One key's value, or why this caller is not given it. `secret` is where the
1714
+ * value is held: a reference's source. `nature` is the one the value opened
1715
+ * under, which its encryption names (`contextOf`), so a row relabelled behind
1716
+ * the vault cannot turn a secret into a plain value: what the proxy leaves
1717
+ * unredacted when an upstream echoes it.
1718
+ */
1719
+ export type UsedValue = {
1720
+ key: string;
1721
+ secret: string;
1722
+ version: number;
1723
+ nature: Nature;
1724
+ value: string;
1725
+ } | {
1726
+ key: string;
1727
+ refused: string;
1728
+ };
1729
+ export type Used = {
1730
+ principal: string;
1731
+ /** The credential's id. */
1732
+ credential: string;
190
1733
  /**
191
- * The instance's access policy (`Policy` in @coffre/core/access): its
192
- * roles, as an Owner edited and made them, and its protected
193
- * environments, as the vault's newest `policy.change` says, by its MAC.
194
- * As it ships, before any. A vault older than 0.10 has none, and the app
195
- * decides as it ships.
1734
+ * The credential's effective end, ISO 8601: the instant the vault starts
1735
+ * refusing it for age, the earliest of its own end, a workload session's
1736
+ * hard end (`notAfter`) and those of the sessions it was narrowed from.
1737
+ * Not `Called.credential.expiresAt`, its own row's end. A grant that ends
1738
+ * sooner, a revoke or a freeze does not move it: what a presigned URL
1739
+ * lasts no longer than, and may outlive those, as on 0.14.7.
196
1740
  */
197
- policy(): Promise<Policy>;
1741
+ expiresAt: string;
1742
+ values: UsedValue[];
1743
+ /** For a workload's session, what only the app can hold its request to: an unsigned upload its binding must allow, a narrowed session's methods and paths. */
1744
+ workload: {
1745
+ binding: string;
1746
+ profile: string;
1747
+ policy: BindingPolicy;
1748
+ constraints: Constraints | null;
1749
+ } | null;
1750
+ };
1751
+ /**
1752
+ * What a use would give: each key's secret, version and nature, or why it
1753
+ * is refused; nothing opened. The nature is the one its rows say, which the
1754
+ * use holds the value to: what `coffre run`'s plan picks the keys it asks
1755
+ * for by, and never what it places a value by, which is the use's.
1756
+ *
1757
+ * For what `coffre run` generates in a personal config, of a key the caller
1758
+ * is given and no other: `versionId`, the version's id, which a write's
1759
+ * `replaces` names (a listing's `versionId`); `recipe`, what made it, null
1760
+ * for a value typed or a reference; `own`, held in the caller's personal
1761
+ * config, not inherited. `personal`: the read found the caller's personal
1762
+ * config of the environment (`@me`), not the environment itself.
1763
+ */
1764
+ export type Peeked = {
1765
+ principal: string;
1766
+ /** The credential's id. */
1767
+ credential: string;
1768
+ personal: boolean;
1769
+ items: ({
1770
+ key: string;
1771
+ secret: string;
1772
+ version: number;
1773
+ nature: Nature;
1774
+ versionId: string;
1775
+ recipe: string | null;
1776
+ own: boolean;
1777
+ } | {
1778
+ key: string;
1779
+ refused: string;
1780
+ })[];
1781
+ };
1782
+ /**
1783
+ * Who a request is: its principal, `user:<email>` or `token:<name>`, the
1784
+ * credential it came in on, and what it holds, as `allows` in
1785
+ * `@coffre/core/access` decides on it: its role in the instance and that
1786
+ * role's scope, its live grants, a token's own scope, the definitions of
1787
+ * the roles it holds and of no other (a role absent from `policy` is one
1788
+ * the caller does not hold, not one that grants nothing to anyone), and
1789
+ * every environment the instance protects.
1790
+ */
1791
+ export type Called = {
1792
+ principal: string;
198
1793
  /**
199
- * Change the policy by one change, its own `policy.change` entry, which
200
- * names it and what it was (docs/design/roles.md):
201
- * - a project or instance role defined, or put back as it ships (null),
202
- * or, one an Owner made, deleted while no grant names it: an Owner of
203
- * the whole instance, and never the Owner role, nor the instance's
204
- * Member;
205
- * - environments of one project protected, by whoever manages its
206
- * environments, before their rows exist too (a fork's); or
207
- * unprotected, by an Owner of the project or of the whole instance
208
- * (`ownsProject`), as far as that project protected them.
209
- * The policy after it, and the newest `policy.change`, which it is as of:
210
- * the change's own, when it changed anything.
1794
+ * `expiresAt` is ISO 8601, the row's own end: a use's `Used.expiresAt`
1795
+ * is the effective one, which a session's hard end and the rows above it
1796
+ * may bring sooner. An MCP connection's access token (kind `mcp`)
1797
+ * says which connection it is under and the scopes it holds, from its
1798
+ * row; no other credential has either. `label` is the one it was made
1799
+ * with: a personal token's, which `GET /me` names it by.
211
1800
  */
212
- changePolicy(input: ChangePolicyInput): Promise<Outcome<{
1801
+ credential: {
1802
+ id: string;
1803
+ kind: string;
1804
+ expiresAt: string;
1805
+ label: string | null;
1806
+ connection?: string;
1807
+ scopes?: McpScope[];
1808
+ };
1809
+ holds: Holdings & {
213
1810
  policy: Policy;
214
- seq: number | null;
215
- }>>;
216
- /**
217
- * Sign the log up to its last entry, in an `audit.checkpoint` entry of
218
- * the vault's, if the chain recomputes from the last checkpoint, the
219
- * vault's entries by their MACs, and that checkpoint's prefix is still
220
- * there, whole. The entry keeps the checkpoint's tally beside it: what a
221
- * walk from the first entry has gathered by the prefix's end (the
222
- * vault's keys, its key batches under way, who is a member and what they
223
- * hold), so that the next checkpoint, and every verification, go on from
224
- * there and read only what is new. A log longer than one walk, as after
225
- * an upgrade from 0.10.0, is signed a stretch a call, behind its head,
226
- * until the checkpoints catch up. Each call also rehashes a stretch of
227
- * what was signed before, round and round, which an entry edited in place
228
- * fails: then it refuses, and every verification reports the refusal.
229
- * A rehash the database fails moves on next time, and `warning` says so;
230
- * a refusal it would have cleared stands meanwhile. The vault reads the log itself: it takes nobody's word for where
231
- * it ends, or for what came before. It checks every member's row too, as
232
- * `access` would, and logs a `vault.tampered` for each one changed around
233
- * it: lists read rows without asking the vault.
234
- */
235
- checkpoint(): Promise<Outcome<{
236
- checkpoint: Checkpoint;
237
- warning?: string;
238
- }>>;
239
- /**
240
- * What the vault's configuration says, which the app shows: the keys its
241
- * checkpoints verify under, by the key id each checkpoint names (the one
242
- * it signs with now, and those of the KEKs it replaced).
243
- */
244
- about(): Promise<{
245
- checkpointKeys: Record<string, CheckpointKey>;
246
- /**
247
- * The emails of those the deployment names Owners of the whole instance
248
- * (`owners`), lowercased: the vault makes them Owners, and refuses to
249
- * demote or remove them. Absent from a vault of 0.5, which names none.
250
- */
251
- owners?: string[];
252
- /**
253
- * @deprecated Always empty: an app of 0.5, deployed after this vault,
254
- * lists and checks root admins here until it is. Gone in 0.7.
255
- */
256
- rootAdmins: [];
257
- }>;
258
- /**
259
- * What an escrowed vault key is checked against: the vault key it wraps
260
- * under now, and each one's check, as the vault wrote it. None of it is
261
- * secret, and the vault answers no guess: a check opens only under its key.
262
- */
263
- keyChecks(): Promise<KeyChecks>;
1811
+ };
264
1812
  /**
265
- * Check the log from a checkpoint's tally, the newest unless `from`
266
- * names another, or the first entry: the vault's entries since by their
267
- * MACs, every checkpoint among them against the prefix it signed, the key
268
- * batches accounted for, and the members and grants replayed on from the
269
- * tally to see that the rows follow. With `to`, a later checkpoint, the
270
- * walk stops at the prefix it signed and must come to the tally it keeps:
271
- * a stretch of the whole log, walked from the first entry a stretch at a
272
- * time. The links and hashes of the chain are the caller's to recompute
273
- * through `upTo`, as the app does first; with none, the vault recomputes
274
- * them itself, no further than one walk. A verdict and nothing else, so
275
- * anyone may ask; the app asks for those who read the whole log
276
- * (`readsWholeLog`).
1813
+ * For a call that asked (`head`): the log's head as the vault last signed
1814
+ * it, read with the caller's rows and held to the vault's MAC; null when
1815
+ * no head stands under it. The audit page proves each entry it shows
1816
+ * against these roots; one past these sizes is proven by nothing here.
277
1817
  */
278
- verifyLog(input: VerifyLogInput): Promise<LogVerification>;
279
- }
1818
+ head?: SignedHead | null;
1819
+ };
1820
+ /**
1821
+ * The log's signed head: how many entries are numbered (`size`), and each
1822
+ * tree's size and root, hex (the changes kept for good, and the uses that
1823
+ * age out, of which `agingFrom` is the first still there). `signedAt` is
1824
+ * ISO 8601. It says the vault signed this log, not that none is newer: the
1825
+ * signer holds the log's end to its own copy every minute, and walks the
1826
+ * rest within a day.
1827
+ */
1828
+ export type SignedHead = {
1829
+ size: number;
1830
+ keptSize: number;
1831
+ keptRoot: string;
1832
+ agingSize: number;
1833
+ agingRoot: string;
1834
+ agingFrom: number;
1835
+ signedAt: string;
1836
+ };
1837
+ /** Why a call is not answered. Nothing it asked was written. */
1838
+ export type Refused = {
1839
+ refused: string;
1840
+ };
1841
+ /**
1842
+ * Every change the vault makes: its operation, and what that one takes.
1843
+ * Each area's are in a file of its own (`changes/`), with what each
1844
+ * answers once it is made.
1845
+ */
1846
+ export type Change = SecretsChanges | PlacesChanges | AccessChanges | SigninChanges | WorkloadChanges | FreezeChanges | McpChanges;
1847
+ export type Answers = SecretsAnswers & PlacesAnswers & AccessAnswers & SigninAnswers & WorkloadAnswers & FreezeAnswers & McpAnswers;
1848
+ /**
1849
+ * Every action the vault writes to the log, an entry's `action`: each
1850
+ * writer's is typed on it, and the audit page keys its sentences on it
1851
+ * (`@coffre/ui`, `TEMPLATES`), so an action added without its sentence,
1852
+ * or a sentence left for one no writer writes, fails the typecheck.
1853
+ */
1854
+ export declare const LOG_ACTIONS: readonly ["secret.read", "secret.write", "secret.loosen", "secret.rename", "secret.refile", "reference.break", "missing.dismiss", "project.create", "project.update", "project.archive", "project.restore", "project.move", "project.delete", "folder.refile", "environment.create", "environment.update", "environment.archive", "environment.restore", "environment.delete", "environment.protect", "environment.unprotect", "upstream.freeze", "upstream.thaw", "member.add", "member.restore", "member.role", "member.remove", "access.grant", "access.revoke", "policy.change", "settings.change", "sign_in", "sign_out", "token.create", "token.revoke", "account.link", "account.unlink", "device.start", "device.approve", "device.deny", "token.exchange", "workload.renew", "token.bind", "token.unbind", "workload.freeze", "workload.unfreeze", "mcp.connect", "mcp.token", "mcp.disconnect", "oauth.register", "mcp.ask", "mcp.approve", "mcp.deny", "upkeep.expire", "vault.adopt"];
1855
+ export type LogAction = (typeof LOG_ACTIONS)[number];
280
1856
  /**
281
1857
  * The vault's entries that change what a member holds: what their row's
282
1858
  * `access_seq` names, and what a finding about them is newer than while it
@@ -302,9 +1878,9 @@ export type RefusalCode =
302
1878
  /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
303
1879
  'bad_claim' |
304
1880
  /**
305
- * A person asked for a sensitive value to be handed back (`handsBack`):
306
- * nobody sees one, Owners included. Their apps use it through the
307
- * credential proxy, and service accounts read it.
1881
+ * A person asked for a sensitive value to be handed back: nobody sees
1882
+ * one, Owners included. Their apps use it through the credential proxy,
1883
+ * and service accounts read it.
308
1884
  */
309
1885
  'sensitive' |
310
1886
  /**
@@ -358,8 +1934,6 @@ export type RefusalCode =
358
1934
  * Asked again on the answer now, it is decided as they are now.
359
1935
  */
360
1936
  'access_changed' |
361
- /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
362
- 'log_broken' |
363
1937
  /**
364
1938
  * A KEK the vault is given does not open what it wrapped: a restore with
365
1939
  * the wrong key, or a key mistyped under the right id. Every key
@@ -413,38 +1987,25 @@ export type WrappedKey = {
413
1987
  bytes: string;
414
1988
  };
415
1989
  /**
416
- * The vault key the vault wraps under now, by provider and ID, and each
417
- * vault key's check, newest first: a known value wrapped under it
418
- * (`KEY_CHECK_VALUE` in `@coffre/core/kek`), in its newest `key.check`
419
- * entry that carries the vault's MAC, at `seq`.
1990
+ * What `about` answers. `kek` is the vault key that wraps every new data
1991
+ * key, `previous` those it still unwraps with, by provider and ID.
1992
+ * `checks` holds the check of each key the vault signs and seals with
1993
+ * (`keyCheckOf` in `@coffre/core/kek`): the one it signs with first, then
1994
+ * those it only verifies with. A check is of a signing key, not of a vault
1995
+ * key, so it names none: with a key service and a `signingKey`, no vault
1996
+ * key has a check at all.
420
1997
  */
421
- export type KeyChecks = {
422
- current: {
423
- kekProvider: string;
424
- kekId: string;
1998
+ export type About = {
1999
+ kek: {
2000
+ provider: string;
2001
+ id: string;
425
2002
  };
426
- checks: (WrappedKey & {
427
- seq: number;
428
- })[];
2003
+ previous: {
2004
+ provider: string;
2005
+ id: string;
2006
+ }[];
2007
+ checks: string[];
429
2008
  };
430
- /**
431
- * Why someone reads: shown in the log, and the same rules apply to each. A
432
- * fork reads to `copy`. The credential proxy reads to `use`, a value it
433
- * injects into a request and never hands back, or to `expose`, one it
434
- * gives a person's app as it is (`coffre run`'s plan).
435
- */
436
- export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
437
- /**
438
- * Whether a read hands values back to whoever asked, which a person never
439
- * gets of a sensitive value: every purpose but the proxy's `use` and a
440
- * fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
441
- * `compare` included, which tells them whether a guess was right, and any
442
- * purpose a later app may name.
443
- */
444
- export declare function handsBack(read: {
445
- purpose: string;
446
- keepsSensitive?: boolean;
447
- }): boolean;
448
2009
  /** Ties the vault's entries to the app's request and audit rows. */
449
2010
  type Correlation = {
450
2011
  requestId?: string | null;
@@ -659,9 +2220,9 @@ export type AdmitInput = Correlation & Through & {
659
2220
  * Left out, an existing member keeps theirs and a new one is a `member`.
660
2221
  * Changing it takes someone who runs the instance, about someone else;
661
2222
  * making someone an Owner, or changing an Owner's, an Owner of the whole
662
- * instance, who may change their own too. It never leaves the instance
663
- * without an Owner of all of it (`last_owner`), nor demotes one the
664
- * deployment names (`owners`; `not_allowed`).
2223
+ * instance (`not_allowed`), who may change their own too. It never leaves
2224
+ * the instance without an Owner of all of it (`last_owner`), nor demotes
2225
+ * one the deployment names (`owners`; `configured_owner`).
665
2226
  */
666
2227
  role?: InstanceRole;
667
2228
  scope?: Scope;
@@ -715,6 +2276,19 @@ export type PolicyChange = {
715
2276
  export declare function policyRevision(seq: number | bigint | null, policy: Pick<Policy, 'protectedIn'>): string;
716
2277
  /** A revision as `policyRevision` writes it. */
717
2278
  export declare const POLICY_REVISION: RegExp;
2279
+ /**
2280
+ * A role's revision, as a change of it is confirmed with
2281
+ * (`policy.change`'s `revision`): a digest of what it holds, its columns in
2282
+ * any order, or of none. The app answers it with a change's preview; the
2283
+ * vault takes the change only while the role's row still says what was
2284
+ * weighed.
2285
+ *
2286
+ * 9c41e07b5d2a8f13 developer, as it ships
2287
+ * 74d0b1e6a9c3f852 no such role
2288
+ */
2289
+ export declare function roleRevision(definition: Pick<RoleDefinition, 'name' | 'description' | 'permissions' | 'protected'> | null): string;
2290
+ /** A revision as `roleRevision` writes it. */
2291
+ export declare const ROLE_REVISION: RegExp;
718
2292
  export type ChangePolicyInput = Correlation & Through & {
719
2293
  actor: string;
720
2294
  change: PolicyChange;
@@ -728,78 +2302,5 @@ export type ChangePolicyInput = Correlation & Through & {
728
2302
  */
729
2303
  revision?: string;
730
2304
  };
731
- /**
732
- * A prefix of the log the vault signed: every entry up to `seq`, the last
733
- * of which has `hash`, which pins every byte before it. Kept as the vault's
734
- * `audit.checkpoint` entry, just after the prefix it signs.
735
- */
736
- export type Checkpoint = {
737
- seq: number;
738
- /** The hash of entry `seq`, hex. */
739
- hash: string;
740
- signedAt: string;
741
- keyId: string;
742
- /** Ed25519 over `checkpointMessage(...)`, base64. */
743
- signature: string;
744
- };
745
- /**
746
- * A public key the vault's checkpoints verify under, base64. One it
747
- * replaced vouches only for checkpoints whose prefix ends before `until`,
748
- * its first entry under the key that replaced it; the one it signs with now
749
- * has none.
750
- */
751
- export type CheckpointKey = {
752
- publicKey: string;
753
- until: number | null;
754
- };
755
- /** An entry of the vault's log, and so the chain up to it. */
756
- export type LogHead = {
757
- seq: number;
758
- hash: string;
759
- };
760
- export type VerifyLogInput = {
761
- /**
762
- * The last entry the app verified, every link and hash up to it
763
- * recomputed and its own entries checked by its key: the vault checks the
764
- * log still holds it, so between them both authors' entries are
765
- * authenticated over the same stretch, and the vault leaves the links to
766
- * the app.
767
- */
768
- upTo?: LogHead | null;
769
- /**
770
- * Where the vault's walk starts: the seq of one of its `audit.checkpoint`
771
- * entries that keeps a tally, or `start`, the first entry. The newest
772
- * such checkpoint when absent, and a vault older than 0.10.1 walks from
773
- * the first entry whatever it says.
774
- */
775
- from?: number | 'start';
776
- /**
777
- * A later checkpoint's entry, whose prefix `upTo` is: the walk ends
778
- * there, and must come to the tally it keeps. The members' rows and the
779
- * key batches are as they are now, not then, so only a walk without one
780
- * holds them to the log.
781
- */
782
- to?: number;
783
- };
784
- /**
785
- * Whether the vault's log holds, with the number of its entries through
786
- * where the walk ended, `through`: `upTo`, the prefix `to` signed, or as
787
- * far as one walk goes. On a failure, the entry where it breaks, or null
788
- * when the chain holds but the members and grants do not follow from it.
789
- * Then `fault` says which, as facts the app can word with names: `reason`
790
- * has only ids. A walk that ends at the present reports live key batches in
791
- * `pending`; overdue ones fail.
792
- */
793
- export type LogVerification = {
794
- ok: true;
795
- entries: number;
796
- pending?: number;
797
- through?: number;
798
- } | {
799
- ok: false;
800
- failedAtSeq: number | null;
801
- reason: string;
802
- fault?: AccessFault;
803
- };
804
2305
  //#endregion
805
- export type { AccessFault, CallerKind, FaultGrant, FaultNames };
2306
+ export type { AccessAnswers, AccessChanges, AccessFault, AccessGrant, Account, AccountLink, AccountUnlink, Bound, CallerKind, CredentialEnd, DeviceDecide, DeviceRedeem, DeviceStart, EnvironmentCopy, EnvironmentCreate, EnvironmentEdit, EnvironmentEdited, Exchanged, FaultGrant, FaultNames, FolderRefile, Forked, FreezeAnswers, FreezeChanges, Frozen, Issued, KeyOutcome, KeyWrite, McpAnswers, McpAsk, McpChanges, McpClient, McpConnect, McpDecide, McpRevoke, McpToken, McpUnasked, MemberPut, MemberRemove, MissingDismiss, Nature, NewBinding, NewCredential, OauthRegister, PlaceDelete, PlaceDeleted, PlacesAnswers, PlacesChanges, ProjectCreate, ProjectEdit, ProjectEdited, ReferenceBreak, Renewed, Replaces, RoleEdit, ScopeInput, SecretPath, SecretRefile, SecretRename, SecretWrite, SecretsAnswers, SecretsChanges, Session, SettingsEdit, Signin, SigninAnswers, SigninChanges, Standing, TokenBind, TokenCreate, TokenExchange, TokenUnbind, Unasked, WorkloadAnswers, WorkloadChanges, WorkloadFreeze, WorkloadProof, WorkloadRenew, WorkloadSignin, WorkloadUnfreeze, WorkloadsUnasked };