@coffre/core 0.14.4 → 0.15.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.
- package/dist/{access-CembYDiI.js → access-CgQTlUMz.js} +93 -1
- package/dist/{access-CU3xEOLH.d.ts → access-DqLJjnLM.d.ts} +67 -1
- package/dist/access.d.ts +2 -2
- package/dist/access.js +2 -2
- package/dist/identity.d.ts +102 -2
- package/dist/identity.js +410 -161
- package/dist/mcp.d.ts +3 -2
- package/dist/mcp.js +6 -2
- package/dist/merkle.d.ts +456 -0
- package/dist/merkle.js +964 -0
- package/dist/schemas.d.ts +11 -3
- package/dist/schemas.js +12 -2
- package/dist/vault.d.ts +1181 -6
- package/dist/vault.js +280 -1
- package/dist/{workloads-CW2dK4AW.d.ts → workloads-D049JH0M.d.ts} +9 -1
- package/dist/workloads.d.ts +2 -2
- package/dist/workloads.js +9 -1
- package/package.json +8 -3
- package/src/access.ts +93 -0
- package/src/answers.ts +209 -0
- package/src/audit/leaf.ts +81 -0
- package/src/audit/merkle.ts +13 -0
- package/src/audit/note.ts +187 -0
- package/src/audit/pair.ts +86 -0
- package/src/audit/tiles.ts +197 -0
- package/src/audit/tree.ts +163 -0
- package/src/audit/verify.ts +393 -0
- package/src/audit/witness.ts +50 -0
- package/src/identity/index.ts +2 -0
- package/src/identity/profile-rules.ts +147 -0
- package/src/identity/run-proof.ts +159 -0
- package/src/identity/workloads.ts +11 -0
- package/src/mcp.ts +6 -2
- package/src/schemas.ts +11 -0
- package/src/vault.ts +955 -1
package/src/vault.ts
CHANGED
|
@@ -7,6 +7,26 @@ export type { CallerKind } from './access.ts';
|
|
|
7
7
|
|
|
8
8
|
export { checkpointMessage, checkpointVerifier, verifyCheckpoint } from './checkpoint.ts';
|
|
9
9
|
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';
|
|
10
30
|
|
|
11
31
|
/**
|
|
12
32
|
* The vault as the app sees it: the contract between `@coffre/server` and
|
|
@@ -33,7 +53,7 @@ export interface Vault {
|
|
|
33
53
|
* refuses `access_changed` and logs no read, and says, by naming it back,
|
|
34
54
|
* that it checked. A vault older than 0.14.1 names none: it checked none.
|
|
35
55
|
*/
|
|
36
|
-
unwrap(input: UnwrapInput): Promise<Outcome<
|
|
56
|
+
unwrap(input: UnwrapInput): Promise<Outcome<Unwrapped>>;
|
|
37
57
|
/**
|
|
38
58
|
* Wrap fresh data keys for new versions `principal` writes: all, or none.
|
|
39
59
|
* `seqs` are the `key.wrap` entries, one per key, which the app's
|
|
@@ -172,6 +192,39 @@ export interface Vault {
|
|
|
172
192
|
* lists and checks root admins here until it is. Gone in 0.7.
|
|
173
193
|
*/
|
|
174
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;
|
|
175
228
|
}>;
|
|
176
229
|
/**
|
|
177
230
|
* What an escrowed vault key is checked against: the vault key it wraps
|
|
@@ -194,8 +247,655 @@ export interface Vault {
|
|
|
194
247
|
* (`readsWholeLog`).
|
|
195
248
|
*/
|
|
196
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
|
+
|
|
260
|
+
/**
|
|
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.
|
|
265
|
+
*/
|
|
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
|
+
|
|
276
|
+
/**
|
|
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.
|
|
287
|
+
*/
|
|
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>;
|
|
197
384
|
}
|
|
198
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;
|
|
405
|
+
}
|
|
406
|
+
|
|
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 };
|
|
423
|
+
|
|
424
|
+
/**
|
|
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.
|
|
429
|
+
*/
|
|
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
|
+
};
|
|
462
|
+
|
|
463
|
+
/**
|
|
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.
|
|
467
|
+
*/
|
|
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
|
+
};
|
|
480
|
+
|
|
481
|
+
/**
|
|
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.
|
|
486
|
+
*/
|
|
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;
|
|
494
|
+
};
|
|
495
|
+
|
|
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;
|
|
511
|
+
/**
|
|
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).
|
|
515
|
+
*/
|
|
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;
|
|
531
|
+
};
|
|
532
|
+
|
|
533
|
+
/**
|
|
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`).
|
|
539
|
+
*/
|
|
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
|
+
};
|
|
562
|
+
|
|
563
|
+
/**
|
|
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.
|
|
569
|
+
*/
|
|
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[] };
|
|
587
|
+
|
|
588
|
+
/**
|
|
589
|
+
* A sign-in through a trust binding (`Vault.signIn`). Times in ms since the
|
|
590
|
+
* epoch, bytes in base64.
|
|
591
|
+
*/
|
|
592
|
+
export type SignInInput = {
|
|
593
|
+
/** The account it signs in as, `token:<id>`. */
|
|
594
|
+
principal: string;
|
|
595
|
+
/**
|
|
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.
|
|
626
|
+
*/
|
|
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;
|
|
630
|
+
};
|
|
631
|
+
|
|
632
|
+
/**
|
|
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;
|
|
640
|
+
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;
|
|
698
|
+
};
|
|
699
|
+
|
|
700
|
+
/**
|
|
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.
|
|
718
|
+
*/
|
|
719
|
+
export type CutoverInput = {
|
|
720
|
+
/**
|
|
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`).
|
|
725
|
+
*/
|
|
726
|
+
checked: { from: ChainMark; to: ChainMark };
|
|
727
|
+
/**
|
|
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.
|
|
733
|
+
*/
|
|
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 }[];
|
|
741
|
+
};
|
|
742
|
+
|
|
743
|
+
/**
|
|
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).
|
|
748
|
+
*/
|
|
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 };
|
|
755
|
+
|
|
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
|
+
};
|
|
770
|
+
|
|
771
|
+
/**
|
|
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.
|
|
776
|
+
*/
|
|
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';
|
|
779
|
+
|
|
780
|
+
/**
|
|
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`).
|
|
785
|
+
*/
|
|
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 };
|
|
790
|
+
|
|
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
|
+
};
|
|
804
|
+
|
|
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' };
|
|
898
|
+
|
|
199
899
|
/**
|
|
200
900
|
* The vault's entries that change what a member holds: what their row's
|
|
201
901
|
* `access_seq` names, and what a finding about them is newer than while it
|
|
@@ -293,6 +993,30 @@ export type RefusalCode =
|
|
|
293
993
|
|
|
294
994
|
export type Outcome<T> = ({ ok: true } & T) | { ok: false; refusal: Refusal };
|
|
295
995
|
|
|
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
|
+
|
|
296
1020
|
/**
|
|
297
1021
|
* A proposed version the app will store. The ids bind its key, and `path`
|
|
298
1022
|
* is the app's label for the write's log. Reads name stored version ids
|
|
@@ -337,6 +1061,37 @@ export type KeyChecks = { current: { kekProvider: string; kekId: string }; check
|
|
|
337
1061
|
*/
|
|
338
1062
|
export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
|
|
339
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).
|
|
1070
|
+
*/
|
|
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
|
+
|
|
340
1095
|
/**
|
|
341
1096
|
* Whether a read hands values back to whoever asked, which a person never
|
|
342
1097
|
* gets of a sensitive value: every purpose but the proxy's `use` and a
|
|
@@ -408,8 +1163,31 @@ export type UnwrapInput = Correlation & Through & {
|
|
|
408
1163
|
* logs the read there too, and decides on the value's own environment.
|
|
409
1164
|
*/
|
|
410
1165
|
items: { secretVersionId: string; via?: Via; through?: string }[];
|
|
1166
|
+
/**
|
|
1167
|
+
* The credential proxy's record of what the values go into, the app's
|
|
1168
|
+
* `credential.use` entry: the vault appends it beside its reads, once it
|
|
1169
|
+
* releases them, under the log's head it already holds, so that the app
|
|
1170
|
+
* takes the head no more for it. Where it was, from where, and its
|
|
1171
|
+
* metadata, JSON, as the app wrote them; its actor is `principal`. Named
|
|
1172
|
+
* back (`used`) once appended: a vault older than 0.14.5 names nothing,
|
|
1173
|
+
* and the app appends it itself.
|
|
1174
|
+
*/
|
|
1175
|
+
use?: UseRecord;
|
|
411
1176
|
};
|
|
412
1177
|
|
|
1178
|
+
/**
|
|
1179
|
+
* The longest `UseRecord.metadata` the vault appends, in characters: room for
|
|
1180
|
+
* a use naming a few hundred keys. The app appends a longer one itself, under
|
|
1181
|
+
* the head, as before 0.14.5.
|
|
1182
|
+
*/
|
|
1183
|
+
export const USE_METADATA_LENGTH = 16_384;
|
|
1184
|
+
|
|
1185
|
+
/** The app's `credential.use` entry, for the vault to append (`UnwrapInput.use`). */
|
|
1186
|
+
export type UseRecord = { projectId: string | null; environmentId: string | null; sourceIp: string | null; metadata: string };
|
|
1187
|
+
|
|
1188
|
+
/** An unwrap's answer: each item's key, the answer it was decided on, and whether it appended the use it was given. */
|
|
1189
|
+
export type Unwrapped = { keys: string[]; accessRevision?: string; used?: true };
|
|
1190
|
+
|
|
413
1191
|
/** A reference, as a read names it: its id, and the seq of the vault's `reference.create` entry. */
|
|
414
1192
|
export type Via = { reference: string; seq: number };
|
|
415
1193
|
|
|
@@ -668,3 +1446,179 @@ export type VerifyLogInput = {
|
|
|
668
1446
|
export type LogVerification =
|
|
669
1447
|
| { ok: true; entries: number; pending?: number; through?: number }
|
|
670
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 };
|