@coffre/core 0.15.0 → 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 (70) hide show
  1. package/README.md +1 -1
  2. package/dist/{access-CgQTlUMz.js → access-CF8UG59J.js} +70 -95
  3. package/dist/{access-DqLJjnLM.d.ts → access-ERdGGHG7.d.ts} +45 -64
  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 +3 -1018
  9. package/dist/identity.js +885 -623
  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 +27 -4
  16. package/dist/mcp.js +31 -10
  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 -12
  21. package/dist/schemas.js +16 -14
  22. package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
  23. package/dist/vault.d.ts +1771 -1419
  24. package/dist/vault.js +96 -302
  25. package/dist/{workloads-D049JH0M.d.ts → workloads-CW2dK4AW.d.ts} +1 -9
  26. package/dist/workloads.d.ts +2 -2
  27. package/dist/workloads.js +1 -9
  28. package/package.json +7 -7
  29. package/src/access.ts +63 -95
  30. package/src/changes/access.ts +140 -0
  31. package/src/changes/freezes.ts +40 -0
  32. package/src/changes/mcp.ts +150 -0
  33. package/src/changes/places.ts +219 -0
  34. package/src/changes/secrets.ts +235 -0
  35. package/src/changes/signin.ts +197 -0
  36. package/src/changes/workloads.ts +166 -0
  37. package/src/context.ts +18 -2
  38. package/src/envelope.ts +35 -12
  39. package/src/identity/auth.ts +11 -3
  40. package/src/identity/aws.ts +62 -0
  41. package/src/identity/github-app.ts +45 -24
  42. package/src/identity/index.ts +3 -2
  43. package/src/identity/{profile-rules.ts → profiles.ts} +1 -9
  44. package/src/identity/proofs.ts +306 -0
  45. package/src/identity/signin/config.ts +1 -1
  46. package/src/identity/tokens.ts +10 -3
  47. package/src/identity/verifier.ts +73 -14
  48. package/src/identity/workload-token.ts +4 -0
  49. package/src/identity/workloads.ts +0 -11
  50. package/src/kek/aws-kms.ts +18 -13
  51. package/src/kek/check.ts +16 -46
  52. package/src/kek/index.ts +2 -2
  53. package/src/kek/types.ts +15 -3
  54. package/src/log/index.ts +7 -0
  55. package/src/{audit → log}/tiles.ts +18 -49
  56. package/src/{audit → log}/tree.ts +2 -2
  57. package/src/mcp.ts +36 -9
  58. package/src/schemas.ts +15 -12
  59. package/src/vault.ts +251 -1150
  60. package/dist/merkle.d.ts +0 -456
  61. package/dist/merkle.js +0 -964
  62. package/src/answers.ts +0 -209
  63. package/src/audit/leaf.ts +0 -81
  64. package/src/audit/merkle.ts +0 -13
  65. package/src/audit/note.ts +0 -187
  66. package/src/audit/pair.ts +0 -86
  67. package/src/audit/verify.ts +0 -393
  68. package/src/audit/witness.ts +0 -50
  69. package/src/checkpoint.ts +0 -22
  70. package/src/identity/run-proof.ts +0 -159
package/dist/vault.d.ts CHANGED
@@ -1,4 +1,1491 @@
1
- import { L as ServiceSetting, M as Role, N as RoleDefinition, O as Policy, P as Scope, f as GrantPlace, i as CredentialScope, n as CallerKind, y as InstanceRole } from "./access-DqLJjnLM.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
@@ -62,1133 +1549,310 @@ type FaultNames = {
62
1549
  };
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
- //#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
- //#region src/answers.d.ts
79
- /** A member: `user:<email>` or `token:<name>`. */
80
- export declare const PRINCIPAL: RegExp;
81
- /** A member's row, as `vault_members` holds it, its instance role and scope read (`storedRole` in @coffre/db/grants). */
82
- type MemberFacts = {
83
- status: 'active' | 'removed';
84
- role: InstanceRole;
85
- scope: Scope;
86
- generation: number;
87
- /** Milliseconds since the epoch. */
88
- statusChangedAt: number;
89
- statusChangedBy: string;
90
- };
91
- /** A grant, as `vault_grants` holds it, its environment's project filled in; times in milliseconds since the epoch. */
92
- type GrantFacts = {
93
- projectId: string | null;
94
- environmentId: string | null;
95
- role: string;
96
- expiresAt: number | null;
97
- grantedAt: number;
98
- grantedBy: string;
99
- };
100
- /**
101
- * What `access` answers about `principal`, from their row and their
102
- * grants, lapsed ones too, as of `at`; `tampered` when a row failed the
103
- * vault's check, which only the vault can tell.
104
- */
105
- export declare function answerFrom(principal: string, row: MemberFacts | undefined, held: readonly GrantFacts[], at: number, tampered: boolean, policy: Policy): Access;
106
- /** A member's instance role, as their row has it: service accounts are members, whatever a row says. */
107
- export declare function roleOf(principal: string, row: Pick<MemberFacts, 'role' | 'scope'>): {
108
- role: InstanceRole;
109
- scope: Scope;
110
- };
111
- /** Whether a grant still holds at `at`. */
112
- export declare function live(grant: {
113
- expiresAt: number | null;
114
- }, at: number): boolean;
115
- /** A grant as `access` answers it. */
116
- export declare function view(grant: GrantFacts): Grant;
117
- /**
118
- * What a `policy.change` entry keeps: the roles an Owner edited or made,
119
- * each whole, and the protected environments. A role as it ships is kept by
120
- * none, so a release that changes a default changes it where nobody edited it.
121
- */
122
- type PolicyEdits = {
123
- roles: Record<string, RoleDefinition>;
124
- instanceRoles: Partial<Record<InstanceRole, RoleDefinition>>;
125
- protected: ProtectedPlace[];
126
- };
127
- /**
128
- * A protected environment, with its project's id, what a grant on the whole
129
- * project reaches of it, and when it was protected, by the vault's clock:
130
- * an id with no row ten minutes later is a fork that was never written.
131
- */
132
- type ProtectedPlace = {
133
- projectId: string;
134
- environmentId: string;
135
- at: number;
136
- };
137
- export declare const NO_EDITS: PolicyEdits;
138
- /**
139
- * The policy when the log has some, but none the vault wrote within reach:
140
- * whoever inserted rows may have hidden an Owner's narrowing, so no role
141
- * holds anything, a service account's neither, but Owner, which holds
142
- * everything always and so may write the policy again.
143
- */
144
- export declare const CLOSED_POLICY: Policy;
145
- /** An environment a policy names, as the policy reads it. */
146
- type PolicyEnvironment = {
147
- slug: string | null;
148
- deleted: boolean;
149
- };
150
- /**
151
- * The policy the newest `policy.change` says, from its metadata, as of
152
- * `at`, with the rows of the environments it protects: none for no entry,
153
- * the roles as they ship; and closed for one whose edits do not hold.
154
- */
155
- export declare function policyFrom(metadata: string | null, rows: ReadonlyMap<string, PolicyEnvironment>, at: number): {
156
- policy: Policy;
157
- edits: PolicyEdits;
158
- readable: boolean;
159
- };
160
- /** A policy entry's edits, checked as the vault wrote them, or null for any that does not hold. */
161
- export declare function readEdits(stored: {
162
- policy?: unknown;
163
- }): PolicyEdits | null;
164
- /**
165
- * The policy `edits` say as of `at`: the roles as they ship, each edited
166
- * one replaced and each made one added; and the protected environments, but
167
- * for those deleted since, the project around one's included: a deleted
168
- * prod protects nothing, and holds nobody back from giving a service
169
- * account a role on all of its project (`givesService`). A fork's id with
170
- * no row yet stays, protected before it is written, ten minutes: one with
171
- * none after that is a fork refused or abandoned, never written. Each
172
- * keeps its slug, which a scoped instance role's filters read. The edits
173
- * keep them all: no write is needed.
174
- */
175
- export declare function livePolicy(rows: ReadonlyMap<string, PolicyEnvironment>, edits: PolicyEdits, at: number): Policy;
176
- /** The settings before anyone changed them: people set up service accounts anywhere they hold access. */
177
- export declare const DEFAULT_SETTINGS: Settings;
178
- /** The settings when the log has some, but none the vault wrote within reach: people set up no service accounts. */
179
- export declare const CLOSED_SETTINGS: Settings;
180
- /** The settings the newest `settings.change` says, from its metadata: none for no entry, the default; closed for one that does not hold. */
181
- export declare function settingsFrom(metadata: string | null): Settings;
182
- //#endregion
183
- //#region src/vault.d.ts
184
- /**
185
- * The vault as the app sees it: the contract between `@coffre/server` and
186
- * `@coffre/vault`, kept in core so that neither side owns it. Every argument
187
- * and result is plain JSON: strings, numbers, booleans, arrays and objects,
188
- * never a Buffer, a Date, a class or a function. So it crosses a Workers RPC
189
- * boundary, or a process boundary later, as it is, and the in-process
190
- * transport proves it by round-tripping everything through JSON.
191
- *
192
- * The app says who is asking and the vault decides. The app never holds a
193
- * key: it encrypts a value under a fresh data key, has the vault wrap that
194
- * key, and stores the result; to read, it names stored versions and the
195
- * vault loads their keys itself.
196
- *
197
- * Decisions come back as values: `{ ok: false, refusal }` for a refusal, which
198
- * the vault has already logged. Only a fault (a bug, the store down) throws.
199
- */
200
- export interface Vault {
201
- /**
202
- * Unwrap data keys for `principal`: all of them, or none. Given the
203
- * revision of an answer of `access` the app decided the read on
204
- * (`accessRevision`), only while the principal's access is still that
205
- * one, under their row and the head the decision holds: otherwise it
206
- * refuses `access_changed` and logs no read, and says, by naming it back,
207
- * that it checked. A vault older than 0.14.1 names none: it checked none.
208
- */
209
- unwrap(input: UnwrapInput): Promise<Outcome<Unwrapped>>;
210
- /**
211
- * Wrap fresh data keys for new versions `principal` writes: all, or none.
212
- * `seqs` are the `key.wrap` entries, one per key, which the app's
213
- * `secret.write` entries name as related. `sensitive` says, per key,
214
- * whether its wrap binds it as sensitive: a vault older than 0.10 answers
215
- * none, binding none, and the app stores no sensitive version it wrapped.
216
- */
217
- wrap(input: WrapInput): Promise<Outcome<Wrapped>>;
218
- /**
219
- * Wrap existing data keys again for new versions of the same secrets,
220
- * under the current key: restoring an old value, or making one stricter.
221
- * It needs a write grant, not a read one, since the key never leaves the
222
- * vault. A new version is never less sensitive than the one it is made
223
- * from, or than its secret's newest: a value is made looser only by
224
- * being written again (`invalid`). Except one: a key's current sensitive
225
- * value made a secret, in place, by an Owner of its project, or of the
226
- * whole instance, on no credential's scope (`ownsProject`; `not_allowed`
227
- * for anyone else), its entry saying `was: 'sensitive'`.
228
- */
229
- rewrap(input: RewrapInput): Promise<Outcome<Wrapped>>;
230
- /**
231
- * Make secrets references to others: whoever can read the holder's
232
- * environment reads the source through it (docs/design/environments.md).
233
- * The vault checks that `principal` reads each source and writes each
234
- * holder, by their own grants, and logs a `reference.create` per item:
235
- * that entry, under the vault's MAC, is the reference. `seqs` are the
236
- * entries, which the app stores beside each reference and names when it
237
- * reads through one (`UnwrapInput`'s `via`). All, or none.
238
- */
239
- reference(input: ReferenceInput): Promise<Outcome<{
240
- seqs: number[];
241
- }>>;
242
- /**
243
- * End references, each with a `reference.end` naming its creation:
244
- * `replaced` when the holder gets a value of its own, which takes write on
245
- * the holder; `broken` otherwise, which takes write on the holder, or
246
- * managing the source's project's access. An ended reference reads no
247
- * more, whatever any row says. All, or none.
248
- */
249
- endReferences(input: EndReferencesInput): Promise<Outcome<{
250
- seqs: number[];
251
- }>>;
252
- /**
253
- * What one principal holds right now: the app asks once per request,
254
- * unless the request reads values on an answer it kept (`accessRevision`),
255
- * and at sign-in for each verified email. A decision, its rows checked:
256
- * lists of who holds what read the rows themselves, and need not ask.
257
- * A person the vault's `owners` names who is no Owner of all of it
258
- * becomes one here, logged (`reason: 'owners'`).
259
- */
260
- access(principal: string): Promise<Access>;
261
- /**
262
- * Set roles at several places for one principal: all of it, or none.
263
- * With `admit`, a service account that is not a member is admitted
264
- * first, in the same decision, as `admit` would: `admitted` says so.
265
- */
266
- setAccess(input: SetAccessInput): Promise<Outcome<{
267
- changes: AccessChange[];
268
- admitted?: Admitted;
269
- }>>;
270
- /**
271
- * Add a member, bring back a removed one, or change a person's instance
272
- * role and its scope. `generation` is theirs now: sessions and tokens of
273
- * an earlier one are dead.
274
- */
275
- admit(input: AdmitInput): Promise<Outcome<Admitted>>;
276
- /**
277
- * Remove a member: revoke every grant and refuse them until admitted
278
- * again, from `generation` on. An Owner, only an Owner of the whole
279
- * instance removes, and never the last.
280
- */
281
- remove(input: RemoveInput): Promise<Outcome<{
282
- revoked: Grant[];
283
- generation: number;
284
- }>>;
285
- /**
286
- * The instance's settings, as the vault's newest `settings.change` entry
287
- * says, by its MAC: an entry is where they live, so each change is logged
288
- * by being made. Everywhere, until someone narrows it.
289
- */
290
- settings(): Promise<Settings>;
291
- /** Change the instance's settings: those who run it, never anyone else. */
292
- setSettings(input: SetSettingsInput): Promise<Outcome<{
293
- settings: Settings;
294
- }>>;
295
- /**
296
- * The instance's access policy (`Policy` in @coffre/core/access): its
297
- * roles, as an Owner edited and made them, and its protected
298
- * environments, as the vault's newest `policy.change` says, by its MAC.
299
- * As it ships, before any. A vault older than 0.10 has none, and the app
300
- * decides as it ships.
301
- */
302
- policy(): Promise<Policy>;
303
- /**
304
- * Change the policy by one change, its own `policy.change` entry, which
305
- * names it and what it was (docs/design/roles.md):
306
- * - a project or instance role defined, or put back as it ships (null),
307
- * or, one an Owner made, deleted while no grant names it: an Owner of
308
- * the whole instance, and never the Owner role, nor the instance's
309
- * Member;
310
- * - environments of one project protected, by whoever manages its
311
- * environments, before their rows exist too (a fork's); or
312
- * unprotected, by an Owner of the project or of the whole instance
313
- * (`ownsProject`), as far as that project protected them.
314
- * The policy after it, and the newest `policy.change`, which it is as of:
315
- * the change's own, when it changed anything.
316
- */
317
- changePolicy(input: ChangePolicyInput): Promise<Outcome<{
318
- policy: Policy;
319
- seq: number | null;
320
- }>>;
321
- /**
322
- * Sign the log up to its last entry, in an `audit.checkpoint` entry of
323
- * the vault's, if the chain recomputes from the last checkpoint, the
324
- * vault's entries by their MACs, and that checkpoint's prefix is still
325
- * there, whole. The entry keeps the checkpoint's tally beside it: what a
326
- * walk from the first entry has gathered by the prefix's end (the
327
- * vault's keys, its key batches under way, who is a member and what they
328
- * hold), so that the next checkpoint, and every verification, go on from
329
- * there and read only what is new. A log longer than one walk, as after
330
- * an upgrade from 0.10.0, is signed a stretch a call, behind its head,
331
- * until the checkpoints catch up. Each call also rehashes a stretch of
332
- * what was signed before, round and round, which an entry edited in place
333
- * fails: then it refuses, and every verification reports the refusal.
334
- * A rehash the database fails moves on next time, and `warning` says so;
335
- * a refusal it would have cleared stands meanwhile. The vault reads the log itself: it takes nobody's word for where
336
- * it ends, or for what came before. It checks every member's row too, as
337
- * `access` would, and logs a `vault.tampered` for each one changed around
338
- * it: lists read rows without asking the vault.
339
- */
340
- checkpoint(): Promise<Outcome<{
341
- checkpoint: Checkpoint;
342
- warning?: string;
343
- }>>;
344
- /**
345
- * What the vault's configuration says, which the app shows: the keys its
346
- * checkpoints verify under, by the key id each checkpoint names (the one
347
- * it signs with now, and those of the KEKs it replaced).
348
- */
349
- about(): Promise<{
350
- checkpointKeys: Record<string, CheckpointKey>;
351
- /**
352
- * The emails of those the deployment names Owners of the whole instance
353
- * (`owners`), lowercased: the vault makes them Owners, and refuses to
354
- * demote or remove them. Absent from a vault of 0.5, which names none.
355
- */
356
- owners?: string[];
357
- /**
358
- * @deprecated Always empty: an app of 0.5, deployed after this vault,
359
- * lists and checks root admins here until it is. Gone in 0.7.
360
- */
361
- rootAdmins: [];
362
- /**
363
- * `'0.15'` when the vault keeps 0.15's log: the app then writes the
364
- * changes to its rows through it (`prepare`). Absent before 0.15.
365
- */
366
- log?: '0.15';
367
- /**
368
- * `true` when the vault also answers 0.15's uses (`use`): its log is
369
- * 0.15's and it has the hot path's login. The app then opens each value
370
- * through a use (docs/design/0.15-plan.md, PR 5b). Absent otherwise.
371
- */
372
- uses?: true;
373
- /**
374
- * `true` when the vault also answers a request's several keys in one call (`useMany`; T167). Said here, as a
375
- * Worker's stub answers any method's name: a vault older than this app, mid-deploy, says nothing, and the app makes
376
- * a use a key. Absent otherwise.
377
- */
378
- batchUses?: true;
379
- /**
380
- * `true` when the vault says whether its checkpointer seals (`sealing`; T169), which `/readyz` asks. Said here,
381
- * as a Worker's stub answers any method's name: of a vault older than this app, mid-deploy, readiness asks nothing.
382
- */
383
- sealing?: true;
384
- /**
385
- * `true` when the vault makes sign-ins through trust bindings and revokes
386
- * credentials itself (`signIn`, `revokeCredential`; T149): its log is
387
- * 0.15's. Said here, as a Worker's stub answers any method's name.
388
- * Absent otherwise.
389
- */
390
- credentials?: true;
391
- /** `true` when the vault issues tokens itself too (`issueToken`; T149, PR 2). Absent otherwise. */
392
- issues?: true;
393
- /** `true` when the vault makes and ends trust bindings itself, and signs in through none it did not seal (`changeBindings`; T149, PR 3a). Absent otherwise. */
394
- binds?: true;
395
- }>;
396
- /**
397
- * What an escrowed vault key is checked against: the vault key it wraps
398
- * under now, and each one's check, as the vault wrote it. None of it is
399
- * secret, and the vault answers no guess: a check opens only under its key.
400
- */
401
- keyChecks(): Promise<KeyChecks>;
402
- /**
403
- * Check the log from a checkpoint's tally, the newest unless `from`
404
- * names another, or the first entry: the vault's entries since by their
405
- * MACs, every checkpoint among them against the prefix it signed, the key
406
- * batches accounted for, and the members and grants replayed on from the
407
- * tally to see that the rows follow. With `to`, a later checkpoint, the
408
- * walk stops at the prefix it signed and must come to the tally it keeps:
409
- * a stretch of the whole log, walked from the first entry a stretch at a
410
- * time. The links and hashes of the chain are the caller's to recompute
411
- * through `upTo`, as the app does first; with none, the vault recomputes
412
- * them itself, no further than one walk. A verdict and nothing else, so
413
- * anyone may ask; the app asks for those who read the whole log
414
- * (`readsWholeLog`).
415
- */
416
- verifyLog(input: VerifyLogInput): Promise<LogVerification>;
417
- /**
418
- * 0.15's use (docs/design/0.15-plan.md, PR 5): one key read on one
419
- * credential, logged as its request and decided on what one statement
420
- * read, the value's data key handed back once its entry has committed.
421
- * Behind the 0.15 switch: the app opens each value through it when the
422
- * vault says so (`about().uses`). A vault without the hot path's login
423
- * has none.
424
- */
425
- use?(input: UseInput): Promise<UseOutcome>;
426
- /**
427
- * 0.15's use as the request names it, one call (T145, PR B; formal/Probing.tla): the vault finds the ids of what it
428
- * names, from its own cache or with one read on a miss, uses the key by them, and answers with the rows the app checks
429
- * (`NamedUseOutcome.app`) and what it decided the caller holds (`standing`). A key the place does not hold, and a plain
430
- * value, it decides on the caller's standing there, logging nothing. Absent from a vault without 0.15's uses.
431
- */
432
- useNamed?(input: NamedUseInput): Promise<NamedUseOutcome>;
433
- /**
434
- * A request's several keys as one call (T167, B2; formal/Batching.tla): each key's use made as `use` makes it, in the
435
- * request's order, in one statement, and decided on what it read; a second call, only once every key is allowed, for
436
- * those that take the principal's lock. All or nothing: every value, or the first key refused, or busy. Absent from a
437
- * vault without 0.15's uses (`about().batchUses` says whether it has it).
438
- */
439
- useMany?(input: UseManyInput): Promise<UseManyOutcome>;
440
- /**
441
- * 0.15's log (docs/design/0.15-plan.md, "As built: PR 4b"): the changes
442
- * the app is about to write to objects its own rows hold (credentials,
443
- * keys, environments), each sealed, as entries the app's transaction
444
- * commits with its rows (`app_change`, migration 0025), before it asks.
445
- * The vault reads nothing: it checks each row's columns as the app read
446
- * them against their seal (`tampered` if the vault never made it), works
447
- * out the changes that turn them into the columns the app will write, and
448
- * seals what they leave. Whether each seal is still its object's newest
449
- * is the transaction's to check, under the fence. Only with 0.15's log on
450
- * (`about().log`); a vault older than 0.15 has none.
451
- */
452
- prepare?(input: PrepareInput): Promise<Outcome<Prepared>>;
453
- /**
454
- * Answers once the log's entry `number` is sealed in a signed checkpoint
455
- * and, if a witness is configured, witnessed or past its 2 s (R51): what a
456
- * change the app committed waits for before it answers. Only with 0.15's
457
- * log on.
458
- */
459
- waitSealed?(input: {
460
- number: string;
461
- }): Promise<Outcome<{
462
- witnessed: boolean | null;
463
- }>>;
464
- /**
465
- * 0.15 (T149, D146; docs/design/credential-lifecycle.md): a sign-in
466
- * through a trust binding, a CI run's or a workload's, made by the vault
467
- * in one statement (`sign_in`, migration 0034; formal/Lifecycle.tla).
468
- * The app verifies the proof and names the binding as it read it; the
469
- * vault makes the credential's object from those columns, and the
470
- * statement goes ahead only while they are the binding's row, its
471
- * account active at its generation, its rate not spent and the token
472
- * not, under their locks: the issue lock, never the fence, so no use
473
- * waits on it (R58), and no 0.14 head. No 0.14 entry either: the change
474
- * records the sign-in (D147). Answers once it is sealed (R51). Only with
475
- * 0.15's log on.
476
- */
477
- signIn?(input: SignInInput): Promise<SignInOutcome>;
478
- /**
479
- * 0.15 (T149): a credential revoked by the vault in one statement
480
- * (`revoke_credential`, migration 0034), from its columns as the app
481
- * read them and their seal: under its row's lock and the fence, held for
482
- * the statement's work alone (RevokeTakesFence). The app has weighed who
483
- * may. Answers once sealed (R51). Only with 0.15's log on.
484
- */
485
- revokeCredential?(input: RevokeCredentialInput): Promise<RevokeCredentialOutcome>;
486
- /**
487
- * 0.15 (T149, PR 2): a token issued by the vault, which weighs it itself
488
- * (`issue_token`, migration 0036; formal/Lifecycle.tla's issue): a
489
- * service account's token, a person's personal token, or a handle. The
490
- * app names the scope it worked out and the row it would hand out; the
491
- * vault reads the issuer, the account and the credential the request came
492
- * in on, decides with the rules of `@coffre/core/access` whether the
493
- * issuer may give that scope (R15, R32), and then writes it in one
494
- * statement that holds those rows shared and goes ahead only while they
495
- * are as it read them (IssuerLocked, IssuerCAS). Nothing held between
496
- * the two; the issue lock, never the fence (R58). Answers once sealed.
497
- */
498
- issueToken?(input: IssueTokenInput): Promise<IssueTokenOutcome>;
499
- /**
500
- * With 0.15's log, a service's trust bindings changed by the vault itself
501
- * (T149, PR 3a; D148): the binding a manager makes, weighed as a service
502
- * token's issue is (who may give the account that scope, R15, R32), and
503
- * those it replaces ended, with the credentials each issued; or, making
504
- * none, an unbind. One statement, which holds what it read as read;
505
- * answers once sealed. A sign-in takes only a binding the vault sealed.
506
- */
507
- changeBindings?(input: ChangeBindingsInput): Promise<ChangeBindingsOutcome>;
1552
+ //#endregion
1553
+ //#region src/vault.d.ts
1554
+ /**
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.
1562
+ *
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.
1567
+ *
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.
1573
+ */
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>;
508
1577
  /**
509
- * 0.15's cutover from 0.14 (docs/design/0.15-plan.md, PR 9;
510
- * formal/Migration015.tla): once, before 0.15's log serves anything, every
511
- * object 0.14 left sealed as 0.14 accepts it (`genesis`), and the log's
512
- * first `cutover` change naming 0.14's last head (the anchor). Without
513
- * `input`, whether it is done, and if not, where 0.14's chain is
514
- * verified from (its newest checkpoint's prefix), for the app to check
515
- * its own entries from there. With `input`, what the app vouches for under
516
- * its key, which the vault never holds: it holds each row to it under its
517
- * locks. Once done, done for good: a second call finds the marker.
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`).
518
1581
  */
519
- cutover?(input?: CutoverInput): Promise<CutoverOutcome>;
1582
+ peek(input: UseInput): Promise<Peeked | Refused>;
520
1583
  /**
521
- * Check 0.15's log (docs/design/0.15-plan.md, PR 8), as the audit page
522
- * does on every visit: the newest signed pair, held to the pairs held
523
- * outside, and every entry after it by its MAC and request, a tick's
524
- * worth (R25). Nothing walks the whole log on a request (D145). With
525
- * 0.14's log alone, `kept` false; a vault older than 0.15 has none.
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.
526
1587
  */
527
- verifyTrees?(): Promise<TreeVerification>;
1588
+ caller(input: Presented & {
1589
+ head?: boolean;
1590
+ }): Promise<Called | Refused>;
528
1591
  /**
529
- * The reads' listing held to 0.15's log, a stretch a call (T166): from
530
- * `start`, then each `next`, the uses the log sealed derived again and
531
- * held to the reads the pages list, each read and each place it was read
532
- * at. For whoever checks the whole log (`coffre verify log`), never a
533
- * page. `kept` false with 0.14's log alone.
1592
+ * Make a change: one operation, named as its log entry's action is, with
1593
+ * its input. All of it, or none.
534
1594
  */
535
- verifyReads?(input: {
536
- from: string;
537
- }): Promise<ReadsVerification>;
1595
+ change<O extends Change['op']>(input: Asked<O>): Promise<{
1596
+ answer: Answers[O];
1597
+ } | Refused>;
538
1598
  /**
539
- * Which of these entries of 0.15's log, as a page of the audit log read
540
- * them, the vault does not vouch for: its MAC, under any of the vault's
541
- * signing keys, as its seals are checked, does not hold over the columns
542
- * shown (T166). The audit pages list 0.15's changes and uses only with
543
- * this check, and mark one it names as forged: written or edited around
544
- * coffre. Pure CPU, no read; at most `VOUCHED_AT_ONCE` entries a call.
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.
545
1606
  */
546
- vouch?(input: VouchInput): Promise<{
547
- forged: string[];
548
- }>;
1607
+ weigh<O extends Exclude<Change['op'], Unasked | WorkloadsUnasked | McpUnasked>>(input: Asked<O>): Promise<{
1608
+ answer: Answers[O];
1609
+ } | Refused>;
549
1610
  /**
550
- * With 0.15's log, whether its checkpointer seals (T169): open, its last
551
- * tick ended well, and within the last few seconds. What `/readyz` asks,
552
- * since a change answers only once sealed (R51). Bounded: a checkpointer
553
- * that does not answer is said not to seal, at once.
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.
554
1615
  */
555
- sealing?(): Promise<Sealing>;
1616
+ about(): Promise<About>;
556
1617
  }
557
- /** Whether 0.15's checkpointer seals, and if not, why (`Vault.sealing`). */
558
- export type Sealing = {
559
- ok: true;
560
- } | {
561
- ok: false;
562
- reason: string;
563
- };
564
- /**
565
- * What the error of a change says when the change committed but its seal
566
- * did not come in time (T169): the checkpointer stalled, or cannot be
567
- * reached. Its words are the contract, since only an error's message
568
- * crosses Workers' RPC: the app answers 503 with Retry-After
569
- * (`isUnsealed`), and the change is in force.
570
- */
571
- export declare const UNSEALED = "was committed, but not sealed in time";
572
- /** Whether `error`, or one of its causes, is a change's seal that did not come in time (`UNSEALED`). */
573
- export declare function isUnsealed(error: unknown): boolean;
574
- /** The most entries one `vouch` call checks: a page of the audit log lists a few hundred at most. */
575
- export declare const VOUCHED_AT_ONCE = 2000;
576
- /** Entries of 0.15's log to vouch for, each with every column its MAC covers, bytes in hex, its number as text. */
577
- export type VouchInput = {
578
- entries: VouchedEntry[];
579
- };
580
- export type VouchedEntry = {
581
- tree: 'changes';
582
- number: string;
583
- at: number;
584
- requestId: string;
585
- object: string;
586
- actor: string;
587
- payload: string;
588
- seal: string | null;
589
- mac: string;
590
- } | {
591
- tree: 'uses';
592
- number: string;
593
- at: number;
594
- requestId: string;
595
- credential: string;
596
- secret: string;
597
- purpose: number;
598
- place: string | null;
599
- mac: string;
600
- } |
601
- /** A read as the projector wrote it (`log_reads`, T166): its MAC covers its number too. */
602
- {
603
- tree: 'reads';
604
- number: string;
605
- at: number;
606
- credential: string;
607
- purpose: number;
608
- principal: string;
609
- secret: string;
610
- environment: string;
611
- project: string;
612
- place: string | null;
613
- source: string | null;
614
- sourceEnvironment: string | null;
615
- sourceProject: string | null;
616
- version: string | null;
617
- mac: string;
618
- } |
619
- /** The projection's cursor (`log_reads_cursor`, T166), named `cursor` in the answer: whether the pages may say reads are whole up to it. */
620
- {
621
- tree: 'cursor';
622
- number: 'cursor';
623
- through: string;
624
- pair: string;
625
- at: number;
626
- mac: string | null;
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;
627
1624
  };
628
1625
  /**
629
- * 0.15's log as its check found it. `problems` names what does not hold,
630
- * each at its entry where it has one: a checkpoint not signed, or not the
631
- * one held outside; an entry whose MAC fails, or under another's request.
632
- * Numbers are decimal text: the log's are 64-bit.
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.
633
1629
  */
634
- export type ReadsVerification = {
635
- kept: false;
636
- } | {
637
- kept: true;
638
- /** Nothing wrong found in the stretch. */
639
- ok: boolean;
640
- problems: string[];
641
- /** The entry the stretch checked through, and how far the projector has listed. */
642
- through: string;
643
- listed: string;
644
- /** Where the next stretch starts; null at the projector's cursor, or on a problem that stops the check. */
645
- next: string | null;
646
- };
647
- export type TreeVerification = {
648
- kept: false;
649
- } | {
650
- kept: true;
651
- /** Checked to the head, and nothing wrong found. */
652
- ok: boolean;
653
- problems: string[];
654
- /** The newest pair checked, and when it was signed (ms); null before the first. */
655
- checkpoint: {
656
- upto: string;
657
- at: number;
658
- } | null;
659
- /** The entries above the newest pair it checked. */
660
- unsealed: number;
1630
+ export type Presented = Trace & {
1631
+ /** The SHA-256 of the token the request presented, in lowercase hex. */
1632
+ token: string;
661
1633
  /**
662
- * Whether more lie there than a check reads (`ABOVE_NEWEST`, 2,000): a
663
- * checkpointer behind. Not checked to the head, so `ok` is false; no
664
- * problem either, and never a break of the log.
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.
665
1637
  */
666
- capped: boolean;
1638
+ proof: string | null;
667
1639
  };
668
1640
  /**
669
- * The columns of a row the app writes that a decision of 0.15's reads, as
670
- * the vault's objects take them (packages/vault/src/objects.ts): times in
671
- * ms since the epoch, uuids as text, JSON as stored.
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.
672
1644
  */
673
- export type CredentialColumns = {
674
- id: string;
675
- principal: string;
676
- kind: string;
677
- /** Its scope as stored, JSON; null for a session's. */
678
- scope: string | null;
679
- revoked: boolean;
680
- /** The earlier of its expiry and its hard end, if any, in whole ms: a stored time's sub-millisecond part dropped, never rounded. */
681
- expiresAt: number | null;
682
- /** Its account's generation when it was issued (`credentials.generation`). */
683
- generation: number;
684
- };
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;
685
1648
  /**
686
- * An MCP connection's (`mcp_connections`), as its object takes them (T147):
687
- * whose it is, at which generation of their account it was approved, its
688
- * end, and whether it was revoked. What a refresh moves (its tokens' hashes)
689
- * and its last use are no part of it.
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.
690
1661
  */
691
- export type ConnectionColumns = {
692
- id: string;
693
- principal: string;
694
- generation: number;
695
- /** Its `expires_at`, in whole ms: a stored time's sub-millisecond part dropped, never rounded. */
696
- expiresAt: number;
697
- revoked: boolean;
698
- };
699
- /** One object's change, as the app will write it: its columns before (null: it makes the object), their seal, and after. */
700
- export type ObjectChange = ChangeOf<'credential', CredentialColumns, CredentialColumns> | ChangeOf<'connection', ConnectionColumns, ConnectionColumns> |
701
- /**
702
- * A key's: null after, archived or erased (no object). `restores`: an
703
- * archived key unarchived, `after` its rows as read: the vault holds them
704
- * to the object its log last sealed, and refuses another (`stale`).
705
- */
706
- (ChangeOf<'secret', SecretColumns, SecretColumns | null> & {
707
- restores?: true;
708
- }) | ChangeOf<'environment', EnvironmentColumns, EnvironmentColumns>;
709
- type ChangeOf<K extends string, Before, After> = {
710
- kind: K;
711
- id: string;
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;
712
1681
  /**
713
- * As the app read the row, with its seal: null for no object (no row, or
714
- * a key archived); a null seal, a row the vault never sealed (0.14's,
715
- * before the cutover).
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.
716
1686
  */
717
- before: {
718
- columns: Before;
719
- seal: string | null;
720
- } | null;
721
- after: After;
722
- };
723
- /** The version a key's value is: its ids, its nature and its wrapped data key; a plain one's text. Never its ciphertext. */
724
- export type VersionColumns = {
725
- id: string;
726
- sensitive: boolean;
727
- /** A plain value's text, which it is (no data key the vault opens); null for any other. Its object holds its digest. */
728
- plaintext: string | null;
729
- kekProvider: string;
730
- kekId: string;
731
- kekVersion: string;
732
- /** The wrapped data key, base64. */
733
- wrappedDek: string;
1687
+ fresh?: boolean;
734
1688
  };
735
1689
  /**
736
- * A live key's columns (`secrets`): where it is, its current version, or,
737
- * for a reference, the source its newest `secret_references` row names
738
- * while it has no version of its own, and that row's id (both null for a
739
- * key with a value, and for one whose newest reference row has ended:
740
- * `ended_at`).
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.
741
1697
  */
742
- export type SecretColumns = {
743
- id: string;
744
- projectId: string;
745
- environmentId: string;
746
- source: string | null;
747
- reference: string | null;
748
- version: VersionColumns | null;
749
- };
750
- /** An environment's columns (`environments`). Its slug as stored: a deleted one's carries a tombstone, `dev~deleted-…`. */
751
- export type EnvironmentColumns = {
752
- id: string;
753
- projectId: string;
754
- slug: string;
755
- owner: string | null;
756
- parentId: string | null;
757
- /** Null until the cutover writes it (0022): not protected. */
758
- protected: boolean | null;
759
- /** Its own `archived_at`. */
760
- archived: boolean;
761
- /** Its project's: 0.14 takes an environment of an archived project as archived. */
762
- projectArchived: boolean;
763
- };
764
- export type PrepareInput = {
765
- /** Who makes the changes, as their entries name them: `user:…`, `token:…`, or the app's own (`coffre`). */
766
- actor: string;
767
- changes: ObjectChange[];
1698
+ export type Upstream = {
1699
+ credential: string;
1700
+ host?: string;
1701
+ egress?: true;
768
1702
  };
769
1703
  /**
770
- * A change sealed, for the app's transaction to commit (`app_change`): its
771
- * entry's fields, the seal it moves the row from and to, and its MAC, bytes
772
- * in base64. A row the vault never sealed is the log's to leave alone until
773
- * the cutover: its call (`requestId` null) only checks, under the fence,
774
- * that the log has no change of its object either.
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.
775
1709
  */
776
- export type PreparedChange = {
777
- kind: ObjectChange['kind'];
778
- id: string;
779
- requestId: string | null;
780
- at: number;
781
- /** The object's key in the log (`log_object`). */
782
- object: string;
783
- actor: string;
784
- payload: string | null;
785
- sealFrom: string | null;
786
- seal: string | null;
787
- mac: string | null;
788
- /** An unarchive's: the seal of the object it restores, which must still be its log's newest sealed one; else null. */
789
- restores: string | null;
790
- };
791
- export type Prepared = {
792
- changes: PreparedChange[];
793
- };
1710
+ export declare const PURPOSES: readonly ["reveal", "run", "compare", "expose", "use"];
1711
+ export type Purpose = (typeof PURPOSES)[number];
794
1712
  /**
795
- * A sign-in through a trust binding (`Vault.signIn`). Times in ms since the
796
- * epoch, bytes in base64.
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.
797
1718
  */
798
- export type SignInInput = {
799
- /** The account it signs in as, `token:<id>`. */
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 = {
800
1730
  principal: string;
1731
+ /** The credential's id. */
1732
+ credential: string;
801
1733
  /**
802
- * The binding as the app read it, with its seal: the vault decides only
803
- * on one whose seal is its own (PR 3a), and the statement holds the row
804
- * to it and to its object's newest change.
805
- */
806
- binding: {
807
- columns: BindingColumns;
808
- seal: string | null;
809
- };
810
- /** The credential the app hands out once made: its row, the app's MAC over it (`auth_mac`) with it. */
811
- credential: SignInCredential;
812
- /** The id of the app's log key, under whose key the MAC was made: refused once the app has rotated from it (`retired`). */
813
- appKey: string;
814
- /** The ID token's signing input's hash, spent once; null for a proof that spends none. */
815
- spent: string | null;
816
- /**
817
- * The last instant the proof holds by its own times, ms (an ID token's
818
- * `exp` and its `iat`'s hour, each with their tolerance): checked again
819
- * in the statement, by the database's clock. Null: its credential's
820
- * `notAfter` bounds it.
821
- */
822
- validUntil: number | null;
823
- /** What the change records of the sign-in besides (D147): the proof, its issuer, and the run's claims. */
824
- record: {
825
- proof: string;
826
- issuer: string;
827
- run: Record<string, string | number>;
828
- };
829
- /**
830
- * The run's ID token, for the vault to verify itself (D148, PR 3b), when
831
- * its sealed binding carries the issuer's keys (its `jwksUri` their
832
- * digest, as a Kubernetes cluster's does), with those keys as its row
833
- * keeps them; the vault then takes `spent`, `validUntil` and `record.run`
834
- * from the token, not from the app. Null for a binding of keys its issuer
835
- * publishes, which the vault does not fetch (it asks no issuer anything),
836
- * and for a proof that is no ID token (an AWS signed request):
837
- * the app verifies those, so a compromised app could sign a run in
838
- * through such a binding, within its limits.
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.
839
1740
  */
840
- idToken: {
841
- token: string;
842
- jwks: string;
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;
843
1749
  } | null;
844
- /** A workload's DPoP proof, whose key the session is bound to, which the vault verifies; null for a CI run's sign-in. */
845
- dpop: string | null;
846
1750
  };
847
1751
  /**
848
- * A trust binding's columns as its object takes them (T149, PR 3a): what a
849
- * sign-in through it decides on. Its keys by `jwksUri` (the issuer's
850
- * discovered URL, or `sha256:<hex>` of keys uploaded with it); its claims
851
- * and policy as the row keeps them, canonical JSON.
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.
852
1763
  */
853
- export type BindingColumns = {
854
- id: string;
1764
+ export type Peeked = {
855
1765
  principal: string;
856
- generation: number;
857
- profile: string;
858
- issuer: string;
859
- /**
860
- * The instance's public URL it was made on (PR 3b): its base audience, as
861
- * a token for it must name it (`expectedAudiences`), and where a workload's
862
- * DPoP proof is signed for. No column: the app names it, and the seal
863
- * holds it, so a binding of another URL's is none of this instance's.
864
- */
865
- origin: string;
866
- jwksUri: string;
867
- claims: string;
868
- scope: string | null;
869
- policy: string | null;
870
- revoked: boolean;
871
- };
872
- /** A binding the vault makes (`changeBindings`): its object's columns and the rest of its row, with the app's MAC over it. */
873
- export type MadeBinding = BindingColumns & {
874
- jwks: string | null;
875
- label: string | null;
876
- createdBy: string;
877
- createdAt: number;
878
- authMac: string;
879
- };
880
- /** A binding a change ends: as the app read it, with its seal and MAC, the app's MAC over it revoked, and the credentials it issued that are live. */
881
- export type EndedBinding = {
882
- /** Its seal null for one 0.14 made, which the log never held: ended all the same, its row revoked with no change. */
883
- before: {
884
- columns: BindingColumns;
885
- seal: string | null;
886
- };
887
- authMacFrom: string;
888
- authMac: string;
889
- /**
890
- * Every live credential it issued, each as `revokeCredential` names one: the statement holds the set to the rows. One
891
- * with no seal (0.14's, or written around the vault) is ended all the same, its row revoked with no change.
892
- */
893
- credentials: {
894
- before: {
895
- columns: CredentialColumns;
896
- seal: string | null;
897
- };
898
- authMacFrom: string;
899
- authMac: string;
900
- }[];
901
- };
902
- export type ChangeBindingsInput = {
903
- /** Who changes them, as its entry names them. */
904
- actor: string;
905
- /** The credential the request came in on, by id; null for none. */
906
- via: string | null;
907
- /** The issuer's access as the app weighed the scope on (`access_seq`), decimal; null when it weighed none. */
908
- actorAccess: string | null;
909
- /** The MCP connection the request came through, at the caller's generation, held to still connected; null for none. */
910
- connection: {
911
- id: string;
912
- generation: number;
913
- } | null;
914
- /** The binding it makes; null for an unbind. Its account at its generation, as its columns name them. */
915
- make: MadeBinding | null;
916
- /** With a binding made, the account's live bindings as the app read them, by id, which it was weighed beside; else null. */
917
- live: string[] | null;
918
- /** The keys a binding made reads (its policy's `reads`), by id and the name they were asked by: none moves before the write. */
919
- reads: {
920
- id: string;
1766
+ /** The credential's id. */
1767
+ credential: string;
1768
+ personal: boolean;
1769
+ items: ({
921
1770
  key: string;
922
- }[];
923
- /** The bindings it ends: those the new one replaces, or the one unbound. */
924
- ends: EndedBinding[];
925
- /** Why they end, for the changes' record. */
926
- reason: 'replaced' | 'keys_moved' | 'unbound';
927
- revokedAt: number;
928
- revokedBy: string;
929
- /** The policy the app weighed on: the newest `policy.change`'s seq and the protected environments' slugs. */
930
- policy: {
931
- seq: string | null;
932
- protected: {
933
- environmentId: string;
934
- slug: string | null;
935
- }[];
936
- };
937
- appKey: string;
938
- };
939
- /**
940
- * Why bindings were not changed, nothing written: as an issue's
941
- * (`IssueTokenRefusal`); `stale` or `tampered`, a row the log does not
942
- * hold as its newest (put back) or not the vault's seal; `unlogged`, the
943
- * credential the request came in on one 0.14 made (a binding 0.14 made,
944
- * the vault ends itself, with no change);
945
- * `full`, the account holds as many live bindings as one may
946
- * (`MAX_BINDINGS`), besides those the change ends.
947
- */
948
- export type ChangeBindingsRefusal = IssueTokenRefusal | 'stale' | 'tampered' | 'full';
949
- /** A point of 0.14's chain: an entry's number and its hash (hex); `-1` and the zero hash before the first. */
950
- export type ChainMark = {
951
- seq: string;
952
- hash: 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
+ })[];
953
1781
  };
954
1782
  /**
955
- * What the app vouches for, of 0.14's, at the cutover (`Vault.cutover`):
956
- * what 0.14 accepts that only the app's key says, each checked as 0.14's
957
- * app checks it.
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.
958
1790
  */
959
- export type CutoverInput = {
1791
+ export type Called = {
1792
+ principal: string;
960
1793
  /**
961
- * The stretch of 0.14's chain whose app entries the app checked by their
962
- * MACs, every link included: from where the vault said it verifies from,
963
- * to the head as the app read it. An app entry after `to` sends the
964
- * cutover back to the app (`moved`).
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.
965
1800
  */
966
- checked: {
967
- from: ChainMark;
968
- to: ChainMark;
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 & {
1810
+ policy: Policy;
969
1811
  };
970
1812
  /**
971
- * Each credential 0.14 accepts as it stands, its object's columns as
972
- * read: its MAC the app's, not revoked nor past its end, its sign-in
973
- * account not unlinked, and no revoke of it in the log (`token.revoke`,
974
- * `sign_out`). One a binding issued is left out: 0.14 reads its scope
975
- * from the binding, so its row holds none to seal.
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.
976
1817
  */
977
- credentials: CredentialColumns[];
978
- /** Each trust binding 0.14 accepts as it stands: its MAC the app's, not revoked, and no `token.unbind` of it. */
979
- bindings: BindingColumns[];
980
- /** Each MCP connection 0.14 accepts as it stands (T147): its MAC the app's, not revoked nor past its end. */
981
- connections: ConnectionColumns[];
982
- /** Each place 0.14's chain deleted, by an authentic `project.delete` or `environment.delete`, with the tombstone it gave the slug. */
983
- deleted: {
984
- kind: 'project' | 'environment';
985
- id: string;
986
- tombstone: string;
987
- }[];
1818
+ head?: SignedHead | null;
988
1819
  };
989
1820
  /**
990
- * The cutover's answer: done (now, or before); not yet, with where 0.14's
991
- * chain is verified from; `moved`, a 0.14 write since the app read what it
992
- * vouched for (ask again); `refused`, 0.14's chain or rows not as 0.14
993
- * accepts them, which a cutover does not seal (an operator's to look at).
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.
994
1827
  */
995
- export type CutoverOutcome = {
996
- ok: true;
997
- done: true;
998
- } | {
999
- ok: true;
1000
- done: false;
1001
- from: ChainMark;
1002
- } | {
1003
- ok: false;
1004
- refused: 'moved' | 'refused';
1005
- why: string;
1006
- };
1007
- export type ChangeBindingsOutcome = {
1008
- ok: true;
1009
- number: string;
1010
- witnessed: boolean | null;
1011
- } | {
1012
- ok: false;
1013
- refused: ChangeBindingsRefusal;
1014
- why?: string;
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;
1015
1836
  };
1016
- /** The row a sign-in writes (`credentials`): a service's credential for a CI run, or a workload's key-bound session. */
1017
- export type SignInCredential = {
1018
- id: string;
1019
- kind: 'service' | 'workload';
1020
- tokenHash: string;
1021
- tokenHint: string;
1022
- label: string | null;
1023
- scope: string | null;
1024
- places: string | null;
1025
- expiresAt: number;
1026
- notAfter: number | null;
1027
- jkt: string | null;
1028
- authMac: string;
1837
+ /** Why a call is not answered. Nothing it asked was written. */
1838
+ export type Refused = {
1839
+ refused: string;
1029
1840
  };
1030
1841
  /**
1031
- * Why a sign-in made nothing, the statement's own words: the account or
1032
- * the binding not as named, frozen, its rate spent (or a lock not had in
1033
- * time), its times past or too far, the token spent, the app's key one it
1034
- * rotated from.
1035
- */
1036
- /** Why a sign-in made nothing; `unsealed`: its binding is none the vault sealed (one 0.14 made, or a row not its object), which signs nobody in (PR 3a). */
1037
- export type SignInRefusal = 'unbound' | 'frozen' | 'busy' | 'expired' | 'replayed' | 'retired' | 'unsealed' | 'proof';
1038
- /**
1039
- * A sign-in's answer. `proof`: the vault's check of the token or the DPoP
1040
- * proof refused it, `reason` saying why as the app's refusals do
1041
- * (`ExchangeReason`), and a key the binding's uploaded set lacks naming
1042
- * it (`kid`).
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.
1043
1845
  */
1044
- export type SignInOutcome = {
1045
- ok: true;
1046
- number: string;
1047
- witnessed: boolean | null;
1048
- } | {
1049
- ok: false;
1050
- refused: Exclude<SignInRefusal, 'proof'>;
1051
- } | {
1052
- ok: false;
1053
- refused: 'proof';
1054
- reason: string;
1055
- message: string;
1056
- kid: string | null;
1057
- };
1058
- /** A token the vault issues (`Vault.issueToken`). Times in ms since the epoch, bytes in base64. */
1059
- /**
1060
- * What the app's entry would name a request by, which a change's record
1061
- * keeps for the audit pages where 0.14's entry stood (D147, T164): the
1062
- * credential or MCP connection whose act it was, as an entry's
1063
- * `credentialId` (a run's credential, a personal token, an app connected
1064
- * through MCP); and, through MCP, the app and the approval, as its `via`.
1065
- * The app's word, which the vault records and never weighs.
1066
- */
1067
- export type RequestTrace = {
1068
- credentialId: string;
1069
- mcp: {
1070
- connectionId: string;
1071
- clientId: string;
1072
- clientName: string;
1073
- approvalId: string | null;
1074
- } | null;
1075
- };
1076
- export type IssueTokenInput = {
1077
- /** Who issues it, `user:…` or `token:…`: the request's caller. */
1078
- actor: string;
1079
- /** The credential the request came in on, by id; null for none (a request the app made itself). */
1080
- via: string | null;
1081
- /** Whose act it was, for its change's record (`RequestTrace`); none for a request on no such credential. */
1082
- trace?: RequestTrace | null;
1083
- /** Whom it acts as: a service account's `token:<id>`, or the actor, for a personal token or a handle. */
1084
- principal: string;
1085
- /** The principal's generation it is issued at. */
1086
- generation: number;
1087
- /**
1088
- * The issuer's access the app weighed the scope on: the vault's newest
1089
- * access entry about them (`issuerNow`), which the vault holds the issue
1090
- * to (`access`, as `issuerStill`); null to hold it to none.
1091
- */
1092
- actorAccess: string | null;
1093
- credential: IssuedTokenRow;
1094
- /** The policy the app weighed the scope on: its newest `policy.change`, and the environments it protected (`policyStill`'s). */
1095
- policy: {
1096
- seq: string | null;
1097
- protected: {
1098
- environmentId: string;
1099
- slug: string | null;
1100
- }[];
1101
- };
1102
- /** The id of the app's log key, under whose key the row's MAC was made (`SignInInput.appKey`). */
1103
- appKey: string;
1104
- };
1105
- /** The row a token's issue writes (`credentials`). */
1106
- export type IssuedTokenRow = {
1107
- id: string;
1108
- kind: 'service' | 'personal' | 'handle';
1109
- tokenHash: string;
1110
- tokenHint: string;
1111
- label: string | null;
1112
- /** Its scope as stored (`storedScope`): what the vault weighs, and seals. */
1113
- scope: string;
1114
- /** A handle's environments, as made for; null for any other. */
1115
- places: string | null;
1116
- expiresAt: number;
1117
- /** Who issued it, as its row names them: the actor's id. */
1118
- createdBy: string;
1119
- authMac: string;
1120
- };
1121
- /**
1122
- * Why a token was not issued, the vault's own words: the issuer may not
1123
- * give that scope, or that kind of token (`refused`); the credential the
1124
- * request came in on, or the issuer, ended (`ended`); the account it is for
1125
- * is not the member it was weighed as (`gone`); the issuer's access moved
1126
- * since the app weighed it (`access`); what it was weighed on moved
1127
- * while it was written, each of the three times the vault weighed it
1128
- * (`moved`), or the policy did (`policy`); a lock not had in time
1129
- * (`busy`); the app's key one it rotated from (`retired`); the credential
1130
- * the request came in on one 0.14 made, which the log never held, so
1131
- * nothing the vault could authenticate (`unlogged`: the app issues on it
1132
- * as before).
1133
- */
1134
- export type IssueTokenRefusal = 'refused' | 'ended' | 'gone' | 'access' | 'moved' | 'policy' | 'busy' | 'retired' | 'unlogged';
1135
- export type IssueTokenOutcome = {
1136
- ok: true;
1137
- number: string;
1138
- witnessed: boolean | null;
1139
- } | {
1140
- ok: false;
1141
- refused: IssueTokenRefusal;
1142
- why?: string;
1143
- };
1144
- /** A revoke (`Vault.revokeCredential`): the credential as the app read it, and the app's MACs over its row before and after. */
1145
- export type RevokeCredentialInput = {
1146
- /** Who revokes it, as its entry names them: `user:…`, `token:…`, or the app's own (`coffre`). */
1147
- actor: string;
1148
- /** Its object's columns as read, and their seal: a row the log holds (one 0.14 made, with none, the app revokes as 0.14 does). */
1149
- before: {
1150
- columns: CredentialColumns;
1151
- seal: string;
1152
- };
1153
- authMacFrom: string;
1154
- authMac: string;
1155
- revokedAt: number;
1156
- revokedBy: string;
1157
- /** Why, for its change's record: a revoke, or its holder's sign-out. */
1158
- reason: 'revoke' | 'sign_out';
1159
- /** The credential the request came in on, for its change's record. */
1160
- via: string | null;
1161
- /** Whose act it was, for its change's record (`RequestTrace`); none for a request on no such credential. */
1162
- trace?: RequestTrace | null;
1163
- /**
1164
- * The policy the caller's right to revoke it was weighed on, held to under
1165
- * the fence (as `policyStill` holds a write to it under 0.14's head): the
1166
- * newest `policy.change`'s sequence number, and the environments it
1167
- * protected, by id, with their slugs (null: deleted). Null for a revoke no policy weighs
1168
- * (its holder's own sign-out).
1169
- */
1170
- policy: {
1171
- seq: string | null;
1172
- protected: {
1173
- environmentId: string;
1174
- slug: string | null;
1175
- }[];
1176
- } | null;
1177
- };
1846
+ export type Change = SecretsChanges | PlacesChanges | AccessChanges | SigninChanges | WorkloadChanges | FreezeChanges | McpChanges;
1847
+ export type Answers = SecretsAnswers & PlacesAnswers & AccessAnswers & SigninAnswers & WorkloadAnswers & FreezeAnswers & McpAnswers;
1178
1848
  /**
1179
- * A revoke: its change's number, or why nothing was written: the row not
1180
- * as read, or revoked already (`moved`); not its object's newest change's
1181
- * (`stale`); its seal not the vault's (`tampered`, a finding); the policy
1182
- * it was weighed on changed (`policy`); a lock not had in time (`busy`).
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.
1183
1853
  */
1184
- export type RevokeCredentialOutcome = {
1185
- ok: true;
1186
- number: string;
1187
- witnessed: boolean | null;
1188
- } | {
1189
- ok: false;
1190
- refused: 'moved' | 'stale' | 'tampered' | 'policy' | 'busy';
1191
- };
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];
1192
1856
  /**
1193
1857
  * The vault's entries that change what a member holds: what their row's
1194
1858
  * `access_seq` names, and what a finding about them is newer than while it
@@ -1214,9 +1878,9 @@ export type RefusalCode =
1214
1878
  /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
1215
1879
  'bad_claim' |
1216
1880
  /**
1217
- * A person asked for a sensitive value to be handed back (`handsBack`):
1218
- * nobody sees one, Owners included. Their apps use it through the
1219
- * 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.
1220
1884
  */
1221
1885
  'sensitive' |
1222
1886
  /**
@@ -1270,8 +1934,6 @@ export type RefusalCode =
1270
1934
  * Asked again on the answer now, it is decided as they are now.
1271
1935
  */
1272
1936
  'access_changed' |
1273
- /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
1274
- 'log_broken' |
1275
1937
  /**
1276
1938
  * A KEK the vault is given does not open what it wrapped: a restore with
1277
1939
  * the wrong key, or a key mistyped under the right id. Every key
@@ -1290,8 +1952,6 @@ export type Outcome<T> = ({
1290
1952
  ok: false;
1291
1953
  refusal: Refusal;
1292
1954
  };
1293
- /** What each refusal says, as the vault answers it and the app shows it. */
1294
- export declare const REFUSAL_MESSAGES: Record<RefusalCode, string>;
1295
1955
  /**
1296
1956
  * A proposed version the app will store. The ids bind its key, and `path`
1297
1957
  * is the app's label for the write's log. Reads name stored version ids
@@ -1327,60 +1987,25 @@ export type WrappedKey = {
1327
1987
  bytes: string;
1328
1988
  };
1329
1989
  /**
1330
- * The vault key the vault wraps under now, by provider and ID, and each
1331
- * vault key's check, newest first: a known value wrapped under it
1332
- * (`KEY_CHECK_VALUE` in `@coffre/core/kek`), in its newest `key.check`
1333
- * 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.
1334
1997
  */
1335
- export type KeyChecks = {
1336
- current: {
1337
- kekProvider: string;
1338
- kekId: string;
1998
+ export type About = {
1999
+ kek: {
2000
+ provider: string;
2001
+ id: string;
1339
2002
  };
1340
- checks: (WrappedKey & {
1341
- seq: number;
1342
- })[];
2003
+ previous: {
2004
+ provider: string;
2005
+ id: string;
2006
+ }[];
2007
+ checks: string[];
1343
2008
  };
1344
- /**
1345
- * Why someone reads: shown in the log, and the same rules apply to each. A
1346
- * fork reads to `copy`. The credential proxy reads to `use`, a value it
1347
- * injects into a request and never hands back, or to `expose`, one it
1348
- * gives a person's app as it is (`coffre run`'s plan).
1349
- */
1350
- export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
1351
- /**
1352
- * A use's purpose, keepsSensitive and way in as 0.15's log stores them, in
1353
- * one smallint (`log_uses.purpose`, schema 0022, 0046): the purpose's code,
1354
- * plus 256 when a copy keeps values sensitive, plus 512 times its way in's
1355
- * (`USE_WAYS`; T147). The vault writes them; the audit pages read them back
1356
- * (T166).
1357
- */
1358
- export declare const USE_PURPOSES: readonly ["reveal", "run", "compare", "copy", "use", "expose"];
1359
- /** Each way in by its code: a credential's, 0, as every use before T147; then `UseWay`'s. */
1360
- export declare const USE_WAYS: readonly ["credential", "connection", "binding", "access"];
1361
- /** A use's code (`USE_PURPOSES`). */
1362
- export declare function useCode(use: {
1363
- purpose: Purpose;
1364
- keepsSensitive?: boolean;
1365
- way?: 'credential' | UseWay;
1366
- }): number;
1367
- /** The purpose, keepsSensitive and way in a use's code stores; null for a code no release writes. */
1368
- export declare function useOfCode(code: number): {
1369
- purpose: Purpose;
1370
- keepsSensitive: boolean;
1371
- way?: UseWay;
1372
- } | null;
1373
- /**
1374
- * Whether a read hands values back to whoever asked, which a person never
1375
- * gets of a sensitive value: every purpose but the proxy's `use` and a
1376
- * fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
1377
- * `compare` included, which tells them whether a guess was right, and any
1378
- * purpose a later app may name.
1379
- */
1380
- export declare function handsBack(read: {
1381
- purpose: string;
1382
- keepsSensitive?: boolean;
1383
- }): boolean;
1384
2009
  /** Ties the vault's entries to the app's request and audit rows. */
1385
2010
  type Correlation = {
1386
2011
  requestId?: string | null;
@@ -1595,9 +2220,9 @@ export type AdmitInput = Correlation & Through & {
1595
2220
  * Left out, an existing member keeps theirs and a new one is a `member`.
1596
2221
  * Changing it takes someone who runs the instance, about someone else;
1597
2222
  * making someone an Owner, or changing an Owner's, an Owner of the whole
1598
- * instance, who may change their own too. It never leaves the instance
1599
- * without an Owner of all of it (`last_owner`), nor demotes one the
1600
- * 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`).
1601
2226
  */
1602
2227
  role?: InstanceRole;
1603
2228
  scope?: Scope;
@@ -1651,6 +2276,19 @@ export type PolicyChange = {
1651
2276
  export declare function policyRevision(seq: number | bigint | null, policy: Pick<Policy, 'protectedIn'>): string;
1652
2277
  /** A revision as `policyRevision` writes it. */
1653
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;
1654
2292
  export type ChangePolicyInput = Correlation & Through & {
1655
2293
  actor: string;
1656
2294
  change: PolicyChange;
@@ -1664,291 +2302,5 @@ export type ChangePolicyInput = Correlation & Through & {
1664
2302
  */
1665
2303
  revision?: string;
1666
2304
  };
1667
- /**
1668
- * A prefix of the log the vault signed: every entry up to `seq`, the last
1669
- * of which has `hash`, which pins every byte before it. Kept as the vault's
1670
- * `audit.checkpoint` entry, just after the prefix it signs.
1671
- */
1672
- export type Checkpoint = {
1673
- seq: number;
1674
- /** The hash of entry `seq`, hex. */
1675
- hash: string;
1676
- signedAt: string;
1677
- keyId: string;
1678
- /** Ed25519 over `checkpointMessage(...)`, base64. */
1679
- signature: string;
1680
- };
1681
- /**
1682
- * A public key the vault's checkpoints verify under, base64. One it
1683
- * replaced vouches only for checkpoints whose prefix ends before `until`,
1684
- * its first entry under the key that replaced it; the one it signs with now
1685
- * has none.
1686
- */
1687
- export type CheckpointKey = {
1688
- publicKey: string;
1689
- until: number | null;
1690
- };
1691
- /** An entry of the vault's log, and so the chain up to it. */
1692
- export type LogHead = {
1693
- seq: number;
1694
- hash: string;
1695
- };
1696
- export type VerifyLogInput = {
1697
- /**
1698
- * The last entry the app verified, every link and hash up to it
1699
- * recomputed and its own entries checked by its key: the vault checks the
1700
- * log still holds it, so between them both authors' entries are
1701
- * authenticated over the same stretch, and the vault leaves the links to
1702
- * the app.
1703
- */
1704
- upTo?: LogHead | null;
1705
- /**
1706
- * Where the vault's walk starts: the seq of one of its `audit.checkpoint`
1707
- * entries that keeps a tally, or `start`, the first entry. The newest
1708
- * such checkpoint when absent, and a vault older than 0.10.1 walks from
1709
- * the first entry whatever it says.
1710
- */
1711
- from?: number | 'start';
1712
- /**
1713
- * A later checkpoint's entry, whose prefix `upTo` is: the walk ends
1714
- * there, and must come to the tally it keeps. The members' rows and the
1715
- * key batches are as they are now, not then, so only a walk without one
1716
- * holds them to the log.
1717
- */
1718
- to?: number;
1719
- };
1720
- /**
1721
- * Whether the vault's log holds, with the number of its entries through
1722
- * where the walk ended, `through`: `upTo`, the prefix `to` signed, or as
1723
- * far as one walk goes. On a failure, the entry where it breaks, or null
1724
- * when the chain holds but the members and grants do not follow from it.
1725
- * Then `fault` says which, as facts the app can word with names: `reason`
1726
- * has only ids. A walk that ends at the present reports live key batches in
1727
- * `pending`; overdue ones fail.
1728
- */
1729
- export type LogVerification = {
1730
- ok: true;
1731
- entries: number;
1732
- pending?: number;
1733
- through?: number;
1734
- } | {
1735
- ok: false;
1736
- failedAtSeq: number | null;
1737
- reason: string;
1738
- fault?: AccessFault;
1739
- };
1740
- /** The longest a use may take from its time to its answer, held in Postgres too (R53): no use is decided later than this after its `at`. */
1741
- export declare const USE_DEADLINE_MS = 3000;
1742
- /** A use's request id: 63 random bits, as text, unique within its millisecond (hot-path-one.md, "Row size"). */
1743
- export declare function newUseRequestId(): string;
1744
- /** A use as the app asks for it: on which credential, which key, through which place, why, and when. */
1745
- export type UseInput = {
1746
- /**
1747
- * What the request came in on (T147): a credentials row, by id; with
1748
- * `way`, an MCP connection or a Cloudflare service binding, by id, or,
1749
- * behind Cloudflare Access, which signs a browser in with no row of
1750
- * coffre's, the person (`user:…`), whose account is all the use weighs.
1751
- */
1752
- credential: string;
1753
- way?: UseWay;
1754
- secretId: string;
1755
- /** The fork an inherited value is read in (`UnwrapInput`'s `through`); null for the key's own environment. */
1756
- place: string | null;
1757
- purpose: Purpose;
1758
- keepsSensitive?: boolean;
1759
- /**
1760
- * The request's id, a whole number below 2^63 as text, unique within its
1761
- * millisecond, and its time, ms since the epoch: a retry of a request
1762
- * whose answer was lost passes both unchanged, and finds the entry the
1763
- * first one wrote (`replayed`).
1764
- */
1765
- requestId: string;
1766
- at: number;
1767
- /** When it must have answered: at most 3 s after `at` (R53). */
1768
- deadline: number;
1769
- };
1770
- /**
1771
- * A request's several keys as the app asks for them (`Vault.useMany`): what `UseInput` names but its key, once, and
1772
- * each key with the place it is read through and its own request id, which its entry takes.
1773
- */
1774
- export type UseManyInput = Omit<UseInput, 'secretId' | 'place' | 'requestId'> & {
1775
- items: readonly {
1776
- secretId: string;
1777
- place: string | null;
1778
- requestId: string;
1779
- }[];
1780
- };
1781
- /**
1782
- * A request's several keys' answer, all or nothing: every value, in the request's order, each with its entry (or the
1783
- * one it rode on); or the first key refused, by its index in the request, logged as its request was (`number`) or not
1784
- * (null: decided before anything of it was written, as a use's refusal by ids is); or busy, nothing decided.
1785
- */
1786
- export type UseManyOutcome = {
1787
- ok: true;
1788
- values: {
1789
- number: string;
1790
- covered: boolean;
1791
- value: UsedValue;
1792
- }[];
1793
- } | {
1794
- ok: false;
1795
- index: number;
1796
- code: UseCode;
1797
- number: string | null;
1798
- } | {
1799
- ok: false;
1800
- busy: UseBusy;
1801
- retryAfter: number;
1802
- };
1803
- /** The way in a use came through that has no credentials row (`UseInput.way`): each a sealed object of the log but Access. */
1804
- export type UseWay = 'connection' | 'binding' | 'access';
1805
- /** Why a use is refused: the rules' codes, and those of sealed inputs. */
1806
- export type UseCode = RefusalCode |
1807
- /** An input's row is not its object's newest change's: put back from before one, deleted, or written around the log. */
1808
- 'stale' |
1809
- /** The credential is not one, was revoked, or had ended at the request's time. */
1810
- 'credential' |
1811
- /** No such key. */
1812
- 'missing' |
1813
- /** The log holds no policy, so no cap: never served, as the vault writes one before its first use. */
1814
- 'no_policy' |
1815
- /**
1816
- * A use by name of a key that reads an archived place, a reference's source's: it reads nothing until that place is
1817
- * back (review r4 of D153). Decided before anything is written, never logged as a use: the app logs the request.
1818
- */
1819
- 'archived';
1820
- /** What a use's refusal says: the rules' as `REFUSAL_MESSAGES`, and those of sealed inputs. */
1821
- export declare function useRefusalMessage(code: UseCode): string;
1822
- /** A use as the request names it (`Vault.useNamed`). */
1823
- export type NamedUseInput = {
1824
- /** The token the request came in on, hashed as its credential's row holds it, base64. */
1825
- tokenHash: string;
1826
- /** Where, by slugs; null for the one environment a handle was made for (the credential proxy's stable URL). */
1827
- place: {
1828
- project: string;
1829
- environment: string;
1830
- } | null;
1831
- /**
1832
- * With `place` null, the environments the request does not mean, by slugs: served not by name when the handle's is
1833
- * one (the stable URL's segments that name an environment of the handle's instead, one the proxy reads as its
1834
- * person's own config).
1835
- */
1836
- unless?: readonly {
1837
- project: string;
1838
- environment: string;
1839
- }[];
1840
- /** The key, by name; null for none: the caller's standing at the place alone, as for a key it does not hold. */
1841
- key: string | null;
1842
- /**
1843
- * The credentials the app's config accepts (review r6 and r7 of D153): `signin`, whether the deployment signs in
1844
- * through coffre's own sign-in (under Cloudflare Access no coffre token is a credential); `issuers`, each sign-in
1845
- * provider it configures, `<provider id>:<issuer hash>`, which a browser session's identity must name. The call
1846
- * holds the token's credential to them first, before anything else it reads: one the app would refuse is answered
1847
- * as a token no credential has, whatever the request names.
1848
- */
1849
- accepts: CredentialAcceptance;
1850
- purpose: Purpose;
1851
- keepsSensitive?: boolean;
1852
- requestId: string;
1853
- at: number;
1854
- deadline: number;
1855
- };
1856
- /** What a named use's credential must be for the app to take it (`NamedUseInput.accepts`). */
1857
- export type CredentialAcceptance = {
1858
- signin: boolean;
1859
- issuers: readonly string[];
1860
- };
1861
- /**
1862
- * A named use's answer. `served: false`: none the vault serves this way (a fork, a personal config, a handle of
1863
- * several environments, or a place its stable URL does not mean), and the app reads it as ever. Otherwise the route
1864
- * the request takes, which the vault picks on the credential and its account alone (`routeOf`; D153, review r2):
1865
- *
1866
- * - `credential`: the credential's own check answers (401; a token of 0.10's sealed first): no credential its seals
1867
- * bear out, or one ended. `outcome`, the vault's refusal, which the app does not answer with.
1868
- * - `busy`: nothing decided, admission's answer, whatever the request names.
1869
- * - `name`: the use's outcome, a plain value's text where one was allowed, and every refusal of the key alike; the rows
1870
- * the app checks before anything leaves (the credential's with its MAC, the place's, the key's), as `app_read`
1871
- * answers them, JSON; the key's id (null for none held); the place, by slugs; and the caller as the vault decided
1872
- * them, from the sealed rows the use read (one who holds nothing where roles, policy or place were not as sealed).
1873
- */
1874
- export type NamedUseOutcome = {
1875
- served: false;
1876
- } | {
1877
- served: true;
1878
- route: 'credential';
1879
- outcome: Extract<UseOutcome, {
1880
- code: UseCode;
1881
- }>;
1882
- } | {
1883
- served: true;
1884
- route: 'busy';
1885
- outcome: Extract<UseOutcome, {
1886
- busy: UseBusy;
1887
- }>;
1888
- } | {
1889
- served: true;
1890
- route: 'name';
1891
- secretId: string | null;
1892
- outcome: UseOutcome | {
1893
- ok: true;
1894
- plain: string;
1895
- versionId: string;
1896
- };
1897
- app: string | null;
1898
- standing: Access;
1899
- /** The place the use was at, by its slugs as the vault read them: the one named, or the handle's own. */
1900
- place: {
1901
- project: string;
1902
- environment: string;
1903
- } | null;
1904
- /** The same place by its ids, as the vault's own rows read it, on either engine: where a refusal is logged. */
1905
- at: {
1906
- projectId: string;
1907
- environmentId: string;
1908
- } | null;
1909
- };
1910
- /** Why a use was not decided at all: the app answers 503, with `Retry-After`. */
1911
- export type UseBusy = 'late' | 'overloaded' | 'replayed' | 'ahead' | 'unconfigured';
1912
- /** A value a use opened: its data key, base64, and the version it decrypts, with what its ciphertext is bound to. */
1913
- export type UsedValue = {
1914
- key: string;
1915
- versionId: string;
1916
- context: {
1917
- projectId: string;
1918
- environmentId: string;
1919
- secretId: string;
1920
- owner?: string;
1921
- sensitive?: true;
1922
- };
1923
- envelope: {
1924
- version: number;
1925
- ciphertext: string;
1926
- iv: string;
1927
- authTag: string;
1928
- };
1929
- };
1930
- /**
1931
- * A use's answer. Allowed: the value, and the entry it was logged as (or,
1932
- * a repeat, rode on: `covered`). Refused: why, logged as the request it
1933
- * was. Busy: nothing was decided, ask again in `retryAfter` seconds:
1934
- * `late` (past its deadline, or below the floor), `overloaded` (refused at
1935
- * admission), `replayed` (a retry of a call that wrote: the first one's
1936
- * entry stands, its value never left), `ahead` (its time past the
1937
- * database's clock), `unconfigured` (no policy logged yet).
1938
- */
1939
- export type UseOutcome = {
1940
- ok: true;
1941
- number: string;
1942
- covered: boolean;
1943
- value: UsedValue;
1944
- } | {
1945
- ok: false;
1946
- code: UseCode;
1947
- number: string | null;
1948
- } | {
1949
- ok: false;
1950
- busy: UseBusy;
1951
- retryAfter: number;
1952
- };
1953
2305
  //#endregion
1954
- export type { AccessFault, CallerKind, FaultGrant, FaultNames, GrantFacts, MemberFacts, PolicyEdits, PolicyEnvironment, ProtectedPlace };
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 };