@coffre/core 0.14.5 → 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/vault.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { A as RoleDefinition, P as ServiceSetting, T as Policy, _ as InstanceRole, f as GrantPlace, i as CredentialScope, j as Scope, k as Role, n as CallerKind } from "./access-qkMZa-6Z.js";
1
+ import { L as ServiceSetting, M as Role, N as RoleDefinition, O as Policy, P as Scope, f as GrantPlace, i as CredentialScope, n as CallerKind, y as InstanceRole } from "./access-DqLJjnLM.js";
2
2
  //#region src/access-fault.d.ts
3
3
  /**
4
4
  * Why the vault's members and grants do not follow from its log, as facts
@@ -75,6 +75,111 @@ export declare function verifyCheckpoint(checkpoint: Checkpoint, publicKey: stri
75
75
  */
76
76
  export declare function checkpointVerifier(publicKey: string): Promise<(checkpoint: Checkpoint) => Promise<boolean>>;
77
77
  //#endregion
78
+ //#region src/answers.d.ts
79
+ /** A member: `user:<email>` or `token:<name>`. */
80
+ export declare const PRINCIPAL: RegExp;
81
+ /** A member's row, as `vault_members` holds it, its instance role and scope read (`storedRole` in @coffre/db/grants). */
82
+ type MemberFacts = {
83
+ status: 'active' | 'removed';
84
+ role: InstanceRole;
85
+ scope: Scope;
86
+ generation: number;
87
+ /** Milliseconds since the epoch. */
88
+ statusChangedAt: number;
89
+ statusChangedBy: string;
90
+ };
91
+ /** A grant, as `vault_grants` holds it, its environment's project filled in; times in milliseconds since the epoch. */
92
+ type GrantFacts = {
93
+ projectId: string | null;
94
+ environmentId: string | null;
95
+ role: string;
96
+ expiresAt: number | null;
97
+ grantedAt: number;
98
+ grantedBy: string;
99
+ };
100
+ /**
101
+ * What `access` answers about `principal`, from their row and their
102
+ * grants, lapsed ones too, as of `at`; `tampered` when a row failed the
103
+ * vault's check, which only the vault can tell.
104
+ */
105
+ export declare function answerFrom(principal: string, row: MemberFacts | undefined, held: readonly GrantFacts[], at: number, tampered: boolean, policy: Policy): Access;
106
+ /** A member's instance role, as their row has it: service accounts are members, whatever a row says. */
107
+ export declare function roleOf(principal: string, row: Pick<MemberFacts, 'role' | 'scope'>): {
108
+ role: InstanceRole;
109
+ scope: Scope;
110
+ };
111
+ /** Whether a grant still holds at `at`. */
112
+ export declare function live(grant: {
113
+ expiresAt: number | null;
114
+ }, at: number): boolean;
115
+ /** A grant as `access` answers it. */
116
+ export declare function view(grant: GrantFacts): Grant;
117
+ /**
118
+ * What a `policy.change` entry keeps: the roles an Owner edited or made,
119
+ * each whole, and the protected environments. A role as it ships is kept by
120
+ * none, so a release that changes a default changes it where nobody edited it.
121
+ */
122
+ type PolicyEdits = {
123
+ roles: Record<string, RoleDefinition>;
124
+ instanceRoles: Partial<Record<InstanceRole, RoleDefinition>>;
125
+ protected: ProtectedPlace[];
126
+ };
127
+ /**
128
+ * A protected environment, with its project's id, what a grant on the whole
129
+ * project reaches of it, and when it was protected, by the vault's clock:
130
+ * an id with no row ten minutes later is a fork that was never written.
131
+ */
132
+ type ProtectedPlace = {
133
+ projectId: string;
134
+ environmentId: string;
135
+ at: number;
136
+ };
137
+ export declare const NO_EDITS: PolicyEdits;
138
+ /**
139
+ * The policy when the log has some, but none the vault wrote within reach:
140
+ * whoever inserted rows may have hidden an Owner's narrowing, so no role
141
+ * holds anything, a service account's neither, but Owner, which holds
142
+ * everything always and so may write the policy again.
143
+ */
144
+ export declare const CLOSED_POLICY: Policy;
145
+ /** An environment a policy names, as the policy reads it. */
146
+ type PolicyEnvironment = {
147
+ slug: string | null;
148
+ deleted: boolean;
149
+ };
150
+ /**
151
+ * The policy the newest `policy.change` says, from its metadata, as of
152
+ * `at`, with the rows of the environments it protects: none for no entry,
153
+ * the roles as they ship; and closed for one whose edits do not hold.
154
+ */
155
+ export declare function policyFrom(metadata: string | null, rows: ReadonlyMap<string, PolicyEnvironment>, at: number): {
156
+ policy: Policy;
157
+ edits: PolicyEdits;
158
+ readable: boolean;
159
+ };
160
+ /** A policy entry's edits, checked as the vault wrote them, or null for any that does not hold. */
161
+ export declare function readEdits(stored: {
162
+ policy?: unknown;
163
+ }): PolicyEdits | null;
164
+ /**
165
+ * The policy `edits` say as of `at`: the roles as they ship, each edited
166
+ * one replaced and each made one added; and the protected environments, but
167
+ * for those deleted since, the project around one's included: a deleted
168
+ * prod protects nothing, and holds nobody back from giving a service
169
+ * account a role on all of its project (`givesService`). A fork's id with
170
+ * no row yet stays, protected before it is written, ten minutes: one with
171
+ * none after that is a fork refused or abandoned, never written. Each
172
+ * keeps its slug, which a scoped instance role's filters read. The edits
173
+ * keep them all: no write is needed.
174
+ */
175
+ export declare function livePolicy(rows: ReadonlyMap<string, PolicyEnvironment>, edits: PolicyEdits, at: number): Policy;
176
+ /** The settings before anyone changed them: people set up service accounts anywhere they hold access. */
177
+ export declare const DEFAULT_SETTINGS: Settings;
178
+ /** The settings when the log has some, but none the vault wrote within reach: people set up no service accounts. */
179
+ export declare const CLOSED_SETTINGS: Settings;
180
+ /** The settings the newest `settings.change` says, from its metadata: none for no entry, the default; closed for one that does not hold. */
181
+ export declare function settingsFrom(metadata: string | null): Settings;
182
+ //#endregion
78
183
  //#region src/vault.d.ts
79
184
  /**
80
185
  * The vault as the app sees it: the contract between `@coffre/server` and
@@ -254,6 +359,39 @@ export interface Vault {
254
359
  * lists and checks root admins here until it is. Gone in 0.7.
255
360
  */
256
361
  rootAdmins: [];
362
+ /**
363
+ * `'0.15'` when the vault keeps 0.15's log: the app then writes the
364
+ * changes to its rows through it (`prepare`). Absent before 0.15.
365
+ */
366
+ log?: '0.15';
367
+ /**
368
+ * `true` when the vault also answers 0.15's uses (`use`): its log is
369
+ * 0.15's and it has the hot path's login. The app then opens each value
370
+ * through a use (docs/design/0.15-plan.md, PR 5b). Absent otherwise.
371
+ */
372
+ uses?: true;
373
+ /**
374
+ * `true` when the vault also answers a request's several keys in one call (`useMany`; T167). Said here, as a
375
+ * Worker's stub answers any method's name: a vault older than this app, mid-deploy, says nothing, and the app makes
376
+ * a use a key. Absent otherwise.
377
+ */
378
+ batchUses?: true;
379
+ /**
380
+ * `true` when the vault says whether its checkpointer seals (`sealing`; T169), which `/readyz` asks. Said here,
381
+ * as a Worker's stub answers any method's name: of a vault older than this app, mid-deploy, readiness asks nothing.
382
+ */
383
+ sealing?: true;
384
+ /**
385
+ * `true` when the vault makes sign-ins through trust bindings and revokes
386
+ * credentials itself (`signIn`, `revokeCredential`; T149): its log is
387
+ * 0.15's. Said here, as a Worker's stub answers any method's name.
388
+ * Absent otherwise.
389
+ */
390
+ credentials?: true;
391
+ /** `true` when the vault issues tokens itself too (`issueToken`; T149, PR 2). Absent otherwise. */
392
+ issues?: true;
393
+ /** `true` when the vault makes and ends trust bindings itself, and signs in through none it did not seal (`changeBindings`; T149, PR 3a). Absent otherwise. */
394
+ binds?: true;
257
395
  }>;
258
396
  /**
259
397
  * What an escrowed vault key is checked against: the vault key it wraps
@@ -276,7 +414,781 @@ export interface Vault {
276
414
  * (`readsWholeLog`).
277
415
  */
278
416
  verifyLog(input: VerifyLogInput): Promise<LogVerification>;
417
+ /**
418
+ * 0.15's use (docs/design/0.15-plan.md, PR 5): one key read on one
419
+ * credential, logged as its request and decided on what one statement
420
+ * read, the value's data key handed back once its entry has committed.
421
+ * Behind the 0.15 switch: the app opens each value through it when the
422
+ * vault says so (`about().uses`). A vault without the hot path's login
423
+ * has none.
424
+ */
425
+ use?(input: UseInput): Promise<UseOutcome>;
426
+ /**
427
+ * 0.15's use as the request names it, one call (T145, PR B; formal/Probing.tla): the vault finds the ids of what it
428
+ * names, from its own cache or with one read on a miss, uses the key by them, and answers with the rows the app checks
429
+ * (`NamedUseOutcome.app`) and what it decided the caller holds (`standing`). A key the place does not hold, and a plain
430
+ * value, it decides on the caller's standing there, logging nothing. Absent from a vault without 0.15's uses.
431
+ */
432
+ useNamed?(input: NamedUseInput): Promise<NamedUseOutcome>;
433
+ /**
434
+ * A request's several keys as one call (T167, B2; formal/Batching.tla): each key's use made as `use` makes it, in the
435
+ * request's order, in one statement, and decided on what it read; a second call, only once every key is allowed, for
436
+ * those that take the principal's lock. All or nothing: every value, or the first key refused, or busy. Absent from a
437
+ * vault without 0.15's uses (`about().batchUses` says whether it has it).
438
+ */
439
+ useMany?(input: UseManyInput): Promise<UseManyOutcome>;
440
+ /**
441
+ * 0.15's log (docs/design/0.15-plan.md, "As built: PR 4b"): the changes
442
+ * the app is about to write to objects its own rows hold (credentials,
443
+ * keys, environments), each sealed, as entries the app's transaction
444
+ * commits with its rows (`app_change`, migration 0025), before it asks.
445
+ * The vault reads nothing: it checks each row's columns as the app read
446
+ * them against their seal (`tampered` if the vault never made it), works
447
+ * out the changes that turn them into the columns the app will write, and
448
+ * seals what they leave. Whether each seal is still its object's newest
449
+ * is the transaction's to check, under the fence. Only with 0.15's log on
450
+ * (`about().log`); a vault older than 0.15 has none.
451
+ */
452
+ prepare?(input: PrepareInput): Promise<Outcome<Prepared>>;
453
+ /**
454
+ * Answers once the log's entry `number` is sealed in a signed checkpoint
455
+ * and, if a witness is configured, witnessed or past its 2 s (R51): what a
456
+ * change the app committed waits for before it answers. Only with 0.15's
457
+ * log on.
458
+ */
459
+ waitSealed?(input: {
460
+ number: string;
461
+ }): Promise<Outcome<{
462
+ witnessed: boolean | null;
463
+ }>>;
464
+ /**
465
+ * 0.15 (T149, D146; docs/design/credential-lifecycle.md): a sign-in
466
+ * through a trust binding, a CI run's or a workload's, made by the vault
467
+ * in one statement (`sign_in`, migration 0034; formal/Lifecycle.tla).
468
+ * The app verifies the proof and names the binding as it read it; the
469
+ * vault makes the credential's object from those columns, and the
470
+ * statement goes ahead only while they are the binding's row, its
471
+ * account active at its generation, its rate not spent and the token
472
+ * not, under their locks: the issue lock, never the fence, so no use
473
+ * waits on it (R58), and no 0.14 head. No 0.14 entry either: the change
474
+ * records the sign-in (D147). Answers once it is sealed (R51). Only with
475
+ * 0.15's log on.
476
+ */
477
+ signIn?(input: SignInInput): Promise<SignInOutcome>;
478
+ /**
479
+ * 0.15 (T149): a credential revoked by the vault in one statement
480
+ * (`revoke_credential`, migration 0034), from its columns as the app
481
+ * read them and their seal: under its row's lock and the fence, held for
482
+ * the statement's work alone (RevokeTakesFence). The app has weighed who
483
+ * may. Answers once sealed (R51). Only with 0.15's log on.
484
+ */
485
+ revokeCredential?(input: RevokeCredentialInput): Promise<RevokeCredentialOutcome>;
486
+ /**
487
+ * 0.15 (T149, PR 2): a token issued by the vault, which weighs it itself
488
+ * (`issue_token`, migration 0036; formal/Lifecycle.tla's issue): a
489
+ * service account's token, a person's personal token, or a handle. The
490
+ * app names the scope it worked out and the row it would hand out; the
491
+ * vault reads the issuer, the account and the credential the request came
492
+ * in on, decides with the rules of `@coffre/core/access` whether the
493
+ * issuer may give that scope (R15, R32), and then writes it in one
494
+ * statement that holds those rows shared and goes ahead only while they
495
+ * are as it read them (IssuerLocked, IssuerCAS). Nothing held between
496
+ * the two; the issue lock, never the fence (R58). Answers once sealed.
497
+ */
498
+ issueToken?(input: IssueTokenInput): Promise<IssueTokenOutcome>;
499
+ /**
500
+ * With 0.15's log, a service's trust bindings changed by the vault itself
501
+ * (T149, PR 3a; D148): the binding a manager makes, weighed as a service
502
+ * token's issue is (who may give the account that scope, R15, R32), and
503
+ * those it replaces ended, with the credentials each issued; or, making
504
+ * none, an unbind. One statement, which holds what it read as read;
505
+ * answers once sealed. A sign-in takes only a binding the vault sealed.
506
+ */
507
+ changeBindings?(input: ChangeBindingsInput): Promise<ChangeBindingsOutcome>;
508
+ /**
509
+ * 0.15's cutover from 0.14 (docs/design/0.15-plan.md, PR 9;
510
+ * formal/Migration015.tla): once, before 0.15's log serves anything, every
511
+ * object 0.14 left sealed as 0.14 accepts it (`genesis`), and the log's
512
+ * first `cutover` change naming 0.14's last head (the anchor). Without
513
+ * `input`, whether it is done, and if not, where 0.14's chain is
514
+ * verified from (its newest checkpoint's prefix), for the app to check
515
+ * its own entries from there. With `input`, what the app vouches for under
516
+ * its key, which the vault never holds: it holds each row to it under its
517
+ * locks. Once done, done for good: a second call finds the marker.
518
+ */
519
+ cutover?(input?: CutoverInput): Promise<CutoverOutcome>;
520
+ /**
521
+ * Check 0.15's log (docs/design/0.15-plan.md, PR 8), as the audit page
522
+ * does on every visit: the newest signed pair, held to the pairs held
523
+ * outside, and every entry after it by its MAC and request, a tick's
524
+ * worth (R25). Nothing walks the whole log on a request (D145). With
525
+ * 0.14's log alone, `kept` false; a vault older than 0.15 has none.
526
+ */
527
+ verifyTrees?(): Promise<TreeVerification>;
528
+ /**
529
+ * The reads' listing held to 0.15's log, a stretch a call (T166): from
530
+ * `start`, then each `next`, the uses the log sealed derived again and
531
+ * held to the reads the pages list, each read and each place it was read
532
+ * at. For whoever checks the whole log (`coffre verify log`), never a
533
+ * page. `kept` false with 0.14's log alone.
534
+ */
535
+ verifyReads?(input: {
536
+ from: string;
537
+ }): Promise<ReadsVerification>;
538
+ /**
539
+ * Which of these entries of 0.15's log, as a page of the audit log read
540
+ * them, the vault does not vouch for: its MAC, under any of the vault's
541
+ * signing keys, as its seals are checked, does not hold over the columns
542
+ * shown (T166). The audit pages list 0.15's changes and uses only with
543
+ * this check, and mark one it names as forged: written or edited around
544
+ * coffre. Pure CPU, no read; at most `VOUCHED_AT_ONCE` entries a call.
545
+ */
546
+ vouch?(input: VouchInput): Promise<{
547
+ forged: string[];
548
+ }>;
549
+ /**
550
+ * With 0.15's log, whether its checkpointer seals (T169): open, its last
551
+ * tick ended well, and within the last few seconds. What `/readyz` asks,
552
+ * since a change answers only once sealed (R51). Bounded: a checkpointer
553
+ * that does not answer is said not to seal, at once.
554
+ */
555
+ sealing?(): Promise<Sealing>;
279
556
  }
557
+ /** Whether 0.15's checkpointer seals, and if not, why (`Vault.sealing`). */
558
+ export type Sealing = {
559
+ ok: true;
560
+ } | {
561
+ ok: false;
562
+ reason: string;
563
+ };
564
+ /**
565
+ * What the error of a change says when the change committed but its seal
566
+ * did not come in time (T169): the checkpointer stalled, or cannot be
567
+ * reached. Its words are the contract, since only an error's message
568
+ * crosses Workers' RPC: the app answers 503 with Retry-After
569
+ * (`isUnsealed`), and the change is in force.
570
+ */
571
+ export declare const UNSEALED = "was committed, but not sealed in time";
572
+ /** Whether `error`, or one of its causes, is a change's seal that did not come in time (`UNSEALED`). */
573
+ export declare function isUnsealed(error: unknown): boolean;
574
+ /** The most entries one `vouch` call checks: a page of the audit log lists a few hundred at most. */
575
+ export declare const VOUCHED_AT_ONCE = 2000;
576
+ /** Entries of 0.15's log to vouch for, each with every column its MAC covers, bytes in hex, its number as text. */
577
+ export type VouchInput = {
578
+ entries: VouchedEntry[];
579
+ };
580
+ export type VouchedEntry = {
581
+ tree: 'changes';
582
+ number: string;
583
+ at: number;
584
+ requestId: string;
585
+ object: string;
586
+ actor: string;
587
+ payload: string;
588
+ seal: string | null;
589
+ mac: string;
590
+ } | {
591
+ tree: 'uses';
592
+ number: string;
593
+ at: number;
594
+ requestId: string;
595
+ credential: string;
596
+ secret: string;
597
+ purpose: number;
598
+ place: string | null;
599
+ mac: string;
600
+ } |
601
+ /** A read as the projector wrote it (`log_reads`, T166): its MAC covers its number too. */
602
+ {
603
+ tree: 'reads';
604
+ number: string;
605
+ at: number;
606
+ credential: string;
607
+ purpose: number;
608
+ principal: string;
609
+ secret: string;
610
+ environment: string;
611
+ project: string;
612
+ place: string | null;
613
+ source: string | null;
614
+ sourceEnvironment: string | null;
615
+ sourceProject: string | null;
616
+ version: string | null;
617
+ mac: string;
618
+ } |
619
+ /** The projection's cursor (`log_reads_cursor`, T166), named `cursor` in the answer: whether the pages may say reads are whole up to it. */
620
+ {
621
+ tree: 'cursor';
622
+ number: 'cursor';
623
+ through: string;
624
+ pair: string;
625
+ at: number;
626
+ mac: string | null;
627
+ };
628
+ /**
629
+ * 0.15's log as its check found it. `problems` names what does not hold,
630
+ * each at its entry where it has one: a checkpoint not signed, or not the
631
+ * one held outside; an entry whose MAC fails, or under another's request.
632
+ * Numbers are decimal text: the log's are 64-bit.
633
+ */
634
+ export type ReadsVerification = {
635
+ kept: false;
636
+ } | {
637
+ kept: true;
638
+ /** Nothing wrong found in the stretch. */
639
+ ok: boolean;
640
+ problems: string[];
641
+ /** The entry the stretch checked through, and how far the projector has listed. */
642
+ through: string;
643
+ listed: string;
644
+ /** Where the next stretch starts; null at the projector's cursor, or on a problem that stops the check. */
645
+ next: string | null;
646
+ };
647
+ export type TreeVerification = {
648
+ kept: false;
649
+ } | {
650
+ kept: true;
651
+ /** Checked to the head, and nothing wrong found. */
652
+ ok: boolean;
653
+ problems: string[];
654
+ /** The newest pair checked, and when it was signed (ms); null before the first. */
655
+ checkpoint: {
656
+ upto: string;
657
+ at: number;
658
+ } | null;
659
+ /** The entries above the newest pair it checked. */
660
+ unsealed: number;
661
+ /**
662
+ * Whether more lie there than a check reads (`ABOVE_NEWEST`, 2,000): a
663
+ * checkpointer behind. Not checked to the head, so `ok` is false; no
664
+ * problem either, and never a break of the log.
665
+ */
666
+ capped: boolean;
667
+ };
668
+ /**
669
+ * The columns of a row the app writes that a decision of 0.15's reads, as
670
+ * the vault's objects take them (packages/vault/src/objects.ts): times in
671
+ * ms since the epoch, uuids as text, JSON as stored.
672
+ */
673
+ export type CredentialColumns = {
674
+ id: string;
675
+ principal: string;
676
+ kind: string;
677
+ /** Its scope as stored, JSON; null for a session's. */
678
+ scope: string | null;
679
+ revoked: boolean;
680
+ /** The earlier of its expiry and its hard end, if any, in whole ms: a stored time's sub-millisecond part dropped, never rounded. */
681
+ expiresAt: number | null;
682
+ /** Its account's generation when it was issued (`credentials.generation`). */
683
+ generation: number;
684
+ };
685
+ /**
686
+ * An MCP connection's (`mcp_connections`), as its object takes them (T147):
687
+ * whose it is, at which generation of their account it was approved, its
688
+ * end, and whether it was revoked. What a refresh moves (its tokens' hashes)
689
+ * and its last use are no part of it.
690
+ */
691
+ export type ConnectionColumns = {
692
+ id: string;
693
+ principal: string;
694
+ generation: number;
695
+ /** Its `expires_at`, in whole ms: a stored time's sub-millisecond part dropped, never rounded. */
696
+ expiresAt: number;
697
+ revoked: boolean;
698
+ };
699
+ /** One object's change, as the app will write it: its columns before (null: it makes the object), their seal, and after. */
700
+ export type ObjectChange = ChangeOf<'credential', CredentialColumns, CredentialColumns> | ChangeOf<'connection', ConnectionColumns, ConnectionColumns> |
701
+ /**
702
+ * A key's: null after, archived or erased (no object). `restores`: an
703
+ * archived key unarchived, `after` its rows as read: the vault holds them
704
+ * to the object its log last sealed, and refuses another (`stale`).
705
+ */
706
+ (ChangeOf<'secret', SecretColumns, SecretColumns | null> & {
707
+ restores?: true;
708
+ }) | ChangeOf<'environment', EnvironmentColumns, EnvironmentColumns>;
709
+ type ChangeOf<K extends string, Before, After> = {
710
+ kind: K;
711
+ id: string;
712
+ /**
713
+ * As the app read the row, with its seal: null for no object (no row, or
714
+ * a key archived); a null seal, a row the vault never sealed (0.14's,
715
+ * before the cutover).
716
+ */
717
+ before: {
718
+ columns: Before;
719
+ seal: string | null;
720
+ } | null;
721
+ after: After;
722
+ };
723
+ /** The version a key's value is: its ids, its nature and its wrapped data key; a plain one's text. Never its ciphertext. */
724
+ export type VersionColumns = {
725
+ id: string;
726
+ sensitive: boolean;
727
+ /** A plain value's text, which it is (no data key the vault opens); null for any other. Its object holds its digest. */
728
+ plaintext: string | null;
729
+ kekProvider: string;
730
+ kekId: string;
731
+ kekVersion: string;
732
+ /** The wrapped data key, base64. */
733
+ wrappedDek: string;
734
+ };
735
+ /**
736
+ * A live key's columns (`secrets`): where it is, its current version, or,
737
+ * for a reference, the source its newest `secret_references` row names
738
+ * while it has no version of its own, and that row's id (both null for a
739
+ * key with a value, and for one whose newest reference row has ended:
740
+ * `ended_at`).
741
+ */
742
+ export type SecretColumns = {
743
+ id: string;
744
+ projectId: string;
745
+ environmentId: string;
746
+ source: string | null;
747
+ reference: string | null;
748
+ version: VersionColumns | null;
749
+ };
750
+ /** An environment's columns (`environments`). Its slug as stored: a deleted one's carries a tombstone, `dev~deleted-…`. */
751
+ export type EnvironmentColumns = {
752
+ id: string;
753
+ projectId: string;
754
+ slug: string;
755
+ owner: string | null;
756
+ parentId: string | null;
757
+ /** Null until the cutover writes it (0022): not protected. */
758
+ protected: boolean | null;
759
+ /** Its own `archived_at`. */
760
+ archived: boolean;
761
+ /** Its project's: 0.14 takes an environment of an archived project as archived. */
762
+ projectArchived: boolean;
763
+ };
764
+ export type PrepareInput = {
765
+ /** Who makes the changes, as their entries name them: `user:…`, `token:…`, or the app's own (`coffre`). */
766
+ actor: string;
767
+ changes: ObjectChange[];
768
+ };
769
+ /**
770
+ * A change sealed, for the app's transaction to commit (`app_change`): its
771
+ * entry's fields, the seal it moves the row from and to, and its MAC, bytes
772
+ * in base64. A row the vault never sealed is the log's to leave alone until
773
+ * the cutover: its call (`requestId` null) only checks, under the fence,
774
+ * that the log has no change of its object either.
775
+ */
776
+ export type PreparedChange = {
777
+ kind: ObjectChange['kind'];
778
+ id: string;
779
+ requestId: string | null;
780
+ at: number;
781
+ /** The object's key in the log (`log_object`). */
782
+ object: string;
783
+ actor: string;
784
+ payload: string | null;
785
+ sealFrom: string | null;
786
+ seal: string | null;
787
+ mac: string | null;
788
+ /** An unarchive's: the seal of the object it restores, which must still be its log's newest sealed one; else null. */
789
+ restores: string | null;
790
+ };
791
+ export type Prepared = {
792
+ changes: PreparedChange[];
793
+ };
794
+ /**
795
+ * A sign-in through a trust binding (`Vault.signIn`). Times in ms since the
796
+ * epoch, bytes in base64.
797
+ */
798
+ export type SignInInput = {
799
+ /** The account it signs in as, `token:<id>`. */
800
+ principal: string;
801
+ /**
802
+ * The binding as the app read it, with its seal: the vault decides only
803
+ * on one whose seal is its own (PR 3a), and the statement holds the row
804
+ * to it and to its object's newest change.
805
+ */
806
+ binding: {
807
+ columns: BindingColumns;
808
+ seal: string | null;
809
+ };
810
+ /** The credential the app hands out once made: its row, the app's MAC over it (`auth_mac`) with it. */
811
+ credential: SignInCredential;
812
+ /** The id of the app's log key, under whose key the MAC was made: refused once the app has rotated from it (`retired`). */
813
+ appKey: string;
814
+ /** The ID token's signing input's hash, spent once; null for a proof that spends none. */
815
+ spent: string | null;
816
+ /**
817
+ * The last instant the proof holds by its own times, ms (an ID token's
818
+ * `exp` and its `iat`'s hour, each with their tolerance): checked again
819
+ * in the statement, by the database's clock. Null: its credential's
820
+ * `notAfter` bounds it.
821
+ */
822
+ validUntil: number | null;
823
+ /** What the change records of the sign-in besides (D147): the proof, its issuer, and the run's claims. */
824
+ record: {
825
+ proof: string;
826
+ issuer: string;
827
+ run: Record<string, string | number>;
828
+ };
829
+ /**
830
+ * The run's ID token, for the vault to verify itself (D148, PR 3b), when
831
+ * its sealed binding carries the issuer's keys (its `jwksUri` their
832
+ * digest, as a Kubernetes cluster's does), with those keys as its row
833
+ * keeps them; the vault then takes `spent`, `validUntil` and `record.run`
834
+ * from the token, not from the app. Null for a binding of keys its issuer
835
+ * publishes, which the vault does not fetch (it asks no issuer anything),
836
+ * and for a proof that is no ID token (an AWS signed request):
837
+ * the app verifies those, so a compromised app could sign a run in
838
+ * through such a binding, within its limits.
839
+ */
840
+ idToken: {
841
+ token: string;
842
+ jwks: string;
843
+ } | null;
844
+ /** A workload's DPoP proof, whose key the session is bound to, which the vault verifies; null for a CI run's sign-in. */
845
+ dpop: string | null;
846
+ };
847
+ /**
848
+ * A trust binding's columns as its object takes them (T149, PR 3a): what a
849
+ * sign-in through it decides on. Its keys by `jwksUri` (the issuer's
850
+ * discovered URL, or `sha256:<hex>` of keys uploaded with it); its claims
851
+ * and policy as the row keeps them, canonical JSON.
852
+ */
853
+ export type BindingColumns = {
854
+ id: string;
855
+ principal: string;
856
+ generation: number;
857
+ profile: string;
858
+ issuer: string;
859
+ /**
860
+ * The instance's public URL it was made on (PR 3b): its base audience, as
861
+ * a token for it must name it (`expectedAudiences`), and where a workload's
862
+ * DPoP proof is signed for. No column: the app names it, and the seal
863
+ * holds it, so a binding of another URL's is none of this instance's.
864
+ */
865
+ origin: string;
866
+ jwksUri: string;
867
+ claims: string;
868
+ scope: string | null;
869
+ policy: string | null;
870
+ revoked: boolean;
871
+ };
872
+ /** A binding the vault makes (`changeBindings`): its object's columns and the rest of its row, with the app's MAC over it. */
873
+ export type MadeBinding = BindingColumns & {
874
+ jwks: string | null;
875
+ label: string | null;
876
+ createdBy: string;
877
+ createdAt: number;
878
+ authMac: string;
879
+ };
880
+ /** A binding a change ends: as the app read it, with its seal and MAC, the app's MAC over it revoked, and the credentials it issued that are live. */
881
+ export type EndedBinding = {
882
+ /** Its seal null for one 0.14 made, which the log never held: ended all the same, its row revoked with no change. */
883
+ before: {
884
+ columns: BindingColumns;
885
+ seal: string | null;
886
+ };
887
+ authMacFrom: string;
888
+ authMac: string;
889
+ /**
890
+ * Every live credential it issued, each as `revokeCredential` names one: the statement holds the set to the rows. One
891
+ * with no seal (0.14's, or written around the vault) is ended all the same, its row revoked with no change.
892
+ */
893
+ credentials: {
894
+ before: {
895
+ columns: CredentialColumns;
896
+ seal: string | null;
897
+ };
898
+ authMacFrom: string;
899
+ authMac: string;
900
+ }[];
901
+ };
902
+ export type ChangeBindingsInput = {
903
+ /** Who changes them, as its entry names them. */
904
+ actor: string;
905
+ /** The credential the request came in on, by id; null for none. */
906
+ via: string | null;
907
+ /** The issuer's access as the app weighed the scope on (`access_seq`), decimal; null when it weighed none. */
908
+ actorAccess: string | null;
909
+ /** The MCP connection the request came through, at the caller's generation, held to still connected; null for none. */
910
+ connection: {
911
+ id: string;
912
+ generation: number;
913
+ } | null;
914
+ /** The binding it makes; null for an unbind. Its account at its generation, as its columns name them. */
915
+ make: MadeBinding | null;
916
+ /** With a binding made, the account's live bindings as the app read them, by id, which it was weighed beside; else null. */
917
+ live: string[] | null;
918
+ /** The keys a binding made reads (its policy's `reads`), by id and the name they were asked by: none moves before the write. */
919
+ reads: {
920
+ id: string;
921
+ key: string;
922
+ }[];
923
+ /** The bindings it ends: those the new one replaces, or the one unbound. */
924
+ ends: EndedBinding[];
925
+ /** Why they end, for the changes' record. */
926
+ reason: 'replaced' | 'keys_moved' | 'unbound';
927
+ revokedAt: number;
928
+ revokedBy: string;
929
+ /** The policy the app weighed on: the newest `policy.change`'s seq and the protected environments' slugs. */
930
+ policy: {
931
+ seq: string | null;
932
+ protected: {
933
+ environmentId: string;
934
+ slug: string | null;
935
+ }[];
936
+ };
937
+ appKey: string;
938
+ };
939
+ /**
940
+ * Why bindings were not changed, nothing written: as an issue's
941
+ * (`IssueTokenRefusal`); `stale` or `tampered`, a row the log does not
942
+ * hold as its newest (put back) or not the vault's seal; `unlogged`, the
943
+ * credential the request came in on one 0.14 made (a binding 0.14 made,
944
+ * the vault ends itself, with no change);
945
+ * `full`, the account holds as many live bindings as one may
946
+ * (`MAX_BINDINGS`), besides those the change ends.
947
+ */
948
+ export type ChangeBindingsRefusal = IssueTokenRefusal | 'stale' | 'tampered' | 'full';
949
+ /** A point of 0.14's chain: an entry's number and its hash (hex); `-1` and the zero hash before the first. */
950
+ export type ChainMark = {
951
+ seq: string;
952
+ hash: string;
953
+ };
954
+ /**
955
+ * What the app vouches for, of 0.14's, at the cutover (`Vault.cutover`):
956
+ * what 0.14 accepts that only the app's key says, each checked as 0.14's
957
+ * app checks it.
958
+ */
959
+ export type CutoverInput = {
960
+ /**
961
+ * The stretch of 0.14's chain whose app entries the app checked by their
962
+ * MACs, every link included: from where the vault said it verifies from,
963
+ * to the head as the app read it. An app entry after `to` sends the
964
+ * cutover back to the app (`moved`).
965
+ */
966
+ checked: {
967
+ from: ChainMark;
968
+ to: ChainMark;
969
+ };
970
+ /**
971
+ * Each credential 0.14 accepts as it stands, its object's columns as
972
+ * read: its MAC the app's, not revoked nor past its end, its sign-in
973
+ * account not unlinked, and no revoke of it in the log (`token.revoke`,
974
+ * `sign_out`). One a binding issued is left out: 0.14 reads its scope
975
+ * from the binding, so its row holds none to seal.
976
+ */
977
+ credentials: CredentialColumns[];
978
+ /** Each trust binding 0.14 accepts as it stands: its MAC the app's, not revoked, and no `token.unbind` of it. */
979
+ bindings: BindingColumns[];
980
+ /** Each MCP connection 0.14 accepts as it stands (T147): its MAC the app's, not revoked nor past its end. */
981
+ connections: ConnectionColumns[];
982
+ /** Each place 0.14's chain deleted, by an authentic `project.delete` or `environment.delete`, with the tombstone it gave the slug. */
983
+ deleted: {
984
+ kind: 'project' | 'environment';
985
+ id: string;
986
+ tombstone: string;
987
+ }[];
988
+ };
989
+ /**
990
+ * The cutover's answer: done (now, or before); not yet, with where 0.14's
991
+ * chain is verified from; `moved`, a 0.14 write since the app read what it
992
+ * vouched for (ask again); `refused`, 0.14's chain or rows not as 0.14
993
+ * accepts them, which a cutover does not seal (an operator's to look at).
994
+ */
995
+ export type CutoverOutcome = {
996
+ ok: true;
997
+ done: true;
998
+ } | {
999
+ ok: true;
1000
+ done: false;
1001
+ from: ChainMark;
1002
+ } | {
1003
+ ok: false;
1004
+ refused: 'moved' | 'refused';
1005
+ why: string;
1006
+ };
1007
+ export type ChangeBindingsOutcome = {
1008
+ ok: true;
1009
+ number: string;
1010
+ witnessed: boolean | null;
1011
+ } | {
1012
+ ok: false;
1013
+ refused: ChangeBindingsRefusal;
1014
+ why?: string;
1015
+ };
1016
+ /** The row a sign-in writes (`credentials`): a service's credential for a CI run, or a workload's key-bound session. */
1017
+ export type SignInCredential = {
1018
+ id: string;
1019
+ kind: 'service' | 'workload';
1020
+ tokenHash: string;
1021
+ tokenHint: string;
1022
+ label: string | null;
1023
+ scope: string | null;
1024
+ places: string | null;
1025
+ expiresAt: number;
1026
+ notAfter: number | null;
1027
+ jkt: string | null;
1028
+ authMac: string;
1029
+ };
1030
+ /**
1031
+ * Why a sign-in made nothing, the statement's own words: the account or
1032
+ * the binding not as named, frozen, its rate spent (or a lock not had in
1033
+ * time), its times past or too far, the token spent, the app's key one it
1034
+ * rotated from.
1035
+ */
1036
+ /** Why a sign-in made nothing; `unsealed`: its binding is none the vault sealed (one 0.14 made, or a row not its object), which signs nobody in (PR 3a). */
1037
+ export type SignInRefusal = 'unbound' | 'frozen' | 'busy' | 'expired' | 'replayed' | 'retired' | 'unsealed' | 'proof';
1038
+ /**
1039
+ * A sign-in's answer. `proof`: the vault's check of the token or the DPoP
1040
+ * proof refused it, `reason` saying why as the app's refusals do
1041
+ * (`ExchangeReason`), and a key the binding's uploaded set lacks naming
1042
+ * it (`kid`).
1043
+ */
1044
+ export type SignInOutcome = {
1045
+ ok: true;
1046
+ number: string;
1047
+ witnessed: boolean | null;
1048
+ } | {
1049
+ ok: false;
1050
+ refused: Exclude<SignInRefusal, 'proof'>;
1051
+ } | {
1052
+ ok: false;
1053
+ refused: 'proof';
1054
+ reason: string;
1055
+ message: string;
1056
+ kid: string | null;
1057
+ };
1058
+ /** A token the vault issues (`Vault.issueToken`). Times in ms since the epoch, bytes in base64. */
1059
+ /**
1060
+ * What the app's entry would name a request by, which a change's record
1061
+ * keeps for the audit pages where 0.14's entry stood (D147, T164): the
1062
+ * credential or MCP connection whose act it was, as an entry's
1063
+ * `credentialId` (a run's credential, a personal token, an app connected
1064
+ * through MCP); and, through MCP, the app and the approval, as its `via`.
1065
+ * The app's word, which the vault records and never weighs.
1066
+ */
1067
+ export type RequestTrace = {
1068
+ credentialId: string;
1069
+ mcp: {
1070
+ connectionId: string;
1071
+ clientId: string;
1072
+ clientName: string;
1073
+ approvalId: string | null;
1074
+ } | null;
1075
+ };
1076
+ export type IssueTokenInput = {
1077
+ /** Who issues it, `user:…` or `token:…`: the request's caller. */
1078
+ actor: string;
1079
+ /** The credential the request came in on, by id; null for none (a request the app made itself). */
1080
+ via: string | null;
1081
+ /** Whose act it was, for its change's record (`RequestTrace`); none for a request on no such credential. */
1082
+ trace?: RequestTrace | null;
1083
+ /** Whom it acts as: a service account's `token:<id>`, or the actor, for a personal token or a handle. */
1084
+ principal: string;
1085
+ /** The principal's generation it is issued at. */
1086
+ generation: number;
1087
+ /**
1088
+ * The issuer's access the app weighed the scope on: the vault's newest
1089
+ * access entry about them (`issuerNow`), which the vault holds the issue
1090
+ * to (`access`, as `issuerStill`); null to hold it to none.
1091
+ */
1092
+ actorAccess: string | null;
1093
+ credential: IssuedTokenRow;
1094
+ /** The policy the app weighed the scope on: its newest `policy.change`, and the environments it protected (`policyStill`'s). */
1095
+ policy: {
1096
+ seq: string | null;
1097
+ protected: {
1098
+ environmentId: string;
1099
+ slug: string | null;
1100
+ }[];
1101
+ };
1102
+ /** The id of the app's log key, under whose key the row's MAC was made (`SignInInput.appKey`). */
1103
+ appKey: string;
1104
+ };
1105
+ /** The row a token's issue writes (`credentials`). */
1106
+ export type IssuedTokenRow = {
1107
+ id: string;
1108
+ kind: 'service' | 'personal' | 'handle';
1109
+ tokenHash: string;
1110
+ tokenHint: string;
1111
+ label: string | null;
1112
+ /** Its scope as stored (`storedScope`): what the vault weighs, and seals. */
1113
+ scope: string;
1114
+ /** A handle's environments, as made for; null for any other. */
1115
+ places: string | null;
1116
+ expiresAt: number;
1117
+ /** Who issued it, as its row names them: the actor's id. */
1118
+ createdBy: string;
1119
+ authMac: string;
1120
+ };
1121
+ /**
1122
+ * Why a token was not issued, the vault's own words: the issuer may not
1123
+ * give that scope, or that kind of token (`refused`); the credential the
1124
+ * request came in on, or the issuer, ended (`ended`); the account it is for
1125
+ * is not the member it was weighed as (`gone`); the issuer's access moved
1126
+ * since the app weighed it (`access`); what it was weighed on moved
1127
+ * while it was written, each of the three times the vault weighed it
1128
+ * (`moved`), or the policy did (`policy`); a lock not had in time
1129
+ * (`busy`); the app's key one it rotated from (`retired`); the credential
1130
+ * the request came in on one 0.14 made, which the log never held, so
1131
+ * nothing the vault could authenticate (`unlogged`: the app issues on it
1132
+ * as before).
1133
+ */
1134
+ export type IssueTokenRefusal = 'refused' | 'ended' | 'gone' | 'access' | 'moved' | 'policy' | 'busy' | 'retired' | 'unlogged';
1135
+ export type IssueTokenOutcome = {
1136
+ ok: true;
1137
+ number: string;
1138
+ witnessed: boolean | null;
1139
+ } | {
1140
+ ok: false;
1141
+ refused: IssueTokenRefusal;
1142
+ why?: string;
1143
+ };
1144
+ /** A revoke (`Vault.revokeCredential`): the credential as the app read it, and the app's MACs over its row before and after. */
1145
+ export type RevokeCredentialInput = {
1146
+ /** Who revokes it, as its entry names them: `user:…`, `token:…`, or the app's own (`coffre`). */
1147
+ actor: string;
1148
+ /** Its object's columns as read, and their seal: a row the log holds (one 0.14 made, with none, the app revokes as 0.14 does). */
1149
+ before: {
1150
+ columns: CredentialColumns;
1151
+ seal: string;
1152
+ };
1153
+ authMacFrom: string;
1154
+ authMac: string;
1155
+ revokedAt: number;
1156
+ revokedBy: string;
1157
+ /** Why, for its change's record: a revoke, or its holder's sign-out. */
1158
+ reason: 'revoke' | 'sign_out';
1159
+ /** The credential the request came in on, for its change's record. */
1160
+ via: string | null;
1161
+ /** Whose act it was, for its change's record (`RequestTrace`); none for a request on no such credential. */
1162
+ trace?: RequestTrace | null;
1163
+ /**
1164
+ * The policy the caller's right to revoke it was weighed on, held to under
1165
+ * the fence (as `policyStill` holds a write to it under 0.14's head): the
1166
+ * newest `policy.change`'s sequence number, and the environments it
1167
+ * protected, by id, with their slugs (null: deleted). Null for a revoke no policy weighs
1168
+ * (its holder's own sign-out).
1169
+ */
1170
+ policy: {
1171
+ seq: string | null;
1172
+ protected: {
1173
+ environmentId: string;
1174
+ slug: string | null;
1175
+ }[];
1176
+ } | null;
1177
+ };
1178
+ /**
1179
+ * A revoke: its change's number, or why nothing was written: the row not
1180
+ * as read, or revoked already (`moved`); not its object's newest change's
1181
+ * (`stale`); its seal not the vault's (`tampered`, a finding); the policy
1182
+ * it was weighed on changed (`policy`); a lock not had in time (`busy`).
1183
+ */
1184
+ export type RevokeCredentialOutcome = {
1185
+ ok: true;
1186
+ number: string;
1187
+ witnessed: boolean | null;
1188
+ } | {
1189
+ ok: false;
1190
+ refused: 'moved' | 'stale' | 'tampered' | 'policy' | 'busy';
1191
+ };
280
1192
  /**
281
1193
  * The vault's entries that change what a member holds: what their row's
282
1194
  * `access_seq` names, and what a finding about them is newer than while it
@@ -378,6 +1290,8 @@ export type Outcome<T> = ({
378
1290
  ok: false;
379
1291
  refusal: Refusal;
380
1292
  };
1293
+ /** What each refusal says, as the vault answers it and the app shows it. */
1294
+ export declare const REFUSAL_MESSAGES: Record<RefusalCode, string>;
381
1295
  /**
382
1296
  * A proposed version the app will store. The ids bind its key, and `path`
383
1297
  * is the app's label for the write's log. Reads name stored version ids
@@ -434,6 +1348,28 @@ export type KeyChecks = {
434
1348
  * gives a person's app as it is (`coffre run`'s plan).
435
1349
  */
436
1350
  export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
1351
+ /**
1352
+ * A use's purpose, keepsSensitive and way in as 0.15's log stores them, in
1353
+ * one smallint (`log_uses.purpose`, schema 0022, 0046): the purpose's code,
1354
+ * plus 256 when a copy keeps values sensitive, plus 512 times its way in's
1355
+ * (`USE_WAYS`; T147). The vault writes them; the audit pages read them back
1356
+ * (T166).
1357
+ */
1358
+ export declare const USE_PURPOSES: readonly ["reveal", "run", "compare", "copy", "use", "expose"];
1359
+ /** Each way in by its code: a credential's, 0, as every use before T147; then `UseWay`'s. */
1360
+ export declare const USE_WAYS: readonly ["credential", "connection", "binding", "access"];
1361
+ /** A use's code (`USE_PURPOSES`). */
1362
+ export declare function useCode(use: {
1363
+ purpose: Purpose;
1364
+ keepsSensitive?: boolean;
1365
+ way?: 'credential' | UseWay;
1366
+ }): number;
1367
+ /** The purpose, keepsSensitive and way in a use's code stores; null for a code no release writes. */
1368
+ export declare function useOfCode(code: number): {
1369
+ purpose: Purpose;
1370
+ keepsSensitive: boolean;
1371
+ way?: UseWay;
1372
+ } | null;
437
1373
  /**
438
1374
  * Whether a read hands values back to whoever asked, which a person never
439
1375
  * gets of a sensitive value: every purpose but the proxy's `use` and a
@@ -801,5 +1737,218 @@ export type LogVerification = {
801
1737
  reason: string;
802
1738
  fault?: AccessFault;
803
1739
  };
1740
+ /** The longest a use may take from its time to its answer, held in Postgres too (R53): no use is decided later than this after its `at`. */
1741
+ export declare const USE_DEADLINE_MS = 3000;
1742
+ /** A use's request id: 63 random bits, as text, unique within its millisecond (hot-path-one.md, "Row size"). */
1743
+ export declare function newUseRequestId(): string;
1744
+ /** A use as the app asks for it: on which credential, which key, through which place, why, and when. */
1745
+ export type UseInput = {
1746
+ /**
1747
+ * What the request came in on (T147): a credentials row, by id; with
1748
+ * `way`, an MCP connection or a Cloudflare service binding, by id, or,
1749
+ * behind Cloudflare Access, which signs a browser in with no row of
1750
+ * coffre's, the person (`user:…`), whose account is all the use weighs.
1751
+ */
1752
+ credential: string;
1753
+ way?: UseWay;
1754
+ secretId: string;
1755
+ /** The fork an inherited value is read in (`UnwrapInput`'s `through`); null for the key's own environment. */
1756
+ place: string | null;
1757
+ purpose: Purpose;
1758
+ keepsSensitive?: boolean;
1759
+ /**
1760
+ * The request's id, a whole number below 2^63 as text, unique within its
1761
+ * millisecond, and its time, ms since the epoch: a retry of a request
1762
+ * whose answer was lost passes both unchanged, and finds the entry the
1763
+ * first one wrote (`replayed`).
1764
+ */
1765
+ requestId: string;
1766
+ at: number;
1767
+ /** When it must have answered: at most 3 s after `at` (R53). */
1768
+ deadline: number;
1769
+ };
1770
+ /**
1771
+ * A request's several keys as the app asks for them (`Vault.useMany`): what `UseInput` names but its key, once, and
1772
+ * each key with the place it is read through and its own request id, which its entry takes.
1773
+ */
1774
+ export type UseManyInput = Omit<UseInput, 'secretId' | 'place' | 'requestId'> & {
1775
+ items: readonly {
1776
+ secretId: string;
1777
+ place: string | null;
1778
+ requestId: string;
1779
+ }[];
1780
+ };
1781
+ /**
1782
+ * A request's several keys' answer, all or nothing: every value, in the request's order, each with its entry (or the
1783
+ * one it rode on); or the first key refused, by its index in the request, logged as its request was (`number`) or not
1784
+ * (null: decided before anything of it was written, as a use's refusal by ids is); or busy, nothing decided.
1785
+ */
1786
+ export type UseManyOutcome = {
1787
+ ok: true;
1788
+ values: {
1789
+ number: string;
1790
+ covered: boolean;
1791
+ value: UsedValue;
1792
+ }[];
1793
+ } | {
1794
+ ok: false;
1795
+ index: number;
1796
+ code: UseCode;
1797
+ number: string | null;
1798
+ } | {
1799
+ ok: false;
1800
+ busy: UseBusy;
1801
+ retryAfter: number;
1802
+ };
1803
+ /** The way in a use came through that has no credentials row (`UseInput.way`): each a sealed object of the log but Access. */
1804
+ export type UseWay = 'connection' | 'binding' | 'access';
1805
+ /** Why a use is refused: the rules' codes, and those of sealed inputs. */
1806
+ export type UseCode = RefusalCode |
1807
+ /** An input's row is not its object's newest change's: put back from before one, deleted, or written around the log. */
1808
+ 'stale' |
1809
+ /** The credential is not one, was revoked, or had ended at the request's time. */
1810
+ 'credential' |
1811
+ /** No such key. */
1812
+ 'missing' |
1813
+ /** The log holds no policy, so no cap: never served, as the vault writes one before its first use. */
1814
+ 'no_policy' |
1815
+ /**
1816
+ * A use by name of a key that reads an archived place, a reference's source's: it reads nothing until that place is
1817
+ * back (review r4 of D153). Decided before anything is written, never logged as a use: the app logs the request.
1818
+ */
1819
+ 'archived';
1820
+ /** What a use's refusal says: the rules' as `REFUSAL_MESSAGES`, and those of sealed inputs. */
1821
+ export declare function useRefusalMessage(code: UseCode): string;
1822
+ /** A use as the request names it (`Vault.useNamed`). */
1823
+ export type NamedUseInput = {
1824
+ /** The token the request came in on, hashed as its credential's row holds it, base64. */
1825
+ tokenHash: string;
1826
+ /** Where, by slugs; null for the one environment a handle was made for (the credential proxy's stable URL). */
1827
+ place: {
1828
+ project: string;
1829
+ environment: string;
1830
+ } | null;
1831
+ /**
1832
+ * With `place` null, the environments the request does not mean, by slugs: served not by name when the handle's is
1833
+ * one (the stable URL's segments that name an environment of the handle's instead, one the proxy reads as its
1834
+ * person's own config).
1835
+ */
1836
+ unless?: readonly {
1837
+ project: string;
1838
+ environment: string;
1839
+ }[];
1840
+ /** The key, by name; null for none: the caller's standing at the place alone, as for a key it does not hold. */
1841
+ key: string | null;
1842
+ /**
1843
+ * The credentials the app's config accepts (review r6 and r7 of D153): `signin`, whether the deployment signs in
1844
+ * through coffre's own sign-in (under Cloudflare Access no coffre token is a credential); `issuers`, each sign-in
1845
+ * provider it configures, `<provider id>:<issuer hash>`, which a browser session's identity must name. The call
1846
+ * holds the token's credential to them first, before anything else it reads: one the app would refuse is answered
1847
+ * as a token no credential has, whatever the request names.
1848
+ */
1849
+ accepts: CredentialAcceptance;
1850
+ purpose: Purpose;
1851
+ keepsSensitive?: boolean;
1852
+ requestId: string;
1853
+ at: number;
1854
+ deadline: number;
1855
+ };
1856
+ /** What a named use's credential must be for the app to take it (`NamedUseInput.accepts`). */
1857
+ export type CredentialAcceptance = {
1858
+ signin: boolean;
1859
+ issuers: readonly string[];
1860
+ };
1861
+ /**
1862
+ * A named use's answer. `served: false`: none the vault serves this way (a fork, a personal config, a handle of
1863
+ * several environments, or a place its stable URL does not mean), and the app reads it as ever. Otherwise the route
1864
+ * the request takes, which the vault picks on the credential and its account alone (`routeOf`; D153, review r2):
1865
+ *
1866
+ * - `credential`: the credential's own check answers (401; a token of 0.10's sealed first): no credential its seals
1867
+ * bear out, or one ended. `outcome`, the vault's refusal, which the app does not answer with.
1868
+ * - `busy`: nothing decided, admission's answer, whatever the request names.
1869
+ * - `name`: the use's outcome, a plain value's text where one was allowed, and every refusal of the key alike; the rows
1870
+ * the app checks before anything leaves (the credential's with its MAC, the place's, the key's), as `app_read`
1871
+ * answers them, JSON; the key's id (null for none held); the place, by slugs; and the caller as the vault decided
1872
+ * them, from the sealed rows the use read (one who holds nothing where roles, policy or place were not as sealed).
1873
+ */
1874
+ export type NamedUseOutcome = {
1875
+ served: false;
1876
+ } | {
1877
+ served: true;
1878
+ route: 'credential';
1879
+ outcome: Extract<UseOutcome, {
1880
+ code: UseCode;
1881
+ }>;
1882
+ } | {
1883
+ served: true;
1884
+ route: 'busy';
1885
+ outcome: Extract<UseOutcome, {
1886
+ busy: UseBusy;
1887
+ }>;
1888
+ } | {
1889
+ served: true;
1890
+ route: 'name';
1891
+ secretId: string | null;
1892
+ outcome: UseOutcome | {
1893
+ ok: true;
1894
+ plain: string;
1895
+ versionId: string;
1896
+ };
1897
+ app: string | null;
1898
+ standing: Access;
1899
+ /** The place the use was at, by its slugs as the vault read them: the one named, or the handle's own. */
1900
+ place: {
1901
+ project: string;
1902
+ environment: string;
1903
+ } | null;
1904
+ /** The same place by its ids, as the vault's own rows read it, on either engine: where a refusal is logged. */
1905
+ at: {
1906
+ projectId: string;
1907
+ environmentId: string;
1908
+ } | null;
1909
+ };
1910
+ /** Why a use was not decided at all: the app answers 503, with `Retry-After`. */
1911
+ export type UseBusy = 'late' | 'overloaded' | 'replayed' | 'ahead' | 'unconfigured';
1912
+ /** A value a use opened: its data key, base64, and the version it decrypts, with what its ciphertext is bound to. */
1913
+ export type UsedValue = {
1914
+ key: string;
1915
+ versionId: string;
1916
+ context: {
1917
+ projectId: string;
1918
+ environmentId: string;
1919
+ secretId: string;
1920
+ owner?: string;
1921
+ sensitive?: true;
1922
+ };
1923
+ envelope: {
1924
+ version: number;
1925
+ ciphertext: string;
1926
+ iv: string;
1927
+ authTag: string;
1928
+ };
1929
+ };
1930
+ /**
1931
+ * A use's answer. Allowed: the value, and the entry it was logged as (or,
1932
+ * a repeat, rode on: `covered`). Refused: why, logged as the request it
1933
+ * was. Busy: nothing was decided, ask again in `retryAfter` seconds:
1934
+ * `late` (past its deadline, or below the floor), `overloaded` (refused at
1935
+ * admission), `replayed` (a retry of a call that wrote: the first one's
1936
+ * entry stands, its value never left), `ahead` (its time past the
1937
+ * database's clock), `unconfigured` (no policy logged yet).
1938
+ */
1939
+ export type UseOutcome = {
1940
+ ok: true;
1941
+ number: string;
1942
+ covered: boolean;
1943
+ value: UsedValue;
1944
+ } | {
1945
+ ok: false;
1946
+ code: UseCode;
1947
+ number: string | null;
1948
+ } | {
1949
+ ok: false;
1950
+ busy: UseBusy;
1951
+ retryAfter: number;
1952
+ };
804
1953
  //#endregion
805
- export type { AccessFault, CallerKind, FaultGrant, FaultNames };
1954
+ export type { AccessFault, CallerKind, FaultGrant, FaultNames, GrantFacts, MemberFacts, PolicyEdits, PolicyEnvironment, ProtectedPlace };