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