@coffre/core 0.15.0 → 0.16.1

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 (70) hide show
  1. package/README.md +1 -1
  2. package/dist/{access-CgQTlUMz.js → access-CF8UG59J.js} +70 -95
  3. package/dist/{access-DqLJjnLM.d.ts → access-ERdGGHG7.d.ts} +45 -64
  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 +3 -1018
  9. package/dist/identity.js +885 -623
  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 +27 -4
  16. package/dist/mcp.js +31 -10
  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 +11 -9
  21. package/dist/schemas.js +16 -14
  22. package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
  23. package/dist/vault.d.ts +1771 -1419
  24. package/dist/vault.js +96 -302
  25. package/dist/{workloads-D049JH0M.d.ts → workloads-CW2dK4AW.d.ts} +1 -9
  26. package/dist/workloads.d.ts +2 -2
  27. package/dist/workloads.js +1 -9
  28. package/package.json +7 -7
  29. package/src/access.ts +63 -95
  30. package/src/changes/access.ts +140 -0
  31. package/src/changes/freezes.ts +40 -0
  32. package/src/changes/mcp.ts +150 -0
  33. package/src/changes/places.ts +219 -0
  34. package/src/changes/secrets.ts +235 -0
  35. package/src/changes/signin.ts +197 -0
  36. package/src/changes/workloads.ts +166 -0
  37. package/src/context.ts +18 -2
  38. package/src/envelope.ts +35 -12
  39. package/src/identity/auth.ts +11 -3
  40. package/src/identity/aws.ts +62 -0
  41. package/src/identity/github-app.ts +45 -24
  42. package/src/identity/index.ts +3 -2
  43. package/src/identity/{profile-rules.ts → profiles.ts} +1 -9
  44. package/src/identity/proofs.ts +306 -0
  45. package/src/identity/signin/config.ts +1 -1
  46. package/src/identity/tokens.ts +10 -3
  47. package/src/identity/verifier.ts +73 -14
  48. package/src/identity/workload-token.ts +4 -0
  49. package/src/identity/workloads.ts +0 -11
  50. package/src/kek/aws-kms.ts +18 -13
  51. package/src/kek/check.ts +16 -46
  52. package/src/kek/index.ts +2 -2
  53. package/src/kek/types.ts +15 -3
  54. package/src/log/index.ts +7 -0
  55. package/src/{audit → log}/tiles.ts +18 -49
  56. package/src/{audit → log}/tree.ts +2 -2
  57. package/src/mcp.ts +36 -9
  58. package/src/schemas.ts +15 -12
  59. package/src/vault.ts +251 -1150
  60. package/dist/merkle.d.ts +0 -456
  61. package/dist/merkle.js +0 -964
  62. package/src/answers.ts +0 -209
  63. package/src/audit/leaf.ts +0 -81
  64. package/src/audit/merkle.ts +0 -13
  65. package/src/audit/note.ts +0 -187
  66. package/src/audit/pair.ts +0 -86
  67. package/src/audit/verify.ts +0 -393
  68. package/src/audit/witness.ts +0 -50
  69. package/src/checkpoint.ts +0 -22
  70. package/src/identity/run-proof.ts +0 -159
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`,
@@ -552,21 +589,6 @@ export function delegableRoles(policy: Policy = DEFAULT_POLICY): Role[] {
552
589
  /** The roles a personal token's scope may name, as they ship. */
553
590
  export const DELEGABLE_ROLES: readonly Role[] = delegableRoles();
554
591
 
555
- /** What a handle reads and uses, and no more: it writes nothing. */
556
- export const HANDLE_HOLDS: RoleDefinition = { name: 'Handle', description: 'Read and use, as its person does.', permissions: ['secret.read', 'secret.use'], protected: ['secret.read', 'secret.use'] };
557
-
558
- /**
559
- * The roles a handle's scope is issued under (the server's `issueHandle`; the vault holds a handle's columns to them, T149): each place
560
- * keeps what its person holds there, in each column, of reading and using
561
- * (`issuedGrant`, capped by `heldColumns`), whatever an Owner made of the
562
- * roles. `viewer` names a place its person reads, `contributor` one they
563
- * only use.
564
- *
565
- * an Owner, at a protected prod read, use / read, use
566
- * a Developer, at the same read, use / use
567
- */
568
- export const HANDLE_POLICY: Policy = { ...DEFAULT_POLICY, roles: { ...ROLES, viewer: HANDLE_HOLDS, contributor: HANDLE_HOLDS } };
569
-
570
592
  /**
571
593
  * The longest a personal token lasts: a week. It is for an afternoon's
572
594
  * script or agent, and whoever needs it longer makes another, as a person,
@@ -574,15 +596,19 @@ export const HANDLE_POLICY: Policy = { ...DEFAULT_POLICY, roles: { ...ROLES, vie
574
596
  */
575
597
  export const MAX_PERSONAL_TOKEN_MINUTES = 7 * 24 * 60;
576
598
 
577
- /** The longest a service account's token lives, in days. The vault holds an issue to it (T149). */
578
- export const MAX_SERVICE_TOKEN_DAYS = 366;
579
-
580
599
  /**
581
600
  * How long a `coffre login` code waits to be approved. The server expires it
582
601
  * then, and the CLI's sign-in hint says so before it has asked for one.
583
602
  */
584
603
  export const DEVICE_TTL_SECONDS = 10 * 60;
585
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
+
586
612
  /**
587
613
  * A credential's scope, by path as the API names it, in words, each role
588
614
  * with its places: `developer on market/dev, api/dev; viewer on market/prod`.
@@ -698,7 +724,7 @@ export function allows(holder: Holdings, permission: Permission, place: Place):
698
724
  if (holder.credentialScope != null && !scopeHolds(holder, permission, place)) return false;
699
725
  const policy = holder.policy ?? DEFAULT_POLICY;
700
726
  if (inScope(holder.scope, place) && holds(own(policy.instanceRoles, holder.role), permission, place, holder)) return true;
701
- 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));
702
728
  }
703
729
 
704
730
  /**
@@ -748,7 +774,8 @@ export type HeldKey = { projectId: string; environmentId: string; secretId: stri
748
774
  * one its credential's scope lists, by the key's id, on a grant that covers
749
775
  * the place where the value is held, never the place a request names. A
750
776
  * rename therefore moves no listing, and no reference, fork or copy moves a
751
- * 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.
752
779
  * A plain value is no secret, use-only to nobody, so it is never asked of.
753
780
  *
754
781
  * api-prod lists STRIPE_WEBHOOK_SECRET's id at market/prod
@@ -809,75 +836,6 @@ export function scopeWithReads(
809
836
  return result;
810
837
  }
811
838
 
812
- /**
813
- * A scope as a token's or binding's row stores it, under its MAC: its
814
- * grants as JSON, by place, each with what its role held when it was
815
- * issued (`issuedGrant`), so that a role widened later widens no credential,
816
- * and, a service's, whether it reads the sensitive values there.
817
- */
818
- export function storedScope(scope: CredentialScope, { reads = false }: { reads?: boolean } = {}): string {
819
- const key = (grant: CredentialScope[number]) => `${grant.projectId}/${grant.environmentId ?? ''}`;
820
- return JSON.stringify(
821
- [...scope]
822
- .sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0))
823
- .map((grant) => {
824
- const { permissions, protected: guarded } = scopeDefinition(grant);
825
- return {
826
- projectId: grant.projectId,
827
- environmentId: grant.environmentId,
828
- role: grant.role,
829
- permissions: { normal: [...permissions], protected: [...guarded] },
830
- ...(grant.sensitive === undefined ? {} : { sensitive: grant.sensitive }),
831
- // A workload session's, with 0.15's log: the keys its binding lets it read, which its object holds (`sealedSessionScope`).
832
- ...(!reads || grant.reads === undefined ? {} : { reads: grant.reads }),
833
- };
834
- }),
835
- );
836
- }
837
-
838
- /**
839
- * The scope a row stores: null for one 0.4 made, not sealed yet, which
840
- * reaches all its account holds, as then. One its MAC checked but that
841
- * does not read as a scope reaches nothing.
842
- */
843
- export function readScope(stored: string | null): CredentialScope | null {
844
- if (stored === null) return null;
845
- let parsed: unknown = null;
846
- try {
847
- parsed = JSON.parse(stored);
848
- } catch {}
849
- return isCredentialScope(parsed) ? parsed : [];
850
- }
851
-
852
- /** What a workload binding's policy lists of reads, by environment id (`BindingPolicy['reads']`). */
853
- type ListedReads = Readonly<Record<string, { readonly keys?: readonly string[] | '*' }>>;
854
-
855
- /**
856
- * What a session reaches, as its caller holds it: its row's scope, an
857
- * enrollment code's, or else its binding's, never null, with its binding's
858
- * `reads` on the grants of the environments they list (`scopeWithReads`).
859
- * Binding creation gives each such environment a grant of its own, so the
860
- * scope itself says each one's project, with nothing to look up. A grant
861
- * without `reads` is use-only, there.
862
- */
863
- export function sessionScope(row: { scope: string | null }, binding: { scope: string | null }, policy: { reads?: ListedReads }): CredentialScope {
864
- const scope = readScope(row.scope ?? binding.scope) ?? [];
865
- const projectOf = new Map<string, string>();
866
- for (const { projectId, environmentId } of scope) if (environmentId != null && projectId !== null) projectOf.set(environmentId, projectId);
867
- return scopeWithReads(scope, policy.reads, projectOf);
868
- }
869
-
870
- /**
871
- * A workload session's scope as its row stores it with 0.15's log: what its
872
- * uses hold (`sessionScope`), its binding's per-key reads included, so that
873
- * its object, all a 0.15 use decides on, is no wider than what 0.14 decides
874
- * on from its binding. The vault makes it from the binding's columns too,
875
- * for the session it signs in (T149).
876
- */
877
- export function sealedSessionScope(scope: string | null, binding: { scope: string | null }, policy: { reads?: ListedReads }): string {
878
- return storedScope(sessionScope({ scope }, binding, policy), { reads: true });
879
- }
880
-
881
839
  /**
882
840
  * Whether the actor may give or take grants at this place: with
883
841
  * `grant.manage` there, from a project grant or an instance role whose
@@ -921,28 +879,38 @@ export type ServiceSetting = Scope;
921
879
  * normal column even in a protected environment, so a person there, who
922
880
  * holds its protected column, gives none what they do not hold themselves:
923
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).
924
886
  */
925
887
  export function givesService(holder: Holdings, setting: ServiceSetting | null, role: Role, place: Place, kept?: RoleDefinition): boolean {
926
888
  if (mayManageAccess(holder, place)) return true;
927
889
  const policy = holder.policy ?? DEFAULT_POLICY;
928
890
  // What the grant holds: its role as the policy defines it, or what a credential kept of it (`issuesCredential`).
929
- const definition = kept ?? definitionOf(policy, role);
891
+ const definition = kept ?? grantDefinition(policy, { projectId: place.projectId, environmentId: place.environmentId ?? null, role });
930
892
  // A role that holds nothing is given by whoever manages access there alone: by anyone else, it would be a grant an
931
893
  // Owner could fill in later, and under a policy the vault cannot read, every role but Owner's holds nothing.
932
894
  if (definition === undefined || definition.permissions.length === 0) return false;
933
895
  if (setting === null || holder.credentialScope != null || !inScope(setting, place)) return false;
934
896
  if (!definition.permissions.every((permission) => allows(holder, permission, place))) return false;
935
897
  // A grant on a whole project reaches its protected environments too, where the service holds the role's normal column:
936
- // 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).
937
900
  const inEnvironments = definition.permissions.filter((permission) => !PROJECT_ONLY_PERMISSIONS.includes(permission));
938
901
  return protectedWithin(policy, place).every((there) => inEnvironments.every((permission) => allows(holder, permission, there)));
939
902
  }
940
903
 
941
- /** 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
+ */
942
910
  export function setsUpServices(holder: Holdings, setting: ServiceSetting | null, places: readonly Place[]): boolean {
943
911
  if (runsInstance(holder)) return true;
944
912
  const roles = Object.keys((holder.policy ?? DEFAULT_POLICY).roles);
945
- 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)));
946
914
  }
947
915
 
948
916
  /** A service account as `managesService` weighs it: its live grants, where they are, and who admitted it. */
@@ -990,7 +958,7 @@ export function issuesCredential(
990
958
  const policy = holder.policy ?? DEFAULT_POLICY;
991
959
  const held: Holdings = { ...NOTHING, policy, service: true, grants: account.grants.map(({ role, place }) => ({ projectId: place.projectId, environmentId: place.environmentId ?? null, role })) };
992
960
  return scope.every(({ role, place, kept }) => givesService(holder, setting, role, place, kept)
993
- && ((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));
994
962
  }
995
963
 
996
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 };