@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/src/vault.ts CHANGED
@@ -1,900 +1,297 @@
1
1
  import { createHash } from 'node:crypto';
2
2
 
3
- import type { AccessFault } from './access-fault.ts';
4
- import type { CallerKind, CredentialScope, GrantPlace, InstanceRole, Policy, Role, RoleDefinition, Scope, ServiceSetting } from './access.ts';
3
+ import type { CallerKind, CredentialScope, GrantPlace, Holdings, InstanceRole, Policy, Role, RoleDefinition, Scope, ServiceSetting } from './access.ts';
4
+ import type { AccessAnswers, AccessChanges } from './changes/access.ts';
5
+ import type { FreezeAnswers, FreezeChanges } from './changes/freezes.ts';
6
+ import type { McpAnswers, McpChanges, McpUnasked } from './changes/mcp.ts';
7
+ import type { PlacesAnswers, PlacesChanges } from './changes/places.ts';
8
+ import type { Nature, SecretsAnswers, SecretsChanges } from './changes/secrets.ts';
9
+ import type { SigninAnswers, SigninChanges, Unasked } from './changes/signin.ts';
10
+ import type { WorkloadAnswers, WorkloadChanges, WorkloadsUnasked } from './changes/workloads.ts';
11
+ import type { BindingPolicy, Constraints } from './identity/index.ts';
12
+ import type { McpScope } from './mcp.ts';
5
13
 
6
14
  export type { CallerKind } from './access.ts';
7
15
 
8
- export { checkpointMessage, checkpointVerifier, verifyCheckpoint } from './checkpoint.ts';
9
16
  export { describeAccessFault, type AccessFault, type FaultGrant, type FaultNames } from './access-fault.ts';
10
- export {
11
- answerFrom,
12
- CLOSED_POLICY,
13
- CLOSED_SETTINGS,
14
- DEFAULT_SETTINGS,
15
- live,
16
- livePolicy,
17
- NO_EDITS,
18
- policyFrom,
19
- PRINCIPAL,
20
- readEdits,
21
- roleOf,
22
- settingsFrom,
23
- view,
24
- type GrantFacts,
25
- type MemberFacts,
26
- type PolicyEdits,
27
- type PolicyEnvironment,
28
- type ProtectedPlace,
29
- } from './answers.ts';
30
17
 
31
18
  /**
32
- * The vault as the app sees it: the contract between `@coffre/server` and
33
- * `@coffre/vault`, kept in core so that neither side owns it. Every argument
34
- * and result is plain JSON: strings, numbers, booleans, arrays and objects,
35
- * never a Buffer, a Date, a class or a function. So it crosses a Workers RPC
36
- * boundary, or a process boundary later, as it is, and the in-process
37
- * transport proves it by round-tripping everything through JSON.
19
+ * The vault as the app sees it (docs/design/0.16.md, "The contract"): the
20
+ * contract between `@coffre/server` and `@coffre/vault`, kept in core so
21
+ * that neither side owns it. Every argument and answer is plain JSON:
22
+ * strings, numbers, booleans, arrays and objects, never a Buffer, a Date, a
23
+ * class or a function. So it crosses a Workers RPC boundary, or a process
24
+ * boundary, as it is, and the in-process transport proves it by
25
+ * round-tripping everything through JSON.
38
26
  *
39
- * The app says who is asking and the vault decides. The app never holds a
40
- * key: it encrypts a value under a fresh data key, has the vault wrap that
41
- * key, and stores the result; to read, it names stored versions and the
42
- * vault loads their keys itself.
27
+ * The app says what a request showed and the vault decides: it finds the
28
+ * credential by its token, reads what it holds and opens the values
29
+ * itself. The app holds no key, no ciphertext it can open and no grant it
30
+ * decides on.
43
31
  *
44
- * Decisions come back as values: `{ ok: false, refusal }` for a refusal, which
45
- * the vault has already logged. Only a fault (a bug, the store down) throws.
32
+ * A decision comes back as a value: `{ refused }` for a refusal, which
33
+ * wrote nothing of what was asked. A refused use writes nothing at all; a
34
+ * change refused to a caller who stands, one log entry that says so, once
35
+ * a minute in each instance for that caller and what they asked. Only a
36
+ * fault throws: a bug, or the database down.
46
37
  */
47
38
  export interface Vault {
39
+ /** Open values for whoever presented a token: a reveal, `coffre run`, an export, a proxied request, a signature. */
40
+ use(input: UseInput): Promise<Used | Refused>;
48
41
  /**
49
- * Unwrap data keys for `principal`: all of them, or none. Given the
50
- * revision of an answer of `access` the app decided the read on
51
- * (`accessRevision`), only while the principal's access is still that
52
- * one, under their row and the head the decision holds: otherwise it
53
- * refuses `access_changed` and logs no read, and says, by naming it back,
54
- * that it checked. A vault older than 0.14.1 names none: it checked none.
42
+ * What `use` would give, as of now, without opening or writing anything:
43
+ * each key's secret and version, or why it is refused. What a watch
44
+ * compares before it reads (`GET …/version`).
55
45
  */
56
- unwrap(input: UnwrapInput): Promise<Outcome<Unwrapped>>;
46
+ peek(input: UseInput): Promise<Peeked | Refused>;
57
47
  /**
58
- * Wrap fresh data keys for new versions `principal` writes: all, or none.
59
- * `seqs` are the `key.wrap` entries, one per key, which the app's
60
- * `secret.write` entries name as related. `sensitive` says, per key,
61
- * whether its wrap binds it as sensitive: a vault older than 0.10 answers
62
- * none, binding none, and the app stores no sensitive version it wrapped.
48
+ * Who a request's credential is and all it holds, for the app to scope a
49
+ * page's queries with. Nothing is opened or changed on the answer: a use
50
+ * and a change read their caller themselves.
63
51
  */
64
- wrap(input: WrapInput): Promise<Outcome<Wrapped>>;
52
+ caller(input: Presented & { head?: boolean }): Promise<Called | Refused>;
65
53
  /**
66
- * Wrap existing data keys again for new versions of the same secrets,
67
- * under the current key: restoring an old value, or making one stricter.
68
- * It needs a write grant, not a read one, since the key never leaves the
69
- * vault. A new version is never less sensitive than the one it is made
70
- * from, or than its secret's newest: a value is made looser only by
71
- * being written again (`invalid`). Except one: a key's current sensitive
72
- * value made a secret, in place, by an Owner of its project, or of the
73
- * whole instance, on no credential's scope (`ownsProject`; `not_allowed`
74
- * for anyone else), its entry saying `was: 'sensitive'`.
54
+ * Make a change: one operation, named as its log entry's action is, with
55
+ * its input. All of it, or none.
75
56
  */
76
- rewrap(input: RewrapInput): Promise<Outcome<Wrapped>>;
77
-
78
- /**
79
- * Make secrets references to others: whoever can read the holder's
80
- * environment reads the source through it (docs/design/environments.md).
81
- * The vault checks that `principal` reads each source and writes each
82
- * holder, by their own grants, and logs a `reference.create` per item:
83
- * that entry, under the vault's MAC, is the reference. `seqs` are the
84
- * entries, which the app stores beside each reference and names when it
85
- * reads through one (`UnwrapInput`'s `via`). All, or none.
86
- */
87
- reference(input: ReferenceInput): Promise<Outcome<{ seqs: number[] }>>;
88
- /**
89
- * End references, each with a `reference.end` naming its creation:
90
- * `replaced` when the holder gets a value of its own, which takes write on
91
- * the holder; `broken` otherwise, which takes write on the holder, or
92
- * managing the source's project's access. An ended reference reads no
93
- * more, whatever any row says. All, or none.
94
- */
95
- endReferences(input: EndReferencesInput): Promise<Outcome<{ seqs: number[] }>>;
96
-
97
- /**
98
- * What one principal holds right now: the app asks once per request,
99
- * unless the request reads values on an answer it kept (`accessRevision`),
100
- * and at sign-in for each verified email. A decision, its rows checked:
101
- * lists of who holds what read the rows themselves, and need not ask.
102
- * A person the vault's `owners` names who is no Owner of all of it
103
- * becomes one here, logged (`reason: 'owners'`).
104
- */
105
- access(principal: string): Promise<Access>;
106
- /**
107
- * Set roles at several places for one principal: all of it, or none.
108
- * With `admit`, a service account that is not a member is admitted
109
- * first, in the same decision, as `admit` would: `admitted` says so.
110
- */
111
- setAccess(input: SetAccessInput): Promise<Outcome<{ changes: AccessChange[]; admitted?: Admitted }>>;
112
- /**
113
- * Add a member, bring back a removed one, or change a person's instance
114
- * role and its scope. `generation` is theirs now: sessions and tokens of
115
- * an earlier one are dead.
116
- */
117
- admit(input: AdmitInput): Promise<Outcome<Admitted>>;
118
- /**
119
- * Remove a member: revoke every grant and refuse them until admitted
120
- * again, from `generation` on. An Owner, only an Owner of the whole
121
- * instance removes, and never the last.
122
- */
123
- remove(input: RemoveInput): Promise<Outcome<{ revoked: Grant[]; generation: number }>>;
124
- /**
125
- * The instance's settings, as the vault's newest `settings.change` entry
126
- * says, by its MAC: an entry is where they live, so each change is logged
127
- * by being made. Everywhere, until someone narrows it.
128
- */
129
- settings(): Promise<Settings>;
130
- /** Change the instance's settings: those who run it, never anyone else. */
131
- setSettings(input: SetSettingsInput): Promise<Outcome<{ settings: Settings }>>;
132
-
133
- /**
134
- * The instance's access policy (`Policy` in @coffre/core/access): its
135
- * roles, as an Owner edited and made them, and its protected
136
- * environments, as the vault's newest `policy.change` says, by its MAC.
137
- * As it ships, before any. A vault older than 0.10 has none, and the app
138
- * decides as it ships.
139
- */
140
- policy(): Promise<Policy>;
141
- /**
142
- * Change the policy by one change, its own `policy.change` entry, which
143
- * names it and what it was (docs/design/roles.md):
144
- * - a project or instance role defined, or put back as it ships (null),
145
- * or, one an Owner made, deleted while no grant names it: an Owner of
146
- * the whole instance, and never the Owner role, nor the instance's
147
- * Member;
148
- * - environments of one project protected, by whoever manages its
149
- * environments, before their rows exist too (a fork's); or
150
- * unprotected, by an Owner of the project or of the whole instance
151
- * (`ownsProject`), as far as that project protected them.
152
- * The policy after it, and the newest `policy.change`, which it is as of:
153
- * the change's own, when it changed anything.
154
- */
155
- changePolicy(input: ChangePolicyInput): Promise<Outcome<{ policy: Policy; seq: number | null }>>;
156
-
157
- /**
158
- * Sign the log up to its last entry, in an `audit.checkpoint` entry of
159
- * the vault's, if the chain recomputes from the last checkpoint, the
160
- * vault's entries by their MACs, and that checkpoint's prefix is still
161
- * there, whole. The entry keeps the checkpoint's tally beside it: what a
162
- * walk from the first entry has gathered by the prefix's end (the
163
- * vault's keys, its key batches under way, who is a member and what they
164
- * hold), so that the next checkpoint, and every verification, go on from
165
- * there and read only what is new. A log longer than one walk, as after
166
- * an upgrade from 0.10.0, is signed a stretch a call, behind its head,
167
- * until the checkpoints catch up. Each call also rehashes a stretch of
168
- * what was signed before, round and round, which an entry edited in place
169
- * fails: then it refuses, and every verification reports the refusal.
170
- * A rehash the database fails moves on next time, and `warning` says so;
171
- * a refusal it would have cleared stands meanwhile. The vault reads the log itself: it takes nobody's word for where
172
- * it ends, or for what came before. It checks every member's row too, as
173
- * `access` would, and logs a `vault.tampered` for each one changed around
174
- * it: lists read rows without asking the vault.
175
- */
176
- checkpoint(): Promise<Outcome<{ checkpoint: Checkpoint; warning?: string }>>;
177
- /**
178
- * What the vault's configuration says, which the app shows: the keys its
179
- * checkpoints verify under, by the key id each checkpoint names (the one
180
- * it signs with now, and those of the KEKs it replaced).
181
- */
182
- about(): Promise<{
183
- checkpointKeys: Record<string, CheckpointKey>;
184
- /**
185
- * The emails of those the deployment names Owners of the whole instance
186
- * (`owners`), lowercased: the vault makes them Owners, and refuses to
187
- * demote or remove them. Absent from a vault of 0.5, which names none.
188
- */
189
- owners?: string[];
190
- /**
191
- * @deprecated Always empty: an app of 0.5, deployed after this vault,
192
- * lists and checks root admins here until it is. Gone in 0.7.
193
- */
194
- rootAdmins: [];
195
- /**
196
- * `'0.15'` when the vault keeps 0.15's log: the app then writes the
197
- * changes to its rows through it (`prepare`). Absent before 0.15.
198
- */
199
- log?: '0.15';
200
- /**
201
- * `true` when the vault also answers 0.15's uses (`use`): its log is
202
- * 0.15's and it has the hot path's login. The app then opens each value
203
- * through a use (docs/design/0.15-plan.md, PR 5b). Absent otherwise.
204
- */
205
- uses?: true;
206
- /**
207
- * `true` when the vault also answers a request's several keys in one call (`useMany`; T167). Said here, as a
208
- * Worker's stub answers any method's name: a vault older than this app, mid-deploy, says nothing, and the app makes
209
- * a use a key. Absent otherwise.
210
- */
211
- batchUses?: true;
212
- /**
213
- * `true` when the vault says whether its checkpointer seals (`sealing`; T169), which `/readyz` asks. Said here,
214
- * as a Worker's stub answers any method's name: of a vault older than this app, mid-deploy, readiness asks nothing.
215
- */
216
- sealing?: true;
217
- /**
218
- * `true` when the vault makes sign-ins through trust bindings and revokes
219
- * credentials itself (`signIn`, `revokeCredential`; T149): its log is
220
- * 0.15's. Said here, as a Worker's stub answers any method's name.
221
- * Absent otherwise.
222
- */
223
- credentials?: true;
224
- /** `true` when the vault issues tokens itself too (`issueToken`; T149, PR 2). Absent otherwise. */
225
- issues?: true;
226
- /** `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. */
227
- binds?: true;
228
- }>;
229
- /**
230
- * What an escrowed vault key is checked against: the vault key it wraps
231
- * under now, and each one's check, as the vault wrote it. None of it is
232
- * secret, and the vault answers no guess: a check opens only under its key.
233
- */
234
- keyChecks(): Promise<KeyChecks>;
235
- /**
236
- * Check the log from a checkpoint's tally, the newest unless `from`
237
- * names another, or the first entry: the vault's entries since by their
238
- * MACs, every checkpoint among them against the prefix it signed, the key
239
- * batches accounted for, and the members and grants replayed on from the
240
- * tally to see that the rows follow. With `to`, a later checkpoint, the
241
- * walk stops at the prefix it signed and must come to the tally it keeps:
242
- * a stretch of the whole log, walked from the first entry a stretch at a
243
- * time. The links and hashes of the chain are the caller's to recompute
244
- * through `upTo`, as the app does first; with none, the vault recomputes
245
- * them itself, no further than one walk. A verdict and nothing else, so
246
- * anyone may ask; the app asks for those who read the whole log
247
- * (`readsWholeLog`).
248
- */
249
- verifyLog(input: VerifyLogInput): Promise<LogVerification>;
250
- /**
251
- * 0.15's use (docs/design/0.15-plan.md, PR 5): one key read on one
252
- * credential, logged as its request and decided on what one statement
253
- * read, the value's data key handed back once its entry has committed.
254
- * Behind the 0.15 switch: the app opens each value through it when the
255
- * vault says so (`about().uses`). A vault without the hot path's login
256
- * has none.
257
- */
258
- use?(input: UseInput): Promise<UseOutcome>;
259
-
57
+ change<O extends Change['op']>(input: Asked<O>): Promise<{ answer: Answers[O] } | Refused>;
260
58
  /**
261
- * 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
262
- * 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
263
- * (`NamedUseOutcome.app`) and what it decided the caller holds (`standing`). A key the place does not hold, and a plain
264
- * value, it decides on the caller's standing there, logging nothing. Absent from a vault without 0.15's uses.
59
+ * What `change` would answer, as of now, with nothing written: the same
60
+ * read and the same decision, so a dry run (`?dryRun=1`) is no second
61
+ * copy of a rule. The change made after reads and decides again, and
62
+ * alone tells a version it opens that does not open (`unreadable`). One
63
+ * refused is logged as the change refused is; one that would be made
64
+ * leaves nothing. Only what a caller asks is weighed: a sign-in or an
65
+ * exchange rests on a proof, which this would try without spending.
265
66
  */
266
- useNamed?(input: NamedUseInput): Promise<NamedUseOutcome>;
267
-
268
- /**
269
- * A request's several keys as one call (T167, B2; formal/Batching.tla): each key's use made as `use` makes it, in the
270
- * request's order, in one statement, and decided on what it read; a second call, only once every key is allowed, for
271
- * those that take the principal's lock. All or nothing: every value, or the first key refused, or busy. Absent from a
272
- * vault without 0.15's uses (`about().batchUses` says whether it has it).
273
- */
274
- useMany?(input: UseManyInput): Promise<UseManyOutcome>;
275
-
67
+ weigh<O extends Exclude<Change['op'], Unasked | WorkloadsUnasked | McpUnasked>>(input: Asked<O>): Promise<{ answer: Answers[O] } | Refused>;
276
68
  /**
277
- * 0.15's log (docs/design/0.15-plan.md, "As built: PR 4b"): the changes
278
- * the app is about to write to objects its own rows hold (credentials,
279
- * keys, environments), each sealed, as entries the app's transaction
280
- * commits with its rows (`app_change`, migration 0025), before it asks.
281
- * The vault reads nothing: it checks each row's columns as the app read
282
- * them against their seal (`tampered` if the vault never made it), works
283
- * out the changes that turn them into the columns the app will write, and
284
- * seals what they leave. Whether each seal is still its object's newest
285
- * is the transaction's to check, under the fence. Only with 0.15's log on
286
- * (`about().log`); a vault older than 0.15 has none.
69
+ * The vault's configuration that is no secret: its vault keys and its
70
+ * signing keys' checks. It asks no caller, reads nothing, writes no
71
+ * entry and opens no connection: it answers what the vault was started
72
+ * with, the same to anyone, so whoever may see it is the app's to say.
287
73
  */
288
- prepare?(input: PrepareInput): Promise<Outcome<Prepared>>;
289
- /**
290
- * Answers once the log's entry `number` is sealed in a signed checkpoint
291
- * and, if a witness is configured, witnessed or past its 2 s (R51): what a
292
- * change the app committed waits for before it answers. Only with 0.15's
293
- * log on.
294
- */
295
- waitSealed?(input: { number: string }): Promise<Outcome<{ witnessed: boolean | null }>>;
296
- /**
297
- * 0.15 (T149, D146; docs/design/credential-lifecycle.md): a sign-in
298
- * through a trust binding, a CI run's or a workload's, made by the vault
299
- * in one statement (`sign_in`, migration 0034; formal/Lifecycle.tla).
300
- * The app verifies the proof and names the binding as it read it; the
301
- * vault makes the credential's object from those columns, and the
302
- * statement goes ahead only while they are the binding's row, its
303
- * account active at its generation, its rate not spent and the token
304
- * not, under their locks: the issue lock, never the fence, so no use
305
- * waits on it (R58), and no 0.14 head. No 0.14 entry either: the change
306
- * records the sign-in (D147). Answers once it is sealed (R51). Only with
307
- * 0.15's log on.
308
- */
309
- signIn?(input: SignInInput): Promise<SignInOutcome>;
310
- /**
311
- * 0.15 (T149): a credential revoked by the vault in one statement
312
- * (`revoke_credential`, migration 0034), from its columns as the app
313
- * read them and their seal: under its row's lock and the fence, held for
314
- * the statement's work alone (RevokeTakesFence). The app has weighed who
315
- * may. Answers once sealed (R51). Only with 0.15's log on.
316
- */
317
- revokeCredential?(input: RevokeCredentialInput): Promise<RevokeCredentialOutcome>;
318
- /**
319
- * 0.15 (T149, PR 2): a token issued by the vault, which weighs it itself
320
- * (`issue_token`, migration 0036; formal/Lifecycle.tla's issue): a
321
- * service account's token, a person's personal token, or a handle. The
322
- * app names the scope it worked out and the row it would hand out; the
323
- * vault reads the issuer, the account and the credential the request came
324
- * in on, decides with the rules of `@coffre/core/access` whether the
325
- * issuer may give that scope (R15, R32), and then writes it in one
326
- * statement that holds those rows shared and goes ahead only while they
327
- * are as it read them (IssuerLocked, IssuerCAS). Nothing held between
328
- * the two; the issue lock, never the fence (R58). Answers once sealed.
329
- */
330
- issueToken?(input: IssueTokenInput): Promise<IssueTokenOutcome>;
331
- /**
332
- * With 0.15's log, a service's trust bindings changed by the vault itself
333
- * (T149, PR 3a; D148): the binding a manager makes, weighed as a service
334
- * token's issue is (who may give the account that scope, R15, R32), and
335
- * those it replaces ended, with the credentials each issued; or, making
336
- * none, an unbind. One statement, which holds what it read as read;
337
- * answers once sealed. A sign-in takes only a binding the vault sealed.
338
- */
339
- changeBindings?(input: ChangeBindingsInput): Promise<ChangeBindingsOutcome>;
340
- /**
341
- * 0.15's cutover from 0.14 (docs/design/0.15-plan.md, PR 9;
342
- * formal/Migration015.tla): once, before 0.15's log serves anything, every
343
- * object 0.14 left sealed as 0.14 accepts it (`genesis`), and the log's
344
- * first `cutover` change naming 0.14's last head (the anchor). Without
345
- * `input`, whether it is done, and if not, where 0.14's chain is
346
- * verified from (its newest checkpoint's prefix), for the app to check
347
- * its own entries from there. With `input`, what the app vouches for under
348
- * its key, which the vault never holds: it holds each row to it under its
349
- * locks. Once done, done for good: a second call finds the marker.
350
- */
351
- cutover?(input?: CutoverInput): Promise<CutoverOutcome>;
352
- /**
353
- * Check 0.15's log (docs/design/0.15-plan.md, PR 8), as the audit page
354
- * does on every visit: the newest signed pair, held to the pairs held
355
- * outside, and every entry after it by its MAC and request, a tick's
356
- * worth (R25). Nothing walks the whole log on a request (D145). With
357
- * 0.14's log alone, `kept` false; a vault older than 0.15 has none.
358
- */
359
- verifyTrees?(): Promise<TreeVerification>;
360
- /**
361
- * The reads' listing held to 0.15's log, a stretch a call (T166): from
362
- * `start`, then each `next`, the uses the log sealed derived again and
363
- * held to the reads the pages list, each read and each place it was read
364
- * at. For whoever checks the whole log (`coffre verify log`), never a
365
- * page. `kept` false with 0.14's log alone.
366
- */
367
- verifyReads?(input: { from: string }): Promise<ReadsVerification>;
368
- /**
369
- * Which of these entries of 0.15's log, as a page of the audit log read
370
- * them, the vault does not vouch for: its MAC, under any of the vault's
371
- * signing keys, as its seals are checked, does not hold over the columns
372
- * shown (T166). The audit pages list 0.15's changes and uses only with
373
- * this check, and mark one it names as forged: written or edited around
374
- * coffre. Pure CPU, no read; at most `VOUCHED_AT_ONCE` entries a call.
375
- */
376
- vouch?(input: VouchInput): Promise<{ forged: string[] }>;
377
- /**
378
- * With 0.15's log, whether its checkpointer seals (T169): open, its last
379
- * tick ended well, and within the last few seconds. What `/readyz` asks,
380
- * since a change answers only once sealed (R51). Bounded: a checkpointer
381
- * that does not answer is said not to seal, at once.
382
- */
383
- sealing?(): Promise<Sealing>;
384
- }
385
-
386
- /** Whether 0.15's checkpointer seals, and if not, why (`Vault.sealing`). */
387
- export type Sealing = { ok: true } | { ok: false; reason: string };
388
-
389
- /**
390
- * What the error of a change says when the change committed but its seal
391
- * did not come in time (T169): the checkpointer stalled, or cannot be
392
- * reached. Its words are the contract, since only an error's message
393
- * crosses Workers' RPC: the app answers 503 with Retry-After
394
- * (`isUnsealed`), and the change is in force.
395
- */
396
- export const UNSEALED = 'was committed, but not sealed in time';
397
-
398
- /** Whether `error`, or one of its causes, is a change's seal that did not come in time (`UNSEALED`). */
399
- export function isUnsealed(error: unknown): boolean {
400
- for (let cause = error; typeof cause === 'object' && cause !== null; cause = (cause as { cause?: unknown }).cause) {
401
- const { message } = cause as { message?: unknown };
402
- if (typeof message === 'string' && message.includes(UNSEALED)) return true;
403
- }
404
- return false;
74
+ about(): Promise<About>;
405
75
  }
406
76
 
407
- /** The most entries one `vouch` call checks: a page of the audit log lists a few hundred at most. */
408
- export const VOUCHED_AT_ONCE = 2000;
409
-
410
- /** Entries of 0.15's log to vouch for, each with every column its MAC covers, bytes in hex, its number as text. */
411
- export type VouchInput = { entries: VouchedEntry[] };
412
-
413
- export type VouchedEntry =
414
- | { tree: 'changes'; number: string; at: number; requestId: string; object: string; actor: string; payload: string; seal: string | null; mac: string }
415
- | { tree: 'uses'; number: string; at: number; requestId: string; credential: string; secret: string; purpose: number; place: string | null; mac: string }
416
- /** A read as the projector wrote it (`log_reads`, T166): its MAC covers its number too. */
417
- | {
418
- tree: 'reads'; number: string; at: number; credential: string; purpose: number; principal: string; secret: string; environment: string; project: string;
419
- place: string | null; source: string | null; sourceEnvironment: string | null; sourceProject: string | null; version: string | null; mac: string;
420
- }
421
- /** The projection's cursor (`log_reads_cursor`, T166), named `cursor` in the answer: whether the pages may say reads are whole up to it. */
422
- | { tree: 'cursor'; number: 'cursor'; through: string; pair: string; at: number; mac: string | null };
77
+ /** Where a request came from, which every call carries. */
78
+ export type Trace = {
79
+ /** The app's id for the request, for the log. */
80
+ request: string | null;
81
+ /** The address it came from, for the log, and for a workload's binding that names its sources. */
82
+ ip: string | null;
83
+ };
423
84
 
424
85
  /**
425
- * 0.15's log as its check found it. `problems` names what does not hold,
426
- * each at its entry where it has one: a checkpoint not signed, or not the
427
- * one held outside; an entry whose MAC fails, or under another's request.
428
- * Numbers are decimal text: the log's are 64-bit.
86
+ * What a request showed, which every call but a change nobody asks starts
87
+ * with. The app never says who is asking: the vault finds the credential
88
+ * by its token.
429
89
  */
430
- export type ReadsVerification =
431
- | { kept: false }
432
- | {
433
- kept: true;
434
- /** Nothing wrong found in the stretch. */
435
- ok: boolean;
436
- problems: string[];
437
- /** The entry the stretch checked through, and how far the projector has listed. */
438
- through: string;
439
- listed: string;
440
- /** Where the next stretch starts; null at the projector's cursor, or on a problem that stops the check. */
441
- next: string | null;
442
- };
443
-
444
- export type TreeVerification =
445
- | { kept: false }
446
- | {
447
- kept: true;
448
- /** Checked to the head, and nothing wrong found. */
449
- ok: boolean;
450
- problems: string[];
451
- /** The newest pair checked, and when it was signed (ms); null before the first. */
452
- checkpoint: { upto: string; at: number } | null;
453
- /** The entries above the newest pair it checked. */
454
- unsealed: number;
455
- /**
456
- * Whether more lie there than a check reads (`ABOVE_NEWEST`, 2,000): a
457
- * checkpointer behind. Not checked to the head, so `ok` is false; no
458
- * problem either, and never a break of the log.
459
- */
460
- capped: boolean;
461
- };
90
+ export type Presented = Trace & {
91
+ /** The SHA-256 of the token the request presented, in lowercase hex. */
92
+ token: string;
93
+ /**
94
+ * The thumbprint of the key that signed the request's proof (RFC 9449),
95
+ * once the app has held the proof to the request: a workload's session
96
+ * is its key's alone. Null with no proof.
97
+ */
98
+ proof: string | null;
99
+ };
462
100
 
463
101
  /**
464
- * The columns of a row the app writes that a decision of 0.15's reads, as
465
- * the vault's objects take them (packages/vault/src/objects.ts): times in
466
- * ms since the epoch, uuids as text, JSON as stored.
102
+ * A change as the app sends it: its operation's input, with what the
103
+ * request showed, or for one nobody asks (`Unasked`), where it came from
104
+ * alone.
467
105
  */
468
- export type CredentialColumns = {
469
- id: string;
470
- principal: string;
471
- kind: string;
472
- /** Its scope as stored, JSON; null for a session's. */
473
- scope: string | null;
474
- revoked: boolean;
475
- /** The earlier of its expiry and its hard end, if any, in whole ms: a stored time's sub-millisecond part dropped, never rounded. */
476
- expiresAt: number | null;
477
- /** Its account's generation when it was issued (`credentials.generation`). */
478
- generation: number;
479
- };
106
+ export type Asked<O extends Change['op']> = O extends Change['op'] ? (O extends Unasked | WorkloadsUnasked | McpUnasked ? Trace : Presented & ForConnection) & Extract<Change, { op: O }> : never;
480
107
 
481
108
  /**
482
- * An MCP connection's (`mcp_connections`), as its object takes them (T147):
483
- * whose it is, at which generation of their account it was approved, its
484
- * end, and whether it was revoked. What a refresh moves (its tokens' hashes)
485
- * and its last use are no part of it.
109
+ * The approval a person makes a change for, on coffre's page
110
+ * (docs/design/0.16.md, "An MCP client's changes"): the change is theirs,
111
+ * made on their browser session, and its entry names the app that asked.
112
+ * The vault reads the connection and the approval with the change's other
113
+ * rows. The connection must stand, be of the caller's own member and
114
+ * generation, and the caller be on a browser session, or the change is
115
+ * refused `disconnected`. The approval must be the connection's, pending,
116
+ * unexpired by the time the write starts, and of the `digest` the page
117
+ * rendered, or it is refused `unknown_approval`. Made, the change marks the
118
+ * approval approved in its own write: no approval is approved without its
119
+ * change, nor a change made twice under one. It decides nothing else: what
120
+ * the change may do is the person's.
486
121
  */
487
- export type ConnectionColumns = {
488
- id: string;
489
- principal: string;
490
- generation: number;
491
- /** Its `expires_at`, in whole ms: a stored time's sub-millisecond part dropped, never rounded. */
492
- expiresAt: number;
493
- revoked: boolean;
122
+ export type ForConnection = {
123
+ via?: { connection: string; approval: string; digest: string };
494
124
  };
495
125
 
496
- /** One object's change, as the app will write it: its columns before (null: it makes the object), their seal, and after. */
497
- export type ObjectChange =
498
- | ChangeOf<'credential', CredentialColumns, CredentialColumns>
499
- | ChangeOf<'connection', ConnectionColumns, ConnectionColumns>
500
- /**
501
- * A key's: null after, archived or erased (no object). `restores`: an
502
- * archived key unarchived, `after` its rows as read: the vault holds them
503
- * to the object its log last sealed, and refuses another (`stale`).
504
- */
505
- | (ChangeOf<'secret', SecretColumns, SecretColumns | null> & { restores?: true })
506
- | ChangeOf<'environment', EnvironmentColumns, EnvironmentColumns>;
507
-
508
- type ChangeOf<K extends string, Before, After> = {
509
- kind: K;
510
- id: string;
126
+ export type UseInput = Presented & {
127
+ /** The place, by its slugs. */
128
+ project: string;
129
+ environment: string;
130
+ /** The caller's personal config of that environment, `@me`, where they have one. */
131
+ mine: boolean;
132
+ /** The keys asked for, by name, 1,000 at most: null is every key the environment has. */
133
+ keys: string[] | null;
134
+ /** `use`: the value is used for the caller, by the credential proxy, and never handed back. Any other hands it back. */
135
+ purpose: Purpose;
136
+ /** What the values are used for (`Upstream`): null for none. */
137
+ upstream: Upstream | null;
511
138
  /**
512
- * As the app read the row, with its seal: null for no object (no row, or
513
- * a key archived); a null seal, a row the vault never sealed (0.14's,
514
- * before the cutover).
139
+ * Read the rows now, never from the vault's memory (`memorySeconds`): an
140
+ * answer that must see a change just made (`coffre run`'s plan after the
141
+ * values it generated were written). Any read may ask it; the rows read are
142
+ * remembered all the same.
515
143
  */
516
- before: { columns: Before; seal: string | null } | null;
517
- after: After;
518
- };
519
-
520
- /** The version a key's value is: its ids, its nature and its wrapped data key; a plain one's text. Never its ciphertext. */
521
- export type VersionColumns = {
522
- id: string;
523
- sensitive: boolean;
524
- /** A plain value's text, which it is (no data key the vault opens); null for any other. Its object holds its digest. */
525
- plaintext: string | null;
526
- kekProvider: string;
527
- kekId: string;
528
- kekVersion: string;
529
- /** The wrapped data key, base64. */
530
- wrappedDek: string;
144
+ fresh?: boolean;
531
145
  };
532
146
 
533
147
  /**
534
- * A live key's columns (`secrets`): where it is, its current version, or,
535
- * for a reference, the source its newest `secret_references` row names
536
- * while it has no version of its own, and that row's id (both null for a
537
- * key with a value, and for one whose newest reference row has ended:
538
- * `ended_at`).
148
+ * The upstream credential a use is for, by its name in the deployment's
149
+ * configuration (`stripe`), and where the proxy sends the values, which the
150
+ * use's entry keeps on the app's word, as 0.14.7's app logged it: the host
151
+ * (`api.stripe.com`, a presigned URL's), and `egress` when the request
152
+ * leaves through the deployment's egress. Signing, verifying, a cipher and
153
+ * a tunnel name no host: they send nothing anywhere, or the host is in the
154
+ * value.
539
155
  */
540
- export type SecretColumns = { id: string; projectId: string; environmentId: string; source: string | null; reference: string | null; version: VersionColumns | null };
541
-
542
- /** An environment's columns (`environments`). Its slug as stored: a deleted one's carries a tombstone, `dev~deleted-…`. */
543
- export type EnvironmentColumns = {
544
- id: string;
545
- projectId: string;
546
- slug: string;
547
- owner: string | null;
548
- parentId: string | null;
549
- /** Null until the cutover writes it (0022): not protected. */
550
- protected: boolean | null;
551
- /** Its own `archived_at`. */
552
- archived: boolean;
553
- /** Its project's: 0.14 takes an environment of an archived project as archived. */
554
- projectArchived: boolean;
555
- };
556
-
557
- export type PrepareInput = {
558
- /** Who makes the changes, as their entries name them: `user:…`, `token:…`, or the app's own (`coffre`). */
559
- actor: string;
560
- changes: ObjectChange[];
561
- };
156
+ export type Upstream = { credential: string; host?: string; egress?: true };
562
157
 
563
158
  /**
564
- * A change sealed, for the app's transaction to commit (`app_change`): its
565
- * entry's fields, the seal it moves the row from and to, and its MAC, bytes
566
- * in base64. A row the vault never sealed is the log's to leave alone until
567
- * the cutover: its call (`requestId` null) only checks, under the fence,
568
- * that the log has no change of its object either.
159
+ * Why someone reads, which the log shows. `use`: the credential proxy
160
+ * injects the value into a request and never hands it back. Every other
161
+ * hands the value back: `reveal` of one key, `run` of an environment,
162
+ * `compare` of a guess in a dry run, `expose` by the proxy to a person's
163
+ * own app.
569
164
  */
570
- export type PreparedChange = {
571
- kind: ObjectChange['kind'];
572
- id: string;
573
- requestId: string | null;
574
- at: number;
575
- /** The object's key in the log (`log_object`). */
576
- object: string;
577
- actor: string;
578
- payload: string | null;
579
- sealFrom: string | null;
580
- seal: string | null;
581
- mac: string | null;
582
- /** An unarchive's: the seal of the object it restores, which must still be its log's newest sealed one; else null. */
583
- restores: string | null;
584
- };
585
-
586
- export type Prepared = { changes: PreparedChange[] };
165
+ export const PURPOSES = ['reveal', 'run', 'compare', 'expose', 'use'] as const;
166
+ export type Purpose = (typeof PURPOSES)[number];
587
167
 
588
168
  /**
589
- * A sign-in through a trust binding (`Vault.signIn`). Times in ms since the
590
- * epoch, bytes in base64.
169
+ * One key's value, or why this caller is not given it. `secret` is where the
170
+ * value is held: a reference's source. `nature` is the one the value opened
171
+ * under, which its encryption names (`contextOf`), so a row relabelled behind
172
+ * the vault cannot turn a secret into a plain value: what the proxy leaves
173
+ * unredacted when an upstream echoes it.
591
174
  */
592
- export type SignInInput = {
593
- /** The account it signs in as, `token:<id>`. */
175
+ export type UsedValue = { key: string; secret: string; version: number; nature: Nature; value: string } | { key: string; refused: string };
176
+
177
+ export type Used = {
594
178
  principal: string;
179
+ /** The credential's id. */
180
+ credential: string;
595
181
  /**
596
- * The binding as the app read it, with its seal: the vault decides only
597
- * on one whose seal is its own (PR 3a), and the statement holds the row
598
- * to it and to its object's newest change.
599
- */
600
- binding: { columns: BindingColumns; seal: string | null };
601
- /** The credential the app hands out once made: its row, the app's MAC over it (`auth_mac`) with it. */
602
- credential: SignInCredential;
603
- /** The id of the app's log key, under whose key the MAC was made: refused once the app has rotated from it (`retired`). */
604
- appKey: string;
605
- /** The ID token's signing input's hash, spent once; null for a proof that spends none. */
606
- spent: string | null;
607
- /**
608
- * The last instant the proof holds by its own times, ms (an ID token's
609
- * `exp` and its `iat`'s hour, each with their tolerance): checked again
610
- * in the statement, by the database's clock. Null: its credential's
611
- * `notAfter` bounds it.
612
- */
613
- validUntil: number | null;
614
- /** What the change records of the sign-in besides (D147): the proof, its issuer, and the run's claims. */
615
- record: { proof: string; issuer: string; run: Record<string, string | number> };
616
- /**
617
- * The run's ID token, for the vault to verify itself (D148, PR 3b), when
618
- * its sealed binding carries the issuer's keys (its `jwksUri` their
619
- * digest, as a Kubernetes cluster's does), with those keys as its row
620
- * keeps them; the vault then takes `spent`, `validUntil` and `record.run`
621
- * from the token, not from the app. Null for a binding of keys its issuer
622
- * publishes, which the vault does not fetch (it asks no issuer anything),
623
- * and for a proof that is no ID token (an AWS signed request):
624
- * the app verifies those, so a compromised app could sign a run in
625
- * through such a binding, within its limits.
182
+ * The credential's effective end, ISO 8601: the instant the vault starts
183
+ * refusing it for age, the earliest of its own end, a workload session's
184
+ * hard end (`notAfter`) and those of the sessions it was narrowed from.
185
+ * Not `Called.credential.expiresAt`, its own row's end. A grant that ends
186
+ * sooner, a revoke or a freeze does not move it: what a presigned URL
187
+ * lasts no longer than, and may outlive those, as on 0.14.7.
626
188
  */
627
- idToken: { token: string; jwks: string } | null;
628
- /** A workload's DPoP proof, whose key the session is bound to, which the vault verifies; null for a CI run's sign-in. */
629
- dpop: string | null;
189
+ expiresAt: string;
190
+ values: UsedValue[];
191
+ /** 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. */
192
+ workload: { binding: string; profile: string; policy: BindingPolicy; constraints: Constraints | null } | null;
630
193
  };
631
194
 
632
195
  /**
633
- * A trust binding's columns as its object takes them (T149, PR 3a): what a
634
- * sign-in through it decides on. Its keys by `jwksUri` (the issuer's
635
- * discovered URL, or `sha256:<hex>` of keys uploaded with it); its claims
636
- * and policy as the row keeps them, canonical JSON.
637
- */
638
- export type BindingColumns = {
639
- id: string;
196
+ * What a use would give: each key's secret, version and nature, or why it
197
+ * is refused; nothing opened. The nature is the one its rows say, which the
198
+ * use holds the value to: what `coffre run`'s plan picks the keys it asks
199
+ * for by, and never what it places a value by, which is the use's.
200
+ *
201
+ * For what `coffre run` generates in a personal config, of a key the caller
202
+ * is given and no other: `versionId`, the version's id, which a write's
203
+ * `replaces` names (a listing's `versionId`); `recipe`, what made it, null
204
+ * for a value typed or a reference; `own`, held in the caller's personal
205
+ * config, not inherited. `personal`: the read found the caller's personal
206
+ * config of the environment (`@me`), not the environment itself.
207
+ */
208
+ export type Peeked = {
640
209
  principal: string;
641
- generation: number;
642
- profile: string;
643
- issuer: string;
644
- /**
645
- * The instance's public URL it was made on (PR 3b): its base audience, as
646
- * a token for it must name it (`expectedAudiences`), and where a workload's
647
- * DPoP proof is signed for. No column: the app names it, and the seal
648
- * holds it, so a binding of another URL's is none of this instance's.
649
- */
650
- origin: string;
651
- jwksUri: string;
652
- claims: string;
653
- scope: string | null;
654
- policy: string | null;
655
- revoked: boolean;
656
- };
657
-
658
- /** A binding the vault makes (`changeBindings`): its object's columns and the rest of its row, with the app's MAC over it. */
659
- export type MadeBinding = BindingColumns & { jwks: string | null; label: string | null; createdBy: string; createdAt: number; authMac: string };
660
-
661
- /** 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. */
662
- export type EndedBinding = {
663
- /** Its seal null for one 0.14 made, which the log never held: ended all the same, its row revoked with no change. */
664
- before: { columns: BindingColumns; seal: string | null };
665
- authMacFrom: string;
666
- authMac: string;
667
- /**
668
- * Every live credential it issued, each as `revokeCredential` names one: the statement holds the set to the rows. One
669
- * with no seal (0.14's, or written around the vault) is ended all the same, its row revoked with no change.
670
- */
671
- credentials: { before: { columns: CredentialColumns; seal: string | null }; authMacFrom: string; authMac: string }[];
672
- };
673
-
674
- export type ChangeBindingsInput = {
675
- /** Who changes them, as its entry names them. */
676
- actor: string;
677
- /** The credential the request came in on, by id; null for none. */
678
- via: string | null;
679
- /** The issuer's access as the app weighed the scope on (`access_seq`), decimal; null when it weighed none. */
680
- actorAccess: string | null;
681
- /** The MCP connection the request came through, at the caller's generation, held to still connected; null for none. */
682
- connection: { id: string; generation: number } | null;
683
- /** The binding it makes; null for an unbind. Its account at its generation, as its columns name them. */
684
- make: MadeBinding | null;
685
- /** With a binding made, the account's live bindings as the app read them, by id, which it was weighed beside; else null. */
686
- live: string[] | null;
687
- /** The keys a binding made reads (its policy's `reads`), by id and the name they were asked by: none moves before the write. */
688
- reads: { id: string; key: string }[];
689
- /** The bindings it ends: those the new one replaces, or the one unbound. */
690
- ends: EndedBinding[];
691
- /** Why they end, for the changes' record. */
692
- reason: 'replaced' | 'keys_moved' | 'unbound';
693
- revokedAt: number;
694
- revokedBy: string;
695
- /** The policy the app weighed on: the newest `policy.change`'s seq and the protected environments' slugs. */
696
- policy: { seq: string | null; protected: { environmentId: string; slug: string | null }[] };
697
- appKey: string;
210
+ /** The credential's id. */
211
+ credential: string;
212
+ personal: boolean;
213
+ items: ({ key: string; secret: string; version: number; nature: Nature; versionId: string; recipe: string | null; own: boolean } | { key: string; refused: string })[];
698
214
  };
699
215
 
700
216
  /**
701
- * Why bindings were not changed, nothing written: as an issue's
702
- * (`IssueTokenRefusal`); `stale` or `tampered`, a row the log does not
703
- * hold as its newest (put back) or not the vault's seal; `unlogged`, the
704
- * credential the request came in on one 0.14 made (a binding 0.14 made,
705
- * the vault ends itself, with no change);
706
- * `full`, the account holds as many live bindings as one may
707
- * (`MAX_BINDINGS`), besides those the change ends.
708
- */
709
- export type ChangeBindingsRefusal = IssueTokenRefusal | 'stale' | 'tampered' | 'full';
710
-
711
- /** A point of 0.14's chain: an entry's number and its hash (hex); `-1` and the zero hash before the first. */
712
- export type ChainMark = { seq: string; hash: string };
713
-
714
- /**
715
- * What the app vouches for, of 0.14's, at the cutover (`Vault.cutover`):
716
- * what 0.14 accepts that only the app's key says, each checked as 0.14's
717
- * app checks it.
217
+ * Who a request is: its principal, `user:<email>` or `token:<name>`, the
218
+ * credential it came in on, and what it holds, as `allows` in
219
+ * `@coffre/core/access` decides on it: its role in the instance and that
220
+ * role's scope, its live grants, a token's own scope, the definitions of
221
+ * the roles it holds and of no other (a role absent from `policy` is one
222
+ * the caller does not hold, not one that grants nothing to anyone), and
223
+ * every environment the instance protects.
718
224
  */
719
- export type CutoverInput = {
225
+ export type Called = {
226
+ principal: string;
720
227
  /**
721
- * The stretch of 0.14's chain whose app entries the app checked by their
722
- * MACs, every link included: from where the vault said it verifies from,
723
- * to the head as the app read it. An app entry after `to` sends the
724
- * cutover back to the app (`moved`).
228
+ * `expiresAt` is ISO 8601, the row's own end: a use's `Used.expiresAt`
229
+ * is the effective one, which a session's hard end and the rows above it
230
+ * may bring sooner. An MCP connection's access token (kind `mcp`)
231
+ * says which connection it is under and the scopes it holds, from its
232
+ * row; no other credential has either. `label` is the one it was made
233
+ * with: a personal token's, which `GET /me` names it by.
725
234
  */
726
- checked: { from: ChainMark; to: ChainMark };
235
+ credential: { id: string; kind: string; expiresAt: string; label: string | null; connection?: string; scopes?: McpScope[] };
236
+ holds: Holdings & { policy: Policy };
727
237
  /**
728
- * Each credential 0.14 accepts as it stands, its object's columns as
729
- * read: its MAC the app's, not revoked nor past its end, its sign-in
730
- * account not unlinked, and no revoke of it in the log (`token.revoke`,
731
- * `sign_out`). One a binding issued is left out: 0.14 reads its scope
732
- * from the binding, so its row holds none to seal.
238
+ * For a call that asked (`head`): the log's head as the vault last signed
239
+ * it, read with the caller's rows and held to the vault's MAC; null when
240
+ * no head stands under it. The audit page proves each entry it shows
241
+ * against these roots; one past these sizes is proven by nothing here.
733
242
  */
734
- credentials: CredentialColumns[];
735
- /** Each trust binding 0.14 accepts as it stands: its MAC the app's, not revoked, and no `token.unbind` of it. */
736
- bindings: BindingColumns[];
737
- /** Each MCP connection 0.14 accepts as it stands (T147): its MAC the app's, not revoked nor past its end. */
738
- connections: ConnectionColumns[];
739
- /** Each place 0.14's chain deleted, by an authentic `project.delete` or `environment.delete`, with the tombstone it gave the slug. */
740
- deleted: { kind: 'project' | 'environment'; id: string; tombstone: string }[];
243
+ head?: SignedHead | null;
741
244
  };
742
245
 
743
246
  /**
744
- * The cutover's answer: done (now, or before); not yet, with where 0.14's
745
- * chain is verified from; `moved`, a 0.14 write since the app read what it
746
- * vouched for (ask again); `refused`, 0.14's chain or rows not as 0.14
747
- * accepts them, which a cutover does not seal (an operator's to look at).
247
+ * The log's signed head: how many entries are numbered (`size`), and each
248
+ * tree's size and root, hex (the changes kept for good, and the uses that
249
+ * age out, of which `agingFrom` is the first still there). `signedAt` is
250
+ * ISO 8601. It says the vault signed this log, not that none is newer: the
251
+ * signer holds the log's end to its own copy every minute, and walks the
252
+ * rest within a day.
748
253
  */
749
- export type CutoverOutcome =
750
- | { ok: true; done: true }
751
- | { ok: true; done: false; from: ChainMark }
752
- | { ok: false; refused: 'moved' | 'refused'; why: string };
753
-
754
- export type ChangeBindingsOutcome = { ok: true; number: string; witnessed: boolean | null } | { ok: false; refused: ChangeBindingsRefusal; why?: string };
254
+ export type SignedHead = { size: number; keptSize: number; keptRoot: string; agingSize: number; agingRoot: string; agingFrom: number; signedAt: string };
755
255
 
756
- /** The row a sign-in writes (`credentials`): a service's credential for a CI run, or a workload's key-bound session. */
757
- export type SignInCredential = {
758
- id: string;
759
- kind: 'service' | 'workload';
760
- tokenHash: string;
761
- tokenHint: string;
762
- label: string | null;
763
- scope: string | null;
764
- places: string | null;
765
- expiresAt: number;
766
- notAfter: number | null;
767
- jkt: string | null;
768
- authMac: string;
769
- };
256
+ /** Why a call is not answered. Nothing it asked was written. */
257
+ export type Refused = { refused: string };
770
258
 
771
259
  /**
772
- * Why a sign-in made nothing, the statement's own words: the account or
773
- * the binding not as named, frozen, its rate spent (or a lock not had in
774
- * time), its times past or too far, the token spent, the app's key one it
775
- * rotated from.
260
+ * Every change the vault makes: its operation, and what that one takes.
261
+ * Each area's are in a file of its own (`changes/`), with what each
262
+ * answers once it is made.
776
263
  */
777
- /** 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). */
778
- export type SignInRefusal = 'unbound' | 'frozen' | 'busy' | 'expired' | 'replayed' | 'retired' | 'unsealed' | 'proof';
264
+ export type Change = SecretsChanges | PlacesChanges | AccessChanges | SigninChanges | WorkloadChanges | FreezeChanges | McpChanges;
265
+ export type Answers = SecretsAnswers & PlacesAnswers & AccessAnswers & SigninAnswers & WorkloadAnswers & FreezeAnswers & McpAnswers;
779
266
 
780
267
  /**
781
- * A sign-in's answer. `proof`: the vault's check of the token or the DPoP
782
- * proof refused it, `reason` saying why as the app's refusals do
783
- * (`ExchangeReason`), and a key the binding's uploaded set lacks naming
784
- * it (`kid`).
268
+ * Every action the vault writes to the log, an entry's `action`: each
269
+ * writer's is typed on it, and the audit page keys its sentences on it
270
+ * (`@coffre/ui`, `TEMPLATES`), so an action added without its sentence,
271
+ * or a sentence left for one no writer writes, fails the typecheck.
785
272
  */
786
- export type SignInOutcome =
787
- | { ok: true; number: string; witnessed: boolean | null }
788
- | { ok: false; refused: Exclude<SignInRefusal, 'proof'> }
789
- | { ok: false; refused: 'proof'; reason: string; message: string; kid: string | null };
273
+ export const LOG_ACTIONS = [
274
+ 'secret.read', 'secret.write', 'secret.loosen', 'secret.rename', 'secret.refile', 'reference.break', 'missing.dismiss',
275
+ 'project.create', 'project.update', 'project.archive', 'project.restore', 'project.move', 'project.delete', 'folder.refile',
276
+ 'environment.create', 'environment.update', 'environment.archive', 'environment.restore', 'environment.delete',
277
+ 'environment.protect', 'environment.unprotect', 'upstream.freeze', 'upstream.thaw',
278
+ 'member.add', 'member.restore', 'member.role', 'member.remove', 'access.grant', 'access.revoke', 'policy.change', 'settings.change',
279
+ 'sign_in', 'sign_out', 'token.create', 'token.revoke', 'account.link', 'account.unlink', 'device.start', 'device.approve', 'device.deny',
280
+ 'token.exchange', 'workload.renew', 'token.bind', 'token.unbind', 'workload.freeze', 'workload.unfreeze',
281
+ 'mcp.connect', 'mcp.token', 'mcp.disconnect', 'oauth.register', 'mcp.ask', 'mcp.approve', 'mcp.deny',
282
+ 'upkeep.expire', 'vault.adopt',
283
+ ] as const;
284
+ export type LogAction = (typeof LOG_ACTIONS)[number];
790
285
 
791
- /** A token the vault issues (`Vault.issueToken`). Times in ms since the epoch, bytes in base64. */
792
- /**
793
- * What the app's entry would name a request by, which a change's record
794
- * keeps for the audit pages where 0.14's entry stood (D147, T164): the
795
- * credential or MCP connection whose act it was, as an entry's
796
- * `credentialId` (a run's credential, a personal token, an app connected
797
- * through MCP); and, through MCP, the app and the approval, as its `via`.
798
- * The app's word, which the vault records and never weighs.
799
- */
800
- export type RequestTrace = {
801
- credentialId: string;
802
- mcp: { connectionId: string; clientId: string; clientName: string; approvalId: string | null } | null;
803
- };
286
+ export type * from './changes/access.ts';
287
+ export type * from './changes/freezes.ts';
288
+ export type * from './changes/mcp.ts';
289
+ export type * from './changes/places.ts';
290
+ export type * from './changes/secrets.ts';
291
+ export type * from './changes/signin.ts';
292
+ export type * from './changes/workloads.ts';
804
293
 
805
- export type IssueTokenInput = {
806
- /** Who issues it, `user:…` or `token:…`: the request's caller. */
807
- actor: string;
808
- /** The credential the request came in on, by id; null for none (a request the app made itself). */
809
- via: string | null;
810
- /** Whose act it was, for its change's record (`RequestTrace`); none for a request on no such credential. */
811
- trace?: RequestTrace | null;
812
- /** Whom it acts as: a service account's `token:<id>`, or the actor, for a personal token or a handle. */
813
- principal: string;
814
- /** The principal's generation it is issued at. */
815
- generation: number;
816
- /**
817
- * The issuer's access the app weighed the scope on: the vault's newest
818
- * access entry about them (`issuerNow`), which the vault holds the issue
819
- * to (`access`, as `issuerStill`); null to hold it to none.
820
- */
821
- actorAccess: string | null;
822
- credential: IssuedTokenRow;
823
- /** The policy the app weighed the scope on: its newest `policy.change`, and the environments it protected (`policyStill`'s). */
824
- policy: { seq: string | null; protected: { environmentId: string; slug: string | null }[] };
825
- /** The id of the app's log key, under whose key the row's MAC was made (`SignInInput.appKey`). */
826
- appKey: string;
827
- };
828
-
829
- /** The row a token's issue writes (`credentials`). */
830
- export type IssuedTokenRow = {
831
- id: string;
832
- kind: 'service' | 'personal' | 'handle';
833
- tokenHash: string;
834
- tokenHint: string;
835
- label: string | null;
836
- /** Its scope as stored (`storedScope`): what the vault weighs, and seals. */
837
- scope: string;
838
- /** A handle's environments, as made for; null for any other. */
839
- places: string | null;
840
- expiresAt: number;
841
- /** Who issued it, as its row names them: the actor's id. */
842
- createdBy: string;
843
- authMac: string;
844
- };
845
-
846
- /**
847
- * Why a token was not issued, the vault's own words: the issuer may not
848
- * give that scope, or that kind of token (`refused`); the credential the
849
- * request came in on, or the issuer, ended (`ended`); the account it is for
850
- * is not the member it was weighed as (`gone`); the issuer's access moved
851
- * since the app weighed it (`access`); what it was weighed on moved
852
- * while it was written, each of the three times the vault weighed it
853
- * (`moved`), or the policy did (`policy`); a lock not had in time
854
- * (`busy`); the app's key one it rotated from (`retired`); the credential
855
- * the request came in on one 0.14 made, which the log never held, so
856
- * nothing the vault could authenticate (`unlogged`: the app issues on it
857
- * as before).
858
- */
859
- export type IssueTokenRefusal = 'refused' | 'ended' | 'gone' | 'access' | 'moved' | 'policy' | 'busy' | 'retired' | 'unlogged';
860
-
861
- export type IssueTokenOutcome = { ok: true; number: string; witnessed: boolean | null } | { ok: false; refused: IssueTokenRefusal; why?: string };
862
-
863
- /** A revoke (`Vault.revokeCredential`): the credential as the app read it, and the app's MACs over its row before and after. */
864
- export type RevokeCredentialInput = {
865
- /** Who revokes it, as its entry names them: `user:…`, `token:…`, or the app's own (`coffre`). */
866
- actor: string;
867
- /** 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). */
868
- before: { columns: CredentialColumns; seal: string };
869
- authMacFrom: string;
870
- authMac: string;
871
- revokedAt: number;
872
- revokedBy: string;
873
- /** Why, for its change's record: a revoke, or its holder's sign-out. */
874
- reason: 'revoke' | 'sign_out';
875
- /** The credential the request came in on, for its change's record. */
876
- via: string | null;
877
- /** Whose act it was, for its change's record (`RequestTrace`); none for a request on no such credential. */
878
- trace?: RequestTrace | null;
879
- /**
880
- * The policy the caller's right to revoke it was weighed on, held to under
881
- * the fence (as `policyStill` holds a write to it under 0.14's head): the
882
- * newest `policy.change`'s sequence number, and the environments it
883
- * protected, by id, with their slugs (null: deleted). Null for a revoke no policy weighs
884
- * (its holder's own sign-out).
885
- */
886
- policy: { seq: string | null; protected: { environmentId: string; slug: string | null }[] } | null;
887
- };
888
-
889
- /**
890
- * A revoke: its change's number, or why nothing was written: the row not
891
- * as read, or revoked already (`moved`); not its object's newest change's
892
- * (`stale`); its seal not the vault's (`tampered`, a finding); the policy
893
- * it was weighed on changed (`policy`); a lock not had in time (`busy`).
894
- */
895
- export type RevokeCredentialOutcome =
896
- | { ok: true; number: string; witnessed: boolean | null }
897
- | { ok: false; refused: 'moved' | 'stale' | 'tampered' | 'policy' | 'busy' };
294
+ // 0.14's contract, from here on: each type goes with the last of the server's code that names it.
898
295
 
899
296
  /**
900
297
  * The vault's entries that change what a member holds: what their row's
@@ -920,9 +317,9 @@ export type RefusalCode =
920
317
  /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
921
318
  | 'bad_claim'
922
319
  /**
923
- * A person asked for a sensitive value to be handed back (`handsBack`):
924
- * nobody sees one, Owners included. Their apps use it through the
925
- * credential proxy, and service accounts read it.
320
+ * A person asked for a sensitive value to be handed back: nobody sees
321
+ * one, Owners included. Their apps use it through the credential proxy,
322
+ * and service accounts read it.
926
323
  */
927
324
  | 'sensitive'
928
325
  /**
@@ -976,8 +373,6 @@ export type RefusalCode =
976
373
  * Asked again on the answer now, it is decided as they are now.
977
374
  */
978
375
  | 'access_changed'
979
- /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
980
- | 'log_broken'
981
376
  /**
982
377
  * A KEK the vault is given does not open what it wrapped: a restore with
983
378
  * the wrong key, or a key mistyped under the right id. Every key
@@ -993,30 +388,6 @@ export type RefusalCode =
993
388
 
994
389
  export type Outcome<T> = ({ ok: true } & T) | { ok: false; refusal: Refusal };
995
390
 
996
- /** What each refusal says, as the vault answers it and the app shows it. */
997
- export const REFUSAL_MESSAGES: Record<RefusalCode, string> = {
998
- removed: 'this member was removed',
999
- not_a_member: 'not a member',
1000
- no_grant: 'no grant covers this',
1001
- expired: 'the grant that covered this has expired',
1002
- bulk_limit: 'too many secrets read in too short a time',
1003
- bad_claim: 'the key does not belong to this secret',
1004
- deleted: 'this project or environment was deleted',
1005
- ended: 'the reference read through was ended',
1006
- personal: "a personal config's values are its owner's alone",
1007
- sensitive: "a sensitive value is never shown to anyone, Owners included: `coffre run` gives your app a placeholder for it through the credential proxy, and a service account reads it",
1008
- not_owner_issued: 'a service account reads a sensitive value only on a token or trust binding an Owner of its project issued',
1009
- use_only: "a workload uses this value through coffre and never holds it: list it in its binding's reads, where the value is held, if it must",
1010
- not_allowed: 'not allowed to change this',
1011
- last_owner: 'the last Owner of the whole instance stays one: make someone else an Owner first',
1012
- invalid: 'not something the rules allow',
1013
- policy_changed: "the instance's roles or protected environments changed while this was asked: try again",
1014
- access_changed: 'what this member holds changed since the read was decided: try again',
1015
- log_broken: 'the vault log does not hold from the last checkpoint',
1016
- wrong_kek: "this vault's key does not open the data it holds",
1017
- tampered: "this member's record failed the vault's integrity check",
1018
- };
1019
-
1020
391
  /**
1021
392
  * A proposed version the app will store. The ids bind its key, and `path`
1022
393
  * is the app's label for the write's log. Reads name stored version ids
@@ -1046,63 +417,15 @@ export type Wrapped = { wrapped: WrappedKey[]; seqs: number[]; sensitive: boolea
1046
417
  export type WrappedKey = { kekProvider: string; kekId: string; kekVersion: string; bytes: string };
1047
418
 
1048
419
  /**
1049
- * The vault key the vault wraps under now, by provider and ID, and each
1050
- * vault key's check, newest first: a known value wrapped under it
1051
- * (`KEY_CHECK_VALUE` in `@coffre/core/kek`), in its newest `key.check`
1052
- * entry that carries the vault's MAC, at `seq`.
1053
- */
1054
- export type KeyChecks = { current: { kekProvider: string; kekId: string }; checks: (WrappedKey & { seq: number })[] };
1055
-
1056
- /**
1057
- * Why someone reads: shown in the log, and the same rules apply to each. A
1058
- * fork reads to `copy`. The credential proxy reads to `use`, a value it
1059
- * injects into a request and never hands back, or to `expose`, one it
1060
- * gives a person's app as it is (`coffre run`'s plan).
1061
- */
1062
- export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
1063
-
1064
- /**
1065
- * A use's purpose, keepsSensitive and way in as 0.15's log stores them, in
1066
- * one smallint (`log_uses.purpose`, schema 0022, 0046): the purpose's code,
1067
- * plus 256 when a copy keeps values sensitive, plus 512 times its way in's
1068
- * (`USE_WAYS`; T147). The vault writes them; the audit pages read them back
1069
- * (T166).
420
+ * What `about` answers. `kek` is the vault key that wraps every new data
421
+ * key, `previous` those it still unwraps with, by provider and ID.
422
+ * `checks` holds the check of each key the vault signs and seals with
423
+ * (`keyCheckOf` in `@coffre/core/kek`): the one it signs with first, then
424
+ * those it only verifies with. A check is of a signing key, not of a vault
425
+ * key, so it names none: with a key service and a `signingKey`, no vault
426
+ * key has a check at all.
1070
427
  */
1071
- export const USE_PURPOSES = ['reveal', 'run', 'compare', 'copy', 'use', 'expose'] as const satisfies readonly Purpose[];
1072
-
1073
- /** Each way in by its code: a credential's, 0, as every use before T147; then `UseWay`'s. */
1074
- export const USE_WAYS = ['credential', 'connection', 'binding', 'access'] as const satisfies readonly ('credential' | UseWay)[];
1075
-
1076
- // Every purpose and every way in has a code: one missing here fails to compile.
1077
- const everyPurpose: [Exclude<Purpose, (typeof USE_PURPOSES)[number]>] extends [never] ? true : never = true;
1078
- const everyWay: [Exclude<UseWay, (typeof USE_WAYS)[number]>] extends [never] ? true : never = true;
1079
- void everyPurpose;
1080
- void everyWay;
1081
-
1082
- /** A use's code (`USE_PURPOSES`). */
1083
- export function useCode(use: { purpose: Purpose; keepsSensitive?: boolean; way?: 'credential' | UseWay }): number {
1084
- return USE_PURPOSES.indexOf(use.purpose) + (use.keepsSensitive === true ? 256 : 0) + 512 * USE_WAYS.indexOf(use.way ?? 'credential');
1085
- }
1086
-
1087
- /** The purpose, keepsSensitive and way in a use's code stores; null for a code no release writes. */
1088
- export function useOfCode(code: number): { purpose: Purpose; keepsSensitive: boolean; way?: UseWay } | null {
1089
- const purpose = USE_PURPOSES[code % 256];
1090
- const way = USE_WAYS[Math.floor(code / 512)];
1091
- if (!Number.isInteger(code) || code < 0 || purpose === undefined || way === undefined) return null;
1092
- return { purpose, keepsSensitive: code % 512 >= 256, ...(way === 'credential' ? {} : { way }) };
1093
- }
1094
-
1095
- /**
1096
- * Whether a read hands values back to whoever asked, which a person never
1097
- * gets of a sensitive value: every purpose but the proxy's `use` and a
1098
- * fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
1099
- * `compare` included, which tells them whether a guess was right, and any
1100
- * purpose a later app may name.
1101
- */
1102
- export function handsBack(read: { purpose: string; keepsSensitive?: boolean }): boolean {
1103
- if (read.purpose === 'use') return false;
1104
- return !(read.purpose === 'copy' && read.keepsSensitive === true);
1105
- }
428
+ export type About = { kek: { provider: string; id: string }; previous: { provider: string; id: string }[]; checks: string[] };
1106
429
 
1107
430
  /** Ties the vault's entries to the app's request and audit rows. */
1108
431
  type Correlation = {
@@ -1314,9 +637,9 @@ export type AdmitInput = Correlation & Through & {
1314
637
  * Left out, an existing member keeps theirs and a new one is a `member`.
1315
638
  * Changing it takes someone who runs the instance, about someone else;
1316
639
  * making someone an Owner, or changing an Owner's, an Owner of the whole
1317
- * instance, who may change their own too. It never leaves the instance
1318
- * without an Owner of all of it (`last_owner`), nor demotes one the
1319
- * deployment names (`owners`; `not_allowed`).
640
+ * instance (`not_allowed`), who may change their own too. It never leaves
641
+ * the instance without an Owner of all of it (`last_owner`), nor demotes
642
+ * one the deployment names (`owners`; `configured_owner`).
1320
643
  */
1321
644
  role?: InstanceRole;
1322
645
  scope?: Scope;
@@ -1369,6 +692,24 @@ export function policyRevision(seq: number | bigint | null, policy: Pick<Policy,
1369
692
  /** A revision as `policyRevision` writes it. */
1370
693
  export const POLICY_REVISION = /^(none|[1-9][0-9]{0,15})\.[0-9a-f]{16}$/;
1371
694
 
695
+ /**
696
+ * A role's revision, as a change of it is confirmed with
697
+ * (`policy.change`'s `revision`): a digest of what it holds, its columns in
698
+ * any order, or of none. The app answers it with a change's preview; the
699
+ * vault takes the change only while the role's row still says what was
700
+ * weighed.
701
+ *
702
+ * 9c41e07b5d2a8f13 developer, as it ships
703
+ * 74d0b1e6a9c3f852 no such role
704
+ */
705
+ export function roleRevision(definition: Pick<RoleDefinition, 'name' | 'description' | 'permissions' | 'protected'> | null): string {
706
+ const said = definition === null ? null : [definition.name, definition.description, [...definition.permissions].sort(), [...definition.protected].sort()];
707
+ return createHash('sha256').update(JSON.stringify(said)).digest('hex').slice(0, 16);
708
+ }
709
+
710
+ /** A revision as `roleRevision` writes it. */
711
+ export const ROLE_REVISION = /^[0-9a-f]{16}$/;
712
+
1372
713
  export type ChangePolicyInput = Correlation & Through & {
1373
714
  actor: string;
1374
715
  change: PolicyChange;
@@ -1382,243 +723,3 @@ export type ChangePolicyInput = Correlation & Through & {
1382
723
  */
1383
724
  revision?: string;
1384
725
  };
1385
-
1386
- /**
1387
- * A prefix of the log the vault signed: every entry up to `seq`, the last
1388
- * of which has `hash`, which pins every byte before it. Kept as the vault's
1389
- * `audit.checkpoint` entry, just after the prefix it signs.
1390
- */
1391
- export type Checkpoint = {
1392
- seq: number;
1393
- /** The hash of entry `seq`, hex. */
1394
- hash: string;
1395
- signedAt: string;
1396
- keyId: string;
1397
- /** Ed25519 over `checkpointMessage(...)`, base64. */
1398
- signature: string;
1399
- };
1400
-
1401
- /**
1402
- * A public key the vault's checkpoints verify under, base64. One it
1403
- * replaced vouches only for checkpoints whose prefix ends before `until`,
1404
- * its first entry under the key that replaced it; the one it signs with now
1405
- * has none.
1406
- */
1407
- export type CheckpointKey = { publicKey: string; until: number | null };
1408
-
1409
- /** An entry of the vault's log, and so the chain up to it. */
1410
- export type LogHead = { seq: number; hash: string };
1411
-
1412
- export type VerifyLogInput = {
1413
- /**
1414
- * The last entry the app verified, every link and hash up to it
1415
- * recomputed and its own entries checked by its key: the vault checks the
1416
- * log still holds it, so between them both authors' entries are
1417
- * authenticated over the same stretch, and the vault leaves the links to
1418
- * the app.
1419
- */
1420
- upTo?: LogHead | null;
1421
- /**
1422
- * Where the vault's walk starts: the seq of one of its `audit.checkpoint`
1423
- * entries that keeps a tally, or `start`, the first entry. The newest
1424
- * such checkpoint when absent, and a vault older than 0.10.1 walks from
1425
- * the first entry whatever it says.
1426
- */
1427
- from?: number | 'start';
1428
- /**
1429
- * A later checkpoint's entry, whose prefix `upTo` is: the walk ends
1430
- * there, and must come to the tally it keeps. The members' rows and the
1431
- * key batches are as they are now, not then, so only a walk without one
1432
- * holds them to the log.
1433
- */
1434
- to?: number;
1435
- };
1436
-
1437
- /**
1438
- * Whether the vault's log holds, with the number of its entries through
1439
- * where the walk ended, `through`: `upTo`, the prefix `to` signed, or as
1440
- * far as one walk goes. On a failure, the entry where it breaks, or null
1441
- * when the chain holds but the members and grants do not follow from it.
1442
- * Then `fault` says which, as facts the app can word with names: `reason`
1443
- * has only ids. A walk that ends at the present reports live key batches in
1444
- * `pending`; overdue ones fail.
1445
- */
1446
- export type LogVerification =
1447
- | { ok: true; entries: number; pending?: number; through?: number }
1448
- | { ok: false; failedAtSeq: number | null; reason: string; fault?: AccessFault };
1449
-
1450
- // --- 0.15's use -------------------------------------------------------------
1451
-
1452
- /** 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`. */
1453
- export const USE_DEADLINE_MS = 3000;
1454
-
1455
- /** A use's request id: 63 random bits, as text, unique within its millisecond (hot-path-one.md, "Row size"). */
1456
- export function newUseRequestId(): string {
1457
- const bytes = crypto.getRandomValues(new Uint8Array(8));
1458
- return (new DataView(bytes.buffer).getBigUint64(0) >> 1n).toString();
1459
- }
1460
-
1461
- /** A use as the app asks for it: on which credential, which key, through which place, why, and when. */
1462
- export type UseInput = {
1463
- /**
1464
- * What the request came in on (T147): a credentials row, by id; with
1465
- * `way`, an MCP connection or a Cloudflare service binding, by id, or,
1466
- * behind Cloudflare Access, which signs a browser in with no row of
1467
- * coffre's, the person (`user:…`), whose account is all the use weighs.
1468
- */
1469
- credential: string;
1470
- way?: UseWay;
1471
- secretId: string;
1472
- /** The fork an inherited value is read in (`UnwrapInput`'s `through`); null for the key's own environment. */
1473
- place: string | null;
1474
- purpose: Purpose;
1475
- keepsSensitive?: boolean;
1476
- /**
1477
- * The request's id, a whole number below 2^63 as text, unique within its
1478
- * millisecond, and its time, ms since the epoch: a retry of a request
1479
- * whose answer was lost passes both unchanged, and finds the entry the
1480
- * first one wrote (`replayed`).
1481
- */
1482
- requestId: string;
1483
- at: number;
1484
- /** When it must have answered: at most 3 s after `at` (R53). */
1485
- deadline: number;
1486
- };
1487
-
1488
- /**
1489
- * A request's several keys as the app asks for them (`Vault.useMany`): what `UseInput` names but its key, once, and
1490
- * each key with the place it is read through and its own request id, which its entry takes.
1491
- */
1492
- export type UseManyInput = Omit<UseInput, 'secretId' | 'place' | 'requestId'> & {
1493
- items: readonly { secretId: string; place: string | null; requestId: string }[];
1494
- };
1495
-
1496
- /**
1497
- * A request's several keys' answer, all or nothing: every value, in the request's order, each with its entry (or the
1498
- * one it rode on); or the first key refused, by its index in the request, logged as its request was (`number`) or not
1499
- * (null: decided before anything of it was written, as a use's refusal by ids is); or busy, nothing decided.
1500
- */
1501
- export type UseManyOutcome =
1502
- | { ok: true; values: { number: string; covered: boolean; value: UsedValue }[] }
1503
- | { ok: false; index: number; code: UseCode; number: string | null }
1504
- | { ok: false; busy: UseBusy; retryAfter: number };
1505
-
1506
- /** The way in a use came through that has no credentials row (`UseInput.way`): each a sealed object of the log but Access. */
1507
- export type UseWay = 'connection' | 'binding' | 'access';
1508
-
1509
- /** Why a use is refused: the rules' codes, and those of sealed inputs. */
1510
- export type UseCode =
1511
- | RefusalCode
1512
- /** An input's row is not its object's newest change's: put back from before one, deleted, or written around the log. */
1513
- | 'stale'
1514
- /** The credential is not one, was revoked, or had ended at the request's time. */
1515
- | 'credential'
1516
- /** No such key. */
1517
- | 'missing'
1518
- /** The log holds no policy, so no cap: never served, as the vault writes one before its first use. */
1519
- | 'no_policy'
1520
- /**
1521
- * A use by name of a key that reads an archived place, a reference's source's: it reads nothing until that place is
1522
- * back (review r4 of D153). Decided before anything is written, never logged as a use: the app logs the request.
1523
- */
1524
- | 'archived';
1525
-
1526
- /** What a use's refusal says: the rules' as `REFUSAL_MESSAGES`, and those of sealed inputs. */
1527
- export function useRefusalMessage(code: UseCode): string {
1528
- switch (code) {
1529
- case 'stale':
1530
- return 'what this read decides on is not as the vault last sealed it: it was put back, or written around coffre';
1531
- case 'credential':
1532
- return 'that credential is unknown, expired or revoked';
1533
- case 'missing':
1534
- return 'no such key';
1535
- case 'no_policy':
1536
- return "the vault's log holds no bulk cap yet";
1537
- case 'archived':
1538
- return 'what it reads is archived';
1539
- default:
1540
- return REFUSAL_MESSAGES[code];
1541
- }
1542
- }
1543
-
1544
- /** A use as the request names it (`Vault.useNamed`). */
1545
- export type NamedUseInput = {
1546
- /** The token the request came in on, hashed as its credential's row holds it, base64. */
1547
- tokenHash: string;
1548
- /** Where, by slugs; null for the one environment a handle was made for (the credential proxy's stable URL). */
1549
- place: { project: string; environment: string } | null;
1550
- /**
1551
- * With `place` null, the environments the request does not mean, by slugs: served not by name when the handle's is
1552
- * one (the stable URL's segments that name an environment of the handle's instead, one the proxy reads as its
1553
- * person's own config).
1554
- */
1555
- unless?: readonly { project: string; environment: string }[];
1556
- /** The key, by name; null for none: the caller's standing at the place alone, as for a key it does not hold. */
1557
- key: string | null;
1558
- /**
1559
- * The credentials the app's config accepts (review r6 and r7 of D153): `signin`, whether the deployment signs in
1560
- * through coffre's own sign-in (under Cloudflare Access no coffre token is a credential); `issuers`, each sign-in
1561
- * provider it configures, `<provider id>:<issuer hash>`, which a browser session's identity must name. The call
1562
- * holds the token's credential to them first, before anything else it reads: one the app would refuse is answered
1563
- * as a token no credential has, whatever the request names.
1564
- */
1565
- accepts: CredentialAcceptance;
1566
- purpose: Purpose;
1567
- keepsSensitive?: boolean;
1568
- requestId: string;
1569
- at: number;
1570
- deadline: number;
1571
- };
1572
-
1573
- /** What a named use's credential must be for the app to take it (`NamedUseInput.accepts`). */
1574
- export type CredentialAcceptance = { signin: boolean; issuers: readonly string[] };
1575
-
1576
- /**
1577
- * A named use's answer. `served: false`: none the vault serves this way (a fork, a personal config, a handle of
1578
- * several environments, or a place its stable URL does not mean), and the app reads it as ever. Otherwise the route
1579
- * the request takes, which the vault picks on the credential and its account alone (`routeOf`; D153, review r2):
1580
- *
1581
- * - `credential`: the credential's own check answers (401; a token of 0.10's sealed first): no credential its seals
1582
- * bear out, or one ended. `outcome`, the vault's refusal, which the app does not answer with.
1583
- * - `busy`: nothing decided, admission's answer, whatever the request names.
1584
- * - `name`: the use's outcome, a plain value's text where one was allowed, and every refusal of the key alike; the rows
1585
- * the app checks before anything leaves (the credential's with its MAC, the place's, the key's), as `app_read`
1586
- * answers them, JSON; the key's id (null for none held); the place, by slugs; and the caller as the vault decided
1587
- * them, from the sealed rows the use read (one who holds nothing where roles, policy or place were not as sealed).
1588
- */
1589
- export type NamedUseOutcome =
1590
- | { served: false }
1591
- | { served: true; route: 'credential'; outcome: Extract<UseOutcome, { code: UseCode }> }
1592
- | { served: true; route: 'busy'; outcome: Extract<UseOutcome, { busy: UseBusy }> }
1593
- | {
1594
- served: true; route: 'name'; secretId: string | null; outcome: UseOutcome | { ok: true; plain: string; versionId: string }; app: string | null; standing: Access;
1595
- /** The place the use was at, by its slugs as the vault read them: the one named, or the handle's own. */
1596
- place: { project: string; environment: string } | null;
1597
- /** The same place by its ids, as the vault's own rows read it, on either engine: where a refusal is logged. */
1598
- at: { projectId: string; environmentId: string } | null;
1599
- };
1600
-
1601
- /** Why a use was not decided at all: the app answers 503, with `Retry-After`. */
1602
- export type UseBusy = 'late' | 'overloaded' | 'replayed' | 'ahead' | 'unconfigured';
1603
-
1604
- /** A value a use opened: its data key, base64, and the version it decrypts, with what its ciphertext is bound to. */
1605
- export type UsedValue = {
1606
- key: string;
1607
- versionId: string;
1608
- context: { projectId: string; environmentId: string; secretId: string; owner?: string; sensitive?: true };
1609
- envelope: { version: number; ciphertext: string; iv: string; authTag: string };
1610
- };
1611
-
1612
- /**
1613
- * A use's answer. Allowed: the value, and the entry it was logged as (or,
1614
- * a repeat, rode on: `covered`). Refused: why, logged as the request it
1615
- * was. Busy: nothing was decided, ask again in `retryAfter` seconds:
1616
- * `late` (past its deadline, or below the floor), `overloaded` (refused at
1617
- * admission), `replayed` (a retry of a call that wrote: the first one's
1618
- * entry stands, its value never left), `ahead` (its time past the
1619
- * database's clock), `unconfigured` (no policy logged yet).
1620
- */
1621
- export type UseOutcome =
1622
- | { ok: true; number: string; covered: boolean; value: UsedValue }
1623
- | { ok: false; code: UseCode; number: string | null }
1624
- | { ok: false; busy: UseBusy; retryAfter: number };