@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/dist/vault.d.ts
CHANGED
|
@@ -1,4 +1,1491 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { A as RoleDefinition, P as ServiceSetting, T as Policy, _ as InstanceRole, d as Filter, f as GrantPlace, i as CredentialScope, j as Scope, k as Role, m as Holdings, n as CallerKind } from "./access-ERdGGHG7.js";
|
|
2
|
+
import { Z as VerifiedUnder, z as CallerIdentity } from "./index-DuG9p3GH.js";
|
|
3
|
+
import { a as BindingPolicy, rt as Constraints } from "./workloads-CW2dK4AW.js";
|
|
4
|
+
import { McpScope } from "./mcp.js";
|
|
5
|
+
import { l as Generation } from "./recipe-BgJpmJum.js";
|
|
6
|
+
//#region src/changes/access.d.ts
|
|
7
|
+
/**
|
|
8
|
+
* The changes of members, grants, roles and the instance's policy
|
|
9
|
+
* (`packages/vault/src/ops/access.ts`). A workload's session makes none of
|
|
10
|
+
* them, whatever its scope holds (`workload_cannot_issue`), as 0.14 refused.
|
|
11
|
+
*/
|
|
12
|
+
type AccessChanges = MemberPut | MemberRemove | AccessGrant | RoleEdit | SettingsEdit;
|
|
13
|
+
type AccessAnswers = {
|
|
14
|
+
/** The role and scope they hold now, the scope's projects by id as the row holds them (null is everywhere), and whether they were admitted or brought back. */
|
|
15
|
+
'member.put': Standing & {
|
|
16
|
+
created: boolean;
|
|
17
|
+
};
|
|
18
|
+
/**
|
|
19
|
+
* How many grants went with them (`revoked`), and how many ways in the
|
|
20
|
+
* removal ended, as they stood when it was made: sign-in accounts it
|
|
21
|
+
* revoked, and, of their generation, live sessions (browser and CLI),
|
|
22
|
+
* tokens (every other credential but an MCP connection's) and connected
|
|
23
|
+
* apps (an MCP connection its client redeemed), which the generation's
|
|
24
|
+
* move ends; and whether the caller runs the instance (`runs`), as the
|
|
25
|
+
* change found them: the leaver's report is theirs to read.
|
|
26
|
+
*/
|
|
27
|
+
'member.remove': {
|
|
28
|
+
revoked: number;
|
|
29
|
+
sessions: number;
|
|
30
|
+
tokens: number;
|
|
31
|
+
identities: number;
|
|
32
|
+
apps: number;
|
|
33
|
+
runs: boolean;
|
|
34
|
+
};
|
|
35
|
+
/** What became of each place, in the order asked; with `admit`, whether this change admitted the service account. */
|
|
36
|
+
'access.grant': {
|
|
37
|
+
changes: AccessChange[];
|
|
38
|
+
created?: boolean;
|
|
39
|
+
};
|
|
40
|
+
/** The role as it is now: null once deleted. */
|
|
41
|
+
'policy.change': {
|
|
42
|
+
role: RoleDefinition | null;
|
|
43
|
+
};
|
|
44
|
+
/** The setting as the row holds it, projects by id. */
|
|
45
|
+
'settings.change': {
|
|
46
|
+
serviceAccounts: Scope;
|
|
47
|
+
};
|
|
48
|
+
};
|
|
49
|
+
type Standing = {
|
|
50
|
+
role: InstanceRole;
|
|
51
|
+
scope: Scope | null;
|
|
52
|
+
};
|
|
53
|
+
/**
|
|
54
|
+
* Where a person's instance role applies, as the app names it: projects by
|
|
55
|
+
* slug, which the vault keeps by id, so a rename keeps them; environments by
|
|
56
|
+
* slug, those of every project. Each list holds 1,000 slugs at most. Null is
|
|
57
|
+
* everywhere.
|
|
58
|
+
*/
|
|
59
|
+
type ScopeInput = {
|
|
60
|
+
projects: Filter;
|
|
61
|
+
environments: Filter;
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* A member admitted, brought back or given an instance role
|
|
65
|
+
* (`member.put`), whichever their row calls for, as 0.14.7's `admit` did:
|
|
66
|
+
* the app cannot know which without reading the row, and only the vault's
|
|
67
|
+
* read can. Its entry is the action that happened:
|
|
68
|
+
*
|
|
69
|
+
* no row `member.add`, as `role`, or `member` when null
|
|
70
|
+
* removed `member.restore`, the same, in the generation their removal moved on to, with no grant
|
|
71
|
+
* active `member.role`, `unchanged` when nothing moves; a null role keeps their role and scope
|
|
72
|
+
*
|
|
73
|
+
* Whoever runs the instance puts a member; only an Owner of the whole
|
|
74
|
+
* instance makes an Owner, changes one, or changes their own role; the last
|
|
75
|
+
* Owner of the whole instance stays one (`last_owner`), and one the
|
|
76
|
+
* deployment names comes in and stays as one (`configured_owner`). A
|
|
77
|
+
* service account holds no instance role but `member`: asked one, refused
|
|
78
|
+
* `invalid`. A person who does not run the instance, on a session, sets up
|
|
79
|
+
* a service account, as `member`, where they could give it something
|
|
80
|
+
* (`setsUpServices`), and brings back one they removed. A refused put is
|
|
81
|
+
* logged as `member.add`, as 0.14.7 logged it.
|
|
82
|
+
*
|
|
83
|
+
* A member, by principal: a person, `user:<email>` in lowercase, or a
|
|
84
|
+
* service account, `token:<name>`, 256 characters at most. `scope` is where
|
|
85
|
+
* the role applies, given only with a role but `member`, which holds
|
|
86
|
+
* nothing. Past these the call is a fault, not a refusal: the app checks
|
|
87
|
+
* them first.
|
|
88
|
+
*/
|
|
89
|
+
type MemberPut = {
|
|
90
|
+
op: 'member.put';
|
|
91
|
+
principal: string;
|
|
92
|
+
role: InstanceRole | null;
|
|
93
|
+
scope: ScopeInput | null;
|
|
94
|
+
};
|
|
95
|
+
/**
|
|
96
|
+
* Remove a member: their grants go, their sign-in accounts are revoked, and
|
|
97
|
+
* their generation moves on, which ends every session, token and binding
|
|
98
|
+
* issued before. Whoever runs the instance removes a member; a person on a
|
|
99
|
+
* session, a service account they manage (`managesService`).
|
|
100
|
+
*/
|
|
101
|
+
type MemberRemove = {
|
|
102
|
+
op: 'member.remove';
|
|
103
|
+
principal: string;
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
106
|
+
* A person's roles at projects and environments, set, changed, given an end
|
|
107
|
+
* or taken away: all of the places or none, each once. A place is a
|
|
108
|
+
* project's slug, or one of its environments' too, which takes a role that
|
|
109
|
+
* holds nothing only a project has (`PROJECT_ONLY_PERMISSIONS`). A role is
|
|
110
|
+
* a project role's id, or null to revoke; `expiresAt` an ISO 8601 time
|
|
111
|
+
* after the change, or null for no end. Whoever manages access at each
|
|
112
|
+
* place (`grant.manage`) gives anything there but to themselves; they may
|
|
113
|
+
* give up their own. A grant is of the member's generation: one left from
|
|
114
|
+
* before a removal is replaced in place. Refused `no_access` where a place
|
|
115
|
+
* is not there or not theirs; to whoever manages every place asked,
|
|
116
|
+
* `not_a_member`, `removed`, and `invalid` for a role there is not, a
|
|
117
|
+
* project's on an environment or an end gone.
|
|
118
|
+
*
|
|
119
|
+
* A service account's grants, where the caller does not manage access: a
|
|
120
|
+
* person on a session gives it what they could give it (`givesService`),
|
|
121
|
+
* and takes away what it holds, if they manage it (`managesService`): they
|
|
122
|
+
* could give it all it holds. `admit` admits it in the same change when
|
|
123
|
+
* it is not a member, or brings it back, all or none, as 0.14.7's
|
|
124
|
+
* `setAccess` did: by someone who could set one up (`setsUpServices`), it
|
|
125
|
+
* holds nothing before and is theirs; one removed, only its remover or
|
|
126
|
+
* whoever runs the instance brings back. A row these weigh that the vault
|
|
127
|
+
* did not write refuses, `tampered`. 1 to 1,000 places; past the shapes
|
|
128
|
+
* above, or `admit` of a person, the call is a fault, not a refusal: the
|
|
129
|
+
* app checks them first. `was`, given, is the grant the member holds at
|
|
130
|
+
* the place as an approval page showed it, or null for none: a live grant
|
|
131
|
+
* of their generation, as the member list has it. One that differs when
|
|
132
|
+
* the vault writes refuses `stale`, and nothing is changed.
|
|
133
|
+
*/
|
|
134
|
+
type AccessGrant = {
|
|
135
|
+
op: 'access.grant';
|
|
136
|
+
principal: string;
|
|
137
|
+
changes: {
|
|
138
|
+
project: string;
|
|
139
|
+
environment: string | null;
|
|
140
|
+
role: Role | null;
|
|
141
|
+
expiresAt: string | null;
|
|
142
|
+
was?: {
|
|
143
|
+
role: Role;
|
|
144
|
+
expiresAt: string | null;
|
|
145
|
+
} | null;
|
|
146
|
+
}[];
|
|
147
|
+
admit?: boolean;
|
|
148
|
+
};
|
|
149
|
+
/**
|
|
150
|
+
* A role defined, edited, put back or deleted (`policy.change`), by an
|
|
151
|
+
* Owner of the whole instance on a session, as 0.14 allowed: a project role
|
|
152
|
+
* (`instance` false), one that ships or one an Owner makes, or one of the
|
|
153
|
+
* instance's that ships (Admin, Auditor). Owner, and the instance's Member,
|
|
154
|
+
* are never edited. `definition` null puts a role that ships back as it
|
|
155
|
+
* ships, and deletes one an Owner made, refused `role_granted` while a
|
|
156
|
+
* grant names it, as is defining one that does not ship and is not there.
|
|
157
|
+
* A project role that holds what only a project has
|
|
158
|
+
* (`PROJECT_ONLY_PERMISSIONS`) is refused `invalid` while a grant on an
|
|
159
|
+
* environment names it, as is deleting a role that is not there.
|
|
160
|
+
* `revision` is the role as its preview weighed it (`roleRevision`), none
|
|
161
|
+
* included: one that changed since is refused `policy_changed`, so that a
|
|
162
|
+
* change is made from the role its preview was. Left out, the change is
|
|
163
|
+
* made from the role as it is. An id is a role's as `ROLE_ID` has it; a
|
|
164
|
+
* definition one `definitionProblem` passes; a revision one
|
|
165
|
+
* `ROLE_REVISION` matches: past those the call is a fault, not a refusal:
|
|
166
|
+
* the app checks them first.
|
|
167
|
+
*/
|
|
168
|
+
type RoleEdit = {
|
|
169
|
+
op: 'policy.change';
|
|
170
|
+
instance: boolean;
|
|
171
|
+
role: Role;
|
|
172
|
+
definition: RoleDefinition | null;
|
|
173
|
+
revision?: string;
|
|
174
|
+
};
|
|
175
|
+
/**
|
|
176
|
+
* Where people set up service accounts themselves (`settings.change`,
|
|
177
|
+
* `ServiceSetting`): projects and environments by slug, 1,000 a list at
|
|
178
|
+
* most. Whoever runs the instance sets it, as 0.14 allowed.
|
|
179
|
+
*/
|
|
180
|
+
type SettingsEdit = {
|
|
181
|
+
op: 'settings.change';
|
|
182
|
+
serviceAccounts: ScopeInput;
|
|
183
|
+
};
|
|
184
|
+
//#endregion
|
|
185
|
+
//#region src/changes/freezes.d.ts
|
|
186
|
+
/**
|
|
187
|
+
* A workload's use stopped at its next request, and let go again
|
|
188
|
+
* (`packages/vault/src/ops/freezes.ts`, docs/design/workload-access.md,
|
|
189
|
+
* 8.2): a freeze is a field of the row it stops, and keeps the sessions,
|
|
190
|
+
* codes and bindings under it, so lifting it restores service with no new
|
|
191
|
+
* sign-in. An upstream credential's is its environment's
|
|
192
|
+
* (`upstream.freeze`, `upstream.thaw`).
|
|
193
|
+
*/
|
|
194
|
+
type FreezeChanges = WorkloadFreeze | WorkloadUnfreeze;
|
|
195
|
+
type FreezeAnswers = {
|
|
196
|
+
/** The target in its one spelling, and since when it is frozen: a freeze already there is kept, with its time. */
|
|
197
|
+
'workload.freeze': Frozen;
|
|
198
|
+
/** The target in its one spelling, and null: it is not frozen now. */
|
|
199
|
+
'workload.unfreeze': Frozen;
|
|
200
|
+
};
|
|
201
|
+
type Frozen = {
|
|
202
|
+
target: string;
|
|
203
|
+
frozenAt: string | null;
|
|
204
|
+
};
|
|
205
|
+
/**
|
|
206
|
+
* What a freeze names, as `freezeTarget` spells it, and who freezes and
|
|
207
|
+
* lifts it:
|
|
208
|
+
*
|
|
209
|
+
* instance every workload's use an Owner of the whole instance, on a session
|
|
210
|
+
* token:<name> one service account's whoever manages it (`managesService`)
|
|
211
|
+
* binding:<uuid> one of its trust bindings the same
|
|
212
|
+
* session:<uuid> one workload's session the same
|
|
213
|
+
*
|
|
214
|
+
* Refused `no_access` where the target is not there (a service account
|
|
215
|
+
* removed, a binding revoked, a session ended or of another generation)
|
|
216
|
+
* or not theirs, one answer; `tampered` where a row the decision weighs
|
|
217
|
+
* was written behind the vault; `workload_cannot_issue` to a workload's
|
|
218
|
+
* session. A target in another spelling, or `credential:…`, is a fault:
|
|
219
|
+
* the app canonicalizes it first. `reason` is why, 1 to 400 characters,
|
|
220
|
+
* which the entry keeps.
|
|
221
|
+
*/
|
|
222
|
+
type WorkloadFreeze = {
|
|
223
|
+
op: 'workload.freeze';
|
|
224
|
+
target: string;
|
|
225
|
+
reason: string;
|
|
226
|
+
};
|
|
227
|
+
/** A freeze lifted: by whoever may make it, as `WorkloadFreeze` says. */
|
|
228
|
+
type WorkloadUnfreeze = {
|
|
229
|
+
op: 'workload.unfreeze';
|
|
230
|
+
target: string;
|
|
231
|
+
};
|
|
232
|
+
//#endregion
|
|
233
|
+
//#region src/changes/mcp.d.ts
|
|
234
|
+
/**
|
|
235
|
+
* The changes of MCP connections and of the OAuth clients that make them
|
|
236
|
+
* (`packages/vault/src/ops/mcp.ts`, docs/design/0.16.md, "MCP
|
|
237
|
+
* connections"). A connection is a credential of kind `mcp` of the person
|
|
238
|
+
* who approved it: its row holds the code until the client redeems it, then
|
|
239
|
+
* the refresh token. Each access token is a credential of its own, of an
|
|
240
|
+
* hour, under it (`ancestors`): it stands while its connection does, so
|
|
241
|
+
* ending the connection ends them all, with no write of theirs.
|
|
242
|
+
*/
|
|
243
|
+
type McpChanges = McpConnect | McpToken | McpRevoke | OauthRegister | McpAsk | McpDecide;
|
|
244
|
+
type McpAnswers = {
|
|
245
|
+
/** The connection, and when its code stops being good, ISO 8601. */
|
|
246
|
+
'mcp.connect': {
|
|
247
|
+
connection: string;
|
|
248
|
+
expiresAt: string;
|
|
249
|
+
};
|
|
250
|
+
/**
|
|
251
|
+
* The tokens made: the access token's credential, its member, when it
|
|
252
|
+
* ends (ISO 8601), and the scopes it holds. Or, for a code or a refresh
|
|
253
|
+
* token presented again, the connection it ended (`ended`), which the
|
|
254
|
+
* app answers `invalid_grant`.
|
|
255
|
+
*/
|
|
256
|
+
'mcp.token': {
|
|
257
|
+
ended: false;
|
|
258
|
+
principal: string;
|
|
259
|
+
connection: string;
|
|
260
|
+
credential: string;
|
|
261
|
+
expiresAt: string;
|
|
262
|
+
scopes: McpScope[];
|
|
263
|
+
} | {
|
|
264
|
+
ended: true;
|
|
265
|
+
connection: string;
|
|
266
|
+
};
|
|
267
|
+
/** The connection ended. */
|
|
268
|
+
'mcp.revoke': {
|
|
269
|
+
connection: string;
|
|
270
|
+
};
|
|
271
|
+
/** The client registered, and when, ISO 8601. */
|
|
272
|
+
'oauth.register': {
|
|
273
|
+
client: string;
|
|
274
|
+
createdAt: string;
|
|
275
|
+
};
|
|
276
|
+
/** The approval opened, and when it expires, ISO 8601. */
|
|
277
|
+
'mcp.ask': {
|
|
278
|
+
approval: string;
|
|
279
|
+
expiresAt: string;
|
|
280
|
+
};
|
|
281
|
+
/** The approval decided. */
|
|
282
|
+
'mcp.decide': {
|
|
283
|
+
approval: string;
|
|
284
|
+
};
|
|
285
|
+
};
|
|
286
|
+
/**
|
|
287
|
+
* The changes nobody asks: a client redeems or gives back what it holds (a
|
|
288
|
+
* code with its PKCE verifier, a refresh token, an access token), and anyone
|
|
289
|
+
* may register a client.
|
|
290
|
+
*/
|
|
291
|
+
type McpUnasked = 'mcp.token' | 'mcp.revoke' | 'oauth.register';
|
|
292
|
+
/**
|
|
293
|
+
* A client as the person approved it: its id (a metadata document's URL,
|
|
294
|
+
* or a registration's id), its name and host as the consent page showed
|
|
295
|
+
* them, how it is known (`cimd`, a document the app fetched; `dcr`, a
|
|
296
|
+
* registration, whose row the vault reads and holds the redirect and the
|
|
297
|
+
* name to), and the redirect the code goes to.
|
|
298
|
+
*/
|
|
299
|
+
type McpClient = {
|
|
300
|
+
id: string;
|
|
301
|
+
name: string;
|
|
302
|
+
host: string | null;
|
|
303
|
+
registration: 'cimd' | 'dcr';
|
|
304
|
+
redirectUri: string;
|
|
305
|
+
};
|
|
306
|
+
/**
|
|
307
|
+
* A person, on a session of theirs, approves an MCP client
|
|
308
|
+
* (`POST /oauth/authorizations`): a connection, whose code the client
|
|
309
|
+
* redeems within a minute (`CODE_SECONDS`) with its PKCE verifier. The app
|
|
310
|
+
* draws the code and sends its SHA-256 (`code`), with the S256 challenge
|
|
311
|
+
* the client sent (`challenge`, RFC 7636) and the scopes the person ticked
|
|
312
|
+
* (`read` always among them).
|
|
313
|
+
*
|
|
314
|
+
* A token, a workload's session or an MCP connection is refused
|
|
315
|
+
* `no_access`: a personal token connecting one would make a connection
|
|
316
|
+
* with all its person holds. A person with `MAX_CONNECTIONS` connections
|
|
317
|
+
* that stand, codes waiting included, is refused `too_many_connections`.
|
|
318
|
+
* A registered client (`dcr`) is its row's: refused `unknown_client` for
|
|
319
|
+
* one not there, or revoked, and `wrong_redirect` for a redirect it did not
|
|
320
|
+
* register; its name is the row's, whatever the app says.
|
|
321
|
+
*/
|
|
322
|
+
type McpConnect = {
|
|
323
|
+
op: 'mcp.connect';
|
|
324
|
+
client: McpClient;
|
|
325
|
+
scopes: McpScope[];
|
|
326
|
+
code: string;
|
|
327
|
+
challenge: string;
|
|
328
|
+
};
|
|
329
|
+
/**
|
|
330
|
+
* A client redeems what it holds for an access token and the next refresh
|
|
331
|
+
* token (`POST /api/oauth/token`). The app draws both and sends their
|
|
332
|
+
* SHA-256 (`tokens`). The access token lasts an hour
|
|
333
|
+
* (`ACCESS_TOKEN_MINUTES`), never past its connection.
|
|
334
|
+
*
|
|
335
|
+
* - `authorization_code`: the code's SHA-256, its PKCE verifier and the
|
|
336
|
+
* redirect it was sent to, within its minute. The connection then lasts
|
|
337
|
+
* `minutes` (365 days at most), and the person's earlier connections of
|
|
338
|
+
* the same client that it grants all of and more end (`supersedes` in
|
|
339
|
+
* @coffre/core/mcp).
|
|
340
|
+
* - `refresh_token`: the refresh token's SHA-256, and the scopes the client
|
|
341
|
+
* narrows the access token to, or null for all the connection holds.
|
|
342
|
+
*
|
|
343
|
+
* Refused, writing nothing: `unknown_grant` for a code or a refresh token
|
|
344
|
+
* that is not there, or whose connection ended; `expired`, a code past its
|
|
345
|
+
* minute or a connection past its end; `wrong_client`, `wrong_redirect`,
|
|
346
|
+
* `wrong_verifier`; `invalid_scope` for a refresh that widens; `deactivated`
|
|
347
|
+
* for a person removed since they connected it; `tampered` for a row
|
|
348
|
+
* written behind the vault; `adopting` before the vault adopted the
|
|
349
|
+
* database. A code or a refresh token presented after it was replaced is a
|
|
350
|
+
* copy someone else holds: the connection ends, in a change that is made
|
|
351
|
+
* (`ended: true`), since a refusal writes nothing.
|
|
352
|
+
*/
|
|
353
|
+
type McpToken = {
|
|
354
|
+
op: 'mcp.token';
|
|
355
|
+
client: string;
|
|
356
|
+
tokens: {
|
|
357
|
+
access: string;
|
|
358
|
+
refresh: string;
|
|
359
|
+
};
|
|
360
|
+
} & ({
|
|
361
|
+
grant: 'authorization_code';
|
|
362
|
+
code: string;
|
|
363
|
+
verifier: string;
|
|
364
|
+
redirectUri: string;
|
|
365
|
+
minutes: number;
|
|
366
|
+
} | {
|
|
367
|
+
grant: 'refresh_token';
|
|
368
|
+
refresh: string;
|
|
369
|
+
scopes: McpScope[] | null;
|
|
370
|
+
});
|
|
371
|
+
/**
|
|
372
|
+
* A client gives back a token it holds (RFC 7009, `POST /api/oauth/revoke`):
|
|
373
|
+
* its refresh token or one of its access tokens, by its SHA-256 (`token`),
|
|
374
|
+
* and its `client_id` when it sent one (`client`). Its connection ends, and
|
|
375
|
+
* every access token under it, as a disconnect does. Nobody asks it but
|
|
376
|
+
* whoever holds the token.
|
|
377
|
+
*
|
|
378
|
+
* Refused, writing nothing, which the endpoint answers as a success, as
|
|
379
|
+
* RFC 7009 has it: `unknown_grant` for a token that is no connection's
|
|
380
|
+
* refresh token nor an access token that stands, whose connection ended
|
|
381
|
+
* already, or that is another client's; `tampered` for a row written
|
|
382
|
+
* behind the vault; `adopting` before the vault adopted the database.
|
|
383
|
+
*/
|
|
384
|
+
type McpRevoke = {
|
|
385
|
+
op: 'mcp.revoke';
|
|
386
|
+
token: string;
|
|
387
|
+
client: string | null;
|
|
388
|
+
};
|
|
389
|
+
/**
|
|
390
|
+
* Anyone registers a client (RFC 7591, `POST /api/oauth/register`): a
|
|
391
|
+
* public one, its name as it claims it and the redirects the app kept
|
|
392
|
+
* (`registrationRedirects` in @coffre/core/mcp). The app's limiter counts
|
|
393
|
+
* who asks; the table holds `MAX_CLIENTS` rows at most, refused `full`
|
|
394
|
+
* past that, and the vault's upkeep deletes those no connection names a
|
|
395
|
+
* week after they were made. Its entry ages out.
|
|
396
|
+
*/
|
|
397
|
+
type OauthRegister = {
|
|
398
|
+
op: 'oauth.register';
|
|
399
|
+
name: string;
|
|
400
|
+
redirectUris: string[];
|
|
401
|
+
};
|
|
402
|
+
/**
|
|
403
|
+
* An MCP client asks for a change, on its access token (`tools/call`): an
|
|
404
|
+
* approval, pending for `APPROVAL_SECONDS`, which its person decides on
|
|
405
|
+
* coffre's page. `arguments` is the tool's, as canonical JSON (keys
|
|
406
|
+
* sorted); the vault keeps them in the row, and the SHA-256 of
|
|
407
|
+
* `[tool, arguments]` beside them (`digest`), which the page sends back.
|
|
408
|
+
* The entry names the tool, the `place` it is about
|
|
409
|
+
* (`project/environment/KEY`, or less) and the digest, never the
|
|
410
|
+
* arguments: they are the client's text. Nothing changes until the person
|
|
411
|
+
* approves it, as theirs (`ForConnection`).
|
|
412
|
+
*
|
|
413
|
+
* Refused, writing nothing: `unauthenticated` for a token that is no MCP
|
|
414
|
+
* access token that stands; `full` for a connection with `MAX_PENDING`
|
|
415
|
+
* approvals waiting, which only their person's decision or their expiry
|
|
416
|
+
* frees; `pending` for one waiting already for the same call, which the
|
|
417
|
+
* app joins.
|
|
418
|
+
*/
|
|
419
|
+
type McpAsk = {
|
|
420
|
+
op: 'mcp.ask';
|
|
421
|
+
tool: string;
|
|
422
|
+
arguments: string;
|
|
423
|
+
place: string | null;
|
|
424
|
+
};
|
|
425
|
+
/**
|
|
426
|
+
* A person, on their browser session, denies an approval, or approves one
|
|
427
|
+
* whose tool changes nothing (`MCP_SHOWS`): the page showed them the value
|
|
428
|
+
* first. `digest` is the one the page rendered. Every other approval is
|
|
429
|
+
* approved by its change (`ForConnection`). Refused `unknown_approval` for
|
|
430
|
+
* one that is not pending (decided, or expired by the time its write
|
|
431
|
+
* starts), not of this digest, or not theirs; `disconnected` for one whose
|
|
432
|
+
* connection no longer stands.
|
|
433
|
+
*/
|
|
434
|
+
type McpDecide = {
|
|
435
|
+
op: 'mcp.decide';
|
|
436
|
+
approval: string;
|
|
437
|
+
approve: boolean;
|
|
438
|
+
digest: string;
|
|
439
|
+
};
|
|
440
|
+
//#endregion
|
|
441
|
+
//#region src/changes/places.d.ts
|
|
442
|
+
/** The changes of projects and environments (`packages/vault/src/ops/places.ts`). */
|
|
443
|
+
type PlacesChanges = ProjectCreate | EnvironmentCreate | ProjectEdit | EnvironmentEdit | FolderRefile | PlaceDelete;
|
|
444
|
+
/**
|
|
445
|
+
* An edit answers the place as it leaves it, `archivedAt` in ISO 8601;
|
|
446
|
+
* asked for what is so already, it changes nothing, and is logged all the
|
|
447
|
+
* same.
|
|
448
|
+
*/
|
|
449
|
+
type ProjectEdited = {
|
|
450
|
+
id: string;
|
|
451
|
+
slug: string;
|
|
452
|
+
archivedAt: string | null;
|
|
453
|
+
folder: string | null;
|
|
454
|
+
};
|
|
455
|
+
type EnvironmentEdited = {
|
|
456
|
+
id: string;
|
|
457
|
+
slug: string;
|
|
458
|
+
archivedAt: string | null;
|
|
459
|
+
protected: boolean;
|
|
460
|
+
};
|
|
461
|
+
type PlacesAnswers = {
|
|
462
|
+
'project.create': {
|
|
463
|
+
id: string;
|
|
464
|
+
};
|
|
465
|
+
/**
|
|
466
|
+
* Its slug is the one asked for, or, for a personal config, the one made
|
|
467
|
+
* for it, which only a list for deletion shows. A personal config is
|
|
468
|
+
* `protected` as the environment it is a config of is.
|
|
469
|
+
*/
|
|
470
|
+
'environment.create': {
|
|
471
|
+
id: string;
|
|
472
|
+
slug: string;
|
|
473
|
+
protected: boolean;
|
|
474
|
+
forked?: Forked;
|
|
475
|
+
};
|
|
476
|
+
/** The projects it filed, by slug. */
|
|
477
|
+
'folder.refile': {
|
|
478
|
+
moved: string[];
|
|
479
|
+
};
|
|
480
|
+
'project.delete': PlaceDeleted;
|
|
481
|
+
'environment.delete': PlaceDeleted;
|
|
482
|
+
} & { [K in ProjectEdit['op']]: ProjectEdited; } & { [K in EnvironmentEdit['op']]: EnvironmentEdited; };
|
|
483
|
+
/**
|
|
484
|
+
* Make a project, as an Admin or Owner of the instance whose scope takes in
|
|
485
|
+
* new projects, on a session's credential. Its slug is free: no project has
|
|
486
|
+
* it, archived ones included. A slug is 1 to 63 of `a-z`, `0-9` and `-`,
|
|
487
|
+
* starting with a letter or digit; past that the call is a fault, not a
|
|
488
|
+
* refusal: the app checks it first.
|
|
489
|
+
*/
|
|
490
|
+
type ProjectCreate = {
|
|
491
|
+
op: 'project.create';
|
|
492
|
+
project: string;
|
|
493
|
+
};
|
|
494
|
+
/**
|
|
495
|
+
* Make an environment in a live project, as one who manages its
|
|
496
|
+
* environments (`environment.manage`): its slug free in the project,
|
|
497
|
+
* shaped as a project's and none of a project's pages (`PROJECT_PAGES`).
|
|
498
|
+
* With `parent`, a fork that inherits from that environment, live, never
|
|
499
|
+
* a personal config, which the caller reads, and which inherits from two
|
|
500
|
+
* at most, so that the fork inherits from three; with `copy`, a fork that
|
|
501
|
+
* copies one (`EnvironmentCopy`). A fork of a protected environment is
|
|
502
|
+
* protected, whatever `protected` says.
|
|
503
|
+
*
|
|
504
|
+
* With `mine`, the caller's personal config of `environment` instead: a
|
|
505
|
+
* person's, who reads or uses it, live, never a personal config itself,
|
|
506
|
+
* with two parents at most. One per person per environment. Its slug is
|
|
507
|
+
* made here, and it is protected as its environment is, through it.
|
|
508
|
+
*/
|
|
509
|
+
type EnvironmentCreate = {
|
|
510
|
+
op: 'environment.create';
|
|
511
|
+
project: string;
|
|
512
|
+
environment: string;
|
|
513
|
+
} & ({
|
|
514
|
+
mine: false;
|
|
515
|
+
parent: string | null;
|
|
516
|
+
protected: boolean;
|
|
517
|
+
copy?: EnvironmentCopy;
|
|
518
|
+
} | {
|
|
519
|
+
mine: true;
|
|
520
|
+
});
|
|
521
|
+
/**
|
|
522
|
+
* A fork that copies (docs/design/forking.md, "Forks"): with `copy`, the
|
|
523
|
+
* new environment inherits from nothing (`parent` null) and holds, made in
|
|
524
|
+
* the same change, each key `from` reads now, as a use of it finds them:
|
|
525
|
+
* its own and those it inherits, each from the nearest environment that
|
|
526
|
+
* holds it or dismissed it, with the folder it is filed in there, and none
|
|
527
|
+
* of its history. A key with no value, a reference broken, is left out.
|
|
528
|
+
* Who forks manages the project's environments and reads `from`, and each
|
|
529
|
+
* environment above it a key comes from (`parent_unreadable`); `from` is a
|
|
530
|
+
* live environment of the project, no personal config, whose chain stands
|
|
531
|
+
* (`broken_chain`).
|
|
532
|
+
*
|
|
533
|
+
* Each key is a copy of its value by default: the vault opens the version
|
|
534
|
+
* and seals it again as the new key's first version, and nobody else holds
|
|
535
|
+
* it. It is kept as it was, plain, a secret or sensitive, and its first
|
|
536
|
+
* date is its source's; it has no recipe and is in no pair, as one typed.
|
|
537
|
+
* With `references`, each key is a reference instead, one hop, to where its
|
|
538
|
+
* value is held: the parent's key, a key it inherits, or a reference's
|
|
539
|
+
* source. That is a reference made, as `secret.write` makes one: its
|
|
540
|
+
* forker reads the source where it is held, by their own grants, and uses
|
|
541
|
+
* it there too if it is sensitive. A key whose source they do not is
|
|
542
|
+
* copied, and named in `copied`. A sensitive value reached through a
|
|
543
|
+
* reference is never copied, whatever is asked: a copy would hold it under
|
|
544
|
+
* this project, which another project's value is not. It stays a reference
|
|
545
|
+
* to its source, which its forker must be able to make, or the fork is
|
|
546
|
+
* refused, `no_access`. A workload copies or refers to no value it only
|
|
547
|
+
* uses where it is held (`use_only`).
|
|
548
|
+
*
|
|
549
|
+
* One change opens and seals again 2,000 values at most (`too_many_keys`),
|
|
550
|
+
* and 8 MiB of them as stored (`too_much_to_copy`, the vault's
|
|
551
|
+
* `MOST_COPIED`, which a mark shares): past either, nothing is made, and
|
|
552
|
+
* the fork is made by references or inherits instead. Either is weighed
|
|
553
|
+
* before any value is read: one that copies by default, by every value it
|
|
554
|
+
* copies; one by references, by every value it may copy (each sensitive
|
|
555
|
+
* value its chain holds, and each a reference reads that is not), so past
|
|
556
|
+
* the bound it is refused even where the forker uses most of them, and is
|
|
557
|
+
* made inheriting instead (docs/design/0.16.md, the paragraph on
|
|
558
|
+
* `MOST_COPIED`).
|
|
559
|
+
*/
|
|
560
|
+
type EnvironmentCopy = {
|
|
561
|
+
from: string;
|
|
562
|
+
references: boolean;
|
|
563
|
+
};
|
|
564
|
+
/** What a fork that copies made: how many keys, how many of them references, and those copied where references were asked for. */
|
|
565
|
+
type Forked = {
|
|
566
|
+
keys: number;
|
|
567
|
+
references: number;
|
|
568
|
+
copied: string[];
|
|
569
|
+
};
|
|
570
|
+
/**
|
|
571
|
+
* A project edited, archived or not, by whoever manages it
|
|
572
|
+
* (`project.manage`), on a project there or archived: a deleted one's
|
|
573
|
+
* tombstone is no project.
|
|
574
|
+
*
|
|
575
|
+
* - `project.update`: its slug, to one free as a new project's is.
|
|
576
|
+
* - `project.archive`: refused, `referenced`, while a reference held
|
|
577
|
+
* outside it reads a value in it (D41): archiving would stop that read.
|
|
578
|
+
* - `project.restore`.
|
|
579
|
+
* - `project.move`: filed in a folder, 1 to 64 characters with no `/`, no
|
|
580
|
+
* control character and no space at either end, or in none.
|
|
581
|
+
*/
|
|
582
|
+
type ProjectEdit = {
|
|
583
|
+
project: string;
|
|
584
|
+
} & ({
|
|
585
|
+
op: 'project.update';
|
|
586
|
+
slug: string;
|
|
587
|
+
} | {
|
|
588
|
+
op: 'project.archive';
|
|
589
|
+
} | {
|
|
590
|
+
op: 'project.restore';
|
|
591
|
+
} | {
|
|
592
|
+
op: 'project.move';
|
|
593
|
+
folder: string | null;
|
|
594
|
+
});
|
|
595
|
+
/**
|
|
596
|
+
* An environment edited, there or archived, by whoever manages its
|
|
597
|
+
* project's environments (`environment.manage`), unless said otherwise. A
|
|
598
|
+
* personal config is edited by none of these: it is archived and restored
|
|
599
|
+
* with its environment, and protected through it.
|
|
600
|
+
*
|
|
601
|
+
* - `environment.update`: its slug, to one free in the project and none of
|
|
602
|
+
* a project's pages. Scopes name environments by slug, so this moves who
|
|
603
|
+
* an instance role reaches there.
|
|
604
|
+
* - `environment.archive`, with its personal configs: refused while a live
|
|
605
|
+
* fork inherits from it (`inherited`), or a reference held outside it
|
|
606
|
+
* reads a value in it (`referenced`).
|
|
607
|
+
* - `environment.restore`, with its personal configs: refused while an
|
|
608
|
+
* environment it inherits from is archived or deleted (`parent_archived`),
|
|
609
|
+
* or one is not there to say (`broken_chain`).
|
|
610
|
+
* - `environment.protect`: each role holds there what its protected column
|
|
611
|
+
* says, for people (docs/design/roles.md). Never by a workload's session
|
|
612
|
+
* (`workload_cannot_issue`), which changes no one's access.
|
|
613
|
+
* - `environment.unprotect`: as protecting, and by an Owner of its project
|
|
614
|
+
* alone, by a grant on it or an instance role whose scope takes in all
|
|
615
|
+
* of it, on no credential's scope (`ownsProject`, R30).
|
|
616
|
+
* - `upstream.freeze`: the deployment's upstream credential of that name,
|
|
617
|
+
* `stripe`, used by nobody in this live environment, by whoever writes
|
|
618
|
+
* there (`secret.write`); `upstream.thaw` lifts it, by an Owner of the
|
|
619
|
+
* project (docs/design/workload-access.md, section 8.2).
|
|
620
|
+
*/
|
|
621
|
+
type EnvironmentEdit = {
|
|
622
|
+
project: string;
|
|
623
|
+
environment: string;
|
|
624
|
+
} & ({
|
|
625
|
+
op: 'environment.update';
|
|
626
|
+
slug: string;
|
|
627
|
+
} | {
|
|
628
|
+
op: 'environment.archive';
|
|
629
|
+
} | {
|
|
630
|
+
op: 'environment.restore';
|
|
631
|
+
} | {
|
|
632
|
+
op: 'environment.protect';
|
|
633
|
+
} | {
|
|
634
|
+
op: 'environment.unprotect';
|
|
635
|
+
} | {
|
|
636
|
+
op: 'upstream.freeze';
|
|
637
|
+
upstream: string;
|
|
638
|
+
} | {
|
|
639
|
+
op: 'upstream.thaw';
|
|
640
|
+
upstream: string;
|
|
641
|
+
});
|
|
642
|
+
/**
|
|
643
|
+
* A folder of projects renamed, `to` a name shaped as `project.move`
|
|
644
|
+
* takes one, or emptied, `to` null: every project filed there, archived
|
|
645
|
+
* ones included, in one change, by whoever manages each of them
|
|
646
|
+
* (`project.manage`). A folder is a label, so renaming onto one that is
|
|
647
|
+
* there merges the two. A folder none of whose projects the caller may
|
|
648
|
+
* file is no folder of theirs: refused as one with no project.
|
|
649
|
+
*/
|
|
650
|
+
type FolderRefile = {
|
|
651
|
+
op: 'folder.refile';
|
|
652
|
+
folder: string;
|
|
653
|
+
to: string | null;
|
|
654
|
+
};
|
|
655
|
+
/**
|
|
656
|
+
* A place deleted for good, as 0.14.7 deleted one (`deletePlace`), in one
|
|
657
|
+
* change: every version under it erased, its ciphertext and wrapped data
|
|
658
|
+
* key emptied, and a plain one's copy cleared; every grant on it revoked;
|
|
659
|
+
* every reference into it or out of it ended, its holder reading nothing
|
|
660
|
+
* since (a reference holds no value of its own); and its slug made a
|
|
661
|
+
* tombstone, `market~deleted-2026-10-05` (`tombstoneOf`), which frees the
|
|
662
|
+
* slug and is never mistaken for what takes it next. Its rows stay, names
|
|
663
|
+
* and dates only, because the log names them. A copy made of one of its
|
|
664
|
+
* values elsewhere, a fork's, is a value of its own and stays. Weighed
|
|
665
|
+
* (`weigh`), it says what it would take, and changes nothing.
|
|
666
|
+
*
|
|
667
|
+
* - `project.delete`: an archived project, with every environment and
|
|
668
|
+
* personal config in it.
|
|
669
|
+
* - `environment.delete`: an archived environment itself, whatever its
|
|
670
|
+
* project is, with its personal configs; refused, `inherited`, while a
|
|
671
|
+
* fork inherits from it, archived or not: deleted, it would leave the
|
|
672
|
+
* fork naming a tombstone.
|
|
673
|
+
*
|
|
674
|
+
* Both by an Admin or Owner of the whole instance, on no credential's
|
|
675
|
+
* scope (`runsInstance`); a place there but live is `not_archived`. A
|
|
676
|
+
* personal config is deleted by its owner, or by whoever manages its
|
|
677
|
+
* project's environments (`environment.manage`), archived or not, never
|
|
678
|
+
* on a personal token (deleting for good stays with people):
|
|
679
|
+
* `environment` names it by its own slug, which only a list for deletion
|
|
680
|
+
* shows, or, with `mine`, the environment it is the caller's config of.
|
|
681
|
+
* A place that holds more versions with a value than one change erases
|
|
682
|
+
* (`MOST_ERASED` in the vault) is refused, `too_large`, and nothing is
|
|
683
|
+
* erased: its environments are deleted one at a time first.
|
|
684
|
+
*/
|
|
685
|
+
type PlaceDelete = {
|
|
686
|
+
op: 'project.delete';
|
|
687
|
+
project: string;
|
|
688
|
+
} | {
|
|
689
|
+
op: 'environment.delete';
|
|
690
|
+
project: string;
|
|
691
|
+
environment: string;
|
|
692
|
+
mine: boolean;
|
|
693
|
+
};
|
|
694
|
+
/** What deleting a place takes, or took. */
|
|
695
|
+
type PlaceDeleted = {
|
|
696
|
+
/** `market`, `market/prod`, or a personal config's `market/dev@ada@acme.example`. */
|
|
697
|
+
path: string;
|
|
698
|
+
/** The slug its tombstone keeps: `market~deleted-2026-10-05`. */
|
|
699
|
+
tombstone: string;
|
|
700
|
+
/** The environments it takes, personal configs too, these by their environment and owner (`dev@ada@acme.example`): a project's every one, or the one with its configs. */
|
|
701
|
+
environments: string[];
|
|
702
|
+
/** The keys named there, which the tombstone keeps, never their values. */
|
|
703
|
+
keys: number;
|
|
704
|
+
/** The versions whose values it erases. */
|
|
705
|
+
versions: number;
|
|
706
|
+
/** The grants on it, lapsed ones too, which it revokes. */
|
|
707
|
+
grants: {
|
|
708
|
+
member: string;
|
|
709
|
+
place: string;
|
|
710
|
+
role: string;
|
|
711
|
+
}[];
|
|
712
|
+
/** The references into it and out of it, which it ends: each holder, and the source it read (`(gone)` for one not found). */
|
|
713
|
+
references: {
|
|
714
|
+
holder: string;
|
|
715
|
+
source: string;
|
|
716
|
+
}[];
|
|
717
|
+
/** Members who hold nothing anywhere afterwards, with no instance role: a service among them may be offboarded. */
|
|
718
|
+
stranded: string[];
|
|
719
|
+
};
|
|
720
|
+
//#endregion
|
|
721
|
+
//#region src/changes/secrets.d.ts
|
|
722
|
+
/** The changes of keys and their values (`packages/vault/src/ops/secrets.ts`). */
|
|
723
|
+
type SecretsChanges = SecretWrite | SecretRename | SecretRefile | ReferenceBreak | MissingDismiss;
|
|
724
|
+
type SecretsAnswers = {
|
|
725
|
+
/**
|
|
726
|
+
* Each key given a value, written or restored: the version it is at now, and the nature it was written as. A key made a
|
|
727
|
+
* reference is given none. And what the write does to each key asked (`outcomes`), which a dry run tells (`weigh`).
|
|
728
|
+
*/
|
|
729
|
+
'secret.write': {
|
|
730
|
+
keys: Record<string, {
|
|
731
|
+
version: number;
|
|
732
|
+
nature: Nature;
|
|
733
|
+
}>;
|
|
734
|
+
outcomes: Record<string, KeyOutcome>;
|
|
735
|
+
};
|
|
736
|
+
/** Where the reference read, as its source's rows say: null when the vault does not see them. */
|
|
737
|
+
'reference.break': {
|
|
738
|
+
source: SecretPath | null;
|
|
739
|
+
};
|
|
740
|
+
/** The key renamed, by its id. */
|
|
741
|
+
'secret.rename': {
|
|
742
|
+
id: string;
|
|
743
|
+
};
|
|
744
|
+
/** The keys filed there, by name, in order. */
|
|
745
|
+
'secret.refile': {
|
|
746
|
+
moved: string[];
|
|
747
|
+
};
|
|
748
|
+
/** What the change did to each key it named: dismissed, restored, or nothing, as it was already. */
|
|
749
|
+
'missing.dismiss': {
|
|
750
|
+
keys: Record<string, 'dismissed' | 'restored' | 'unchanged'>;
|
|
751
|
+
};
|
|
752
|
+
};
|
|
753
|
+
/**
|
|
754
|
+
* What a write does to one key, as 0.14's dry run said it (`DryRunOutcome`):
|
|
755
|
+
* `added`, a key made, by a value or a reference; `archived`; `unchanged`,
|
|
756
|
+
* nothing at all, a key archived already, filed where it is, or made a
|
|
757
|
+
* reference to the source it reads; `changed`, anything else. Or, for a
|
|
758
|
+
* value written over the key's own, live, of the nature it is written as,
|
|
759
|
+
* typed and no reference (`compare`): the same or not only by opening that
|
|
760
|
+
* version, which a decision never does. A dry run asks a use to compare
|
|
761
|
+
* (purpose `compare`), which opens and logs the value as a read: the version
|
|
762
|
+
* named is the one a use must hand back for the answer to stand. The write
|
|
763
|
+
* itself never compares: it writes the value as a new version.
|
|
764
|
+
*/
|
|
765
|
+
type KeyOutcome = 'added' | 'changed' | 'archived' | 'unchanged' | {
|
|
766
|
+
compare: {
|
|
767
|
+
secret: string;
|
|
768
|
+
version: number;
|
|
769
|
+
};
|
|
770
|
+
};
|
|
771
|
+
/** A key by where it is held: `market/prod/STRIPE_KEY`. */
|
|
772
|
+
type SecretPath = {
|
|
773
|
+
project: string;
|
|
774
|
+
environment: string;
|
|
775
|
+
key: string;
|
|
776
|
+
};
|
|
777
|
+
/** How a value is kept: a secret, a sensitive one that no person is handed back, or a plain one that whoever lists its environment sees. */
|
|
778
|
+
type Nature = 'secret' | 'sensitive' | 'plain';
|
|
779
|
+
/**
|
|
780
|
+
* What a write does to one key of its environment, one thing or several:
|
|
781
|
+
*
|
|
782
|
+
* - `value`: the key's next version, the key made if the environment has
|
|
783
|
+
* none by that name. Its `nature` as given, or, given none, the key's
|
|
784
|
+
* own kept, or, where the environment holds none, the one it inherits,
|
|
785
|
+
* and both for an archived key brought back: sensitive stays sensitive, and anything else is written a secret, a
|
|
786
|
+
* plain one's and one inherited from nowhere included. A reference's is
|
|
787
|
+
* its source's.
|
|
788
|
+
* `generated`: a client made it, by that recipe, which Regenerate makes
|
|
789
|
+
* the next one by (`@coffre/core/recipe`), as `formatRecipe` writes it.
|
|
790
|
+
* Never plain. A key pair's recipe writes its two keys together, each
|
|
791
|
+
* naming both, `{ private, public }`, with the same recipe: the two
|
|
792
|
+
* halves of one pair. A value typed, restored or referred to makes none.
|
|
793
|
+
* - `restore`: the key's next version, the value of that version of its
|
|
794
|
+
* own, opened and sealed again by the vault, which never hands it out.
|
|
795
|
+
* The value comes back as it was kept, plain, a secret or sensitive, and
|
|
796
|
+
* sensitive while the key is, as a write with no nature says (above), or
|
|
797
|
+
* while the key's newest value was. Its first date is its source's (the
|
|
798
|
+
* member report's). Made by a recipe or in a pair, it comes back as typed:
|
|
799
|
+
* Regenerate makes a new value, and it pairs with nothing. Whoever restores
|
|
800
|
+
* reads the key there (`secret.read`): the value serves again. And never
|
|
801
|
+
* looser than the newest copy of the same value, by its first date: a
|
|
802
|
+
* value marked sensitive comes back sensitive from a version before the
|
|
803
|
+
* mark, and one marked a secret from its plain version.
|
|
804
|
+
* - `nature` alone (`coffre mark`): the key's value kept, made of that
|
|
805
|
+
* nature, as the key's next version, which the vault opens and seals
|
|
806
|
+
* again: nature and version are in what its encryption names. Its first
|
|
807
|
+
* date, recipe and pair are kept: the value is the same. Stricter only,
|
|
808
|
+
* plain to a secret or sensitive, a secret to sensitive, by whoever
|
|
809
|
+
* writes keys there (`secret.write`); a sensitive value made a secret by
|
|
810
|
+
* an Owner of the project alone, as a person on no credential's scope
|
|
811
|
+
* (`not_owner` to anyone else), and plain never: that takes the value
|
|
812
|
+
* written again (`looser`). The nature it has already writes nothing
|
|
813
|
+
* (`unchanged`). The key is the environment's own, live and holding a
|
|
814
|
+
* value: `archived`, `is_reference` (mark its source), `inherited_key`
|
|
815
|
+
* (mark it where it is held), `no_value`, or `unknown_key`. A change
|
|
816
|
+
* that makes any key looser is logged `secret.loosen`, with every key's
|
|
817
|
+
* line, and `secret.write` otherwise.
|
|
818
|
+
* - `ref`: the key made a reference to that key, which whoever reads this
|
|
819
|
+
* environment then reads through it, value and nature, as it changes. Its
|
|
820
|
+
* own value, if any, is history. The source is a key of a live project and
|
|
821
|
+
* environment, no personal config's, that the writer reads there (and
|
|
822
|
+
* uses, a sensitive one), and that is no reference itself; nor is a key
|
|
823
|
+
* other references read made one: one hop only. A workload refers only to
|
|
824
|
+
* a value it is handed back where it is held, a plain one or one its
|
|
825
|
+
* binding lists.
|
|
826
|
+
* - `archived`: true archives the key, false brings it back. A key is
|
|
827
|
+
* archived with no value written.
|
|
828
|
+
* - `folder`: the folder it is listed in, null for none.
|
|
829
|
+
* - `inherit`, alone: in a fork, true resets the key to what a parent
|
|
830
|
+
* passes down, its own row archived with its history, and false makes
|
|
831
|
+
* its own value serve over that again. Either takes `secret.write`, as
|
|
832
|
+
* writing over a parent's does, and false `secret.read` too: the value
|
|
833
|
+
* serves again. A key no parent passes down is `not_inherited`.
|
|
834
|
+
*
|
|
835
|
+
* Any of these but `inherit` may say what the key read when its author
|
|
836
|
+
* looked (`replaces`): the version the key's value is now, by its id, as a
|
|
837
|
+
* listing gave it (`versionId`), its own live one or, in a fork that holds
|
|
838
|
+
* none live, the one it inherits; `{ source }`, a reference, here or
|
|
839
|
+
* inherited, to that secret, by its id (a listing's `reference.sourceId`);
|
|
840
|
+
* or `null`, a key that reads no value now and is no reference, here or
|
|
841
|
+
* inherited (new, archived with none passed down, or a reference broken).
|
|
842
|
+
* Anything else, a key renamed, archived, made a reference or written
|
|
843
|
+
* since, refuses the write, `stale`: a regenerate, or an MCP approval's
|
|
844
|
+
* change, addresses keys by name, and would otherwise change a key that no
|
|
845
|
+
* longer holds what its person read.
|
|
846
|
+
*
|
|
847
|
+
* A key that gets neither a value nor a reference is one the environment
|
|
848
|
+
* holds. In a fork, a key reset to what it inherits is written over as if
|
|
849
|
+
* it were live: it overrides its parent's again, as 0.14's did.
|
|
850
|
+
*/
|
|
851
|
+
type KeyWrite = {
|
|
852
|
+
key: string;
|
|
853
|
+
archived?: boolean;
|
|
854
|
+
folder?: string | null;
|
|
855
|
+
replaces?: Replaces;
|
|
856
|
+
inherit?: undefined;
|
|
857
|
+
} & ({
|
|
858
|
+
value: string;
|
|
859
|
+
nature?: Nature;
|
|
860
|
+
generated?: Generation;
|
|
861
|
+
ref?: undefined;
|
|
862
|
+
restore?: undefined;
|
|
863
|
+
} | {
|
|
864
|
+
restore: number;
|
|
865
|
+
value?: undefined;
|
|
866
|
+
nature?: undefined;
|
|
867
|
+
generated?: undefined;
|
|
868
|
+
ref?: undefined;
|
|
869
|
+
} | {
|
|
870
|
+
ref: SecretPath;
|
|
871
|
+
value?: undefined;
|
|
872
|
+
nature?: undefined;
|
|
873
|
+
generated?: undefined;
|
|
874
|
+
restore?: undefined;
|
|
875
|
+
} | {
|
|
876
|
+
value?: undefined;
|
|
877
|
+
nature?: undefined;
|
|
878
|
+
generated?: undefined;
|
|
879
|
+
ref?: undefined;
|
|
880
|
+
restore?: undefined;
|
|
881
|
+
}) | {
|
|
882
|
+
key: string;
|
|
883
|
+
nature: Nature;
|
|
884
|
+
replaces?: Replaces;
|
|
885
|
+
archived?: undefined;
|
|
886
|
+
folder?: undefined;
|
|
887
|
+
inherit?: undefined;
|
|
888
|
+
value?: undefined;
|
|
889
|
+
generated?: undefined;
|
|
890
|
+
ref?: undefined;
|
|
891
|
+
restore?: undefined;
|
|
892
|
+
} | {
|
|
893
|
+
key: string;
|
|
894
|
+
inherit: boolean;
|
|
895
|
+
archived?: undefined;
|
|
896
|
+
folder?: undefined;
|
|
897
|
+
value?: undefined;
|
|
898
|
+
nature?: undefined;
|
|
899
|
+
generated?: undefined;
|
|
900
|
+
replaces?: undefined;
|
|
901
|
+
ref?: undefined;
|
|
902
|
+
restore?: undefined;
|
|
903
|
+
};
|
|
904
|
+
/** What a key read when its author looked (`KeyWrite`'s): a version by its id, a reference to a secret by its id, or nothing. */
|
|
905
|
+
type Replaces = string | null | {
|
|
906
|
+
source: string;
|
|
907
|
+
};
|
|
908
|
+
/**
|
|
909
|
+
* Write keys in one environment, all of them or none. 1 to 2,000 keys,
|
|
910
|
+
* each once and named as a key is (`[A-Za-z_][A-Za-z0-9_]{0,127}`); a value
|
|
911
|
+
* is well-formed text with no NUL, 64 Ki characters at most, generated by a recipe as `formatRecipe` writes it, a key pair's two halves both in the write, and replacing a version named by a UUID, and the values
|
|
912
|
+
* of one write 1 MiB of UTF-8 in all, each version restored counted as the most a value weighs, 192 KiB (so 5 at most), since its size is known only once the vault reads it; a version restored a positive integer; a reference's source named by slugs and its key's name; a folder 1 to 64 UTF-16 units, with no slash or control character
|
|
913
|
+
* and nothing `trim` removes at either end (`folderName`); a mark one of the three natures, alone. Past any of these
|
|
914
|
+
* the call is a fault, not a refusal: the app checks them first.
|
|
915
|
+
*
|
|
916
|
+
* In a personal config (`mine`), its owner alone writes, a person
|
|
917
|
+
* (`not_a_person` to a service account), while they read or use the
|
|
918
|
+
* environment it is a config of, and as far as their credential's scope
|
|
919
|
+
* does there; no grant or role reaches it. It holds no reference, and a
|
|
920
|
+
* value written there with no nature over a plain one stays plain: nobody
|
|
921
|
+
* but its owner lists it. A write that gives a key a value makes the
|
|
922
|
+
* config where they have none, as an environment of three parents at most
|
|
923
|
+
* (`too_deep`); anything else asked of a config not there is asked of a
|
|
924
|
+
* key not there.
|
|
925
|
+
*/
|
|
926
|
+
type SecretWrite = {
|
|
927
|
+
op: 'secret.write';
|
|
928
|
+
project: string;
|
|
929
|
+
environment: string;
|
|
930
|
+
/** In the caller's personal config of `environment` (`dev@me`), made by this write if they have none and it gives a key a value. */
|
|
931
|
+
mine?: boolean;
|
|
932
|
+
keys: KeyWrite[];
|
|
933
|
+
};
|
|
934
|
+
/**
|
|
935
|
+
* A key renamed (`to`), with its history, by whoever writes keys there. A
|
|
936
|
+
* live key, named as `SecretWrite`'s: an archived one is brought back
|
|
937
|
+
* first (`archived`), and a name the environment holds already, archived
|
|
938
|
+
* or not, is `duplicate_key`. Its references read it still, by its id.
|
|
939
|
+
*
|
|
940
|
+
* The name carries down to every environment that inherits from it, forks
|
|
941
|
+
* of forks, archived ones and personal configs included: each one's own
|
|
942
|
+
* row of the key, its override, takes the new name, and so does its
|
|
943
|
+
* dismissal, so each goes on overriding or doing without the key it did.
|
|
944
|
+
* Where one already holds a key of the new name of its own, a shared fork
|
|
945
|
+
* refuses the rename, `duplicate_key_below`; a personal config, named to
|
|
946
|
+
* nobody but its owner, has its own moved out of the way, `NEW_2` (or
|
|
947
|
+
* `_3`, and on). No value moves, so the renamer needs nothing in the
|
|
948
|
+
* forks. Renamed onto its own name, nothing changes. In the caller's
|
|
949
|
+
* personal config (`mine`), as `SecretWrite`'s: a config has no forks.
|
|
950
|
+
*/
|
|
951
|
+
type SecretRename = {
|
|
952
|
+
op: 'secret.rename';
|
|
953
|
+
project: string;
|
|
954
|
+
environment: string;
|
|
955
|
+
/** In the caller's personal config of `environment` (`dev@me`). */
|
|
956
|
+
mine?: boolean;
|
|
957
|
+
key: string;
|
|
958
|
+
to: string;
|
|
959
|
+
/** What the key read when its author looked, as a write's (`KeyWrite`): anything else now, `stale`. */
|
|
960
|
+
replaces?: Replaces;
|
|
961
|
+
};
|
|
962
|
+
/**
|
|
963
|
+
* A folder of one environment's keys renamed (`to`), or emptied (`to`
|
|
964
|
+
* null): every key filed there, archived ones too, all of them or none, by
|
|
965
|
+
* whoever writes keys there. A folder is a label, so renaming onto one
|
|
966
|
+
* that is there merges the two. A folder no key is filed in is no folder:
|
|
967
|
+
* refused `no_folder`. Folders are named as `SecretWrite`'s; past that, a
|
|
968
|
+
* fault.
|
|
969
|
+
*/
|
|
970
|
+
type SecretRefile = {
|
|
971
|
+
op: 'secret.refile';
|
|
972
|
+
project: string;
|
|
973
|
+
environment: string;
|
|
974
|
+
/** In the caller's personal config of `environment` (`dev@me`). */
|
|
975
|
+
mine?: boolean;
|
|
976
|
+
folder: string;
|
|
977
|
+
to: string | null;
|
|
978
|
+
};
|
|
979
|
+
/**
|
|
980
|
+
* End the reference a key is: whoever read through it reads nothing there,
|
|
981
|
+
* until the key is given a value or made a reference again. Whoever writes
|
|
982
|
+
* the key may, and whoever manages access in its source's project, who
|
|
983
|
+
* need not see the key's environment at all.
|
|
984
|
+
*/
|
|
985
|
+
type ReferenceBreak = {
|
|
986
|
+
op: 'reference.break';
|
|
987
|
+
project: string;
|
|
988
|
+
environment: string;
|
|
989
|
+
key: string;
|
|
990
|
+
};
|
|
991
|
+
/**
|
|
992
|
+
* Keys an environment does without (`dismissed: true`), or does again
|
|
993
|
+
* (`false`), 0.14's `setDismissals`, by whoever writes keys there: the
|
|
994
|
+
* team's decision, which its missing keys list leaves out until someone
|
|
995
|
+
* restores it. A key named twice, or a key past 2,000 in one change, is a
|
|
996
|
+
* fault and a refusal (`too_many_keys`) respectively.
|
|
997
|
+
*
|
|
998
|
+
* In a fork, or a personal config (`mine`), a dismissal is also a removal:
|
|
999
|
+
* the environment no longer inherits the key, and a use there reads
|
|
1000
|
+
* nothing of it. One it holds a live row of, a value or a reference, would
|
|
1001
|
+
* serve whatever is dismissed, so dismissing it is refused, `held_here`:
|
|
1002
|
+
* reset it to what it inherits first, or archive it. Outside a fork, such a
|
|
1003
|
+
* dismissal is moot, and allowed, as in 0.14.7. A personal config is
|
|
1004
|
+
* dismissed in only by its owner, and only once they have one: a
|
|
1005
|
+
* dismissal makes none, `no_config`.
|
|
1006
|
+
*/
|
|
1007
|
+
type MissingDismiss = {
|
|
1008
|
+
op: 'missing.dismiss';
|
|
1009
|
+
project: string;
|
|
1010
|
+
environment: string;
|
|
1011
|
+
/** In the caller's personal config of `environment` (`dev@me`). */
|
|
1012
|
+
mine?: boolean;
|
|
1013
|
+
keys: {
|
|
1014
|
+
key: string;
|
|
1015
|
+
dismissed: boolean;
|
|
1016
|
+
}[];
|
|
1017
|
+
};
|
|
1018
|
+
//#endregion
|
|
1019
|
+
//#region src/changes/signin.d.ts
|
|
1020
|
+
/**
|
|
1021
|
+
* The changes of sign-in and of credentials (`packages/vault/src/ops/signin.ts`,
|
|
1022
|
+
* docs/design/0.16.md, "Signing in").
|
|
1023
|
+
*/
|
|
1024
|
+
type SigninChanges = Signin | CredentialEnd | AccountLink | AccountUnlink | TokenCreate | DeviceStart | DeviceDecide | DeviceRedeem;
|
|
1025
|
+
type SigninAnswers = {
|
|
1026
|
+
signin: Issued;
|
|
1027
|
+
/** The credential ended. */
|
|
1028
|
+
'credential.end': {
|
|
1029
|
+
credential: string;
|
|
1030
|
+
};
|
|
1031
|
+
/** The identity the account is bound by. */
|
|
1032
|
+
'account.link': {
|
|
1033
|
+
identity: string;
|
|
1034
|
+
};
|
|
1035
|
+
'account.unlink': {
|
|
1036
|
+
identity: string;
|
|
1037
|
+
};
|
|
1038
|
+
/**
|
|
1039
|
+
* The token made, and what it reaches, each place by its path and the
|
|
1040
|
+
* role there; a service's, the places of those whose sensitive values it
|
|
1041
|
+
* will not read (`withheld`, R32), as `token.bind` answers them.
|
|
1042
|
+
*/
|
|
1043
|
+
'token.create': Issued & {
|
|
1044
|
+
scope: Record<string, string>;
|
|
1045
|
+
withheld?: string[];
|
|
1046
|
+
};
|
|
1047
|
+
/** The device login, and when its codes stop being good, ISO 8601. */
|
|
1048
|
+
'device.start': {
|
|
1049
|
+
deviceLogin: string;
|
|
1050
|
+
expiresAt: string;
|
|
1051
|
+
};
|
|
1052
|
+
/** The device login decided. */
|
|
1053
|
+
'device.decide': {
|
|
1054
|
+
deviceLogin: string;
|
|
1055
|
+
};
|
|
1056
|
+
/** The CLI's session. */
|
|
1057
|
+
'device.redeem': Issued;
|
|
1058
|
+
};
|
|
1059
|
+
/**
|
|
1060
|
+
* The operations nobody asks: no credential comes with them, only where
|
|
1061
|
+
* their request came from (`Trace`). Each rests on what the app verified,
|
|
1062
|
+
* or on a secret of its own (a device code).
|
|
1063
|
+
*/
|
|
1064
|
+
type Unasked = 'signin' | 'device.start' | 'device.redeem';
|
|
1065
|
+
/**
|
|
1066
|
+
* An account at a sign-in provider, as the app verified it with the
|
|
1067
|
+
* provider: the vault takes it on the app's word, and its entry says so.
|
|
1068
|
+
* `issuer` is the hash the app keeps a provider's issuer by; `emails` are
|
|
1069
|
+
* the addresses the provider verified, lowercase, its primary one first, 20
|
|
1070
|
+
* at most.
|
|
1071
|
+
*/
|
|
1072
|
+
type Account = {
|
|
1073
|
+
provider: string;
|
|
1074
|
+
issuer: string;
|
|
1075
|
+
subject: string;
|
|
1076
|
+
emails: string[];
|
|
1077
|
+
};
|
|
1078
|
+
/**
|
|
1079
|
+
* A credential to make. The app draws its token and sends the SHA-256,
|
|
1080
|
+
* lowercase hex: the vault never sees a token. `minutes` is how long it
|
|
1081
|
+
* lasts, within what its kind may.
|
|
1082
|
+
*/
|
|
1083
|
+
type NewCredential = {
|
|
1084
|
+
token: string;
|
|
1085
|
+
minutes: number;
|
|
1086
|
+
label: string | null;
|
|
1087
|
+
};
|
|
1088
|
+
/** A credential made: whose it is, its id, and when it ends, ISO 8601. */
|
|
1089
|
+
type Issued = {
|
|
1090
|
+
principal: string;
|
|
1091
|
+
credential: string;
|
|
1092
|
+
expiresAt: string;
|
|
1093
|
+
};
|
|
1094
|
+
/**
|
|
1095
|
+
* A person signs in to a browser with an account the app verified.
|
|
1096
|
+
*
|
|
1097
|
+
* - The account is bound, its identity not revoked: its member signs in,
|
|
1098
|
+
* if they are active and of the generation it was bound in
|
|
1099
|
+
* (`deactivated` otherwise).
|
|
1100
|
+
* - The account is new: the first of its emails that names a member names
|
|
1101
|
+
* who it is (`not_registered` for none). They must be active
|
|
1102
|
+
* (`deactivated`) and have no account yet (`account_mismatch`: they sign
|
|
1103
|
+
* in with the one they have, and link this one). It is bound to them.
|
|
1104
|
+
* - An email the vault's configuration names an Owner is a member whatever
|
|
1105
|
+
* the rows say: made one, or made an active Owner of the whole instance
|
|
1106
|
+
* again, in the same change.
|
|
1107
|
+
* - Before the vault has adopted the database nobody signs in
|
|
1108
|
+
* (`adopting`, for the app to answer 503). A row the decision would read
|
|
1109
|
+
* that is there and not the vault's refuses it (`tampered`).
|
|
1110
|
+
*
|
|
1111
|
+
* `replaces` is the SHA-256 of the session token the browser showed, if it
|
|
1112
|
+
* showed one: that session ends in the same change, whoever's it was.
|
|
1113
|
+
*/
|
|
1114
|
+
type Signin = {
|
|
1115
|
+
op: 'signin';
|
|
1116
|
+
account: Account;
|
|
1117
|
+
session: NewCredential;
|
|
1118
|
+
replaces: string | null;
|
|
1119
|
+
};
|
|
1120
|
+
/**
|
|
1121
|
+
* End a credential: write its row revoked. Ending one that is already
|
|
1122
|
+
* ended, expired, not there or not the caller's to end is one refusal,
|
|
1123
|
+
* `unknown_credential`, which does not say which.
|
|
1124
|
+
*
|
|
1125
|
+
* - `credential` null: the one the request came in on, signing out
|
|
1126
|
+
* (`sign_out`). Any credential that stands signs itself out but a
|
|
1127
|
+
* handle, which is the proxy's; one that does not is told
|
|
1128
|
+
* `unauthenticated`, which the app answers as signed out all the same.
|
|
1129
|
+
* - `credential` an id (`token.revoke`), by what the route named it as
|
|
1130
|
+
* (`of`), and by the callers 0.14.7's route reached: no personal token
|
|
1131
|
+
* but on the handles route. A credential with a scope holds nothing of
|
|
1132
|
+
* the instance's own (`runsInstance` in @coffre/core/access), so a
|
|
1133
|
+
* service's token ends its own service's alone, or one of a service it
|
|
1134
|
+
* manages:
|
|
1135
|
+
* - `of` null: one of the caller's own, any kind, or anyone's for whoever
|
|
1136
|
+
* runs the instance (`DELETE /sessions/:id`, which a workload's session
|
|
1137
|
+
* does not reach);
|
|
1138
|
+
* - `of` `'handle'`: a handle of the caller's own, and nothing else, on
|
|
1139
|
+
* a personal token too (`DELETE /handles/:id`, `coffre run` ending its
|
|
1140
|
+
* own);
|
|
1141
|
+
* - `of` a member: a token or a workload's session of that member
|
|
1142
|
+
* (`DELETE /members/:member/tokens/:id`): theirs, for a person who
|
|
1143
|
+
* manages the service account (`managesService`), or for whoever runs
|
|
1144
|
+
* the instance.
|
|
1145
|
+
*/
|
|
1146
|
+
type CredentialEnd = {
|
|
1147
|
+
op: 'credential.end';
|
|
1148
|
+
} & ({
|
|
1149
|
+
credential: null;
|
|
1150
|
+
of: null;
|
|
1151
|
+
} | {
|
|
1152
|
+
credential: string;
|
|
1153
|
+
of: null | 'handle' | {
|
|
1154
|
+
member: string;
|
|
1155
|
+
};
|
|
1156
|
+
});
|
|
1157
|
+
/**
|
|
1158
|
+
* A person, on a browser session, binds a second account the app verified
|
|
1159
|
+
* to themselves. Refused `already_linked` if the account is bound to
|
|
1160
|
+
* anyone, themselves included.
|
|
1161
|
+
*/
|
|
1162
|
+
type AccountLink = {
|
|
1163
|
+
op: 'account.link';
|
|
1164
|
+
account: Account;
|
|
1165
|
+
};
|
|
1166
|
+
/**
|
|
1167
|
+
* The caller revokes one of their own accounts, by its identity's id
|
|
1168
|
+
* (`unknown_identity` for one that is not theirs, or not bound). The
|
|
1169
|
+
* sessions it opened end with it, with no write: the rule that reads them
|
|
1170
|
+
* refuses a session whose account is revoked. Their last account too: they
|
|
1171
|
+
* sign in again with any account a verified email of theirs names, as the
|
|
1172
|
+
* first time.
|
|
1173
|
+
*/
|
|
1174
|
+
type AccountUnlink = {
|
|
1175
|
+
op: 'account.unlink';
|
|
1176
|
+
identity: string;
|
|
1177
|
+
};
|
|
1178
|
+
/**
|
|
1179
|
+
* Make a token (`token.create`), one of three kinds. The app draws it and
|
|
1180
|
+
* sends its SHA-256 (`credential`), and its hint as the token's list shows it,
|
|
1181
|
+
* its kind's prefix and its last four characters (`coffre_pat_…x7Qd`). Its
|
|
1182
|
+
* scope is sealed on its row, each place by id with what its role held
|
|
1183
|
+
* there as it was made, and never changes after: a request made with it
|
|
1184
|
+
* holds what both that and its member hold then. A credential with a
|
|
1185
|
+
* scope never makes one, but a personal token a handle; a personal token
|
|
1186
|
+
* asking for a personal token is told what it is (`personal_token`), whoever
|
|
1187
|
+
* it names; a workload's session makes none (`workload_cannot_issue`).
|
|
1188
|
+
*
|
|
1189
|
+
* - `personal`: a person, on a session, for themselves (`member`, the route's
|
|
1190
|
+
* `user:<email>`: anyone else's is `no_access`, as 0.14.7 refused a person
|
|
1191
|
+
* making another's); a label, a week at most, and a scope by path (`{ "market/dev": "viewer" }`), each role one
|
|
1192
|
+
* that manages no access and that they hold all of at its place now, in
|
|
1193
|
+
* a project's protected environments too (0.14.7's `personalScope`).
|
|
1194
|
+
* - `handle`: a person, on a session or a personal token of theirs, for
|
|
1195
|
+
* the proxy (docs/design/credential-proxy.md); a label, a week at most
|
|
1196
|
+
* and never past the token it is made on, and the environments it stands
|
|
1197
|
+
* in for by path, `@me` for the person's personal config of one. It
|
|
1198
|
+
* reaches each, and each parent it inherits from that they read or use,
|
|
1199
|
+
* reading where they read and using where they only use.
|
|
1200
|
+
* - `service`: a token of the service account `member`, for whoever
|
|
1201
|
+
* manages it (`issuesCredential`); a label or none, 366 days at most, and
|
|
1202
|
+
* the scope asked or, `scope` null, every grant it holds. Each place
|
|
1203
|
+
* reads the sensitive values there only if the caller is an Owner of its
|
|
1204
|
+
* project (`ownsProject`, R32). Refused `use_only` on an instance whose
|
|
1205
|
+
* services sign in with a key only.
|
|
1206
|
+
*
|
|
1207
|
+
* A place that is not there and one beyond the caller are one refusal,
|
|
1208
|
+
* `no_access`; a role there is not, or one its place does not take,
|
|
1209
|
+
* `invalid`; a service's token with nothing to reach, `no_grants`.
|
|
1210
|
+
*/
|
|
1211
|
+
type TokenCreate = {
|
|
1212
|
+
op: 'token.create';
|
|
1213
|
+
credential: NewCredential;
|
|
1214
|
+
hint: string;
|
|
1215
|
+
} & ({
|
|
1216
|
+
kind: 'personal';
|
|
1217
|
+
member: string;
|
|
1218
|
+
scope: Record<string, string>;
|
|
1219
|
+
} | {
|
|
1220
|
+
kind: 'handle';
|
|
1221
|
+
paths: string[];
|
|
1222
|
+
} | {
|
|
1223
|
+
kind: 'service';
|
|
1224
|
+
member: string;
|
|
1225
|
+
scope: Record<string, string> | null;
|
|
1226
|
+
});
|
|
1227
|
+
/**
|
|
1228
|
+
* A CLI asks to be signed in from a browser (RFC 8628, `coffre login`).
|
|
1229
|
+
* The app draws both codes: the device code, which only the CLI holds and
|
|
1230
|
+
* the vault has by its SHA-256 (`code`, lowercase hex), and the user code
|
|
1231
|
+
* a person types in their browser (`USER_CODE` in @coffre/core/access).
|
|
1232
|
+
* `label` is what the CLI calls itself, as the person approving it sees
|
|
1233
|
+
* it. It waits 10 minutes for a decision (`DEVICE_TTL_SECONDS`).
|
|
1234
|
+
*
|
|
1235
|
+
* Refused `taken` when a row holds either code already, expired or not:
|
|
1236
|
+
* the app draws again. Before the vault has adopted the database,
|
|
1237
|
+
* `adopting`; with an instance's row that is not the vault's, `tampered`.
|
|
1238
|
+
* How many wait at once is the app's to cap, before it asks.
|
|
1239
|
+
*/
|
|
1240
|
+
type DeviceStart = {
|
|
1241
|
+
op: 'device.start';
|
|
1242
|
+
code: string;
|
|
1243
|
+
userCode: string;
|
|
1244
|
+
label: string | null;
|
|
1245
|
+
};
|
|
1246
|
+
/**
|
|
1247
|
+
* A person, on a session of theirs, approves or denies a device login by
|
|
1248
|
+
* the user code it shows (`device.approve`, `device.deny`): approved, the
|
|
1249
|
+
* CLI that holds its device code collects a session of theirs. One that is
|
|
1250
|
+
* not there, decided, or past its 10 minutes is refused `unknown_code`;
|
|
1251
|
+
* a token, a service account's or a person's, `no_access`.
|
|
1252
|
+
*/
|
|
1253
|
+
type DeviceDecide = {
|
|
1254
|
+
op: 'device.decide';
|
|
1255
|
+
userCode: string;
|
|
1256
|
+
approve: boolean;
|
|
1257
|
+
};
|
|
1258
|
+
/**
|
|
1259
|
+
* The CLI collects its session, by its device code's SHA-256 (`code`): once
|
|
1260
|
+
* a person approved its device login, within its 10 minutes, and once. The
|
|
1261
|
+
* session is the approver's, of the generation they approved it in, for
|
|
1262
|
+
* `minutes` (365 days at most), labelled as the CLI called itself.
|
|
1263
|
+
*
|
|
1264
|
+
* The CLI polls until then. Refused, writing nothing (RFC 8628's errors):
|
|
1265
|
+
* `pending` while nobody has decided; `denied` once someone denied it, or
|
|
1266
|
+
* when its approver is no longer an active member of the generation they
|
|
1267
|
+
* approved it in; `expired` for one that is past its 10 minutes, collected
|
|
1268
|
+
* already, or not there. `adopting` and `tampered` as for a sign-in, and
|
|
1269
|
+
* `tampered` for a device login or its approver written behind the vault.
|
|
1270
|
+
*/
|
|
1271
|
+
type DeviceRedeem = {
|
|
1272
|
+
op: 'device.redeem';
|
|
1273
|
+
code: string;
|
|
1274
|
+
session: {
|
|
1275
|
+
token: string;
|
|
1276
|
+
minutes: number;
|
|
1277
|
+
};
|
|
1278
|
+
};
|
|
1279
|
+
//#endregion
|
|
1280
|
+
//#region src/changes/workloads.d.ts
|
|
1281
|
+
/**
|
|
1282
|
+
* The changes of workloads signing in (`packages/vault/src/ops/workloads.ts`,
|
|
1283
|
+
* docs/design/0.16.md, "A workload signing in").
|
|
1284
|
+
*/
|
|
1285
|
+
type WorkloadChanges = TokenExchange | WorkloadSignin | WorkloadRenew | TokenBind | TokenUnbind;
|
|
1286
|
+
type WorkloadAnswers = {
|
|
1287
|
+
'token.exchange': Exchanged;
|
|
1288
|
+
'workload.signin': Session;
|
|
1289
|
+
'workload.renew': Renewed;
|
|
1290
|
+
'token.bind': Bound;
|
|
1291
|
+
'token.unbind': {
|
|
1292
|
+
binding: string;
|
|
1293
|
+
};
|
|
1294
|
+
};
|
|
1295
|
+
/** The workloads' changes nobody asks: a CI run, or a workload signing in, has no credential yet, only its platform's proof. */
|
|
1296
|
+
type WorkloadsUnasked = 'token.exchange' | 'workload.signin';
|
|
1297
|
+
/**
|
|
1298
|
+
* A CI run trades its platform's ID token for a service token of five
|
|
1299
|
+
* minutes, issued by the oldest of the service's bindings with no policy
|
|
1300
|
+
* that takes it.
|
|
1301
|
+
*
|
|
1302
|
+
* - `token` is the ID token itself, which the vault reads its claims
|
|
1303
|
+
* from: the app verified its signature under `under`, the issuer and
|
|
1304
|
+
* the address of its keys, and the vault takes that on its word. For a
|
|
1305
|
+
* binding that carries its keys, `under.jwksUri` is theirs,
|
|
1306
|
+
* `sha256:<hex>`, and the vault verifies the signature itself, under the
|
|
1307
|
+
* keys on its own row.
|
|
1308
|
+
* - `publicUrl` is the app's own, which a CI run's token names as its
|
|
1309
|
+
* audience.
|
|
1310
|
+
* - `credential` is the SHA-256 of the token the app drew, lowercase hex.
|
|
1311
|
+
*
|
|
1312
|
+
* Refused (docs/design/0.16.md, "A refusal"): `no_match`, `audience`,
|
|
1313
|
+
* `expired`, `too_old`, `malformed`, `replayed`, `unknown_signer`, and
|
|
1314
|
+
* `tampered` for a binding or the service's row written behind the vault.
|
|
1315
|
+
* A refusal writes nothing and is not logged.
|
|
1316
|
+
*/
|
|
1317
|
+
type TokenExchange = {
|
|
1318
|
+
op: 'token.exchange';
|
|
1319
|
+
service: string;
|
|
1320
|
+
token: string;
|
|
1321
|
+
under: VerifiedUnder;
|
|
1322
|
+
publicUrl: string;
|
|
1323
|
+
credential: string;
|
|
1324
|
+
};
|
|
1325
|
+
/** The token made, and the binding that issued it, by which the app counts a binding's rate. */
|
|
1326
|
+
type Exchanged = Issued & {
|
|
1327
|
+
binding: string;
|
|
1328
|
+
};
|
|
1329
|
+
/**
|
|
1330
|
+
* A workload's proof, by its kind: a platform's ID token, with the keys the
|
|
1331
|
+
* app verified it under (`token.exchange`'s `token` and `under`), or STS's
|
|
1332
|
+
* answer to the `GetCallerIdentity` request the workload signed, which the
|
|
1333
|
+
* app checked whole and sent.
|
|
1334
|
+
*/
|
|
1335
|
+
type WorkloadProof = {
|
|
1336
|
+
oidc: {
|
|
1337
|
+
token: string;
|
|
1338
|
+
under: VerifiedUnder;
|
|
1339
|
+
};
|
|
1340
|
+
} | {
|
|
1341
|
+
aws: CallerIdentity;
|
|
1342
|
+
};
|
|
1343
|
+
/**
|
|
1344
|
+
* A workload trades its proof for a session bound to a key it holds,
|
|
1345
|
+
* issued by the oldest of the service's bindings with a policy, of that
|
|
1346
|
+
* proof's profiles, that takes it.
|
|
1347
|
+
*
|
|
1348
|
+
* - `key` is the thumbprint of the key the request's own proof (RFC 9449)
|
|
1349
|
+
* named, which the app held to the request: the session is that key's
|
|
1350
|
+
* alone, and a token whose audience names a key names this one.
|
|
1351
|
+
* - `publicUrl` and `credential` as for `token.exchange`.
|
|
1352
|
+
*
|
|
1353
|
+
* Refused as `token.exchange` is, and `frozen` for a service, a binding or
|
|
1354
|
+
* every workload a manager froze, as 0.14 refused it. A binding whose
|
|
1355
|
+
* sources the request comes from outside, or that lists reads where the
|
|
1356
|
+
* deployment lets none (`noReads`), is `no_match`. A refusal writes nothing
|
|
1357
|
+
* and is not logged.
|
|
1358
|
+
*/
|
|
1359
|
+
type WorkloadSignin = {
|
|
1360
|
+
op: 'workload.signin';
|
|
1361
|
+
service: string;
|
|
1362
|
+
proof: WorkloadProof;
|
|
1363
|
+
key: string;
|
|
1364
|
+
publicUrl: string;
|
|
1365
|
+
credential: string;
|
|
1366
|
+
};
|
|
1367
|
+
/**
|
|
1368
|
+
* The session made: its token's expiry, an hour on or its hard end, and
|
|
1369
|
+
* that hard end; the environments it reaches as of now, by id, as its row
|
|
1370
|
+
* lists them, which the app names by path; and the binding that issued it,
|
|
1371
|
+
* by which the app counts a binding's rate.
|
|
1372
|
+
*/
|
|
1373
|
+
type Session = Issued & {
|
|
1374
|
+
binding: string;
|
|
1375
|
+
notAfter: string;
|
|
1376
|
+
places: string[];
|
|
1377
|
+
};
|
|
1378
|
+
/**
|
|
1379
|
+
* A workload's session moves its own expiry on, by its key's proof: an
|
|
1380
|
+
* hour from now, never past its hard end. A frozen session renews, so that
|
|
1381
|
+
* lifting the freeze restores it; one stopped for any other reason, or
|
|
1382
|
+
* narrowed from another, does not. Refused `expired` within five seconds of
|
|
1383
|
+
* its expiry, so that a renewal that comes late revives nothing.
|
|
1384
|
+
*/
|
|
1385
|
+
type WorkloadRenew = {
|
|
1386
|
+
op: 'workload.renew';
|
|
1387
|
+
};
|
|
1388
|
+
/** The session's expiry, moved on, or as it was at its hard end. */
|
|
1389
|
+
type Renewed = {
|
|
1390
|
+
expiresAt: string;
|
|
1391
|
+
};
|
|
1392
|
+
/**
|
|
1393
|
+
* A binding to make, as 0.14's `POST /members/:m/bindings` took it, and
|
|
1394
|
+
* checked as it did (`checkBinding`, `checkPolicy`, the profile's rule):
|
|
1395
|
+
*
|
|
1396
|
+
* - `keys`: where its issuer's keys are, the address the app's discovery
|
|
1397
|
+
* found (a URN profile's, its issuer), which the vault takes on the
|
|
1398
|
+
* app's word and seals; or the keys themselves, uploaded, a JWKS the
|
|
1399
|
+
* vault checks and keeps (`uploadedKeys`).
|
|
1400
|
+
* - `policy`: a workload's binding's, null for one a CI run's exchange
|
|
1401
|
+
* takes (a bearer profile's; under `useOnly`, every binding is a
|
|
1402
|
+
* workload's). Its `reads` name each environment by path, and its keys
|
|
1403
|
+
* by name or `"*"`, which the vault finds and seals by id.
|
|
1404
|
+
* - `scope`: what its credentials reach, by path, as a service token's
|
|
1405
|
+
* (`token.create`); null for what the bindings it replaces reached, of
|
|
1406
|
+
* what the service still holds, or else all the service holds.
|
|
1407
|
+
* - `replaces`: the live bindings it takes the place of, by id. Those of
|
|
1408
|
+
* its issuer whose keys are elsewhere go too (`keys_moved`).
|
|
1409
|
+
* - `only`: true when `replaces` is all it may end, as an approval page
|
|
1410
|
+
* listed them: one of its issuer's whose keys are elsewhere and that it
|
|
1411
|
+
* does not name refuses `stale`, and nothing is made.
|
|
1412
|
+
*/
|
|
1413
|
+
type NewBinding = {
|
|
1414
|
+
profile: string;
|
|
1415
|
+
issuer: string | null;
|
|
1416
|
+
claims: Record<string, unknown>;
|
|
1417
|
+
keys: {
|
|
1418
|
+
uri: string;
|
|
1419
|
+
} | {
|
|
1420
|
+
jwks: unknown;
|
|
1421
|
+
};
|
|
1422
|
+
policy: Record<string, unknown> | null;
|
|
1423
|
+
scope: Record<string, string> | null;
|
|
1424
|
+
label: string | null;
|
|
1425
|
+
replaces: string[];
|
|
1426
|
+
only?: boolean;
|
|
1427
|
+
};
|
|
1428
|
+
/**
|
|
1429
|
+
* Trust a workload as a service (`binding`), or give its bindings on an
|
|
1430
|
+
* issuer new keys, uploaded (`keys`): each is replaced by one the same but
|
|
1431
|
+
* for its keys, reaching what it did of what the service still holds.
|
|
1432
|
+
* Whoever manages the service (`managesService`), each grant of the scope
|
|
1433
|
+
* one they could give it and it holds (`issuesCredential`); its sensitive
|
|
1434
|
+
* values only where an Owner of the project binds it (`ownsProject`). A
|
|
1435
|
+
* binding is never edited: a replaced one is revoked, and the credentials
|
|
1436
|
+
* it issued end with it.
|
|
1437
|
+
*
|
|
1438
|
+
* Refused: `unauthenticated` and a stopped caller's words; `no_access`,
|
|
1439
|
+
* for one who does not manage the service, or a place not found or beyond
|
|
1440
|
+
* them; `unknown_principal`, a service that is not active; `tampered`, any
|
|
1441
|
+
* row read that is not the vault's; `invalid`, a role that is none there, a
|
|
1442
|
+
* read outside the scope or of a key the environment does not hold, a
|
|
1443
|
+
* policy its reads break, uploaded keys that are no JWKS, or replaced
|
|
1444
|
+
* bindings that reach nothing the service still holds or a place with two
|
|
1445
|
+
* roles; `no_grants`, a scope with nothing to reach; `not_owner_issued`, a
|
|
1446
|
+
* sensitive key read where no Owner of its project binds; `no_reads`, reads
|
|
1447
|
+
* where the deployment lets none; `unknown_binding`, a binding replaced
|
|
1448
|
+
* that is not live, or no binding on the issuer whose keys are replaced;
|
|
1449
|
+
* `keys_differ`, other bindings on the issuer whose keys are elsewhere,
|
|
1450
|
+
* uploaded on one side; `same_keys`, keys the bindings carry already;
|
|
1451
|
+
* `too_many_bindings`, past `MAX_BINDINGS` live.
|
|
1452
|
+
*/
|
|
1453
|
+
type TokenBind = {
|
|
1454
|
+
op: 'token.bind';
|
|
1455
|
+
member: string;
|
|
1456
|
+
} & ({
|
|
1457
|
+
binding: NewBinding;
|
|
1458
|
+
} | {
|
|
1459
|
+
keys: {
|
|
1460
|
+
issuer: string;
|
|
1461
|
+
jwks: unknown;
|
|
1462
|
+
};
|
|
1463
|
+
});
|
|
1464
|
+
/**
|
|
1465
|
+
* The bindings made, each with what it reaches by path and role and the
|
|
1466
|
+
* places of those whose sensitive values it will not read (`withheld`:
|
|
1467
|
+
* each holds one of a project no Owner of which binds it, R32), and the
|
|
1468
|
+
* bindings revoked, by id.
|
|
1469
|
+
*/
|
|
1470
|
+
type Bound = {
|
|
1471
|
+
bindings: {
|
|
1472
|
+
id: string;
|
|
1473
|
+
scope: Record<string, string>;
|
|
1474
|
+
withheld: string[];
|
|
1475
|
+
}[];
|
|
1476
|
+
replaced: string[];
|
|
1477
|
+
};
|
|
1478
|
+
/**
|
|
1479
|
+
* Remove a binding: whoever manages its service. Its row is revoked, and
|
|
1480
|
+
* the credentials it issued end with it. Refused `unknown_binding` for
|
|
1481
|
+
* one that is not a live binding of the service, and as `token.bind` is.
|
|
1482
|
+
*/
|
|
1483
|
+
type TokenUnbind = {
|
|
1484
|
+
op: 'token.unbind';
|
|
1485
|
+
member: string;
|
|
1486
|
+
binding: string;
|
|
1487
|
+
};
|
|
1488
|
+
//#endregion
|
|
2
1489
|
//#region src/access-fault.d.ts
|
|
3
1490
|
/**
|
|
4
1491
|
* Why the vault's members and grants do not follow from its log, as facts
|
|
@@ -62,1133 +1549,310 @@ type FaultNames = {
|
|
|
62
1549
|
};
|
|
63
1550
|
/** The fault in a sentence, with whatever names the caller can give. */
|
|
64
1551
|
export declare function describeAccessFault(fault: AccessFault, names?: FaultNames): string;
|
|
65
|
-
//#endregion
|
|
66
|
-
//#region src/
|
|
67
|
-
/**
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
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
|
|
183
|
-
//#region src/vault.d.ts
|
|
184
|
-
/**
|
|
185
|
-
* The vault as the app sees it: the contract between `@coffre/server` and
|
|
186
|
-
* `@coffre/vault`, kept in core so that neither side owns it. Every argument
|
|
187
|
-
* and result is plain JSON: strings, numbers, booleans, arrays and objects,
|
|
188
|
-
* never a Buffer, a Date, a class or a function. So it crosses a Workers RPC
|
|
189
|
-
* boundary, or a process boundary later, as it is, and the in-process
|
|
190
|
-
* transport proves it by round-tripping everything through JSON.
|
|
191
|
-
*
|
|
192
|
-
* The app says who is asking and the vault decides. The app never holds a
|
|
193
|
-
* key: it encrypts a value under a fresh data key, has the vault wrap that
|
|
194
|
-
* key, and stores the result; to read, it names stored versions and the
|
|
195
|
-
* vault loads their keys itself.
|
|
196
|
-
*
|
|
197
|
-
* Decisions come back as values: `{ ok: false, refusal }` for a refusal, which
|
|
198
|
-
* the vault has already logged. Only a fault (a bug, the store down) throws.
|
|
199
|
-
*/
|
|
200
|
-
export interface Vault {
|
|
201
|
-
/**
|
|
202
|
-
* Unwrap data keys for `principal`: all of them, or none. Given the
|
|
203
|
-
* revision of an answer of `access` the app decided the read on
|
|
204
|
-
* (`accessRevision`), only while the principal's access is still that
|
|
205
|
-
* one, under their row and the head the decision holds: otherwise it
|
|
206
|
-
* refuses `access_changed` and logs no read, and says, by naming it back,
|
|
207
|
-
* that it checked. A vault older than 0.14.1 names none: it checked none.
|
|
208
|
-
*/
|
|
209
|
-
unwrap(input: UnwrapInput): Promise<Outcome<Unwrapped>>;
|
|
210
|
-
/**
|
|
211
|
-
* Wrap fresh data keys for new versions `principal` writes: all, or none.
|
|
212
|
-
* `seqs` are the `key.wrap` entries, one per key, which the app's
|
|
213
|
-
* `secret.write` entries name as related. `sensitive` says, per key,
|
|
214
|
-
* whether its wrap binds it as sensitive: a vault older than 0.10 answers
|
|
215
|
-
* none, binding none, and the app stores no sensitive version it wrapped.
|
|
216
|
-
*/
|
|
217
|
-
wrap(input: WrapInput): Promise<Outcome<Wrapped>>;
|
|
218
|
-
/**
|
|
219
|
-
* Wrap existing data keys again for new versions of the same secrets,
|
|
220
|
-
* under the current key: restoring an old value, or making one stricter.
|
|
221
|
-
* It needs a write grant, not a read one, since the key never leaves the
|
|
222
|
-
* vault. A new version is never less sensitive than the one it is made
|
|
223
|
-
* from, or than its secret's newest: a value is made looser only by
|
|
224
|
-
* being written again (`invalid`). Except one: a key's current sensitive
|
|
225
|
-
* value made a secret, in place, by an Owner of its project, or of the
|
|
226
|
-
* whole instance, on no credential's scope (`ownsProject`; `not_allowed`
|
|
227
|
-
* for anyone else), its entry saying `was: 'sensitive'`.
|
|
228
|
-
*/
|
|
229
|
-
rewrap(input: RewrapInput): Promise<Outcome<Wrapped>>;
|
|
230
|
-
/**
|
|
231
|
-
* Make secrets references to others: whoever can read the holder's
|
|
232
|
-
* environment reads the source through it (docs/design/environments.md).
|
|
233
|
-
* The vault checks that `principal` reads each source and writes each
|
|
234
|
-
* holder, by their own grants, and logs a `reference.create` per item:
|
|
235
|
-
* that entry, under the vault's MAC, is the reference. `seqs` are the
|
|
236
|
-
* entries, which the app stores beside each reference and names when it
|
|
237
|
-
* reads through one (`UnwrapInput`'s `via`). All, or none.
|
|
238
|
-
*/
|
|
239
|
-
reference(input: ReferenceInput): Promise<Outcome<{
|
|
240
|
-
seqs: number[];
|
|
241
|
-
}>>;
|
|
242
|
-
/**
|
|
243
|
-
* End references, each with a `reference.end` naming its creation:
|
|
244
|
-
* `replaced` when the holder gets a value of its own, which takes write on
|
|
245
|
-
* the holder; `broken` otherwise, which takes write on the holder, or
|
|
246
|
-
* managing the source's project's access. An ended reference reads no
|
|
247
|
-
* more, whatever any row says. All, or none.
|
|
248
|
-
*/
|
|
249
|
-
endReferences(input: EndReferencesInput): Promise<Outcome<{
|
|
250
|
-
seqs: number[];
|
|
251
|
-
}>>;
|
|
252
|
-
/**
|
|
253
|
-
* What one principal holds right now: the app asks once per request,
|
|
254
|
-
* unless the request reads values on an answer it kept (`accessRevision`),
|
|
255
|
-
* and at sign-in for each verified email. A decision, its rows checked:
|
|
256
|
-
* lists of who holds what read the rows themselves, and need not ask.
|
|
257
|
-
* A person the vault's `owners` names who is no Owner of all of it
|
|
258
|
-
* becomes one here, logged (`reason: 'owners'`).
|
|
259
|
-
*/
|
|
260
|
-
access(principal: string): Promise<Access>;
|
|
261
|
-
/**
|
|
262
|
-
* Set roles at several places for one principal: all of it, or none.
|
|
263
|
-
* With `admit`, a service account that is not a member is admitted
|
|
264
|
-
* first, in the same decision, as `admit` would: `admitted` says so.
|
|
265
|
-
*/
|
|
266
|
-
setAccess(input: SetAccessInput): Promise<Outcome<{
|
|
267
|
-
changes: AccessChange[];
|
|
268
|
-
admitted?: Admitted;
|
|
269
|
-
}>>;
|
|
270
|
-
/**
|
|
271
|
-
* Add a member, bring back a removed one, or change a person's instance
|
|
272
|
-
* role and its scope. `generation` is theirs now: sessions and tokens of
|
|
273
|
-
* an earlier one are dead.
|
|
274
|
-
*/
|
|
275
|
-
admit(input: AdmitInput): Promise<Outcome<Admitted>>;
|
|
276
|
-
/**
|
|
277
|
-
* Remove a member: revoke every grant and refuse them until admitted
|
|
278
|
-
* again, from `generation` on. An Owner, only an Owner of the whole
|
|
279
|
-
* instance removes, and never the last.
|
|
280
|
-
*/
|
|
281
|
-
remove(input: RemoveInput): Promise<Outcome<{
|
|
282
|
-
revoked: Grant[];
|
|
283
|
-
generation: number;
|
|
284
|
-
}>>;
|
|
285
|
-
/**
|
|
286
|
-
* The instance's settings, as the vault's newest `settings.change` entry
|
|
287
|
-
* says, by its MAC: an entry is where they live, so each change is logged
|
|
288
|
-
* by being made. Everywhere, until someone narrows it.
|
|
289
|
-
*/
|
|
290
|
-
settings(): Promise<Settings>;
|
|
291
|
-
/** Change the instance's settings: those who run it, never anyone else. */
|
|
292
|
-
setSettings(input: SetSettingsInput): Promise<Outcome<{
|
|
293
|
-
settings: Settings;
|
|
294
|
-
}>>;
|
|
295
|
-
/**
|
|
296
|
-
* The instance's access policy (`Policy` in @coffre/core/access): its
|
|
297
|
-
* roles, as an Owner edited and made them, and its protected
|
|
298
|
-
* environments, as the vault's newest `policy.change` says, by its MAC.
|
|
299
|
-
* As it ships, before any. A vault older than 0.10 has none, and the app
|
|
300
|
-
* decides as it ships.
|
|
301
|
-
*/
|
|
302
|
-
policy(): Promise<Policy>;
|
|
303
|
-
/**
|
|
304
|
-
* Change the policy by one change, its own `policy.change` entry, which
|
|
305
|
-
* names it and what it was (docs/design/roles.md):
|
|
306
|
-
* - a project or instance role defined, or put back as it ships (null),
|
|
307
|
-
* or, one an Owner made, deleted while no grant names it: an Owner of
|
|
308
|
-
* the whole instance, and never the Owner role, nor the instance's
|
|
309
|
-
* Member;
|
|
310
|
-
* - environments of one project protected, by whoever manages its
|
|
311
|
-
* environments, before their rows exist too (a fork's); or
|
|
312
|
-
* unprotected, by an Owner of the project or of the whole instance
|
|
313
|
-
* (`ownsProject`), as far as that project protected them.
|
|
314
|
-
* The policy after it, and the newest `policy.change`, which it is as of:
|
|
315
|
-
* the change's own, when it changed anything.
|
|
316
|
-
*/
|
|
317
|
-
changePolicy(input: ChangePolicyInput): Promise<Outcome<{
|
|
318
|
-
policy: Policy;
|
|
319
|
-
seq: number | null;
|
|
320
|
-
}>>;
|
|
321
|
-
/**
|
|
322
|
-
* Sign the log up to its last entry, in an `audit.checkpoint` entry of
|
|
323
|
-
* the vault's, if the chain recomputes from the last checkpoint, the
|
|
324
|
-
* vault's entries by their MACs, and that checkpoint's prefix is still
|
|
325
|
-
* there, whole. The entry keeps the checkpoint's tally beside it: what a
|
|
326
|
-
* walk from the first entry has gathered by the prefix's end (the
|
|
327
|
-
* vault's keys, its key batches under way, who is a member and what they
|
|
328
|
-
* hold), so that the next checkpoint, and every verification, go on from
|
|
329
|
-
* there and read only what is new. A log longer than one walk, as after
|
|
330
|
-
* an upgrade from 0.10.0, is signed a stretch a call, behind its head,
|
|
331
|
-
* until the checkpoints catch up. Each call also rehashes a stretch of
|
|
332
|
-
* what was signed before, round and round, which an entry edited in place
|
|
333
|
-
* fails: then it refuses, and every verification reports the refusal.
|
|
334
|
-
* A rehash the database fails moves on next time, and `warning` says so;
|
|
335
|
-
* a refusal it would have cleared stands meanwhile. The vault reads the log itself: it takes nobody's word for where
|
|
336
|
-
* it ends, or for what came before. It checks every member's row too, as
|
|
337
|
-
* `access` would, and logs a `vault.tampered` for each one changed around
|
|
338
|
-
* it: lists read rows without asking the vault.
|
|
339
|
-
*/
|
|
340
|
-
checkpoint(): Promise<Outcome<{
|
|
341
|
-
checkpoint: Checkpoint;
|
|
342
|
-
warning?: string;
|
|
343
|
-
}>>;
|
|
344
|
-
/**
|
|
345
|
-
* What the vault's configuration says, which the app shows: the keys its
|
|
346
|
-
* checkpoints verify under, by the key id each checkpoint names (the one
|
|
347
|
-
* it signs with now, and those of the KEKs it replaced).
|
|
348
|
-
*/
|
|
349
|
-
about(): Promise<{
|
|
350
|
-
checkpointKeys: Record<string, CheckpointKey>;
|
|
351
|
-
/**
|
|
352
|
-
* The emails of those the deployment names Owners of the whole instance
|
|
353
|
-
* (`owners`), lowercased: the vault makes them Owners, and refuses to
|
|
354
|
-
* demote or remove them. Absent from a vault of 0.5, which names none.
|
|
355
|
-
*/
|
|
356
|
-
owners?: string[];
|
|
357
|
-
/**
|
|
358
|
-
* @deprecated Always empty: an app of 0.5, deployed after this vault,
|
|
359
|
-
* lists and checks root admins here until it is. Gone in 0.7.
|
|
360
|
-
*/
|
|
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;
|
|
395
|
-
}>;
|
|
396
|
-
/**
|
|
397
|
-
* What an escrowed vault key is checked against: the vault key it wraps
|
|
398
|
-
* under now, and each one's check, as the vault wrote it. None of it is
|
|
399
|
-
* secret, and the vault answers no guess: a check opens only under its key.
|
|
400
|
-
*/
|
|
401
|
-
keyChecks(): Promise<KeyChecks>;
|
|
402
|
-
/**
|
|
403
|
-
* Check the log from a checkpoint's tally, the newest unless `from`
|
|
404
|
-
* names another, or the first entry: the vault's entries since by their
|
|
405
|
-
* MACs, every checkpoint among them against the prefix it signed, the key
|
|
406
|
-
* batches accounted for, and the members and grants replayed on from the
|
|
407
|
-
* tally to see that the rows follow. With `to`, a later checkpoint, the
|
|
408
|
-
* walk stops at the prefix it signed and must come to the tally it keeps:
|
|
409
|
-
* a stretch of the whole log, walked from the first entry a stretch at a
|
|
410
|
-
* time. The links and hashes of the chain are the caller's to recompute
|
|
411
|
-
* through `upTo`, as the app does first; with none, the vault recomputes
|
|
412
|
-
* them itself, no further than one walk. A verdict and nothing else, so
|
|
413
|
-
* anyone may ask; the app asks for those who read the whole log
|
|
414
|
-
* (`readsWholeLog`).
|
|
415
|
-
*/
|
|
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>;
|
|
1552
|
+
//#endregion
|
|
1553
|
+
//#region src/vault.d.ts
|
|
1554
|
+
/**
|
|
1555
|
+
* The vault as the app sees it (docs/design/0.16.md, "The contract"): the
|
|
1556
|
+
* contract between `@coffre/server` and `@coffre/vault`, kept in core so
|
|
1557
|
+
* that neither side owns it. Every argument and answer is plain JSON:
|
|
1558
|
+
* strings, numbers, booleans, arrays and objects, never a Buffer, a Date, a
|
|
1559
|
+
* class or a function. So it crosses a Workers RPC boundary, or a process
|
|
1560
|
+
* boundary, as it is, and the in-process transport proves it by
|
|
1561
|
+
* round-tripping everything through JSON.
|
|
1562
|
+
*
|
|
1563
|
+
* The app says what a request showed and the vault decides: it finds the
|
|
1564
|
+
* credential by its token, reads what it holds and opens the values
|
|
1565
|
+
* itself. The app holds no key, no ciphertext it can open and no grant it
|
|
1566
|
+
* decides on.
|
|
1567
|
+
*
|
|
1568
|
+
* A decision comes back as a value: `{ refused }` for a refusal, which
|
|
1569
|
+
* wrote nothing of what was asked. A refused use writes nothing at all; a
|
|
1570
|
+
* change refused to a caller who stands, one log entry that says so, once
|
|
1571
|
+
* a minute in each instance for that caller and what they asked. Only a
|
|
1572
|
+
* fault throws: a bug, or the database down.
|
|
1573
|
+
*/
|
|
1574
|
+
export interface Vault {
|
|
1575
|
+
/** Open values for whoever presented a token: a reveal, `coffre run`, an export, a proxied request, a signature. */
|
|
1576
|
+
use(input: UseInput): Promise<Used | Refused>;
|
|
508
1577
|
/**
|
|
509
|
-
*
|
|
510
|
-
*
|
|
511
|
-
*
|
|
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.
|
|
1578
|
+
* What `use` would give, as of now, without opening or writing anything:
|
|
1579
|
+
* each key's secret and version, or why it is refused. What a watch
|
|
1580
|
+
* compares before it reads (`GET …/version`).
|
|
518
1581
|
*/
|
|
519
|
-
|
|
1582
|
+
peek(input: UseInput): Promise<Peeked | Refused>;
|
|
520
1583
|
/**
|
|
521
|
-
*
|
|
522
|
-
*
|
|
523
|
-
*
|
|
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.
|
|
1584
|
+
* Who a request's credential is and all it holds, for the app to scope a
|
|
1585
|
+
* page's queries with. Nothing is opened or changed on the answer: a use
|
|
1586
|
+
* and a change read their caller themselves.
|
|
526
1587
|
*/
|
|
527
|
-
|
|
1588
|
+
caller(input: Presented & {
|
|
1589
|
+
head?: boolean;
|
|
1590
|
+
}): Promise<Called | Refused>;
|
|
528
1591
|
/**
|
|
529
|
-
*
|
|
530
|
-
*
|
|
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.
|
|
1592
|
+
* Make a change: one operation, named as its log entry's action is, with
|
|
1593
|
+
* its input. All of it, or none.
|
|
534
1594
|
*/
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
}
|
|
1595
|
+
change<O extends Change['op']>(input: Asked<O>): Promise<{
|
|
1596
|
+
answer: Answers[O];
|
|
1597
|
+
} | Refused>;
|
|
538
1598
|
/**
|
|
539
|
-
*
|
|
540
|
-
*
|
|
541
|
-
*
|
|
542
|
-
*
|
|
543
|
-
*
|
|
544
|
-
*
|
|
1599
|
+
* What `change` would answer, as of now, with nothing written: the same
|
|
1600
|
+
* read and the same decision, so a dry run (`?dryRun=1`) is no second
|
|
1601
|
+
* copy of a rule. The change made after reads and decides again, and
|
|
1602
|
+
* alone tells a version it opens that does not open (`unreadable`). One
|
|
1603
|
+
* refused is logged as the change refused is; one that would be made
|
|
1604
|
+
* leaves nothing. Only what a caller asks is weighed: a sign-in or an
|
|
1605
|
+
* exchange rests on a proof, which this would try without spending.
|
|
545
1606
|
*/
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
}>;
|
|
1607
|
+
weigh<O extends Exclude<Change['op'], Unasked | WorkloadsUnasked | McpUnasked>>(input: Asked<O>): Promise<{
|
|
1608
|
+
answer: Answers[O];
|
|
1609
|
+
} | Refused>;
|
|
549
1610
|
/**
|
|
550
|
-
*
|
|
551
|
-
*
|
|
552
|
-
*
|
|
553
|
-
*
|
|
1611
|
+
* The vault's configuration that is no secret: its vault keys and its
|
|
1612
|
+
* signing keys' checks. It asks no caller, reads nothing, writes no
|
|
1613
|
+
* entry and opens no connection: it answers what the vault was started
|
|
1614
|
+
* with, the same to anyone, so whoever may see it is the app's to say.
|
|
554
1615
|
*/
|
|
555
|
-
|
|
1616
|
+
about(): Promise<About>;
|
|
556
1617
|
}
|
|
557
|
-
/**
|
|
558
|
-
export type
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
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;
|
|
1618
|
+
/** Where a request came from, which every call carries. */
|
|
1619
|
+
export type Trace = {
|
|
1620
|
+
/** The app's id for the request, for the log. */
|
|
1621
|
+
request: string | null;
|
|
1622
|
+
/** The address it came from, for the log, and for a workload's binding that names its sources. */
|
|
1623
|
+
ip: string | null;
|
|
627
1624
|
};
|
|
628
1625
|
/**
|
|
629
|
-
*
|
|
630
|
-
*
|
|
631
|
-
*
|
|
632
|
-
* Numbers are decimal text: the log's are 64-bit.
|
|
1626
|
+
* What a request showed, which every call but a change nobody asks starts
|
|
1627
|
+
* with. The app never says who is asking: the vault finds the credential
|
|
1628
|
+
* by its token.
|
|
633
1629
|
*/
|
|
634
|
-
export type
|
|
635
|
-
|
|
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;
|
|
1630
|
+
export type Presented = Trace & {
|
|
1631
|
+
/** The SHA-256 of the token the request presented, in lowercase hex. */
|
|
1632
|
+
token: string;
|
|
661
1633
|
/**
|
|
662
|
-
*
|
|
663
|
-
*
|
|
664
|
-
*
|
|
1634
|
+
* The thumbprint of the key that signed the request's proof (RFC 9449),
|
|
1635
|
+
* once the app has held the proof to the request: a workload's session
|
|
1636
|
+
* is its key's alone. Null with no proof.
|
|
665
1637
|
*/
|
|
666
|
-
|
|
1638
|
+
proof: string | null;
|
|
667
1639
|
};
|
|
668
1640
|
/**
|
|
669
|
-
*
|
|
670
|
-
*
|
|
671
|
-
*
|
|
1641
|
+
* A change as the app sends it: its operation's input, with what the
|
|
1642
|
+
* request showed, or for one nobody asks (`Unasked`), where it came from
|
|
1643
|
+
* alone.
|
|
672
1644
|
*/
|
|
673
|
-
export type
|
|
674
|
-
|
|
675
|
-
|
|
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
|
-
};
|
|
1645
|
+
export type Asked<O extends Change['op']> = O extends Change['op'] ? (O extends Unasked | WorkloadsUnasked | McpUnasked ? Trace : Presented & ForConnection) & Extract<Change, {
|
|
1646
|
+
op: O;
|
|
1647
|
+
}> : never;
|
|
685
1648
|
/**
|
|
686
|
-
*
|
|
687
|
-
*
|
|
688
|
-
*
|
|
689
|
-
*
|
|
1649
|
+
* The approval a person makes a change for, on coffre's page
|
|
1650
|
+
* (docs/design/0.16.md, "An MCP client's changes"): the change is theirs,
|
|
1651
|
+
* made on their browser session, and its entry names the app that asked.
|
|
1652
|
+
* The vault reads the connection and the approval with the change's other
|
|
1653
|
+
* rows. The connection must stand, be of the caller's own member and
|
|
1654
|
+
* generation, and the caller be on a browser session, or the change is
|
|
1655
|
+
* refused `disconnected`. The approval must be the connection's, pending,
|
|
1656
|
+
* unexpired by the time the write starts, and of the `digest` the page
|
|
1657
|
+
* rendered, or it is refused `unknown_approval`. Made, the change marks the
|
|
1658
|
+
* approval approved in its own write: no approval is approved without its
|
|
1659
|
+
* change, nor a change made twice under one. It decides nothing else: what
|
|
1660
|
+
* the change may do is the person's.
|
|
690
1661
|
*/
|
|
691
|
-
export type
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
/**
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
kind: K;
|
|
711
|
-
id: string;
|
|
1662
|
+
export type ForConnection = {
|
|
1663
|
+
via?: {
|
|
1664
|
+
connection: string;
|
|
1665
|
+
approval: string;
|
|
1666
|
+
digest: string;
|
|
1667
|
+
};
|
|
1668
|
+
};
|
|
1669
|
+
export type UseInput = Presented & {
|
|
1670
|
+
/** The place, by its slugs. */
|
|
1671
|
+
project: string;
|
|
1672
|
+
environment: string;
|
|
1673
|
+
/** The caller's personal config of that environment, `@me`, where they have one. */
|
|
1674
|
+
mine: boolean;
|
|
1675
|
+
/** The keys asked for, by name, 1,000 at most: null is every key the environment has. */
|
|
1676
|
+
keys: string[] | null;
|
|
1677
|
+
/** `use`: the value is used for the caller, by the credential proxy, and never handed back. Any other hands it back. */
|
|
1678
|
+
purpose: Purpose;
|
|
1679
|
+
/** What the values are used for (`Upstream`): null for none. */
|
|
1680
|
+
upstream: Upstream | null;
|
|
712
1681
|
/**
|
|
713
|
-
*
|
|
714
|
-
*
|
|
715
|
-
*
|
|
1682
|
+
* Read the rows now, never from the vault's memory (`memorySeconds`): an
|
|
1683
|
+
* answer that must see a change just made (`coffre run`'s plan after the
|
|
1684
|
+
* values it generated were written). Any read may ask it; the rows read are
|
|
1685
|
+
* remembered all the same.
|
|
716
1686
|
*/
|
|
717
|
-
|
|
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;
|
|
1687
|
+
fresh?: boolean;
|
|
734
1688
|
};
|
|
735
1689
|
/**
|
|
736
|
-
*
|
|
737
|
-
*
|
|
738
|
-
*
|
|
739
|
-
*
|
|
740
|
-
*
|
|
1690
|
+
* The upstream credential a use is for, by its name in the deployment's
|
|
1691
|
+
* configuration (`stripe`), and where the proxy sends the values, which the
|
|
1692
|
+
* use's entry keeps on the app's word, as 0.14.7's app logged it: the host
|
|
1693
|
+
* (`api.stripe.com`, a presigned URL's), and `egress` when the request
|
|
1694
|
+
* leaves through the deployment's egress. Signing, verifying, a cipher and
|
|
1695
|
+
* a tunnel name no host: they send nothing anywhere, or the host is in the
|
|
1696
|
+
* value.
|
|
741
1697
|
*/
|
|
742
|
-
export type
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
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[];
|
|
1698
|
+
export type Upstream = {
|
|
1699
|
+
credential: string;
|
|
1700
|
+
host?: string;
|
|
1701
|
+
egress?: true;
|
|
768
1702
|
};
|
|
769
1703
|
/**
|
|
770
|
-
*
|
|
771
|
-
*
|
|
772
|
-
*
|
|
773
|
-
*
|
|
774
|
-
*
|
|
1704
|
+
* Why someone reads, which the log shows. `use`: the credential proxy
|
|
1705
|
+
* injects the value into a request and never hands it back. Every other
|
|
1706
|
+
* hands the value back: `reveal` of one key, `run` of an environment,
|
|
1707
|
+
* `compare` of a guess in a dry run, `expose` by the proxy to a person's
|
|
1708
|
+
* own app.
|
|
775
1709
|
*/
|
|
776
|
-
export
|
|
777
|
-
|
|
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
|
-
};
|
|
1710
|
+
export declare const PURPOSES: readonly ["reveal", "run", "compare", "expose", "use"];
|
|
1711
|
+
export type Purpose = (typeof PURPOSES)[number];
|
|
794
1712
|
/**
|
|
795
|
-
*
|
|
796
|
-
*
|
|
1713
|
+
* One key's value, or why this caller is not given it. `secret` is where the
|
|
1714
|
+
* value is held: a reference's source. `nature` is the one the value opened
|
|
1715
|
+
* under, which its encryption names (`contextOf`), so a row relabelled behind
|
|
1716
|
+
* the vault cannot turn a secret into a plain value: what the proxy leaves
|
|
1717
|
+
* unredacted when an upstream echoes it.
|
|
797
1718
|
*/
|
|
798
|
-
export type
|
|
799
|
-
|
|
1719
|
+
export type UsedValue = {
|
|
1720
|
+
key: string;
|
|
1721
|
+
secret: string;
|
|
1722
|
+
version: number;
|
|
1723
|
+
nature: Nature;
|
|
1724
|
+
value: string;
|
|
1725
|
+
} | {
|
|
1726
|
+
key: string;
|
|
1727
|
+
refused: string;
|
|
1728
|
+
};
|
|
1729
|
+
export type Used = {
|
|
800
1730
|
principal: string;
|
|
1731
|
+
/** The credential's id. */
|
|
1732
|
+
credential: string;
|
|
801
1733
|
/**
|
|
802
|
-
* The
|
|
803
|
-
*
|
|
804
|
-
*
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
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.
|
|
1734
|
+
* The credential's effective end, ISO 8601: the instant the vault starts
|
|
1735
|
+
* refusing it for age, the earliest of its own end, a workload session's
|
|
1736
|
+
* hard end (`notAfter`) and those of the sessions it was narrowed from.
|
|
1737
|
+
* Not `Called.credential.expiresAt`, its own row's end. A grant that ends
|
|
1738
|
+
* sooner, a revoke or a freeze does not move it: what a presigned URL
|
|
1739
|
+
* lasts no longer than, and may outlive those, as on 0.14.7.
|
|
839
1740
|
*/
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
1741
|
+
expiresAt: string;
|
|
1742
|
+
values: UsedValue[];
|
|
1743
|
+
/** 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. */
|
|
1744
|
+
workload: {
|
|
1745
|
+
binding: string;
|
|
1746
|
+
profile: string;
|
|
1747
|
+
policy: BindingPolicy;
|
|
1748
|
+
constraints: Constraints | null;
|
|
843
1749
|
} | 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
1750
|
};
|
|
847
1751
|
/**
|
|
848
|
-
*
|
|
849
|
-
*
|
|
850
|
-
*
|
|
851
|
-
* and
|
|
1752
|
+
* What a use would give: each key's secret, version and nature, or why it
|
|
1753
|
+
* is refused; nothing opened. The nature is the one its rows say, which the
|
|
1754
|
+
* use holds the value to: what `coffre run`'s plan picks the keys it asks
|
|
1755
|
+
* for by, and never what it places a value by, which is the use's.
|
|
1756
|
+
*
|
|
1757
|
+
* For what `coffre run` generates in a personal config, of a key the caller
|
|
1758
|
+
* is given and no other: `versionId`, the version's id, which a write's
|
|
1759
|
+
* `replaces` names (a listing's `versionId`); `recipe`, what made it, null
|
|
1760
|
+
* for a value typed or a reference; `own`, held in the caller's personal
|
|
1761
|
+
* config, not inherited. `personal`: the read found the caller's personal
|
|
1762
|
+
* config of the environment (`@me`), not the environment itself.
|
|
852
1763
|
*/
|
|
853
|
-
export type
|
|
854
|
-
id: string;
|
|
1764
|
+
export type Peeked = {
|
|
855
1765
|
principal: string;
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
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;
|
|
1766
|
+
/** The credential's id. */
|
|
1767
|
+
credential: string;
|
|
1768
|
+
personal: boolean;
|
|
1769
|
+
items: ({
|
|
921
1770
|
key: string;
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
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;
|
|
1771
|
+
secret: string;
|
|
1772
|
+
version: number;
|
|
1773
|
+
nature: Nature;
|
|
1774
|
+
versionId: string;
|
|
1775
|
+
recipe: string | null;
|
|
1776
|
+
own: boolean;
|
|
1777
|
+
} | {
|
|
1778
|
+
key: string;
|
|
1779
|
+
refused: string;
|
|
1780
|
+
})[];
|
|
953
1781
|
};
|
|
954
1782
|
/**
|
|
955
|
-
*
|
|
956
|
-
*
|
|
957
|
-
*
|
|
1783
|
+
* Who a request is: its principal, `user:<email>` or `token:<name>`, the
|
|
1784
|
+
* credential it came in on, and what it holds, as `allows` in
|
|
1785
|
+
* `@coffre/core/access` decides on it: its role in the instance and that
|
|
1786
|
+
* role's scope, its live grants, a token's own scope, the definitions of
|
|
1787
|
+
* the roles it holds and of no other (a role absent from `policy` is one
|
|
1788
|
+
* the caller does not hold, not one that grants nothing to anyone), and
|
|
1789
|
+
* every environment the instance protects.
|
|
958
1790
|
*/
|
|
959
|
-
export type
|
|
1791
|
+
export type Called = {
|
|
1792
|
+
principal: string;
|
|
960
1793
|
/**
|
|
961
|
-
*
|
|
962
|
-
*
|
|
963
|
-
*
|
|
964
|
-
*
|
|
1794
|
+
* `expiresAt` is ISO 8601, the row's own end: a use's `Used.expiresAt`
|
|
1795
|
+
* is the effective one, which a session's hard end and the rows above it
|
|
1796
|
+
* may bring sooner. An MCP connection's access token (kind `mcp`)
|
|
1797
|
+
* says which connection it is under and the scopes it holds, from its
|
|
1798
|
+
* row; no other credential has either. `label` is the one it was made
|
|
1799
|
+
* with: a personal token's, which `GET /me` names it by.
|
|
965
1800
|
*/
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
1801
|
+
credential: {
|
|
1802
|
+
id: string;
|
|
1803
|
+
kind: string;
|
|
1804
|
+
expiresAt: string;
|
|
1805
|
+
label: string | null;
|
|
1806
|
+
connection?: string;
|
|
1807
|
+
scopes?: McpScope[];
|
|
1808
|
+
};
|
|
1809
|
+
holds: Holdings & {
|
|
1810
|
+
policy: Policy;
|
|
969
1811
|
};
|
|
970
1812
|
/**
|
|
971
|
-
*
|
|
972
|
-
* read
|
|
973
|
-
*
|
|
974
|
-
*
|
|
975
|
-
* from the binding, so its row holds none to seal.
|
|
1813
|
+
* For a call that asked (`head`): the log's head as the vault last signed
|
|
1814
|
+
* it, read with the caller's rows and held to the vault's MAC; null when
|
|
1815
|
+
* no head stands under it. The audit page proves each entry it shows
|
|
1816
|
+
* against these roots; one past these sizes is proven by nothing here.
|
|
976
1817
|
*/
|
|
977
|
-
|
|
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
|
-
}[];
|
|
1818
|
+
head?: SignedHead | null;
|
|
988
1819
|
};
|
|
989
1820
|
/**
|
|
990
|
-
* The
|
|
991
|
-
*
|
|
992
|
-
*
|
|
993
|
-
*
|
|
1821
|
+
* The log's signed head: how many entries are numbered (`size`), and each
|
|
1822
|
+
* tree's size and root, hex (the changes kept for good, and the uses that
|
|
1823
|
+
* age out, of which `agingFrom` is the first still there). `signedAt` is
|
|
1824
|
+
* ISO 8601. It says the vault signed this log, not that none is newer: the
|
|
1825
|
+
* signer holds the log's end to its own copy every minute, and walks the
|
|
1826
|
+
* rest within a day.
|
|
994
1827
|
*/
|
|
995
|
-
export type
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
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;
|
|
1828
|
+
export type SignedHead = {
|
|
1829
|
+
size: number;
|
|
1830
|
+
keptSize: number;
|
|
1831
|
+
keptRoot: string;
|
|
1832
|
+
agingSize: number;
|
|
1833
|
+
agingRoot: string;
|
|
1834
|
+
agingFrom: number;
|
|
1835
|
+
signedAt: string;
|
|
1015
1836
|
};
|
|
1016
|
-
/**
|
|
1017
|
-
export type
|
|
1018
|
-
|
|
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;
|
|
1837
|
+
/** Why a call is not answered. Nothing it asked was written. */
|
|
1838
|
+
export type Refused = {
|
|
1839
|
+
refused: string;
|
|
1029
1840
|
};
|
|
1030
1841
|
/**
|
|
1031
|
-
*
|
|
1032
|
-
*
|
|
1033
|
-
*
|
|
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`).
|
|
1842
|
+
* Every change the vault makes: its operation, and what that one takes.
|
|
1843
|
+
* Each area's are in a file of its own (`changes/`), with what each
|
|
1844
|
+
* answers once it is made.
|
|
1043
1845
|
*/
|
|
1044
|
-
export type
|
|
1045
|
-
|
|
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
|
-
};
|
|
1846
|
+
export type Change = SecretsChanges | PlacesChanges | AccessChanges | SigninChanges | WorkloadChanges | FreezeChanges | McpChanges;
|
|
1847
|
+
export type Answers = SecretsAnswers & PlacesAnswers & AccessAnswers & SigninAnswers & WorkloadAnswers & FreezeAnswers & McpAnswers;
|
|
1178
1848
|
/**
|
|
1179
|
-
*
|
|
1180
|
-
*
|
|
1181
|
-
* (`
|
|
1182
|
-
*
|
|
1849
|
+
* Every action the vault writes to the log, an entry's `action`: each
|
|
1850
|
+
* writer's is typed on it, and the audit page keys its sentences on it
|
|
1851
|
+
* (`@coffre/ui`, `TEMPLATES`), so an action added without its sentence,
|
|
1852
|
+
* or a sentence left for one no writer writes, fails the typecheck.
|
|
1183
1853
|
*/
|
|
1184
|
-
export
|
|
1185
|
-
|
|
1186
|
-
number: string;
|
|
1187
|
-
witnessed: boolean | null;
|
|
1188
|
-
} | {
|
|
1189
|
-
ok: false;
|
|
1190
|
-
refused: 'moved' | 'stale' | 'tampered' | 'policy' | 'busy';
|
|
1191
|
-
};
|
|
1854
|
+
export declare const LOG_ACTIONS: readonly ["secret.read", "secret.write", "secret.loosen", "secret.rename", "secret.refile", "reference.break", "missing.dismiss", "project.create", "project.update", "project.archive", "project.restore", "project.move", "project.delete", "folder.refile", "environment.create", "environment.update", "environment.archive", "environment.restore", "environment.delete", "environment.protect", "environment.unprotect", "upstream.freeze", "upstream.thaw", "member.add", "member.restore", "member.role", "member.remove", "access.grant", "access.revoke", "policy.change", "settings.change", "sign_in", "sign_out", "token.create", "token.revoke", "account.link", "account.unlink", "device.start", "device.approve", "device.deny", "token.exchange", "workload.renew", "token.bind", "token.unbind", "workload.freeze", "workload.unfreeze", "mcp.connect", "mcp.token", "mcp.disconnect", "oauth.register", "mcp.ask", "mcp.approve", "mcp.deny", "upkeep.expire", "vault.adopt"];
|
|
1855
|
+
export type LogAction = (typeof LOG_ACTIONS)[number];
|
|
1192
1856
|
/**
|
|
1193
1857
|
* The vault's entries that change what a member holds: what their row's
|
|
1194
1858
|
* `access_seq` names, and what a finding about them is newer than while it
|
|
@@ -1214,9 +1878,9 @@ export type RefusalCode =
|
|
|
1214
1878
|
/** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
|
|
1215
1879
|
'bad_claim' |
|
|
1216
1880
|
/**
|
|
1217
|
-
* A person asked for a sensitive value to be handed back
|
|
1218
|
-
*
|
|
1219
|
-
*
|
|
1881
|
+
* A person asked for a sensitive value to be handed back: nobody sees
|
|
1882
|
+
* one, Owners included. Their apps use it through the credential proxy,
|
|
1883
|
+
* and service accounts read it.
|
|
1220
1884
|
*/
|
|
1221
1885
|
'sensitive' |
|
|
1222
1886
|
/**
|
|
@@ -1270,8 +1934,6 @@ export type RefusalCode =
|
|
|
1270
1934
|
* Asked again on the answer now, it is decided as they are now.
|
|
1271
1935
|
*/
|
|
1272
1936
|
'access_changed' |
|
|
1273
|
-
/** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
|
|
1274
|
-
'log_broken' |
|
|
1275
1937
|
/**
|
|
1276
1938
|
* A KEK the vault is given does not open what it wrapped: a restore with
|
|
1277
1939
|
* the wrong key, or a key mistyped under the right id. Every key
|
|
@@ -1290,8 +1952,6 @@ export type Outcome<T> = ({
|
|
|
1290
1952
|
ok: false;
|
|
1291
1953
|
refusal: Refusal;
|
|
1292
1954
|
};
|
|
1293
|
-
/** What each refusal says, as the vault answers it and the app shows it. */
|
|
1294
|
-
export declare const REFUSAL_MESSAGES: Record<RefusalCode, string>;
|
|
1295
1955
|
/**
|
|
1296
1956
|
* A proposed version the app will store. The ids bind its key, and `path`
|
|
1297
1957
|
* is the app's label for the write's log. Reads name stored version ids
|
|
@@ -1327,60 +1987,25 @@ export type WrappedKey = {
|
|
|
1327
1987
|
bytes: string;
|
|
1328
1988
|
};
|
|
1329
1989
|
/**
|
|
1330
|
-
*
|
|
1331
|
-
*
|
|
1332
|
-
*
|
|
1333
|
-
*
|
|
1990
|
+
* What `about` answers. `kek` is the vault key that wraps every new data
|
|
1991
|
+
* key, `previous` those it still unwraps with, by provider and ID.
|
|
1992
|
+
* `checks` holds the check of each key the vault signs and seals with
|
|
1993
|
+
* (`keyCheckOf` in `@coffre/core/kek`): the one it signs with first, then
|
|
1994
|
+
* those it only verifies with. A check is of a signing key, not of a vault
|
|
1995
|
+
* key, so it names none: with a key service and a `signingKey`, no vault
|
|
1996
|
+
* key has a check at all.
|
|
1334
1997
|
*/
|
|
1335
|
-
export type
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
1998
|
+
export type About = {
|
|
1999
|
+
kek: {
|
|
2000
|
+
provider: string;
|
|
2001
|
+
id: string;
|
|
1339
2002
|
};
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
|
-
|
|
2003
|
+
previous: {
|
|
2004
|
+
provider: string;
|
|
2005
|
+
id: string;
|
|
2006
|
+
}[];
|
|
2007
|
+
checks: string[];
|
|
1343
2008
|
};
|
|
1344
|
-
/**
|
|
1345
|
-
* Why someone reads: shown in the log, and the same rules apply to each. A
|
|
1346
|
-
* fork reads to `copy`. The credential proxy reads to `use`, a value it
|
|
1347
|
-
* injects into a request and never hands back, or to `expose`, one it
|
|
1348
|
-
* gives a person's app as it is (`coffre run`'s plan).
|
|
1349
|
-
*/
|
|
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;
|
|
1373
|
-
/**
|
|
1374
|
-
* Whether a read hands values back to whoever asked, which a person never
|
|
1375
|
-
* gets of a sensitive value: every purpose but the proxy's `use` and a
|
|
1376
|
-
* fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
|
|
1377
|
-
* `compare` included, which tells them whether a guess was right, and any
|
|
1378
|
-
* purpose a later app may name.
|
|
1379
|
-
*/
|
|
1380
|
-
export declare function handsBack(read: {
|
|
1381
|
-
purpose: string;
|
|
1382
|
-
keepsSensitive?: boolean;
|
|
1383
|
-
}): boolean;
|
|
1384
2009
|
/** Ties the vault's entries to the app's request and audit rows. */
|
|
1385
2010
|
type Correlation = {
|
|
1386
2011
|
requestId?: string | null;
|
|
@@ -1595,9 +2220,9 @@ export type AdmitInput = Correlation & Through & {
|
|
|
1595
2220
|
* Left out, an existing member keeps theirs and a new one is a `member`.
|
|
1596
2221
|
* Changing it takes someone who runs the instance, about someone else;
|
|
1597
2222
|
* making someone an Owner, or changing an Owner's, an Owner of the whole
|
|
1598
|
-
* instance, who may change their own too. It never leaves
|
|
1599
|
-
* without an Owner of all of it (`last_owner`), nor demotes
|
|
1600
|
-
* deployment names (`owners`; `
|
|
2223
|
+
* instance (`not_allowed`), who may change their own too. It never leaves
|
|
2224
|
+
* the instance without an Owner of all of it (`last_owner`), nor demotes
|
|
2225
|
+
* one the deployment names (`owners`; `configured_owner`).
|
|
1601
2226
|
*/
|
|
1602
2227
|
role?: InstanceRole;
|
|
1603
2228
|
scope?: Scope;
|
|
@@ -1651,6 +2276,19 @@ export type PolicyChange = {
|
|
|
1651
2276
|
export declare function policyRevision(seq: number | bigint | null, policy: Pick<Policy, 'protectedIn'>): string;
|
|
1652
2277
|
/** A revision as `policyRevision` writes it. */
|
|
1653
2278
|
export declare const POLICY_REVISION: RegExp;
|
|
2279
|
+
/**
|
|
2280
|
+
* A role's revision, as a change of it is confirmed with
|
|
2281
|
+
* (`policy.change`'s `revision`): a digest of what it holds, its columns in
|
|
2282
|
+
* any order, or of none. The app answers it with a change's preview; the
|
|
2283
|
+
* vault takes the change only while the role's row still says what was
|
|
2284
|
+
* weighed.
|
|
2285
|
+
*
|
|
2286
|
+
* 9c41e07b5d2a8f13 developer, as it ships
|
|
2287
|
+
* 74d0b1e6a9c3f852 no such role
|
|
2288
|
+
*/
|
|
2289
|
+
export declare function roleRevision(definition: Pick<RoleDefinition, 'name' | 'description' | 'permissions' | 'protected'> | null): string;
|
|
2290
|
+
/** A revision as `roleRevision` writes it. */
|
|
2291
|
+
export declare const ROLE_REVISION: RegExp;
|
|
1654
2292
|
export type ChangePolicyInput = Correlation & Through & {
|
|
1655
2293
|
actor: string;
|
|
1656
2294
|
change: PolicyChange;
|
|
@@ -1664,291 +2302,5 @@ export type ChangePolicyInput = Correlation & Through & {
|
|
|
1664
2302
|
*/
|
|
1665
2303
|
revision?: string;
|
|
1666
2304
|
};
|
|
1667
|
-
/**
|
|
1668
|
-
* A prefix of the log the vault signed: every entry up to `seq`, the last
|
|
1669
|
-
* of which has `hash`, which pins every byte before it. Kept as the vault's
|
|
1670
|
-
* `audit.checkpoint` entry, just after the prefix it signs.
|
|
1671
|
-
*/
|
|
1672
|
-
export type Checkpoint = {
|
|
1673
|
-
seq: number;
|
|
1674
|
-
/** The hash of entry `seq`, hex. */
|
|
1675
|
-
hash: string;
|
|
1676
|
-
signedAt: string;
|
|
1677
|
-
keyId: string;
|
|
1678
|
-
/** Ed25519 over `checkpointMessage(...)`, base64. */
|
|
1679
|
-
signature: string;
|
|
1680
|
-
};
|
|
1681
|
-
/**
|
|
1682
|
-
* A public key the vault's checkpoints verify under, base64. One it
|
|
1683
|
-
* replaced vouches only for checkpoints whose prefix ends before `until`,
|
|
1684
|
-
* its first entry under the key that replaced it; the one it signs with now
|
|
1685
|
-
* has none.
|
|
1686
|
-
*/
|
|
1687
|
-
export type CheckpointKey = {
|
|
1688
|
-
publicKey: string;
|
|
1689
|
-
until: number | null;
|
|
1690
|
-
};
|
|
1691
|
-
/** An entry of the vault's log, and so the chain up to it. */
|
|
1692
|
-
export type LogHead = {
|
|
1693
|
-
seq: number;
|
|
1694
|
-
hash: string;
|
|
1695
|
-
};
|
|
1696
|
-
export type VerifyLogInput = {
|
|
1697
|
-
/**
|
|
1698
|
-
* The last entry the app verified, every link and hash up to it
|
|
1699
|
-
* recomputed and its own entries checked by its key: the vault checks the
|
|
1700
|
-
* log still holds it, so between them both authors' entries are
|
|
1701
|
-
* authenticated over the same stretch, and the vault leaves the links to
|
|
1702
|
-
* the app.
|
|
1703
|
-
*/
|
|
1704
|
-
upTo?: LogHead | null;
|
|
1705
|
-
/**
|
|
1706
|
-
* Where the vault's walk starts: the seq of one of its `audit.checkpoint`
|
|
1707
|
-
* entries that keeps a tally, or `start`, the first entry. The newest
|
|
1708
|
-
* such checkpoint when absent, and a vault older than 0.10.1 walks from
|
|
1709
|
-
* the first entry whatever it says.
|
|
1710
|
-
*/
|
|
1711
|
-
from?: number | 'start';
|
|
1712
|
-
/**
|
|
1713
|
-
* A later checkpoint's entry, whose prefix `upTo` is: the walk ends
|
|
1714
|
-
* there, and must come to the tally it keeps. The members' rows and the
|
|
1715
|
-
* key batches are as they are now, not then, so only a walk without one
|
|
1716
|
-
* holds them to the log.
|
|
1717
|
-
*/
|
|
1718
|
-
to?: number;
|
|
1719
|
-
};
|
|
1720
|
-
/**
|
|
1721
|
-
* Whether the vault's log holds, with the number of its entries through
|
|
1722
|
-
* where the walk ended, `through`: `upTo`, the prefix `to` signed, or as
|
|
1723
|
-
* far as one walk goes. On a failure, the entry where it breaks, or null
|
|
1724
|
-
* when the chain holds but the members and grants do not follow from it.
|
|
1725
|
-
* Then `fault` says which, as facts the app can word with names: `reason`
|
|
1726
|
-
* has only ids. A walk that ends at the present reports live key batches in
|
|
1727
|
-
* `pending`; overdue ones fail.
|
|
1728
|
-
*/
|
|
1729
|
-
export type LogVerification = {
|
|
1730
|
-
ok: true;
|
|
1731
|
-
entries: number;
|
|
1732
|
-
pending?: number;
|
|
1733
|
-
through?: number;
|
|
1734
|
-
} | {
|
|
1735
|
-
ok: false;
|
|
1736
|
-
failedAtSeq: number | null;
|
|
1737
|
-
reason: string;
|
|
1738
|
-
fault?: AccessFault;
|
|
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
|
-
};
|
|
1953
2305
|
//#endregion
|
|
1954
|
-
export type { AccessFault, CallerKind, FaultGrant, FaultNames,
|
|
2306
|
+
export type { AccessAnswers, AccessChanges, AccessFault, AccessGrant, Account, AccountLink, AccountUnlink, Bound, CallerKind, CredentialEnd, DeviceDecide, DeviceRedeem, DeviceStart, EnvironmentCopy, EnvironmentCreate, EnvironmentEdit, EnvironmentEdited, Exchanged, FaultGrant, FaultNames, FolderRefile, Forked, FreezeAnswers, FreezeChanges, Frozen, Issued, KeyOutcome, KeyWrite, McpAnswers, McpAsk, McpChanges, McpClient, McpConnect, McpDecide, McpRevoke, McpToken, McpUnasked, MemberPut, MemberRemove, MissingDismiss, Nature, NewBinding, NewCredential, OauthRegister, PlaceDelete, PlaceDeleted, PlacesAnswers, PlacesChanges, ProjectCreate, ProjectEdit, ProjectEdited, ReferenceBreak, Renewed, Replaces, RoleEdit, ScopeInput, SecretPath, SecretRefile, SecretRename, SecretWrite, SecretsAnswers, SecretsChanges, Session, SettingsEdit, Signin, SigninAnswers, SigninChanges, Standing, TokenBind, TokenCreate, TokenExchange, TokenUnbind, Unasked, WorkloadAnswers, WorkloadChanges, WorkloadFreeze, WorkloadProof, WorkloadRenew, WorkloadSignin, WorkloadUnfreeze, WorkloadsUnasked };
|