@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.
Files changed (56) hide show
  1. package/README.md +1 -1
  2. package/dist/{access-BrdZKp1d.js → access-CF8UG59J.js} +70 -8
  3. package/dist/{access-qkMZa-6Z.d.ts → access-ERdGGHG7.d.ts} +45 -3
  4. package/dist/access.d.ts +2 -2
  5. package/dist/access.js +2 -2
  6. package/dist/envelope.d.ts +28 -9
  7. package/dist/envelope.js +25 -8
  8. package/dist/identity.d.ts +2 -917
  9. package/dist/identity.js +1036 -525
  10. package/dist/index-DuG9p3GH.d.ts +1233 -0
  11. package/dist/kek.d.ts +10 -16
  12. package/dist/kek.js +26 -41
  13. package/dist/log.d.ts +114 -0
  14. package/dist/log.js +291 -0
  15. package/dist/mcp.d.ts +25 -1
  16. package/dist/mcp.js +29 -4
  17. package/dist/recipe-BgJpmJum.d.ts +128 -0
  18. package/dist/recipe.d.ts +2 -127
  19. package/dist/{registry-D7X-x202.d.ts → registry-B7_LUDsJ.d.ts} +30 -5
  20. package/dist/schemas.d.ts +14 -4
  21. package/dist/schemas.js +16 -4
  22. package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
  23. package/dist/vault.d.ts +1800 -299
  24. package/dist/vault.js +99 -32
  25. package/package.json +8 -3
  26. package/src/access.ts +63 -8
  27. package/src/changes/access.ts +140 -0
  28. package/src/changes/freezes.ts +40 -0
  29. package/src/changes/mcp.ts +150 -0
  30. package/src/changes/places.ts +219 -0
  31. package/src/changes/secrets.ts +235 -0
  32. package/src/changes/signin.ts +197 -0
  33. package/src/changes/workloads.ts +166 -0
  34. package/src/context.ts +18 -2
  35. package/src/envelope.ts +35 -12
  36. package/src/identity/auth.ts +11 -3
  37. package/src/identity/aws.ts +62 -0
  38. package/src/identity/github-app.ts +45 -24
  39. package/src/identity/index.ts +3 -0
  40. package/src/identity/profiles.ts +139 -0
  41. package/src/identity/proofs.ts +306 -0
  42. package/src/identity/signin/config.ts +1 -1
  43. package/src/identity/tokens.ts +10 -3
  44. package/src/identity/verifier.ts +73 -14
  45. package/src/identity/workload-token.ts +4 -0
  46. package/src/kek/aws-kms.ts +18 -13
  47. package/src/kek/check.ts +16 -46
  48. package/src/kek/index.ts +2 -2
  49. package/src/kek/types.ts +15 -3
  50. package/src/log/index.ts +7 -0
  51. package/src/log/tiles.ts +166 -0
  52. package/src/log/tree.ts +163 -0
  53. package/src/mcp.ts +34 -3
  54. package/src/schemas.ts +16 -2
  55. package/src/vault.ts +308 -276
  56. 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, USE_METADATA_LENGTH, accessRevision, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision, verifyCheckpoint };
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.14.7",
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.14.7"
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.14.7"
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 = definitionOf(policy, grant.role);
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(definitionOf(policy, grant.role), permission, place, holder));
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: their roles and the value's nature decide.
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 ?? definitionOf(policy, role);
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
- /** Whether `holder` gives a service account anything anywhere among `places`: whether they set any up. */
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 ?? definitionOf(policy, role))?.permissions.every((permission) => allows(held, permission, place)) ?? false));
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 };