@coffre/core 0.14.7 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +1 -1
  2. package/dist/{access-BrdZKp1d.js → access-CF8UG59J.js} +70 -8
  3. package/dist/{access-qkMZa-6Z.d.ts → access-ERdGGHG7.d.ts} +45 -3
  4. package/dist/access.d.ts +2 -2
  5. package/dist/access.js +2 -2
  6. package/dist/envelope.d.ts +28 -9
  7. package/dist/envelope.js +25 -8
  8. package/dist/identity.d.ts +2 -917
  9. package/dist/identity.js +1036 -525
  10. package/dist/index-DuG9p3GH.d.ts +1233 -0
  11. package/dist/kek.d.ts +10 -16
  12. package/dist/kek.js +26 -41
  13. package/dist/log.d.ts +114 -0
  14. package/dist/log.js +291 -0
  15. package/dist/mcp.d.ts +25 -1
  16. package/dist/mcp.js +29 -4
  17. package/dist/recipe-BgJpmJum.d.ts +128 -0
  18. package/dist/recipe.d.ts +2 -127
  19. package/dist/{registry-D7X-x202.d.ts → registry-B7_LUDsJ.d.ts} +30 -5
  20. package/dist/schemas.d.ts +14 -4
  21. package/dist/schemas.js +16 -4
  22. package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
  23. package/dist/vault.d.ts +1800 -299
  24. package/dist/vault.js +99 -32
  25. package/package.json +8 -3
  26. package/src/access.ts +63 -8
  27. package/src/changes/access.ts +140 -0
  28. package/src/changes/freezes.ts +40 -0
  29. package/src/changes/mcp.ts +150 -0
  30. package/src/changes/places.ts +219 -0
  31. package/src/changes/secrets.ts +235 -0
  32. package/src/changes/signin.ts +197 -0
  33. package/src/changes/workloads.ts +166 -0
  34. package/src/context.ts +18 -2
  35. package/src/envelope.ts +35 -12
  36. package/src/identity/auth.ts +11 -3
  37. package/src/identity/aws.ts +62 -0
  38. package/src/identity/github-app.ts +45 -24
  39. package/src/identity/index.ts +3 -0
  40. package/src/identity/profiles.ts +139 -0
  41. package/src/identity/proofs.ts +306 -0
  42. package/src/identity/signin/config.ts +1 -1
  43. package/src/identity/tokens.ts +10 -3
  44. package/src/identity/verifier.ts +73 -14
  45. package/src/identity/workload-token.ts +4 -0
  46. package/src/kek/aws-kms.ts +18 -13
  47. package/src/kek/check.ts +16 -46
  48. package/src/kek/index.ts +2 -2
  49. package/src/kek/types.ts +15 -3
  50. package/src/log/index.ts +7 -0
  51. package/src/log/tiles.ts +166 -0
  52. package/src/log/tree.ts +163 -0
  53. package/src/mcp.ts +34 -3
  54. package/src/schemas.ts +16 -2
  55. package/src/vault.ts +308 -276
  56. package/src/checkpoint.ts +0 -22
package/src/vault.ts CHANGED
@@ -1,201 +1,298 @@
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
17
 
11
18
  /**
12
- * The vault as the app sees it: the contract between `@coffre/server` and
13
- * `@coffre/vault`, kept in core so that neither side owns it. Every argument
14
- * and result is plain JSON: strings, numbers, booleans, arrays and objects,
15
- * never a Buffer, a Date, a class or a function. So it crosses a Workers RPC
16
- * boundary, or a process boundary later, as it is, and the in-process
17
- * 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.
18
26
  *
19
- * The app says who is asking and the vault decides. The app never holds a
20
- * key: it encrypts a value under a fresh data key, has the vault wrap that
21
- * key, and stores the result; to read, it names stored versions and the
22
- * 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.
23
31
  *
24
- * Decisions come back as values: `{ ok: false, refusal }` for a refusal, which
25
- * 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.
26
37
  */
27
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>;
28
41
  /**
29
- * Unwrap data keys for `principal`: all of them, or none. Given the
30
- * revision of an answer of `access` the app decided the read on
31
- * (`accessRevision`), only while the principal's access is still that
32
- * one, under their row and the head the decision holds: otherwise it
33
- * refuses `access_changed` and logs no read, and says, by naming it back,
34
- * 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`).
35
45
  */
36
- unwrap(input: UnwrapInput): Promise<Outcome<Unwrapped>>;
46
+ peek(input: UseInput): Promise<Peeked | Refused>;
37
47
  /**
38
- * Wrap fresh data keys for new versions `principal` writes: all, or none.
39
- * `seqs` are the `key.wrap` entries, one per key, which the app's
40
- * `secret.write` entries name as related. `sensitive` says, per key,
41
- * whether its wrap binds it as sensitive: a vault older than 0.10 answers
42
- * 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.
43
51
  */
44
- wrap(input: WrapInput): Promise<Outcome<Wrapped>>;
52
+ caller(input: Presented & { head?: boolean }): Promise<Called | Refused>;
45
53
  /**
46
- * Wrap existing data keys again for new versions of the same secrets,
47
- * under the current key: restoring an old value, or making one stricter.
48
- * It needs a write grant, not a read one, since the key never leaves the
49
- * vault. A new version is never less sensitive than the one it is made
50
- * from, or than its secret's newest: a value is made looser only by
51
- * being written again (`invalid`). Except one: a key's current sensitive
52
- * value made a secret, in place, by an Owner of its project, or of the
53
- * whole instance, on no credential's scope (`ownsProject`; `not_allowed`
54
- * for anyone else), its entry saying `was: 'sensitive'`.
55
- */
56
- rewrap(input: RewrapInput): Promise<Outcome<Wrapped>>;
57
-
58
- /**
59
- * Make secrets references to others: whoever can read the holder's
60
- * environment reads the source through it (docs/design/environments.md).
61
- * The vault checks that `principal` reads each source and writes each
62
- * holder, by their own grants, and logs a `reference.create` per item:
63
- * that entry, under the vault's MAC, is the reference. `seqs` are the
64
- * entries, which the app stores beside each reference and names when it
65
- * reads through one (`UnwrapInput`'s `via`). All, or none.
66
- */
67
- reference(input: ReferenceInput): Promise<Outcome<{ seqs: number[] }>>;
68
- /**
69
- * End references, each with a `reference.end` naming its creation:
70
- * `replaced` when the holder gets a value of its own, which takes write on
71
- * the holder; `broken` otherwise, which takes write on the holder, or
72
- * managing the source's project's access. An ended reference reads no
73
- * more, whatever any row says. All, or none.
74
- */
75
- endReferences(input: EndReferencesInput): Promise<Outcome<{ seqs: number[] }>>;
76
-
77
- /**
78
- * What one principal holds right now: the app asks once per request,
79
- * unless the request reads values on an answer it kept (`accessRevision`),
80
- * and at sign-in for each verified email. A decision, its rows checked:
81
- * lists of who holds what read the rows themselves, and need not ask.
82
- * A person the vault's `owners` names who is no Owner of all of it
83
- * becomes one here, logged (`reason: 'owners'`).
84
- */
85
- access(principal: string): Promise<Access>;
86
- /**
87
- * Set roles at several places for one principal: all of it, or none.
88
- * With `admit`, a service account that is not a member is admitted
89
- * first, in the same decision, as `admit` would: `admitted` says so.
90
- */
91
- setAccess(input: SetAccessInput): Promise<Outcome<{ changes: AccessChange[]; admitted?: Admitted }>>;
92
- /**
93
- * Add a member, bring back a removed one, or change a person's instance
94
- * role and its scope. `generation` is theirs now: sessions and tokens of
95
- * an earlier one are dead.
96
- */
97
- admit(input: AdmitInput): Promise<Outcome<Admitted>>;
98
- /**
99
- * Remove a member: revoke every grant and refuse them until admitted
100
- * again, from `generation` on. An Owner, only an Owner of the whole
101
- * instance removes, and never the last.
102
- */
103
- remove(input: RemoveInput): Promise<Outcome<{ revoked: Grant[]; generation: number }>>;
104
- /**
105
- * The instance's settings, as the vault's newest `settings.change` entry
106
- * says, by its MAC: an entry is where they live, so each change is logged
107
- * by being made. Everywhere, until someone narrows it.
108
- */
109
- settings(): Promise<Settings>;
110
- /** Change the instance's settings: those who run it, never anyone else. */
111
- setSettings(input: SetSettingsInput): Promise<Outcome<{ settings: Settings }>>;
112
-
113
- /**
114
- * The instance's access policy (`Policy` in @coffre/core/access): its
115
- * roles, as an Owner edited and made them, and its protected
116
- * environments, as the vault's newest `policy.change` says, by its MAC.
117
- * As it ships, before any. A vault older than 0.10 has none, and the app
118
- * decides as it ships.
119
- */
120
- policy(): Promise<Policy>;
121
- /**
122
- * Change the policy by one change, its own `policy.change` entry, which
123
- * names it and what it was (docs/design/roles.md):
124
- * - a project or instance role defined, or put back as it ships (null),
125
- * or, one an Owner made, deleted while no grant names it: an Owner of
126
- * the whole instance, and never the Owner role, nor the instance's
127
- * Member;
128
- * - environments of one project protected, by whoever manages its
129
- * environments, before their rows exist too (a fork's); or
130
- * unprotected, by an Owner of the project or of the whole instance
131
- * (`ownsProject`), as far as that project protected them.
132
- * The policy after it, and the newest `policy.change`, which it is as of:
133
- * the change's own, when it changed anything.
134
- */
135
- changePolicy(input: ChangePolicyInput): Promise<Outcome<{ policy: Policy; seq: number | null }>>;
136
-
137
- /**
138
- * Sign the log up to its last entry, in an `audit.checkpoint` entry of
139
- * the vault's, if the chain recomputes from the last checkpoint, the
140
- * vault's entries by their MACs, and that checkpoint's prefix is still
141
- * there, whole. The entry keeps the checkpoint's tally beside it: what a
142
- * walk from the first entry has gathered by the prefix's end (the
143
- * vault's keys, its key batches under way, who is a member and what they
144
- * hold), so that the next checkpoint, and every verification, go on from
145
- * there and read only what is new. A log longer than one walk, as after
146
- * an upgrade from 0.10.0, is signed a stretch a call, behind its head,
147
- * until the checkpoints catch up. Each call also rehashes a stretch of
148
- * what was signed before, round and round, which an entry edited in place
149
- * fails: then it refuses, and every verification reports the refusal.
150
- * A rehash the database fails moves on next time, and `warning` says so;
151
- * a refusal it would have cleared stands meanwhile. The vault reads the log itself: it takes nobody's word for where
152
- * it ends, or for what came before. It checks every member's row too, as
153
- * `access` would, and logs a `vault.tampered` for each one changed around
154
- * it: lists read rows without asking the vault.
155
- */
156
- checkpoint(): Promise<Outcome<{ checkpoint: Checkpoint; warning?: string }>>;
157
- /**
158
- * What the vault's configuration says, which the app shows: the keys its
159
- * checkpoints verify under, by the key id each checkpoint names (the one
160
- * it signs with now, and those of the KEKs it replaced).
161
- */
162
- about(): Promise<{
163
- checkpointKeys: Record<string, CheckpointKey>;
164
- /**
165
- * The emails of those the deployment names Owners of the whole instance
166
- * (`owners`), lowercased: the vault makes them Owners, and refuses to
167
- * demote or remove them. Absent from a vault of 0.5, which names none.
168
- */
169
- owners?: string[];
170
- /**
171
- * @deprecated Always empty: an app of 0.5, deployed after this vault,
172
- * lists and checks root admins here until it is. Gone in 0.7.
173
- */
174
- rootAdmins: [];
175
- }>;
176
- /**
177
- * What an escrowed vault key is checked against: the vault key it wraps
178
- * under now, and each one's check, as the vault wrote it. None of it is
179
- * secret, and the vault answers no guess: a check opens only under its key.
180
- */
181
- keyChecks(): Promise<KeyChecks>;
182
- /**
183
- * Check the log from a checkpoint's tally, the newest unless `from`
184
- * names another, or the first entry: the vault's entries since by their
185
- * MACs, every checkpoint among them against the prefix it signed, the key
186
- * batches accounted for, and the members and grants replayed on from the
187
- * tally to see that the rows follow. With `to`, a later checkpoint, the
188
- * walk stops at the prefix it signed and must come to the tally it keeps:
189
- * a stretch of the whole log, walked from the first entry a stretch at a
190
- * time. The links and hashes of the chain are the caller's to recompute
191
- * through `upTo`, as the app does first; with none, the vault recomputes
192
- * them itself, no further than one walk. A verdict and nothing else, so
193
- * anyone may ask; the app asks for those who read the whole log
194
- * (`readsWholeLog`).
195
- */
196
- verifyLog(input: VerifyLogInput): Promise<LogVerification>;
54
+ * Make a change: one operation, named as its log entry's action is, with
55
+ * its input. All of it, or none.
56
+ */
57
+ change<O extends Change['op']>(input: Asked<O>): Promise<{ answer: Answers[O] } | Refused>;
58
+ /**
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.
66
+ */
67
+ weigh<O extends Exclude<Change['op'], Unasked | WorkloadsUnasked | McpUnasked>>(input: Asked<O>): Promise<{ answer: Answers[O] } | Refused>;
68
+ /**
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.
73
+ */
74
+ about(): Promise<About>;
197
75
  }
198
76
 
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
+ };
84
+
85
+ /**
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.
89
+ */
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
+ };
100
+
101
+ /**
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.
105
+ */
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;
107
+
108
+ /**
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.
121
+ */
122
+ export type ForConnection = {
123
+ via?: { connection: string; approval: string; digest: string };
124
+ };
125
+
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;
138
+ /**
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.
143
+ */
144
+ fresh?: boolean;
145
+ };
146
+
147
+ /**
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.
155
+ */
156
+ export type Upstream = { credential: string; host?: string; egress?: true };
157
+
158
+ /**
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.
164
+ */
165
+ export const PURPOSES = ['reveal', 'run', 'compare', 'expose', 'use'] as const;
166
+ export type Purpose = (typeof PURPOSES)[number];
167
+
168
+ /**
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.
174
+ */
175
+ export type UsedValue = { key: string; secret: string; version: number; nature: Nature; value: string } | { key: string; refused: string };
176
+
177
+ export type Used = {
178
+ principal: string;
179
+ /** The credential's id. */
180
+ credential: string;
181
+ /**
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.
188
+ */
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;
193
+ };
194
+
195
+ /**
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 = {
209
+ principal: 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 })[];
214
+ };
215
+
216
+ /**
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.
224
+ */
225
+ export type Called = {
226
+ principal: string;
227
+ /**
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.
234
+ */
235
+ credential: { id: string; kind: string; expiresAt: string; label: string | null; connection?: string; scopes?: McpScope[] };
236
+ holds: Holdings & { policy: Policy };
237
+ /**
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.
242
+ */
243
+ head?: SignedHead | null;
244
+ };
245
+
246
+ /**
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.
253
+ */
254
+ export type SignedHead = { size: number; keptSize: number; keptRoot: string; agingSize: number; agingRoot: string; agingFrom: number; signedAt: string };
255
+
256
+ /** Why a call is not answered. Nothing it asked was written. */
257
+ export type Refused = { refused: string };
258
+
259
+ /**
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.
263
+ */
264
+ export type Change = SecretsChanges | PlacesChanges | AccessChanges | SigninChanges | WorkloadChanges | FreezeChanges | McpChanges;
265
+ export type Answers = SecretsAnswers & PlacesAnswers & AccessAnswers & SigninAnswers & WorkloadAnswers & FreezeAnswers & McpAnswers;
266
+
267
+ /**
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.
272
+ */
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];
285
+
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';
293
+
294
+ // 0.14's contract, from here on: each type goes with the last of the server's code that names it.
295
+
199
296
  /**
200
297
  * The vault's entries that change what a member holds: what their row's
201
298
  * `access_seq` names, and what a finding about them is newer than while it
@@ -220,9 +317,9 @@ export type RefusalCode =
220
317
  /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
221
318
  | 'bad_claim'
222
319
  /**
223
- * A person asked for a sensitive value to be handed back (`handsBack`):
224
- * nobody sees one, Owners included. Their apps use it through the
225
- * 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.
226
323
  */
227
324
  | 'sensitive'
228
325
  /**
@@ -276,8 +373,6 @@ export type RefusalCode =
276
373
  * Asked again on the answer now, it is decided as they are now.
277
374
  */
278
375
  | 'access_changed'
279
- /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
280
- | 'log_broken'
281
376
  /**
282
377
  * A KEK the vault is given does not open what it wrapped: a restore with
283
378
  * the wrong key, or a key mistyped under the right id. Every key
@@ -322,32 +417,15 @@ export type Wrapped = { wrapped: WrappedKey[]; seqs: number[]; sensitive: boolea
322
417
  export type WrappedKey = { kekProvider: string; kekId: string; kekVersion: string; bytes: string };
323
418
 
324
419
  /**
325
- * The vault key the vault wraps under now, by provider and ID, and each
326
- * vault key's check, newest first: a known value wrapped under it
327
- * (`KEY_CHECK_VALUE` in `@coffre/core/kek`), in its newest `key.check`
328
- * entry that carries the vault's MAC, at `seq`.
329
- */
330
- export type KeyChecks = { current: { kekProvider: string; kekId: string }; checks: (WrappedKey & { seq: number })[] };
331
-
332
- /**
333
- * Why someone reads: shown in the log, and the same rules apply to each. A
334
- * fork reads to `copy`. The credential proxy reads to `use`, a value it
335
- * injects into a request and never hands back, or to `expose`, one it
336
- * gives a person's app as it is (`coffre run`'s plan).
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.
337
427
  */
338
- export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
339
-
340
- /**
341
- * Whether a read hands values back to whoever asked, which a person never
342
- * gets of a sensitive value: every purpose but the proxy's `use` and a
343
- * fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
344
- * `compare` included, which tells them whether a guess was right, and any
345
- * purpose a later app may name.
346
- */
347
- export function handsBack(read: { purpose: string; keepsSensitive?: boolean }): boolean {
348
- if (read.purpose === 'use') return false;
349
- return !(read.purpose === 'copy' && read.keepsSensitive === true);
350
- }
428
+ export type About = { kek: { provider: string; id: string }; previous: { provider: string; id: string }[]; checks: string[] };
351
429
 
352
430
  /** Ties the vault's entries to the app's request and audit rows. */
353
431
  type Correlation = {
@@ -559,9 +637,9 @@ export type AdmitInput = Correlation & Through & {
559
637
  * Left out, an existing member keeps theirs and a new one is a `member`.
560
638
  * Changing it takes someone who runs the instance, about someone else;
561
639
  * making someone an Owner, or changing an Owner's, an Owner of the whole
562
- * instance, who may change their own too. It never leaves the instance
563
- * without an Owner of all of it (`last_owner`), nor demotes one the
564
- * 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`).
565
643
  */
566
644
  role?: InstanceRole;
567
645
  scope?: Scope;
@@ -614,6 +692,24 @@ export function policyRevision(seq: number | bigint | null, policy: Pick<Policy,
614
692
  /** A revision as `policyRevision` writes it. */
615
693
  export const POLICY_REVISION = /^(none|[1-9][0-9]{0,15})\.[0-9a-f]{16}$/;
616
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
+
617
713
  export type ChangePolicyInput = Correlation & Through & {
618
714
  actor: string;
619
715
  change: PolicyChange;
@@ -627,67 +723,3 @@ export type ChangePolicyInput = Correlation & Through & {
627
723
  */
628
724
  revision?: string;
629
725
  };
630
-
631
- /**
632
- * A prefix of the log the vault signed: every entry up to `seq`, the last
633
- * of which has `hash`, which pins every byte before it. Kept as the vault's
634
- * `audit.checkpoint` entry, just after the prefix it signs.
635
- */
636
- export type Checkpoint = {
637
- seq: number;
638
- /** The hash of entry `seq`, hex. */
639
- hash: string;
640
- signedAt: string;
641
- keyId: string;
642
- /** Ed25519 over `checkpointMessage(...)`, base64. */
643
- signature: string;
644
- };
645
-
646
- /**
647
- * A public key the vault's checkpoints verify under, base64. One it
648
- * replaced vouches only for checkpoints whose prefix ends before `until`,
649
- * its first entry under the key that replaced it; the one it signs with now
650
- * has none.
651
- */
652
- export type CheckpointKey = { publicKey: string; until: number | null };
653
-
654
- /** An entry of the vault's log, and so the chain up to it. */
655
- export type LogHead = { seq: number; hash: string };
656
-
657
- export type VerifyLogInput = {
658
- /**
659
- * The last entry the app verified, every link and hash up to it
660
- * recomputed and its own entries checked by its key: the vault checks the
661
- * log still holds it, so between them both authors' entries are
662
- * authenticated over the same stretch, and the vault leaves the links to
663
- * the app.
664
- */
665
- upTo?: LogHead | null;
666
- /**
667
- * Where the vault's walk starts: the seq of one of its `audit.checkpoint`
668
- * entries that keeps a tally, or `start`, the first entry. The newest
669
- * such checkpoint when absent, and a vault older than 0.10.1 walks from
670
- * the first entry whatever it says.
671
- */
672
- from?: number | 'start';
673
- /**
674
- * A later checkpoint's entry, whose prefix `upTo` is: the walk ends
675
- * there, and must come to the tally it keeps. The members' rows and the
676
- * key batches are as they are now, not then, so only a walk without one
677
- * holds them to the log.
678
- */
679
- to?: number;
680
- };
681
-
682
- /**
683
- * Whether the vault's log holds, with the number of its entries through
684
- * where the walk ended, `through`: `upTo`, the prefix `to` signed, or as
685
- * far as one walk goes. On a failure, the entry where it breaks, or null
686
- * when the chain holds but the members and grants do not follow from it.
687
- * Then `fault` says which, as facts the app can word with names: `reason`
688
- * has only ids. A walk that ends at the present reports live key batches in
689
- * `pending`; overdue ones fail.
690
- */
691
- export type LogVerification =
692
- | { ok: true; entries: number; pending?: number; through?: number }
693
- | { ok: false; failedAtSeq: number | null; reason: string; fault?: AccessFault };