@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/dist/vault.js
CHANGED
|
@@ -1,24 +1,4 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
|
-
//#region src/checkpoint.ts
|
|
3
|
-
/** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
|
|
4
|
-
function checkpointMessage(checkpoint) {
|
|
5
|
-
const { seq, hash, signedAt } = checkpoint;
|
|
6
|
-
return new Uint8Array(new TextEncoder().encode(`coffre.checkpoint.v3|${seq}|${hash}|${signedAt}`));
|
|
7
|
-
}
|
|
8
|
-
/** Whether `checkpoint` was signed by the key whose raw public half is `publicKey`. */
|
|
9
|
-
async function verifyCheckpoint(checkpoint, publicKey) {
|
|
10
|
-
return (await checkpointVerifier(publicKey))(checkpoint);
|
|
11
|
-
}
|
|
12
|
-
/**
|
|
13
|
-
* `verifyCheckpoint` for many checkpoints signed by one key, the key
|
|
14
|
-
* imported once: a full verification checks every checkpoint, one every
|
|
15
|
-
* five minutes.
|
|
16
|
-
*/
|
|
17
|
-
async function checkpointVerifier(publicKey) {
|
|
18
|
-
const key = await crypto.subtle.importKey("raw", new Uint8Array(Buffer.from(publicKey, "base64")), { name: "Ed25519" }, false, ["verify"]);
|
|
19
|
-
return (checkpoint) => crypto.subtle.verify("Ed25519", key, new Uint8Array(Buffer.from(checkpoint.signature, "base64")), checkpointMessage(checkpoint));
|
|
20
|
-
}
|
|
21
|
-
//#endregion
|
|
22
2
|
//#region src/access-fault.ts
|
|
23
3
|
/** The fault in a sentence, with whatever names the caller can give. */
|
|
24
4
|
function describeAccessFault(fault, names = {}) {
|
|
@@ -42,6 +22,83 @@ function describeAccessFault(fault, names = {}) {
|
|
|
42
22
|
//#endregion
|
|
43
23
|
//#region src/vault.ts
|
|
44
24
|
/**
|
|
25
|
+
* Why someone reads, which the log shows. `use`: the credential proxy
|
|
26
|
+
* injects the value into a request and never hands it back. Every other
|
|
27
|
+
* hands the value back: `reveal` of one key, `run` of an environment,
|
|
28
|
+
* `compare` of a guess in a dry run, `expose` by the proxy to a person's
|
|
29
|
+
* own app.
|
|
30
|
+
*/
|
|
31
|
+
const PURPOSES = [
|
|
32
|
+
"reveal",
|
|
33
|
+
"run",
|
|
34
|
+
"compare",
|
|
35
|
+
"expose",
|
|
36
|
+
"use"
|
|
37
|
+
];
|
|
38
|
+
/**
|
|
39
|
+
* Every action the vault writes to the log, an entry's `action`: each
|
|
40
|
+
* writer's is typed on it, and the audit page keys its sentences on it
|
|
41
|
+
* (`@coffre/ui`, `TEMPLATES`), so an action added without its sentence,
|
|
42
|
+
* or a sentence left for one no writer writes, fails the typecheck.
|
|
43
|
+
*/
|
|
44
|
+
const LOG_ACTIONS = [
|
|
45
|
+
"secret.read",
|
|
46
|
+
"secret.write",
|
|
47
|
+
"secret.loosen",
|
|
48
|
+
"secret.rename",
|
|
49
|
+
"secret.refile",
|
|
50
|
+
"reference.break",
|
|
51
|
+
"missing.dismiss",
|
|
52
|
+
"project.create",
|
|
53
|
+
"project.update",
|
|
54
|
+
"project.archive",
|
|
55
|
+
"project.restore",
|
|
56
|
+
"project.move",
|
|
57
|
+
"project.delete",
|
|
58
|
+
"folder.refile",
|
|
59
|
+
"environment.create",
|
|
60
|
+
"environment.update",
|
|
61
|
+
"environment.archive",
|
|
62
|
+
"environment.restore",
|
|
63
|
+
"environment.delete",
|
|
64
|
+
"environment.protect",
|
|
65
|
+
"environment.unprotect",
|
|
66
|
+
"upstream.freeze",
|
|
67
|
+
"upstream.thaw",
|
|
68
|
+
"member.add",
|
|
69
|
+
"member.restore",
|
|
70
|
+
"member.role",
|
|
71
|
+
"member.remove",
|
|
72
|
+
"access.grant",
|
|
73
|
+
"access.revoke",
|
|
74
|
+
"policy.change",
|
|
75
|
+
"settings.change",
|
|
76
|
+
"sign_in",
|
|
77
|
+
"sign_out",
|
|
78
|
+
"token.create",
|
|
79
|
+
"token.revoke",
|
|
80
|
+
"account.link",
|
|
81
|
+
"account.unlink",
|
|
82
|
+
"device.start",
|
|
83
|
+
"device.approve",
|
|
84
|
+
"device.deny",
|
|
85
|
+
"token.exchange",
|
|
86
|
+
"workload.renew",
|
|
87
|
+
"token.bind",
|
|
88
|
+
"token.unbind",
|
|
89
|
+
"workload.freeze",
|
|
90
|
+
"workload.unfreeze",
|
|
91
|
+
"mcp.connect",
|
|
92
|
+
"mcp.token",
|
|
93
|
+
"mcp.disconnect",
|
|
94
|
+
"oauth.register",
|
|
95
|
+
"mcp.ask",
|
|
96
|
+
"mcp.approve",
|
|
97
|
+
"mcp.deny",
|
|
98
|
+
"upkeep.expire",
|
|
99
|
+
"vault.adopt"
|
|
100
|
+
];
|
|
101
|
+
/**
|
|
45
102
|
* The vault's entries that change what a member holds: what their row's
|
|
46
103
|
* `access_seq` names, and what a finding about them is newer than while it
|
|
47
104
|
* stands.
|
|
@@ -56,17 +113,6 @@ const ACCESS_ACTIONS = [
|
|
|
56
113
|
"access.revoke"
|
|
57
114
|
];
|
|
58
115
|
/**
|
|
59
|
-
* Whether a read hands values back to whoever asked, which a person never
|
|
60
|
-
* gets of a sensitive value: every purpose but the proxy's `use` and a
|
|
61
|
-
* fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
|
|
62
|
-
* `compare` included, which tells them whether a guess was right, and any
|
|
63
|
-
* purpose a later app may name.
|
|
64
|
-
*/
|
|
65
|
-
function handsBack(read) {
|
|
66
|
-
if (read.purpose === "use") return false;
|
|
67
|
-
return !(read.purpose === "copy" && read.keepsSensitive === true);
|
|
68
|
-
}
|
|
69
|
-
/**
|
|
70
116
|
* The longest `UseRecord.metadata` the vault appends, in characters: room for
|
|
71
117
|
* a use naming a few hundred keys. The app appends a longer one itself, under
|
|
72
118
|
* the head, as before 0.14.5.
|
|
@@ -108,5 +154,26 @@ function policyRevision(seq, policy) {
|
|
|
108
154
|
}
|
|
109
155
|
/** A revision as `policyRevision` writes it. */
|
|
110
156
|
const POLICY_REVISION = /^(none|[1-9][0-9]{0,15})\.[0-9a-f]{16}$/;
|
|
157
|
+
/**
|
|
158
|
+
* A role's revision, as a change of it is confirmed with
|
|
159
|
+
* (`policy.change`'s `revision`): a digest of what it holds, its columns in
|
|
160
|
+
* any order, or of none. The app answers it with a change's preview; the
|
|
161
|
+
* vault takes the change only while the role's row still says what was
|
|
162
|
+
* weighed.
|
|
163
|
+
*
|
|
164
|
+
* 9c41e07b5d2a8f13 developer, as it ships
|
|
165
|
+
* 74d0b1e6a9c3f852 no such role
|
|
166
|
+
*/
|
|
167
|
+
function roleRevision(definition) {
|
|
168
|
+
const said = definition === null ? null : [
|
|
169
|
+
definition.name,
|
|
170
|
+
definition.description,
|
|
171
|
+
[...definition.permissions].sort(),
|
|
172
|
+
[...definition.protected].sort()
|
|
173
|
+
];
|
|
174
|
+
return createHash("sha256").update(JSON.stringify(said)).digest("hex").slice(0, 16);
|
|
175
|
+
}
|
|
176
|
+
/** A revision as `roleRevision` writes it. */
|
|
177
|
+
const ROLE_REVISION = /^[0-9a-f]{16}$/;
|
|
111
178
|
//#endregion
|
|
112
|
-
export { ACCESS_ACTIONS, POLICY_REVISION,
|
|
179
|
+
export { ACCESS_ACTIONS, LOG_ACTIONS, POLICY_REVISION, PURPOSES, ROLE_REVISION, USE_METADATA_LENGTH, accessRevision, describeAccessFault, policyRevision, roleRevision };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@coffre/core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.16.0",
|
|
4
4
|
"description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -47,6 +47,11 @@
|
|
|
47
47
|
"types": "./dist/kek.d.ts",
|
|
48
48
|
"default": "./dist/kek.js"
|
|
49
49
|
},
|
|
50
|
+
"./log": {
|
|
51
|
+
"coffre:source": "./src/log/index.ts",
|
|
52
|
+
"types": "./dist/log.d.ts",
|
|
53
|
+
"default": "./dist/log.js"
|
|
54
|
+
},
|
|
50
55
|
"./mcp": {
|
|
51
56
|
"coffre:source": "./src/mcp.ts",
|
|
52
57
|
"types": "./dist/mcp.d.ts",
|
|
@@ -83,14 +88,14 @@
|
|
|
83
88
|
"jose": "6.2.3",
|
|
84
89
|
"oauth4webapi": "3.8.8",
|
|
85
90
|
"zod": "4.4.3",
|
|
86
|
-
"@coffre/client": "0.
|
|
91
|
+
"@coffre/client": "0.16.0"
|
|
87
92
|
},
|
|
88
93
|
"devDependencies": {
|
|
89
94
|
"@hegeldev/hegel": "0.4.7",
|
|
90
95
|
"@types/node": "26.1.1",
|
|
91
96
|
"tsdown": "0.23.0",
|
|
92
97
|
"typescript": "5.9.3",
|
|
93
|
-
"@coffre/conformance": "0.
|
|
98
|
+
"@coffre/conformance": "0.16.0"
|
|
94
99
|
},
|
|
95
100
|
"scripts": {
|
|
96
101
|
"build": "tsdown",
|
package/src/access.ts
CHANGED
|
@@ -135,6 +135,23 @@ export function definitionOf(policy: Policy, role: Role): RoleDefinition | undef
|
|
|
135
135
|
return own(policy.roles, role);
|
|
136
136
|
}
|
|
137
137
|
|
|
138
|
+
/**
|
|
139
|
+
* What a grant's role gives at the grant's place, as `policy` defines it:
|
|
140
|
+
* its definition, but nothing on an environment while the role holds a
|
|
141
|
+
* permission only a project takes (`assignableToEnvironment`), as a
|
|
142
|
+
* credential's scope never holds one there (`isCredentialScope`). Every
|
|
143
|
+
* reading of a grant's role goes through it, so that a role widened past
|
|
144
|
+
* what its environment grants take, around a grant hidden from the
|
|
145
|
+
* widening, gives that grant nothing until it is narrowed back:
|
|
146
|
+
*
|
|
147
|
+
* Eve: viewer-plus on market/dev reads market/dev
|
|
148
|
+
* viewer-plus widened to grant.manage Eve holds nothing at market/dev
|
|
149
|
+
*/
|
|
150
|
+
export function grantDefinition(policy: Policy, grant: GrantPlace & { role: Role }): RoleDefinition | undefined {
|
|
151
|
+
if (grant.environmentId != null && !assignableToEnvironment(grant.role, policy)) return undefined;
|
|
152
|
+
return definitionOf(policy, grant.role);
|
|
153
|
+
}
|
|
154
|
+
|
|
138
155
|
/** A record's own value at `key`: `constructor` or `__proto__` names nothing. */
|
|
139
156
|
function own<T>(record: Readonly<Record<string, T>>, key: string): T | undefined {
|
|
140
157
|
return Object.hasOwn(record, key) ? record[key] : undefined;
|
|
@@ -483,7 +500,7 @@ export type ScopeGrant = GrantPlace & { role: Role; permissions?: Columns; sensi
|
|
|
483
500
|
* Developer widened to read in prod the token still only uses prod
|
|
484
501
|
*/
|
|
485
502
|
export function issuedGrant(grant: GrantPlace & { role: Role }, policy: Policy = DEFAULT_POLICY, held?: Columns): ScopeGrant {
|
|
486
|
-
const definition =
|
|
503
|
+
const definition = grantDefinition(policy, grant);
|
|
487
504
|
const within = (column: readonly Permission[] = [], cap?: readonly Permission[]) => (cap === undefined ? [...column] : column.filter((permission) => cap.includes(permission)));
|
|
488
505
|
return {
|
|
489
506
|
projectId: grant.projectId,
|
|
@@ -493,6 +510,26 @@ export function issuedGrant(grant: GrantPlace & { role: Role }, policy: Policy =
|
|
|
493
510
|
};
|
|
494
511
|
}
|
|
495
512
|
|
|
513
|
+
/**
|
|
514
|
+
* Of a grant issued anew and the one it takes the place of, what both
|
|
515
|
+
* hold, column by column, and the sensitive values only if both read them:
|
|
516
|
+
* a binding that replaces others keeps no more than they did, whatever its
|
|
517
|
+
* role holds now (0.14.7's `narrowest`).
|
|
518
|
+
*
|
|
519
|
+
* was viewer on market/dev: read, use / use
|
|
520
|
+
* now viewer, edited since: read / read, use
|
|
521
|
+
* kept read / use
|
|
522
|
+
*/
|
|
523
|
+
export function narrowest(now: ScopeGrant, before: ScopeGrant): ScopeGrant {
|
|
524
|
+
const both = (a: readonly Permission[], b: readonly Permission[]) => a.filter((permission) => b.includes(permission));
|
|
525
|
+
const [a, b] = [scopeDefinition(now), scopeDefinition(before)];
|
|
526
|
+
return {
|
|
527
|
+
...now,
|
|
528
|
+
permissions: { normal: both(a.permissions, b.permissions), protected: both(a.protected, b.protected) },
|
|
529
|
+
...(now.sensitive === undefined ? {} : { sensitive: now.sensitive && before.sensitive === true }),
|
|
530
|
+
};
|
|
531
|
+
}
|
|
532
|
+
|
|
496
533
|
/**
|
|
497
534
|
* What `holder` holds at `place` in each column a credential's grant there
|
|
498
535
|
* keeps (`issuedGrant`): `normal`, as if nothing were protected; `protected`,
|
|
@@ -565,6 +602,13 @@ export const MAX_PERSONAL_TOKEN_MINUTES = 7 * 24 * 60;
|
|
|
565
602
|
*/
|
|
566
603
|
export const DEVICE_TTL_SECONDS = 10 * 60;
|
|
567
604
|
|
|
605
|
+
/**
|
|
606
|
+
* A device login's user code, as the app draws it and the vault takes it:
|
|
607
|
+
* eight letters in two fours, `BCDF-GHJK`, of an alphabet with no vowel, so
|
|
608
|
+
* that a code never spells a word, and no letter that reads as a digit.
|
|
609
|
+
*/
|
|
610
|
+
export const USER_CODE = /^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$/;
|
|
611
|
+
|
|
568
612
|
/**
|
|
569
613
|
* A credential's scope, by path as the API names it, in words, each role
|
|
570
614
|
* with its places: `developer on market/dev, api/dev; viewer on market/prod`.
|
|
@@ -680,7 +724,7 @@ export function allows(holder: Holdings, permission: Permission, place: Place):
|
|
|
680
724
|
if (holder.credentialScope != null && !scopeHolds(holder, permission, place)) return false;
|
|
681
725
|
const policy = holder.policy ?? DEFAULT_POLICY;
|
|
682
726
|
if (inScope(holder.scope, place) && holds(own(policy.instanceRoles, holder.role), permission, place, holder)) return true;
|
|
683
|
-
return holder.grants.some((grant) => covers(grant, place) && holds(
|
|
727
|
+
return holder.grants.some((grant) => covers(grant, place) && holds(grantDefinition(policy, grant), permission, place, holder));
|
|
684
728
|
}
|
|
685
729
|
|
|
686
730
|
/**
|
|
@@ -730,7 +774,8 @@ export type HeldKey = { projectId: string; environmentId: string; secretId: stri
|
|
|
730
774
|
* one its credential's scope lists, by the key's id, on a grant that covers
|
|
731
775
|
* the place where the value is held, never the place a request names. A
|
|
732
776
|
* rename therefore moves no listing, and no reference, fork or copy moves a
|
|
733
|
-
* value under one. Nobody else's:
|
|
777
|
+
* value under one. Nobody else's: for them, whether their role reads where
|
|
778
|
+
* the key lives (the vault's `decide`), and the value's nature.
|
|
734
779
|
* A plain value is no secret, use-only to nobody, so it is never asked of.
|
|
735
780
|
*
|
|
736
781
|
* api-prod lists STRIPE_WEBHOOK_SECRET's id at market/prod
|
|
@@ -834,28 +879,38 @@ export type ServiceSetting = Scope;
|
|
|
834
879
|
* normal column even in a protected environment, so a person there, who
|
|
835
880
|
* holds its protected column, gives none what they do not hold themselves:
|
|
836
881
|
* a Developer of a protected prod, who only uses it, gives no viewer there.
|
|
882
|
+
* A grant on a whole project reaches the environments it protects, so it
|
|
883
|
+
* takes holding the role in each of them too, as 0.14.7 did: a Developer
|
|
884
|
+
* of `market` gives developer on `market` while nothing there is
|
|
885
|
+
* protected, and only environment by environment once prod is (D241).
|
|
837
886
|
*/
|
|
838
887
|
export function givesService(holder: Holdings, setting: ServiceSetting | null, role: Role, place: Place, kept?: RoleDefinition): boolean {
|
|
839
888
|
if (mayManageAccess(holder, place)) return true;
|
|
840
889
|
const policy = holder.policy ?? DEFAULT_POLICY;
|
|
841
890
|
// What the grant holds: its role as the policy defines it, or what a credential kept of it (`issuesCredential`).
|
|
842
|
-
const definition = kept ??
|
|
891
|
+
const definition = kept ?? grantDefinition(policy, { projectId: place.projectId, environmentId: place.environmentId ?? null, role });
|
|
843
892
|
// A role that holds nothing is given by whoever manages access there alone: by anyone else, it would be a grant an
|
|
844
893
|
// Owner could fill in later, and under a policy the vault cannot read, every role but Owner's holds nothing.
|
|
845
894
|
if (definition === undefined || definition.permissions.length === 0) return false;
|
|
846
895
|
if (setting === null || holder.credentialScope != null || !inScope(setting, place)) return false;
|
|
847
896
|
if (!definition.permissions.every((permission) => allows(holder, permission, place))) return false;
|
|
848
897
|
// A grant on a whole project reaches its protected environments too, where the service holds the role's normal column:
|
|
849
|
-
// the person giving it holds that there as well, or gives none.
|
|
898
|
+
// the person giving it holds that there as well, or gives none. Those the decision's rows protect, as 0.14.7 weighed
|
|
899
|
+
// them: an environment's row a database writer hides from it goes unweighed (D241, docs/design/0.16.md).
|
|
850
900
|
const inEnvironments = definition.permissions.filter((permission) => !PROJECT_ONLY_PERMISSIONS.includes(permission));
|
|
851
901
|
return protectedWithin(policy, place).every((there) => inEnvironments.every((permission) => allows(holder, permission, there)));
|
|
852
902
|
}
|
|
853
903
|
|
|
854
|
-
/**
|
|
904
|
+
/**
|
|
905
|
+
* Whether `holder` gives a service account anything anywhere among
|
|
906
|
+
* `places`: whether they set any up. Where they manage access, they give
|
|
907
|
+
* any role; elsewhere, one of those `holder.policy` defines, which must
|
|
908
|
+
* then be every role, not only those they hold.
|
|
909
|
+
*/
|
|
855
910
|
export function setsUpServices(holder: Holdings, setting: ServiceSetting | null, places: readonly Place[]): boolean {
|
|
856
911
|
if (runsInstance(holder)) return true;
|
|
857
912
|
const roles = Object.keys((holder.policy ?? DEFAULT_POLICY).roles);
|
|
858
|
-
return places.some((place) => roles.some((role) => givesService(holder, setting, role, place)));
|
|
913
|
+
return places.some((place) => mayManageAccess(holder, place) || roles.some((role) => givesService(holder, setting, role, place)));
|
|
859
914
|
}
|
|
860
915
|
|
|
861
916
|
/** A service account as `managesService` weighs it: its live grants, where they are, and who admitted it. */
|
|
@@ -903,7 +958,7 @@ export function issuesCredential(
|
|
|
903
958
|
const policy = holder.policy ?? DEFAULT_POLICY;
|
|
904
959
|
const held: Holdings = { ...NOTHING, policy, service: true, grants: account.grants.map(({ role, place }) => ({ projectId: place.projectId, environmentId: place.environmentId ?? null, role })) };
|
|
905
960
|
return scope.every(({ role, place, kept }) => givesService(holder, setting, role, place, kept)
|
|
906
|
-
&& ((kept ??
|
|
961
|
+
&& ((kept ?? grantDefinition(policy, { projectId: place.projectId, environmentId: place.environmentId ?? null, role }))?.permissions.every((permission) => allows(held, permission, place)) ?? false));
|
|
907
962
|
}
|
|
908
963
|
|
|
909
964
|
/**
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import type { Filter, InstanceRole, Role, RoleDefinition, Scope } from '../access.ts';
|
|
2
|
+
import type { AccessChange } from '../vault.ts';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The changes of members, grants, roles and the instance's policy
|
|
6
|
+
* (`packages/vault/src/ops/access.ts`). A workload's session makes none of
|
|
7
|
+
* them, whatever its scope holds (`workload_cannot_issue`), as 0.14 refused.
|
|
8
|
+
*/
|
|
9
|
+
export type AccessChanges = MemberPut | MemberRemove | AccessGrant | RoleEdit | SettingsEdit;
|
|
10
|
+
|
|
11
|
+
export type AccessAnswers = {
|
|
12
|
+
/** 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. */
|
|
13
|
+
'member.put': Standing & { created: boolean };
|
|
14
|
+
/**
|
|
15
|
+
* How many grants went with them (`revoked`), and how many ways in the
|
|
16
|
+
* removal ended, as they stood when it was made: sign-in accounts it
|
|
17
|
+
* revoked, and, of their generation, live sessions (browser and CLI),
|
|
18
|
+
* tokens (every other credential but an MCP connection's) and connected
|
|
19
|
+
* apps (an MCP connection its client redeemed), which the generation's
|
|
20
|
+
* move ends; and whether the caller runs the instance (`runs`), as the
|
|
21
|
+
* change found them: the leaver's report is theirs to read.
|
|
22
|
+
*/
|
|
23
|
+
'member.remove': { revoked: number; sessions: number; tokens: number; identities: number; apps: number; runs: boolean };
|
|
24
|
+
/** What became of each place, in the order asked; with `admit`, whether this change admitted the service account. */
|
|
25
|
+
'access.grant': { changes: AccessChange[]; created?: boolean };
|
|
26
|
+
/** The role as it is now: null once deleted. */
|
|
27
|
+
'policy.change': { role: RoleDefinition | null };
|
|
28
|
+
/** The setting as the row holds it, projects by id. */
|
|
29
|
+
'settings.change': { serviceAccounts: Scope };
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
export type Standing = { role: InstanceRole; scope: Scope | null };
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Where a person's instance role applies, as the app names it: projects by
|
|
36
|
+
* slug, which the vault keeps by id, so a rename keeps them; environments by
|
|
37
|
+
* slug, those of every project. Each list holds 1,000 slugs at most. Null is
|
|
38
|
+
* everywhere.
|
|
39
|
+
*/
|
|
40
|
+
export type ScopeInput = { projects: Filter; environments: Filter };
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* A member admitted, brought back or given an instance role
|
|
44
|
+
* (`member.put`), whichever their row calls for, as 0.14.7's `admit` did:
|
|
45
|
+
* the app cannot know which without reading the row, and only the vault's
|
|
46
|
+
* read can. Its entry is the action that happened:
|
|
47
|
+
*
|
|
48
|
+
* no row `member.add`, as `role`, or `member` when null
|
|
49
|
+
* removed `member.restore`, the same, in the generation their removal moved on to, with no grant
|
|
50
|
+
* active `member.role`, `unchanged` when nothing moves; a null role keeps their role and scope
|
|
51
|
+
*
|
|
52
|
+
* Whoever runs the instance puts a member; only an Owner of the whole
|
|
53
|
+
* instance makes an Owner, changes one, or changes their own role; the last
|
|
54
|
+
* Owner of the whole instance stays one (`last_owner`), and one the
|
|
55
|
+
* deployment names comes in and stays as one (`configured_owner`). A
|
|
56
|
+
* service account holds no instance role but `member`: asked one, refused
|
|
57
|
+
* `invalid`. A person who does not run the instance, on a session, sets up
|
|
58
|
+
* a service account, as `member`, where they could give it something
|
|
59
|
+
* (`setsUpServices`), and brings back one they removed. A refused put is
|
|
60
|
+
* logged as `member.add`, as 0.14.7 logged it.
|
|
61
|
+
*
|
|
62
|
+
* A member, by principal: a person, `user:<email>` in lowercase, or a
|
|
63
|
+
* service account, `token:<name>`, 256 characters at most. `scope` is where
|
|
64
|
+
* the role applies, given only with a role but `member`, which holds
|
|
65
|
+
* nothing. Past these the call is a fault, not a refusal: the app checks
|
|
66
|
+
* them first.
|
|
67
|
+
*/
|
|
68
|
+
export type MemberPut = { op: 'member.put'; principal: string; role: InstanceRole | null; scope: ScopeInput | null };
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Remove a member: their grants go, their sign-in accounts are revoked, and
|
|
72
|
+
* their generation moves on, which ends every session, token and binding
|
|
73
|
+
* issued before. Whoever runs the instance removes a member; a person on a
|
|
74
|
+
* session, a service account they manage (`managesService`).
|
|
75
|
+
*/
|
|
76
|
+
export type MemberRemove = { op: 'member.remove'; principal: string };
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* A person's roles at projects and environments, set, changed, given an end
|
|
80
|
+
* or taken away: all of the places or none, each once. A place is a
|
|
81
|
+
* project's slug, or one of its environments' too, which takes a role that
|
|
82
|
+
* holds nothing only a project has (`PROJECT_ONLY_PERMISSIONS`). A role is
|
|
83
|
+
* a project role's id, or null to revoke; `expiresAt` an ISO 8601 time
|
|
84
|
+
* after the change, or null for no end. Whoever manages access at each
|
|
85
|
+
* place (`grant.manage`) gives anything there but to themselves; they may
|
|
86
|
+
* give up their own. A grant is of the member's generation: one left from
|
|
87
|
+
* before a removal is replaced in place. Refused `no_access` where a place
|
|
88
|
+
* is not there or not theirs; to whoever manages every place asked,
|
|
89
|
+
* `not_a_member`, `removed`, and `invalid` for a role there is not, a
|
|
90
|
+
* project's on an environment or an end gone.
|
|
91
|
+
*
|
|
92
|
+
* A service account's grants, where the caller does not manage access: a
|
|
93
|
+
* person on a session gives it what they could give it (`givesService`),
|
|
94
|
+
* and takes away what it holds, if they manage it (`managesService`): they
|
|
95
|
+
* could give it all it holds. `admit` admits it in the same change when
|
|
96
|
+
* it is not a member, or brings it back, all or none, as 0.14.7's
|
|
97
|
+
* `setAccess` did: by someone who could set one up (`setsUpServices`), it
|
|
98
|
+
* holds nothing before and is theirs; one removed, only its remover or
|
|
99
|
+
* whoever runs the instance brings back. A row these weigh that the vault
|
|
100
|
+
* did not write refuses, `tampered`. 1 to 1,000 places; past the shapes
|
|
101
|
+
* above, or `admit` of a person, the call is a fault, not a refusal: the
|
|
102
|
+
* app checks them first. `was`, given, is the grant the member holds at
|
|
103
|
+
* the place as an approval page showed it, or null for none: a live grant
|
|
104
|
+
* of their generation, as the member list has it. One that differs when
|
|
105
|
+
* the vault writes refuses `stale`, and nothing is changed.
|
|
106
|
+
*/
|
|
107
|
+
export type AccessGrant = {
|
|
108
|
+
op: 'access.grant';
|
|
109
|
+
principal: string;
|
|
110
|
+
changes: { project: string; environment: string | null; role: Role | null; expiresAt: string | null; was?: { role: Role; expiresAt: string | null } | null }[];
|
|
111
|
+
admit?: boolean;
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* A role defined, edited, put back or deleted (`policy.change`), by an
|
|
116
|
+
* Owner of the whole instance on a session, as 0.14 allowed: a project role
|
|
117
|
+
* (`instance` false), one that ships or one an Owner makes, or one of the
|
|
118
|
+
* instance's that ships (Admin, Auditor). Owner, and the instance's Member,
|
|
119
|
+
* are never edited. `definition` null puts a role that ships back as it
|
|
120
|
+
* ships, and deletes one an Owner made, refused `role_granted` while a
|
|
121
|
+
* grant names it, as is defining one that does not ship and is not there.
|
|
122
|
+
* A project role that holds what only a project has
|
|
123
|
+
* (`PROJECT_ONLY_PERMISSIONS`) is refused `invalid` while a grant on an
|
|
124
|
+
* environment names it, as is deleting a role that is not there.
|
|
125
|
+
* `revision` is the role as its preview weighed it (`roleRevision`), none
|
|
126
|
+
* included: one that changed since is refused `policy_changed`, so that a
|
|
127
|
+
* change is made from the role its preview was. Left out, the change is
|
|
128
|
+
* made from the role as it is. An id is a role's as `ROLE_ID` has it; a
|
|
129
|
+
* definition one `definitionProblem` passes; a revision one
|
|
130
|
+
* `ROLE_REVISION` matches: past those the call is a fault, not a refusal:
|
|
131
|
+
* the app checks them first.
|
|
132
|
+
*/
|
|
133
|
+
export type RoleEdit = { op: 'policy.change'; instance: boolean; role: Role; definition: RoleDefinition | null; revision?: string };
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Where people set up service accounts themselves (`settings.change`,
|
|
137
|
+
* `ServiceSetting`): projects and environments by slug, 1,000 a list at
|
|
138
|
+
* most. Whoever runs the instance sets it, as 0.14 allowed.
|
|
139
|
+
*/
|
|
140
|
+
export type SettingsEdit = { op: 'settings.change'; serviceAccounts: ScopeInput };
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A workload's use stopped at its next request, and let go again
|
|
3
|
+
* (`packages/vault/src/ops/freezes.ts`, docs/design/workload-access.md,
|
|
4
|
+
* 8.2): a freeze is a field of the row it stops, and keeps the sessions,
|
|
5
|
+
* codes and bindings under it, so lifting it restores service with no new
|
|
6
|
+
* sign-in. An upstream credential's is its environment's
|
|
7
|
+
* (`upstream.freeze`, `upstream.thaw`).
|
|
8
|
+
*/
|
|
9
|
+
export type FreezeChanges = WorkloadFreeze | WorkloadUnfreeze;
|
|
10
|
+
|
|
11
|
+
export type FreezeAnswers = {
|
|
12
|
+
/** The target in its one spelling, and since when it is frozen: a freeze already there is kept, with its time. */
|
|
13
|
+
'workload.freeze': Frozen;
|
|
14
|
+
/** The target in its one spelling, and null: it is not frozen now. */
|
|
15
|
+
'workload.unfreeze': Frozen;
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
export type Frozen = { target: string; frozenAt: string | null };
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* What a freeze names, as `freezeTarget` spells it, and who freezes and
|
|
22
|
+
* lifts it:
|
|
23
|
+
*
|
|
24
|
+
* instance every workload's use an Owner of the whole instance, on a session
|
|
25
|
+
* token:<name> one service account's whoever manages it (`managesService`)
|
|
26
|
+
* binding:<uuid> one of its trust bindings the same
|
|
27
|
+
* session:<uuid> one workload's session the same
|
|
28
|
+
*
|
|
29
|
+
* Refused `no_access` where the target is not there (a service account
|
|
30
|
+
* removed, a binding revoked, a session ended or of another generation)
|
|
31
|
+
* or not theirs, one answer; `tampered` where a row the decision weighs
|
|
32
|
+
* was written behind the vault; `workload_cannot_issue` to a workload's
|
|
33
|
+
* session. A target in another spelling, or `credential:…`, is a fault:
|
|
34
|
+
* the app canonicalizes it first. `reason` is why, 1 to 400 characters,
|
|
35
|
+
* which the entry keeps.
|
|
36
|
+
*/
|
|
37
|
+
export type WorkloadFreeze = { op: 'workload.freeze'; target: string; reason: string };
|
|
38
|
+
|
|
39
|
+
/** A freeze lifted: by whoever may make it, as `WorkloadFreeze` says. */
|
|
40
|
+
export type WorkloadUnfreeze = { op: 'workload.unfreeze'; target: string };
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import type { McpScope } from '../mcp.ts';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The changes of MCP connections and of the OAuth clients that make them
|
|
5
|
+
* (`packages/vault/src/ops/mcp.ts`, docs/design/0.16.md, "MCP
|
|
6
|
+
* connections"). A connection is a credential of kind `mcp` of the person
|
|
7
|
+
* who approved it: its row holds the code until the client redeems it, then
|
|
8
|
+
* the refresh token. Each access token is a credential of its own, of an
|
|
9
|
+
* hour, under it (`ancestors`): it stands while its connection does, so
|
|
10
|
+
* ending the connection ends them all, with no write of theirs.
|
|
11
|
+
*/
|
|
12
|
+
export type McpChanges = McpConnect | McpToken | McpRevoke | OauthRegister | McpAsk | McpDecide;
|
|
13
|
+
|
|
14
|
+
export type McpAnswers = {
|
|
15
|
+
/** The connection, and when its code stops being good, ISO 8601. */
|
|
16
|
+
'mcp.connect': { connection: string; expiresAt: string };
|
|
17
|
+
/**
|
|
18
|
+
* The tokens made: the access token's credential, its member, when it
|
|
19
|
+
* ends (ISO 8601), and the scopes it holds. Or, for a code or a refresh
|
|
20
|
+
* token presented again, the connection it ended (`ended`), which the
|
|
21
|
+
* app answers `invalid_grant`.
|
|
22
|
+
*/
|
|
23
|
+
'mcp.token': { ended: false; principal: string; connection: string; credential: string; expiresAt: string; scopes: McpScope[] } | { ended: true; connection: string };
|
|
24
|
+
/** The connection ended. */
|
|
25
|
+
'mcp.revoke': { connection: string };
|
|
26
|
+
/** The client registered, and when, ISO 8601. */
|
|
27
|
+
'oauth.register': { client: string; createdAt: string };
|
|
28
|
+
/** The approval opened, and when it expires, ISO 8601. */
|
|
29
|
+
'mcp.ask': { approval: string; expiresAt: string };
|
|
30
|
+
/** The approval decided. */
|
|
31
|
+
'mcp.decide': { approval: string };
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* The changes nobody asks: a client redeems or gives back what it holds (a
|
|
36
|
+
* code with its PKCE verifier, a refresh token, an access token), and anyone
|
|
37
|
+
* may register a client.
|
|
38
|
+
*/
|
|
39
|
+
export type McpUnasked = 'mcp.token' | 'mcp.revoke' | 'oauth.register';
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* A client as the person approved it: its id (a metadata document's URL,
|
|
43
|
+
* or a registration's id), its name and host as the consent page showed
|
|
44
|
+
* them, how it is known (`cimd`, a document the app fetched; `dcr`, a
|
|
45
|
+
* registration, whose row the vault reads and holds the redirect and the
|
|
46
|
+
* name to), and the redirect the code goes to.
|
|
47
|
+
*/
|
|
48
|
+
export type McpClient = { id: string; name: string; host: string | null; registration: 'cimd' | 'dcr'; redirectUri: string };
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* A person, on a session of theirs, approves an MCP client
|
|
52
|
+
* (`POST /oauth/authorizations`): a connection, whose code the client
|
|
53
|
+
* redeems within a minute (`CODE_SECONDS`) with its PKCE verifier. The app
|
|
54
|
+
* draws the code and sends its SHA-256 (`code`), with the S256 challenge
|
|
55
|
+
* the client sent (`challenge`, RFC 7636) and the scopes the person ticked
|
|
56
|
+
* (`read` always among them).
|
|
57
|
+
*
|
|
58
|
+
* A token, a workload's session or an MCP connection is refused
|
|
59
|
+
* `no_access`: a personal token connecting one would make a connection
|
|
60
|
+
* with all its person holds. A person with `MAX_CONNECTIONS` connections
|
|
61
|
+
* that stand, codes waiting included, is refused `too_many_connections`.
|
|
62
|
+
* A registered client (`dcr`) is its row's: refused `unknown_client` for
|
|
63
|
+
* one not there, or revoked, and `wrong_redirect` for a redirect it did not
|
|
64
|
+
* register; its name is the row's, whatever the app says.
|
|
65
|
+
*/
|
|
66
|
+
export type McpConnect = { op: 'mcp.connect'; client: McpClient; scopes: McpScope[]; code: string; challenge: string };
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* A client redeems what it holds for an access token and the next refresh
|
|
70
|
+
* token (`POST /api/oauth/token`). The app draws both and sends their
|
|
71
|
+
* SHA-256 (`tokens`). The access token lasts an hour
|
|
72
|
+
* (`ACCESS_TOKEN_MINUTES`), never past its connection.
|
|
73
|
+
*
|
|
74
|
+
* - `authorization_code`: the code's SHA-256, its PKCE verifier and the
|
|
75
|
+
* redirect it was sent to, within its minute. The connection then lasts
|
|
76
|
+
* `minutes` (365 days at most), and the person's earlier connections of
|
|
77
|
+
* the same client that it grants all of and more end (`supersedes` in
|
|
78
|
+
* @coffre/core/mcp).
|
|
79
|
+
* - `refresh_token`: the refresh token's SHA-256, and the scopes the client
|
|
80
|
+
* narrows the access token to, or null for all the connection holds.
|
|
81
|
+
*
|
|
82
|
+
* Refused, writing nothing: `unknown_grant` for a code or a refresh token
|
|
83
|
+
* that is not there, or whose connection ended; `expired`, a code past its
|
|
84
|
+
* minute or a connection past its end; `wrong_client`, `wrong_redirect`,
|
|
85
|
+
* `wrong_verifier`; `invalid_scope` for a refresh that widens; `deactivated`
|
|
86
|
+
* for a person removed since they connected it; `tampered` for a row
|
|
87
|
+
* written behind the vault; `adopting` before the vault adopted the
|
|
88
|
+
* database. A code or a refresh token presented after it was replaced is a
|
|
89
|
+
* copy someone else holds: the connection ends, in a change that is made
|
|
90
|
+
* (`ended: true`), since a refusal writes nothing.
|
|
91
|
+
*/
|
|
92
|
+
export type McpToken = { op: 'mcp.token'; client: string; tokens: { access: string; refresh: string } } & (
|
|
93
|
+
| { grant: 'authorization_code'; code: string; verifier: string; redirectUri: string; minutes: number }
|
|
94
|
+
| { grant: 'refresh_token'; refresh: string; scopes: McpScope[] | null }
|
|
95
|
+
);
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* A client gives back a token it holds (RFC 7009, `POST /api/oauth/revoke`):
|
|
99
|
+
* its refresh token or one of its access tokens, by its SHA-256 (`token`),
|
|
100
|
+
* and its `client_id` when it sent one (`client`). Its connection ends, and
|
|
101
|
+
* every access token under it, as a disconnect does. Nobody asks it but
|
|
102
|
+
* whoever holds the token.
|
|
103
|
+
*
|
|
104
|
+
* Refused, writing nothing, which the endpoint answers as a success, as
|
|
105
|
+
* RFC 7009 has it: `unknown_grant` for a token that is no connection's
|
|
106
|
+
* refresh token nor an access token that stands, whose connection ended
|
|
107
|
+
* already, or that is another client's; `tampered` for a row written
|
|
108
|
+
* behind the vault; `adopting` before the vault adopted the database.
|
|
109
|
+
*/
|
|
110
|
+
export type McpRevoke = { op: 'mcp.revoke'; token: string; client: string | null };
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Anyone registers a client (RFC 7591, `POST /api/oauth/register`): a
|
|
114
|
+
* public one, its name as it claims it and the redirects the app kept
|
|
115
|
+
* (`registrationRedirects` in @coffre/core/mcp). The app's limiter counts
|
|
116
|
+
* who asks; the table holds `MAX_CLIENTS` rows at most, refused `full`
|
|
117
|
+
* past that, and the vault's upkeep deletes those no connection names a
|
|
118
|
+
* week after they were made. Its entry ages out.
|
|
119
|
+
*/
|
|
120
|
+
export type OauthRegister = { op: 'oauth.register'; name: string; redirectUris: string[] };
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* An MCP client asks for a change, on its access token (`tools/call`): an
|
|
124
|
+
* approval, pending for `APPROVAL_SECONDS`, which its person decides on
|
|
125
|
+
* coffre's page. `arguments` is the tool's, as canonical JSON (keys
|
|
126
|
+
* sorted); the vault keeps them in the row, and the SHA-256 of
|
|
127
|
+
* `[tool, arguments]` beside them (`digest`), which the page sends back.
|
|
128
|
+
* The entry names the tool, the `place` it is about
|
|
129
|
+
* (`project/environment/KEY`, or less) and the digest, never the
|
|
130
|
+
* arguments: they are the client's text. Nothing changes until the person
|
|
131
|
+
* approves it, as theirs (`ForConnection`).
|
|
132
|
+
*
|
|
133
|
+
* Refused, writing nothing: `unauthenticated` for a token that is no MCP
|
|
134
|
+
* access token that stands; `full` for a connection with `MAX_PENDING`
|
|
135
|
+
* approvals waiting, which only their person's decision or their expiry
|
|
136
|
+
* frees; `pending` for one waiting already for the same call, which the
|
|
137
|
+
* app joins.
|
|
138
|
+
*/
|
|
139
|
+
export type McpAsk = { op: 'mcp.ask'; tool: string; arguments: string; place: string | null };
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* A person, on their browser session, denies an approval, or approves one
|
|
143
|
+
* whose tool changes nothing (`MCP_SHOWS`): the page showed them the value
|
|
144
|
+
* first. `digest` is the one the page rendered. Every other approval is
|
|
145
|
+
* approved by its change (`ForConnection`). Refused `unknown_approval` for
|
|
146
|
+
* one that is not pending (decided, or expired by the time its write
|
|
147
|
+
* starts), not of this digest, or not theirs; `disconnected` for one whose
|
|
148
|
+
* connection no longer stands.
|
|
149
|
+
*/
|
|
150
|
+
export type McpDecide = { op: 'mcp.decide'; approval: string; approve: boolean; digest: string };
|