@coffre/core 0.15.0 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/{access-CgQTlUMz.js → access-CF8UG59J.js} +70 -95
- package/dist/{access-DqLJjnLM.d.ts → access-ERdGGHG7.d.ts} +45 -64
- package/dist/access.d.ts +2 -2
- package/dist/access.js +2 -2
- package/dist/envelope.d.ts +28 -9
- package/dist/envelope.js +25 -8
- package/dist/identity.d.ts +3 -1018
- package/dist/identity.js +885 -623
- package/dist/index-DuG9p3GH.d.ts +1233 -0
- package/dist/kek.d.ts +10 -16
- package/dist/kek.js +26 -41
- package/dist/log.d.ts +114 -0
- package/dist/log.js +291 -0
- package/dist/mcp.d.ts +27 -4
- package/dist/mcp.js +31 -10
- package/dist/recipe-BgJpmJum.d.ts +128 -0
- package/dist/recipe.d.ts +2 -127
- package/dist/{registry-D7X-x202.d.ts → registry-B7_LUDsJ.d.ts} +30 -5
- package/dist/schemas.d.ts +14 -12
- package/dist/schemas.js +16 -14
- package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
- package/dist/vault.d.ts +1771 -1419
- package/dist/vault.js +96 -302
- package/dist/{workloads-D049JH0M.d.ts → workloads-CW2dK4AW.d.ts} +1 -9
- package/dist/workloads.d.ts +2 -2
- package/dist/workloads.js +1 -9
- package/package.json +7 -7
- package/src/access.ts +63 -95
- package/src/changes/access.ts +140 -0
- package/src/changes/freezes.ts +40 -0
- package/src/changes/mcp.ts +150 -0
- package/src/changes/places.ts +219 -0
- package/src/changes/secrets.ts +235 -0
- package/src/changes/signin.ts +197 -0
- package/src/changes/workloads.ts +166 -0
- package/src/context.ts +18 -2
- package/src/envelope.ts +35 -12
- package/src/identity/auth.ts +11 -3
- package/src/identity/aws.ts +62 -0
- package/src/identity/github-app.ts +45 -24
- package/src/identity/index.ts +3 -2
- package/src/identity/{profile-rules.ts → profiles.ts} +1 -9
- package/src/identity/proofs.ts +306 -0
- package/src/identity/signin/config.ts +1 -1
- package/src/identity/tokens.ts +10 -3
- package/src/identity/verifier.ts +73 -14
- package/src/identity/workload-token.ts +4 -0
- package/src/identity/workloads.ts +0 -11
- package/src/kek/aws-kms.ts +18 -13
- package/src/kek/check.ts +16 -46
- package/src/kek/index.ts +2 -2
- package/src/kek/types.ts +15 -3
- package/src/log/index.ts +7 -0
- package/src/{audit → log}/tiles.ts +18 -49
- package/src/{audit → log}/tree.ts +2 -2
- package/src/mcp.ts +36 -9
- package/src/schemas.ts +15 -12
- package/src/vault.ts +251 -1150
- package/dist/merkle.d.ts +0 -456
- package/dist/merkle.js +0 -964
- package/src/answers.ts +0 -209
- package/src/audit/leaf.ts +0 -81
- package/src/audit/merkle.ts +0 -13
- package/src/audit/note.ts +0 -187
- package/src/audit/pair.ts +0 -86
- package/src/audit/verify.ts +0 -393
- package/src/audit/witness.ts +0 -50
- package/src/checkpoint.ts +0 -22
- package/src/identity/run-proof.ts +0 -159
package/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`,
|
|
@@ -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(
|
|
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:
|
|
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 ??
|
|
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
|
-
/**
|
|
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 ??
|
|
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 };
|