@coffre/core 0.14.7 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/{access-BrdZKp1d.js → access-CF8UG59J.js} +70 -8
- package/dist/{access-qkMZa-6Z.d.ts → access-ERdGGHG7.d.ts} +45 -3
- 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 +2 -917
- package/dist/identity.js +1036 -525
- 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 +25 -1
- package/dist/mcp.js +29 -4
- 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 -4
- package/dist/schemas.js +16 -4
- package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
- package/dist/vault.d.ts +1800 -299
- package/dist/vault.js +99 -32
- package/package.json +8 -3
- package/src/access.ts +63 -8
- 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 -0
- package/src/identity/profiles.ts +139 -0
- 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/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/log/tiles.ts +166 -0
- package/src/log/tree.ts +163 -0
- package/src/mcp.ts +34 -3
- package/src/schemas.ts +16 -2
- package/src/vault.ts +308 -276
- package/src/checkpoint.ts +0 -22
package/src/vault.ts
CHANGED
|
@@ -1,201 +1,298 @@
|
|
|
1
1
|
import { createHash } from 'node:crypto';
|
|
2
2
|
|
|
3
|
-
import type {
|
|
4
|
-
import type {
|
|
3
|
+
import type { CallerKind, CredentialScope, GrantPlace, Holdings, InstanceRole, Policy, Role, RoleDefinition, Scope, ServiceSetting } from './access.ts';
|
|
4
|
+
import type { AccessAnswers, AccessChanges } from './changes/access.ts';
|
|
5
|
+
import type { FreezeAnswers, FreezeChanges } from './changes/freezes.ts';
|
|
6
|
+
import type { McpAnswers, McpChanges, McpUnasked } from './changes/mcp.ts';
|
|
7
|
+
import type { PlacesAnswers, PlacesChanges } from './changes/places.ts';
|
|
8
|
+
import type { Nature, SecretsAnswers, SecretsChanges } from './changes/secrets.ts';
|
|
9
|
+
import type { SigninAnswers, SigninChanges, Unasked } from './changes/signin.ts';
|
|
10
|
+
import type { WorkloadAnswers, WorkloadChanges, WorkloadsUnasked } from './changes/workloads.ts';
|
|
11
|
+
import type { BindingPolicy, Constraints } from './identity/index.ts';
|
|
12
|
+
import type { McpScope } from './mcp.ts';
|
|
5
13
|
|
|
6
14
|
export type { CallerKind } from './access.ts';
|
|
7
15
|
|
|
8
|
-
export { checkpointMessage, checkpointVerifier, verifyCheckpoint } from './checkpoint.ts';
|
|
9
16
|
export { describeAccessFault, type AccessFault, type FaultGrant, type FaultNames } from './access-fault.ts';
|
|
10
17
|
|
|
11
18
|
/**
|
|
12
|
-
* The vault as the app sees it
|
|
13
|
-
* `@coffre/vault`, kept in core so
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
19
|
+
* The vault as the app sees it (docs/design/0.16.md, "The contract"): the
|
|
20
|
+
* contract between `@coffre/server` and `@coffre/vault`, kept in core so
|
|
21
|
+
* that neither side owns it. Every argument and answer is plain JSON:
|
|
22
|
+
* strings, numbers, booleans, arrays and objects, never a Buffer, a Date, a
|
|
23
|
+
* class or a function. So it crosses a Workers RPC boundary, or a process
|
|
24
|
+
* boundary, as it is, and the in-process transport proves it by
|
|
25
|
+
* round-tripping everything through JSON.
|
|
18
26
|
*
|
|
19
|
-
* The app says
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
27
|
+
* The app says what a request showed and the vault decides: it finds the
|
|
28
|
+
* credential by its token, reads what it holds and opens the values
|
|
29
|
+
* itself. The app holds no key, no ciphertext it can open and no grant it
|
|
30
|
+
* decides on.
|
|
23
31
|
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
32
|
+
* A decision comes back as a value: `{ refused }` for a refusal, which
|
|
33
|
+
* wrote nothing of what was asked. A refused use writes nothing at all; a
|
|
34
|
+
* change refused to a caller who stands, one log entry that says so, once
|
|
35
|
+
* a minute in each instance for that caller and what they asked. Only a
|
|
36
|
+
* fault throws: a bug, or the database down.
|
|
26
37
|
*/
|
|
27
38
|
export interface Vault {
|
|
39
|
+
/** Open values for whoever presented a token: a reveal, `coffre run`, an export, a proxied request, a signature. */
|
|
40
|
+
use(input: UseInput): Promise<Used | Refused>;
|
|
28
41
|
/**
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
* one, under their row and the head the decision holds: otherwise it
|
|
33
|
-
* refuses `access_changed` and logs no read, and says, by naming it back,
|
|
34
|
-
* that it checked. A vault older than 0.14.1 names none: it checked none.
|
|
42
|
+
* What `use` would give, as of now, without opening or writing anything:
|
|
43
|
+
* each key's secret and version, or why it is refused. What a watch
|
|
44
|
+
* compares before it reads (`GET …/version`).
|
|
35
45
|
*/
|
|
36
|
-
|
|
46
|
+
peek(input: UseInput): Promise<Peeked | Refused>;
|
|
37
47
|
/**
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
* whether its wrap binds it as sensitive: a vault older than 0.10 answers
|
|
42
|
-
* none, binding none, and the app stores no sensitive version it wrapped.
|
|
48
|
+
* Who a request's credential is and all it holds, for the app to scope a
|
|
49
|
+
* page's queries with. Nothing is opened or changed on the answer: a use
|
|
50
|
+
* and a change read their caller themselves.
|
|
43
51
|
*/
|
|
44
|
-
|
|
52
|
+
caller(input: Presented & { head?: boolean }): Promise<Called | Refused>;
|
|
45
53
|
/**
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
* The vault
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
reference(input: ReferenceInput): Promise<Outcome<{ seqs: number[] }>>;
|
|
68
|
-
/**
|
|
69
|
-
* End references, each with a `reference.end` naming its creation:
|
|
70
|
-
* `replaced` when the holder gets a value of its own, which takes write on
|
|
71
|
-
* the holder; `broken` otherwise, which takes write on the holder, or
|
|
72
|
-
* managing the source's project's access. An ended reference reads no
|
|
73
|
-
* more, whatever any row says. All, or none.
|
|
74
|
-
*/
|
|
75
|
-
endReferences(input: EndReferencesInput): Promise<Outcome<{ seqs: number[] }>>;
|
|
76
|
-
|
|
77
|
-
/**
|
|
78
|
-
* What one principal holds right now: the app asks once per request,
|
|
79
|
-
* unless the request reads values on an answer it kept (`accessRevision`),
|
|
80
|
-
* and at sign-in for each verified email. A decision, its rows checked:
|
|
81
|
-
* lists of who holds what read the rows themselves, and need not ask.
|
|
82
|
-
* A person the vault's `owners` names who is no Owner of all of it
|
|
83
|
-
* becomes one here, logged (`reason: 'owners'`).
|
|
84
|
-
*/
|
|
85
|
-
access(principal: string): Promise<Access>;
|
|
86
|
-
/**
|
|
87
|
-
* Set roles at several places for one principal: all of it, or none.
|
|
88
|
-
* With `admit`, a service account that is not a member is admitted
|
|
89
|
-
* first, in the same decision, as `admit` would: `admitted` says so.
|
|
90
|
-
*/
|
|
91
|
-
setAccess(input: SetAccessInput): Promise<Outcome<{ changes: AccessChange[]; admitted?: Admitted }>>;
|
|
92
|
-
/**
|
|
93
|
-
* Add a member, bring back a removed one, or change a person's instance
|
|
94
|
-
* role and its scope. `generation` is theirs now: sessions and tokens of
|
|
95
|
-
* an earlier one are dead.
|
|
96
|
-
*/
|
|
97
|
-
admit(input: AdmitInput): Promise<Outcome<Admitted>>;
|
|
98
|
-
/**
|
|
99
|
-
* Remove a member: revoke every grant and refuse them until admitted
|
|
100
|
-
* again, from `generation` on. An Owner, only an Owner of the whole
|
|
101
|
-
* instance removes, and never the last.
|
|
102
|
-
*/
|
|
103
|
-
remove(input: RemoveInput): Promise<Outcome<{ revoked: Grant[]; generation: number }>>;
|
|
104
|
-
/**
|
|
105
|
-
* The instance's settings, as the vault's newest `settings.change` entry
|
|
106
|
-
* says, by its MAC: an entry is where they live, so each change is logged
|
|
107
|
-
* by being made. Everywhere, until someone narrows it.
|
|
108
|
-
*/
|
|
109
|
-
settings(): Promise<Settings>;
|
|
110
|
-
/** Change the instance's settings: those who run it, never anyone else. */
|
|
111
|
-
setSettings(input: SetSettingsInput): Promise<Outcome<{ settings: Settings }>>;
|
|
112
|
-
|
|
113
|
-
/**
|
|
114
|
-
* The instance's access policy (`Policy` in @coffre/core/access): its
|
|
115
|
-
* roles, as an Owner edited and made them, and its protected
|
|
116
|
-
* environments, as the vault's newest `policy.change` says, by its MAC.
|
|
117
|
-
* As it ships, before any. A vault older than 0.10 has none, and the app
|
|
118
|
-
* decides as it ships.
|
|
119
|
-
*/
|
|
120
|
-
policy(): Promise<Policy>;
|
|
121
|
-
/**
|
|
122
|
-
* Change the policy by one change, its own `policy.change` entry, which
|
|
123
|
-
* names it and what it was (docs/design/roles.md):
|
|
124
|
-
* - a project or instance role defined, or put back as it ships (null),
|
|
125
|
-
* or, one an Owner made, deleted while no grant names it: an Owner of
|
|
126
|
-
* the whole instance, and never the Owner role, nor the instance's
|
|
127
|
-
* Member;
|
|
128
|
-
* - environments of one project protected, by whoever manages its
|
|
129
|
-
* environments, before their rows exist too (a fork's); or
|
|
130
|
-
* unprotected, by an Owner of the project or of the whole instance
|
|
131
|
-
* (`ownsProject`), as far as that project protected them.
|
|
132
|
-
* The policy after it, and the newest `policy.change`, which it is as of:
|
|
133
|
-
* the change's own, when it changed anything.
|
|
134
|
-
*/
|
|
135
|
-
changePolicy(input: ChangePolicyInput): Promise<Outcome<{ policy: Policy; seq: number | null }>>;
|
|
136
|
-
|
|
137
|
-
/**
|
|
138
|
-
* Sign the log up to its last entry, in an `audit.checkpoint` entry of
|
|
139
|
-
* the vault's, if the chain recomputes from the last checkpoint, the
|
|
140
|
-
* vault's entries by their MACs, and that checkpoint's prefix is still
|
|
141
|
-
* there, whole. The entry keeps the checkpoint's tally beside it: what a
|
|
142
|
-
* walk from the first entry has gathered by the prefix's end (the
|
|
143
|
-
* vault's keys, its key batches under way, who is a member and what they
|
|
144
|
-
* hold), so that the next checkpoint, and every verification, go on from
|
|
145
|
-
* there and read only what is new. A log longer than one walk, as after
|
|
146
|
-
* an upgrade from 0.10.0, is signed a stretch a call, behind its head,
|
|
147
|
-
* until the checkpoints catch up. Each call also rehashes a stretch of
|
|
148
|
-
* what was signed before, round and round, which an entry edited in place
|
|
149
|
-
* fails: then it refuses, and every verification reports the refusal.
|
|
150
|
-
* A rehash the database fails moves on next time, and `warning` says so;
|
|
151
|
-
* a refusal it would have cleared stands meanwhile. The vault reads the log itself: it takes nobody's word for where
|
|
152
|
-
* it ends, or for what came before. It checks every member's row too, as
|
|
153
|
-
* `access` would, and logs a `vault.tampered` for each one changed around
|
|
154
|
-
* it: lists read rows without asking the vault.
|
|
155
|
-
*/
|
|
156
|
-
checkpoint(): Promise<Outcome<{ checkpoint: Checkpoint; warning?: string }>>;
|
|
157
|
-
/**
|
|
158
|
-
* What the vault's configuration says, which the app shows: the keys its
|
|
159
|
-
* checkpoints verify under, by the key id each checkpoint names (the one
|
|
160
|
-
* it signs with now, and those of the KEKs it replaced).
|
|
161
|
-
*/
|
|
162
|
-
about(): Promise<{
|
|
163
|
-
checkpointKeys: Record<string, CheckpointKey>;
|
|
164
|
-
/**
|
|
165
|
-
* The emails of those the deployment names Owners of the whole instance
|
|
166
|
-
* (`owners`), lowercased: the vault makes them Owners, and refuses to
|
|
167
|
-
* demote or remove them. Absent from a vault of 0.5, which names none.
|
|
168
|
-
*/
|
|
169
|
-
owners?: string[];
|
|
170
|
-
/**
|
|
171
|
-
* @deprecated Always empty: an app of 0.5, deployed after this vault,
|
|
172
|
-
* lists and checks root admins here until it is. Gone in 0.7.
|
|
173
|
-
*/
|
|
174
|
-
rootAdmins: [];
|
|
175
|
-
}>;
|
|
176
|
-
/**
|
|
177
|
-
* What an escrowed vault key is checked against: the vault key it wraps
|
|
178
|
-
* under now, and each one's check, as the vault wrote it. None of it is
|
|
179
|
-
* secret, and the vault answers no guess: a check opens only under its key.
|
|
180
|
-
*/
|
|
181
|
-
keyChecks(): Promise<KeyChecks>;
|
|
182
|
-
/**
|
|
183
|
-
* Check the log from a checkpoint's tally, the newest unless `from`
|
|
184
|
-
* names another, or the first entry: the vault's entries since by their
|
|
185
|
-
* MACs, every checkpoint among them against the prefix it signed, the key
|
|
186
|
-
* batches accounted for, and the members and grants replayed on from the
|
|
187
|
-
* tally to see that the rows follow. With `to`, a later checkpoint, the
|
|
188
|
-
* walk stops at the prefix it signed and must come to the tally it keeps:
|
|
189
|
-
* a stretch of the whole log, walked from the first entry a stretch at a
|
|
190
|
-
* time. The links and hashes of the chain are the caller's to recompute
|
|
191
|
-
* through `upTo`, as the app does first; with none, the vault recomputes
|
|
192
|
-
* them itself, no further than one walk. A verdict and nothing else, so
|
|
193
|
-
* anyone may ask; the app asks for those who read the whole log
|
|
194
|
-
* (`readsWholeLog`).
|
|
195
|
-
*/
|
|
196
|
-
verifyLog(input: VerifyLogInput): Promise<LogVerification>;
|
|
54
|
+
* Make a change: one operation, named as its log entry's action is, with
|
|
55
|
+
* its input. All of it, or none.
|
|
56
|
+
*/
|
|
57
|
+
change<O extends Change['op']>(input: Asked<O>): Promise<{ answer: Answers[O] } | Refused>;
|
|
58
|
+
/**
|
|
59
|
+
* What `change` would answer, as of now, with nothing written: the same
|
|
60
|
+
* read and the same decision, so a dry run (`?dryRun=1`) is no second
|
|
61
|
+
* copy of a rule. The change made after reads and decides again, and
|
|
62
|
+
* alone tells a version it opens that does not open (`unreadable`). One
|
|
63
|
+
* refused is logged as the change refused is; one that would be made
|
|
64
|
+
* leaves nothing. Only what a caller asks is weighed: a sign-in or an
|
|
65
|
+
* exchange rests on a proof, which this would try without spending.
|
|
66
|
+
*/
|
|
67
|
+
weigh<O extends Exclude<Change['op'], Unasked | WorkloadsUnasked | McpUnasked>>(input: Asked<O>): Promise<{ answer: Answers[O] } | Refused>;
|
|
68
|
+
/**
|
|
69
|
+
* The vault's configuration that is no secret: its vault keys and its
|
|
70
|
+
* signing keys' checks. It asks no caller, reads nothing, writes no
|
|
71
|
+
* entry and opens no connection: it answers what the vault was started
|
|
72
|
+
* with, the same to anyone, so whoever may see it is the app's to say.
|
|
73
|
+
*/
|
|
74
|
+
about(): Promise<About>;
|
|
197
75
|
}
|
|
198
76
|
|
|
77
|
+
/** Where a request came from, which every call carries. */
|
|
78
|
+
export type Trace = {
|
|
79
|
+
/** The app's id for the request, for the log. */
|
|
80
|
+
request: string | null;
|
|
81
|
+
/** The address it came from, for the log, and for a workload's binding that names its sources. */
|
|
82
|
+
ip: string | null;
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* What a request showed, which every call but a change nobody asks starts
|
|
87
|
+
* with. The app never says who is asking: the vault finds the credential
|
|
88
|
+
* by its token.
|
|
89
|
+
*/
|
|
90
|
+
export type Presented = Trace & {
|
|
91
|
+
/** The SHA-256 of the token the request presented, in lowercase hex. */
|
|
92
|
+
token: string;
|
|
93
|
+
/**
|
|
94
|
+
* The thumbprint of the key that signed the request's proof (RFC 9449),
|
|
95
|
+
* once the app has held the proof to the request: a workload's session
|
|
96
|
+
* is its key's alone. Null with no proof.
|
|
97
|
+
*/
|
|
98
|
+
proof: string | null;
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* A change as the app sends it: its operation's input, with what the
|
|
103
|
+
* request showed, or for one nobody asks (`Unasked`), where it came from
|
|
104
|
+
* alone.
|
|
105
|
+
*/
|
|
106
|
+
export type Asked<O extends Change['op']> = O extends Change['op'] ? (O extends Unasked | WorkloadsUnasked | McpUnasked ? Trace : Presented & ForConnection) & Extract<Change, { op: O }> : never;
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* The approval a person makes a change for, on coffre's page
|
|
110
|
+
* (docs/design/0.16.md, "An MCP client's changes"): the change is theirs,
|
|
111
|
+
* made on their browser session, and its entry names the app that asked.
|
|
112
|
+
* The vault reads the connection and the approval with the change's other
|
|
113
|
+
* rows. The connection must stand, be of the caller's own member and
|
|
114
|
+
* generation, and the caller be on a browser session, or the change is
|
|
115
|
+
* refused `disconnected`. The approval must be the connection's, pending,
|
|
116
|
+
* unexpired by the time the write starts, and of the `digest` the page
|
|
117
|
+
* rendered, or it is refused `unknown_approval`. Made, the change marks the
|
|
118
|
+
* approval approved in its own write: no approval is approved without its
|
|
119
|
+
* change, nor a change made twice under one. It decides nothing else: what
|
|
120
|
+
* the change may do is the person's.
|
|
121
|
+
*/
|
|
122
|
+
export type ForConnection = {
|
|
123
|
+
via?: { connection: string; approval: string; digest: string };
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
export type UseInput = Presented & {
|
|
127
|
+
/** The place, by its slugs. */
|
|
128
|
+
project: string;
|
|
129
|
+
environment: string;
|
|
130
|
+
/** The caller's personal config of that environment, `@me`, where they have one. */
|
|
131
|
+
mine: boolean;
|
|
132
|
+
/** The keys asked for, by name, 1,000 at most: null is every key the environment has. */
|
|
133
|
+
keys: string[] | null;
|
|
134
|
+
/** `use`: the value is used for the caller, by the credential proxy, and never handed back. Any other hands it back. */
|
|
135
|
+
purpose: Purpose;
|
|
136
|
+
/** What the values are used for (`Upstream`): null for none. */
|
|
137
|
+
upstream: Upstream | null;
|
|
138
|
+
/**
|
|
139
|
+
* Read the rows now, never from the vault's memory (`memorySeconds`): an
|
|
140
|
+
* answer that must see a change just made (`coffre run`'s plan after the
|
|
141
|
+
* values it generated were written). Any read may ask it; the rows read are
|
|
142
|
+
* remembered all the same.
|
|
143
|
+
*/
|
|
144
|
+
fresh?: boolean;
|
|
145
|
+
};
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The upstream credential a use is for, by its name in the deployment's
|
|
149
|
+
* configuration (`stripe`), and where the proxy sends the values, which the
|
|
150
|
+
* use's entry keeps on the app's word, as 0.14.7's app logged it: the host
|
|
151
|
+
* (`api.stripe.com`, a presigned URL's), and `egress` when the request
|
|
152
|
+
* leaves through the deployment's egress. Signing, verifying, a cipher and
|
|
153
|
+
* a tunnel name no host: they send nothing anywhere, or the host is in the
|
|
154
|
+
* value.
|
|
155
|
+
*/
|
|
156
|
+
export type Upstream = { credential: string; host?: string; egress?: true };
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Why someone reads, which the log shows. `use`: the credential proxy
|
|
160
|
+
* injects the value into a request and never hands it back. Every other
|
|
161
|
+
* hands the value back: `reveal` of one key, `run` of an environment,
|
|
162
|
+
* `compare` of a guess in a dry run, `expose` by the proxy to a person's
|
|
163
|
+
* own app.
|
|
164
|
+
*/
|
|
165
|
+
export const PURPOSES = ['reveal', 'run', 'compare', 'expose', 'use'] as const;
|
|
166
|
+
export type Purpose = (typeof PURPOSES)[number];
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* One key's value, or why this caller is not given it. `secret` is where the
|
|
170
|
+
* value is held: a reference's source. `nature` is the one the value opened
|
|
171
|
+
* under, which its encryption names (`contextOf`), so a row relabelled behind
|
|
172
|
+
* the vault cannot turn a secret into a plain value: what the proxy leaves
|
|
173
|
+
* unredacted when an upstream echoes it.
|
|
174
|
+
*/
|
|
175
|
+
export type UsedValue = { key: string; secret: string; version: number; nature: Nature; value: string } | { key: string; refused: string };
|
|
176
|
+
|
|
177
|
+
export type Used = {
|
|
178
|
+
principal: string;
|
|
179
|
+
/** The credential's id. */
|
|
180
|
+
credential: string;
|
|
181
|
+
/**
|
|
182
|
+
* The credential's effective end, ISO 8601: the instant the vault starts
|
|
183
|
+
* refusing it for age, the earliest of its own end, a workload session's
|
|
184
|
+
* hard end (`notAfter`) and those of the sessions it was narrowed from.
|
|
185
|
+
* Not `Called.credential.expiresAt`, its own row's end. A grant that ends
|
|
186
|
+
* sooner, a revoke or a freeze does not move it: what a presigned URL
|
|
187
|
+
* lasts no longer than, and may outlive those, as on 0.14.7.
|
|
188
|
+
*/
|
|
189
|
+
expiresAt: string;
|
|
190
|
+
values: UsedValue[];
|
|
191
|
+
/** For a workload's session, what only the app can hold its request to: an unsigned upload its binding must allow, a narrowed session's methods and paths. */
|
|
192
|
+
workload: { binding: string; profile: string; policy: BindingPolicy; constraints: Constraints | null } | null;
|
|
193
|
+
};
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* What a use would give: each key's secret, version and nature, or why it
|
|
197
|
+
* is refused; nothing opened. The nature is the one its rows say, which the
|
|
198
|
+
* use holds the value to: what `coffre run`'s plan picks the keys it asks
|
|
199
|
+
* for by, and never what it places a value by, which is the use's.
|
|
200
|
+
*
|
|
201
|
+
* For what `coffre run` generates in a personal config, of a key the caller
|
|
202
|
+
* is given and no other: `versionId`, the version's id, which a write's
|
|
203
|
+
* `replaces` names (a listing's `versionId`); `recipe`, what made it, null
|
|
204
|
+
* for a value typed or a reference; `own`, held in the caller's personal
|
|
205
|
+
* config, not inherited. `personal`: the read found the caller's personal
|
|
206
|
+
* config of the environment (`@me`), not the environment itself.
|
|
207
|
+
*/
|
|
208
|
+
export type Peeked = {
|
|
209
|
+
principal: string;
|
|
210
|
+
/** The credential's id. */
|
|
211
|
+
credential: string;
|
|
212
|
+
personal: boolean;
|
|
213
|
+
items: ({ key: string; secret: string; version: number; nature: Nature; versionId: string; recipe: string | null; own: boolean } | { key: string; refused: string })[];
|
|
214
|
+
};
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Who a request is: its principal, `user:<email>` or `token:<name>`, the
|
|
218
|
+
* credential it came in on, and what it holds, as `allows` in
|
|
219
|
+
* `@coffre/core/access` decides on it: its role in the instance and that
|
|
220
|
+
* role's scope, its live grants, a token's own scope, the definitions of
|
|
221
|
+
* the roles it holds and of no other (a role absent from `policy` is one
|
|
222
|
+
* the caller does not hold, not one that grants nothing to anyone), and
|
|
223
|
+
* every environment the instance protects.
|
|
224
|
+
*/
|
|
225
|
+
export type Called = {
|
|
226
|
+
principal: string;
|
|
227
|
+
/**
|
|
228
|
+
* `expiresAt` is ISO 8601, the row's own end: a use's `Used.expiresAt`
|
|
229
|
+
* is the effective one, which a session's hard end and the rows above it
|
|
230
|
+
* may bring sooner. An MCP connection's access token (kind `mcp`)
|
|
231
|
+
* says which connection it is under and the scopes it holds, from its
|
|
232
|
+
* row; no other credential has either. `label` is the one it was made
|
|
233
|
+
* with: a personal token's, which `GET /me` names it by.
|
|
234
|
+
*/
|
|
235
|
+
credential: { id: string; kind: string; expiresAt: string; label: string | null; connection?: string; scopes?: McpScope[] };
|
|
236
|
+
holds: Holdings & { policy: Policy };
|
|
237
|
+
/**
|
|
238
|
+
* For a call that asked (`head`): the log's head as the vault last signed
|
|
239
|
+
* it, read with the caller's rows and held to the vault's MAC; null when
|
|
240
|
+
* no head stands under it. The audit page proves each entry it shows
|
|
241
|
+
* against these roots; one past these sizes is proven by nothing here.
|
|
242
|
+
*/
|
|
243
|
+
head?: SignedHead | null;
|
|
244
|
+
};
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* The log's signed head: how many entries are numbered (`size`), and each
|
|
248
|
+
* tree's size and root, hex (the changes kept for good, and the uses that
|
|
249
|
+
* age out, of which `agingFrom` is the first still there). `signedAt` is
|
|
250
|
+
* ISO 8601. It says the vault signed this log, not that none is newer: the
|
|
251
|
+
* signer holds the log's end to its own copy every minute, and walks the
|
|
252
|
+
* rest within a day.
|
|
253
|
+
*/
|
|
254
|
+
export type SignedHead = { size: number; keptSize: number; keptRoot: string; agingSize: number; agingRoot: string; agingFrom: number; signedAt: string };
|
|
255
|
+
|
|
256
|
+
/** Why a call is not answered. Nothing it asked was written. */
|
|
257
|
+
export type Refused = { refused: string };
|
|
258
|
+
|
|
259
|
+
/**
|
|
260
|
+
* Every change the vault makes: its operation, and what that one takes.
|
|
261
|
+
* Each area's are in a file of its own (`changes/`), with what each
|
|
262
|
+
* answers once it is made.
|
|
263
|
+
*/
|
|
264
|
+
export type Change = SecretsChanges | PlacesChanges | AccessChanges | SigninChanges | WorkloadChanges | FreezeChanges | McpChanges;
|
|
265
|
+
export type Answers = SecretsAnswers & PlacesAnswers & AccessAnswers & SigninAnswers & WorkloadAnswers & FreezeAnswers & McpAnswers;
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* Every action the vault writes to the log, an entry's `action`: each
|
|
269
|
+
* writer's is typed on it, and the audit page keys its sentences on it
|
|
270
|
+
* (`@coffre/ui`, `TEMPLATES`), so an action added without its sentence,
|
|
271
|
+
* or a sentence left for one no writer writes, fails the typecheck.
|
|
272
|
+
*/
|
|
273
|
+
export const LOG_ACTIONS = [
|
|
274
|
+
'secret.read', 'secret.write', 'secret.loosen', 'secret.rename', 'secret.refile', 'reference.break', 'missing.dismiss',
|
|
275
|
+
'project.create', 'project.update', 'project.archive', 'project.restore', 'project.move', 'project.delete', 'folder.refile',
|
|
276
|
+
'environment.create', 'environment.update', 'environment.archive', 'environment.restore', 'environment.delete',
|
|
277
|
+
'environment.protect', 'environment.unprotect', 'upstream.freeze', 'upstream.thaw',
|
|
278
|
+
'member.add', 'member.restore', 'member.role', 'member.remove', 'access.grant', 'access.revoke', 'policy.change', 'settings.change',
|
|
279
|
+
'sign_in', 'sign_out', 'token.create', 'token.revoke', 'account.link', 'account.unlink', 'device.start', 'device.approve', 'device.deny',
|
|
280
|
+
'token.exchange', 'workload.renew', 'token.bind', 'token.unbind', 'workload.freeze', 'workload.unfreeze',
|
|
281
|
+
'mcp.connect', 'mcp.token', 'mcp.disconnect', 'oauth.register', 'mcp.ask', 'mcp.approve', 'mcp.deny',
|
|
282
|
+
'upkeep.expire', 'vault.adopt',
|
|
283
|
+
] as const;
|
|
284
|
+
export type LogAction = (typeof LOG_ACTIONS)[number];
|
|
285
|
+
|
|
286
|
+
export type * from './changes/access.ts';
|
|
287
|
+
export type * from './changes/freezes.ts';
|
|
288
|
+
export type * from './changes/mcp.ts';
|
|
289
|
+
export type * from './changes/places.ts';
|
|
290
|
+
export type * from './changes/secrets.ts';
|
|
291
|
+
export type * from './changes/signin.ts';
|
|
292
|
+
export type * from './changes/workloads.ts';
|
|
293
|
+
|
|
294
|
+
// 0.14's contract, from here on: each type goes with the last of the server's code that names it.
|
|
295
|
+
|
|
199
296
|
/**
|
|
200
297
|
* The vault's entries that change what a member holds: what their row's
|
|
201
298
|
* `access_seq` names, and what a finding about them is newer than while it
|
|
@@ -220,9 +317,9 @@ export type RefusalCode =
|
|
|
220
317
|
/** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
|
|
221
318
|
| 'bad_claim'
|
|
222
319
|
/**
|
|
223
|
-
* A person asked for a sensitive value to be handed back
|
|
224
|
-
*
|
|
225
|
-
*
|
|
320
|
+
* A person asked for a sensitive value to be handed back: nobody sees
|
|
321
|
+
* one, Owners included. Their apps use it through the credential proxy,
|
|
322
|
+
* and service accounts read it.
|
|
226
323
|
*/
|
|
227
324
|
| 'sensitive'
|
|
228
325
|
/**
|
|
@@ -276,8 +373,6 @@ export type RefusalCode =
|
|
|
276
373
|
* Asked again on the answer now, it is decided as they are now.
|
|
277
374
|
*/
|
|
278
375
|
| 'access_changed'
|
|
279
|
-
/** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
|
|
280
|
-
| 'log_broken'
|
|
281
376
|
/**
|
|
282
377
|
* A KEK the vault is given does not open what it wrapped: a restore with
|
|
283
378
|
* the wrong key, or a key mistyped under the right id. Every key
|
|
@@ -322,32 +417,15 @@ export type Wrapped = { wrapped: WrappedKey[]; seqs: number[]; sensitive: boolea
|
|
|
322
417
|
export type WrappedKey = { kekProvider: string; kekId: string; kekVersion: string; bytes: string };
|
|
323
418
|
|
|
324
419
|
/**
|
|
325
|
-
*
|
|
326
|
-
*
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
/**
|
|
333
|
-
* Why someone reads: shown in the log, and the same rules apply to each. A
|
|
334
|
-
* fork reads to `copy`. The credential proxy reads to `use`, a value it
|
|
335
|
-
* injects into a request and never hands back, or to `expose`, one it
|
|
336
|
-
* gives a person's app as it is (`coffre run`'s plan).
|
|
420
|
+
* What `about` answers. `kek` is the vault key that wraps every new data
|
|
421
|
+
* key, `previous` those it still unwraps with, by provider and ID.
|
|
422
|
+
* `checks` holds the check of each key the vault signs and seals with
|
|
423
|
+
* (`keyCheckOf` in `@coffre/core/kek`): the one it signs with first, then
|
|
424
|
+
* those it only verifies with. A check is of a signing key, not of a vault
|
|
425
|
+
* key, so it names none: with a key service and a `signingKey`, no vault
|
|
426
|
+
* key has a check at all.
|
|
337
427
|
*/
|
|
338
|
-
export type
|
|
339
|
-
|
|
340
|
-
/**
|
|
341
|
-
* Whether a read hands values back to whoever asked, which a person never
|
|
342
|
-
* gets of a sensitive value: every purpose but the proxy's `use` and a
|
|
343
|
-
* fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
|
|
344
|
-
* `compare` included, which tells them whether a guess was right, and any
|
|
345
|
-
* purpose a later app may name.
|
|
346
|
-
*/
|
|
347
|
-
export function handsBack(read: { purpose: string; keepsSensitive?: boolean }): boolean {
|
|
348
|
-
if (read.purpose === 'use') return false;
|
|
349
|
-
return !(read.purpose === 'copy' && read.keepsSensitive === true);
|
|
350
|
-
}
|
|
428
|
+
export type About = { kek: { provider: string; id: string }; previous: { provider: string; id: string }[]; checks: string[] };
|
|
351
429
|
|
|
352
430
|
/** Ties the vault's entries to the app's request and audit rows. */
|
|
353
431
|
type Correlation = {
|
|
@@ -559,9 +637,9 @@ export type AdmitInput = Correlation & Through & {
|
|
|
559
637
|
* Left out, an existing member keeps theirs and a new one is a `member`.
|
|
560
638
|
* Changing it takes someone who runs the instance, about someone else;
|
|
561
639
|
* making someone an Owner, or changing an Owner's, an Owner of the whole
|
|
562
|
-
* instance, who may change their own too. It never leaves
|
|
563
|
-
* without an Owner of all of it (`last_owner`), nor demotes
|
|
564
|
-
* deployment names (`owners`; `
|
|
640
|
+
* instance (`not_allowed`), who may change their own too. It never leaves
|
|
641
|
+
* the instance without an Owner of all of it (`last_owner`), nor demotes
|
|
642
|
+
* one the deployment names (`owners`; `configured_owner`).
|
|
565
643
|
*/
|
|
566
644
|
role?: InstanceRole;
|
|
567
645
|
scope?: Scope;
|
|
@@ -614,6 +692,24 @@ export function policyRevision(seq: number | bigint | null, policy: Pick<Policy,
|
|
|
614
692
|
/** A revision as `policyRevision` writes it. */
|
|
615
693
|
export const POLICY_REVISION = /^(none|[1-9][0-9]{0,15})\.[0-9a-f]{16}$/;
|
|
616
694
|
|
|
695
|
+
/**
|
|
696
|
+
* A role's revision, as a change of it is confirmed with
|
|
697
|
+
* (`policy.change`'s `revision`): a digest of what it holds, its columns in
|
|
698
|
+
* any order, or of none. The app answers it with a change's preview; the
|
|
699
|
+
* vault takes the change only while the role's row still says what was
|
|
700
|
+
* weighed.
|
|
701
|
+
*
|
|
702
|
+
* 9c41e07b5d2a8f13 developer, as it ships
|
|
703
|
+
* 74d0b1e6a9c3f852 no such role
|
|
704
|
+
*/
|
|
705
|
+
export function roleRevision(definition: Pick<RoleDefinition, 'name' | 'description' | 'permissions' | 'protected'> | null): string {
|
|
706
|
+
const said = definition === null ? null : [definition.name, definition.description, [...definition.permissions].sort(), [...definition.protected].sort()];
|
|
707
|
+
return createHash('sha256').update(JSON.stringify(said)).digest('hex').slice(0, 16);
|
|
708
|
+
}
|
|
709
|
+
|
|
710
|
+
/** A revision as `roleRevision` writes it. */
|
|
711
|
+
export const ROLE_REVISION = /^[0-9a-f]{16}$/;
|
|
712
|
+
|
|
617
713
|
export type ChangePolicyInput = Correlation & Through & {
|
|
618
714
|
actor: string;
|
|
619
715
|
change: PolicyChange;
|
|
@@ -627,67 +723,3 @@ export type ChangePolicyInput = Correlation & Through & {
|
|
|
627
723
|
*/
|
|
628
724
|
revision?: string;
|
|
629
725
|
};
|
|
630
|
-
|
|
631
|
-
/**
|
|
632
|
-
* A prefix of the log the vault signed: every entry up to `seq`, the last
|
|
633
|
-
* of which has `hash`, which pins every byte before it. Kept as the vault's
|
|
634
|
-
* `audit.checkpoint` entry, just after the prefix it signs.
|
|
635
|
-
*/
|
|
636
|
-
export type Checkpoint = {
|
|
637
|
-
seq: number;
|
|
638
|
-
/** The hash of entry `seq`, hex. */
|
|
639
|
-
hash: string;
|
|
640
|
-
signedAt: string;
|
|
641
|
-
keyId: string;
|
|
642
|
-
/** Ed25519 over `checkpointMessage(...)`, base64. */
|
|
643
|
-
signature: string;
|
|
644
|
-
};
|
|
645
|
-
|
|
646
|
-
/**
|
|
647
|
-
* A public key the vault's checkpoints verify under, base64. One it
|
|
648
|
-
* replaced vouches only for checkpoints whose prefix ends before `until`,
|
|
649
|
-
* its first entry under the key that replaced it; the one it signs with now
|
|
650
|
-
* has none.
|
|
651
|
-
*/
|
|
652
|
-
export type CheckpointKey = { publicKey: string; until: number | null };
|
|
653
|
-
|
|
654
|
-
/** An entry of the vault's log, and so the chain up to it. */
|
|
655
|
-
export type LogHead = { seq: number; hash: string };
|
|
656
|
-
|
|
657
|
-
export type VerifyLogInput = {
|
|
658
|
-
/**
|
|
659
|
-
* The last entry the app verified, every link and hash up to it
|
|
660
|
-
* recomputed and its own entries checked by its key: the vault checks the
|
|
661
|
-
* log still holds it, so between them both authors' entries are
|
|
662
|
-
* authenticated over the same stretch, and the vault leaves the links to
|
|
663
|
-
* the app.
|
|
664
|
-
*/
|
|
665
|
-
upTo?: LogHead | null;
|
|
666
|
-
/**
|
|
667
|
-
* Where the vault's walk starts: the seq of one of its `audit.checkpoint`
|
|
668
|
-
* entries that keeps a tally, or `start`, the first entry. The newest
|
|
669
|
-
* such checkpoint when absent, and a vault older than 0.10.1 walks from
|
|
670
|
-
* the first entry whatever it says.
|
|
671
|
-
*/
|
|
672
|
-
from?: number | 'start';
|
|
673
|
-
/**
|
|
674
|
-
* A later checkpoint's entry, whose prefix `upTo` is: the walk ends
|
|
675
|
-
* there, and must come to the tally it keeps. The members' rows and the
|
|
676
|
-
* key batches are as they are now, not then, so only a walk without one
|
|
677
|
-
* holds them to the log.
|
|
678
|
-
*/
|
|
679
|
-
to?: number;
|
|
680
|
-
};
|
|
681
|
-
|
|
682
|
-
/**
|
|
683
|
-
* Whether the vault's log holds, with the number of its entries through
|
|
684
|
-
* where the walk ended, `through`: `upTo`, the prefix `to` signed, or as
|
|
685
|
-
* far as one walk goes. On a failure, the entry where it breaks, or null
|
|
686
|
-
* when the chain holds but the members and grants do not follow from it.
|
|
687
|
-
* Then `fault` says which, as facts the app can word with names: `reason`
|
|
688
|
-
* has only ids. A walk that ends at the present reports live key batches in
|
|
689
|
-
* `pending`; overdue ones fail.
|
|
690
|
-
*/
|
|
691
|
-
export type LogVerification =
|
|
692
|
-
| { ok: true; entries: number; pending?: number; through?: number }
|
|
693
|
-
| { ok: false; failedAtSeq: number | null; reason: string; fault?: AccessFault };
|