@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/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @coffre/core
2
2
 
3
3
  What coffre's other packages share: access rules, envelope encryption, the
4
- key-encryption keys (a local key, or AWS KMS), the audit chain, identity and
4
+ key-encryption keys (a local key, or AWS KMS), the log's entries and proofs, identity and
5
5
  sign-in, and `Vault`, the contract between the server and the vault.
6
6
 
7
7
  A deployment does not import it. `@coffre/server` and `@coffre/vault`
@@ -273,6 +273,22 @@ function assignableToEnvironment(role, policy = DEFAULT_POLICY) {
273
273
  function definitionOf(policy, role) {
274
274
  return own(policy.roles, role);
275
275
  }
276
+ /**
277
+ * What a grant's role gives at the grant's place, as `policy` defines it:
278
+ * its definition, but nothing on an environment while the role holds a
279
+ * permission only a project takes (`assignableToEnvironment`), as a
280
+ * credential's scope never holds one there (`isCredentialScope`). Every
281
+ * reading of a grant's role goes through it, so that a role widened past
282
+ * what its environment grants take, around a grant hidden from the
283
+ * widening, gives that grant nothing until it is narrowed back:
284
+ *
285
+ * Eve: viewer-plus on market/dev reads market/dev
286
+ * viewer-plus widened to grant.manage Eve holds nothing at market/dev
287
+ */
288
+ function grantDefinition(policy, grant) {
289
+ if (grant.environmentId != null && !assignableToEnvironment(grant.role, policy)) return void 0;
290
+ return definitionOf(policy, grant.role);
291
+ }
276
292
  /** A record's own value at `key`: `constructor` or `__proto__` names nothing. */
277
293
  function own(record, key) {
278
294
  return Object.hasOwn(record, key) ? record[key] : void 0;
@@ -520,7 +536,7 @@ function grantKind(grant) {
520
536
  * Developer widened to read in prod the token still only uses prod
521
537
  */
522
538
  function issuedGrant(grant, policy = DEFAULT_POLICY, held) {
523
- const definition = definitionOf(policy, grant.role);
539
+ const definition = grantDefinition(policy, grant);
524
540
  const within = (column = [], cap) => cap === void 0 ? [...column] : column.filter((permission) => cap.includes(permission));
525
541
  return {
526
542
  projectId: grant.projectId,
@@ -533,6 +549,28 @@ function issuedGrant(grant, policy = DEFAULT_POLICY, held) {
533
549
  };
534
550
  }
535
551
  /**
552
+ * Of a grant issued anew and the one it takes the place of, what both
553
+ * hold, column by column, and the sensitive values only if both read them:
554
+ * a binding that replaces others keeps no more than they did, whatever its
555
+ * role holds now (0.14.7's `narrowest`).
556
+ *
557
+ * was viewer on market/dev: read, use / use
558
+ * now viewer, edited since: read / read, use
559
+ * kept read / use
560
+ */
561
+ function narrowest(now, before) {
562
+ const both = (a, b) => a.filter((permission) => b.includes(permission));
563
+ const [a, b] = [scopeDefinition(now), scopeDefinition(before)];
564
+ return {
565
+ ...now,
566
+ permissions: {
567
+ normal: both(a.permissions, b.permissions),
568
+ protected: both(a.protected, b.protected)
569
+ },
570
+ ...now.sensitive === void 0 ? {} : { sensitive: now.sensitive && before.sensitive === true }
571
+ };
572
+ }
573
+ /**
536
574
  * What `holder` holds at `place` in each column a credential's grant there
537
575
  * keeps (`issuedGrant`): `normal`, as if nothing were protected; `protected`,
538
576
  * as a person in a protected environment. At an environment, as if it were
@@ -610,45 +648,24 @@ function delegableRoles(policy = DEFAULT_POLICY) {
610
648
  }
611
649
  /** The roles a personal token's scope may name, as they ship. */
612
650
  const DELEGABLE_ROLES = delegableRoles();
613
- /** What a handle reads and uses, and no more: it writes nothing. */
614
- const HANDLE_HOLDS = {
615
- name: "Handle",
616
- description: "Read and use, as its person does.",
617
- permissions: ["secret.read", "secret.use"],
618
- protected: ["secret.read", "secret.use"]
619
- };
620
- /**
621
- * 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
622
- * keeps what its person holds there, in each column, of reading and using
623
- * (`issuedGrant`, capped by `heldColumns`), whatever an Owner made of the
624
- * roles. `viewer` names a place its person reads, `contributor` one they
625
- * only use.
626
- *
627
- * an Owner, at a protected prod read, use / read, use
628
- * a Developer, at the same read, use / use
629
- */
630
- const HANDLE_POLICY = {
631
- ...DEFAULT_POLICY,
632
- roles: {
633
- ...ROLES,
634
- viewer: HANDLE_HOLDS,
635
- contributor: HANDLE_HOLDS
636
- }
637
- };
638
651
  /**
639
652
  * The longest a personal token lasts: a week. It is for an afternoon's
640
653
  * script or agent, and whoever needs it longer makes another, as a person,
641
654
  * rather than keep one around.
642
655
  */
643
656
  const MAX_PERSONAL_TOKEN_MINUTES = 10080;
644
- /** The longest a service account's token lives, in days. The vault holds an issue to it (T149). */
645
- const MAX_SERVICE_TOKEN_DAYS = 366;
646
657
  /**
647
658
  * How long a `coffre login` code waits to be approved. The server expires it
648
659
  * then, and the CLI's sign-in hint says so before it has asked for one.
649
660
  */
650
661
  const DEVICE_TTL_SECONDS = 600;
651
662
  /**
663
+ * A device login's user code, as the app draws it and the vault takes it:
664
+ * eight letters in two fours, `BCDF-GHJK`, of an alphabet with no vowel, so
665
+ * that a code never spells a word, and no letter that reads as a digit.
666
+ */
667
+ const USER_CODE = /^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$/;
668
+ /**
652
669
  * A credential's scope, by path as the API names it, in words, each role
653
670
  * with its places: `developer on market/dev, api/dev; viewer on market/prod`.
654
671
  */
@@ -717,7 +734,7 @@ function allows(holder, permission, place) {
717
734
  if (holder.credentialScope != null && !scopeHolds(holder, permission, place)) return false;
718
735
  const policy = holder.policy ?? DEFAULT_POLICY;
719
736
  if (inScope(holder.scope, place) && holds(own(policy.instanceRoles, holder.role), permission, place, holder)) return true;
720
- return holder.grants.some((grant) => covers(grant, place) && holds(definitionOf(policy, grant.role), permission, place, holder));
737
+ return holder.grants.some((grant) => covers(grant, place) && holds(grantDefinition(policy, grant), permission, place, holder));
721
738
  }
722
739
  /**
723
740
  * Whether the credential a request came in on, a scoped token or binding,
@@ -760,7 +777,8 @@ function readsSensitive(holder, projectId) {
760
777
  * one its credential's scope lists, by the key's id, on a grant that covers
761
778
  * the place where the value is held, never the place a request names. A
762
779
  * rename therefore moves no listing, and no reference, fork or copy moves a
763
- * value under one. Nobody else's: their roles and the value's nature decide.
780
+ * value under one. Nobody else's: for them, whether their role reads where
781
+ * the key lives (the vault's `decide`), and the value's nature.
764
782
  * A plain value is no secret, use-only to nobody, so it is never asked of.
765
783
  *
766
784
  * api-prod lists STRIPE_WEBHOOK_SECRET's id at market/prod
@@ -825,66 +843,6 @@ function scopeWithReads(scope, reads, projectOf) {
825
843
  return result;
826
844
  }
827
845
  /**
828
- * A scope as a token's or binding's row stores it, under its MAC: its
829
- * grants as JSON, by place, each with what its role held when it was
830
- * issued (`issuedGrant`), so that a role widened later widens no credential,
831
- * and, a service's, whether it reads the sensitive values there.
832
- */
833
- function storedScope(scope, { reads = false } = {}) {
834
- const key = (grant) => `${grant.projectId}/${grant.environmentId ?? ""}`;
835
- return JSON.stringify([...scope].sort((a, b) => key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0).map((grant) => {
836
- const { permissions, protected: guarded } = scopeDefinition(grant);
837
- return {
838
- projectId: grant.projectId,
839
- environmentId: grant.environmentId,
840
- role: grant.role,
841
- permissions: {
842
- normal: [...permissions],
843
- protected: [...guarded]
844
- },
845
- ...grant.sensitive === void 0 ? {} : { sensitive: grant.sensitive },
846
- ...!reads || grant.reads === void 0 ? {} : { reads: grant.reads }
847
- };
848
- }));
849
- }
850
- /**
851
- * The scope a row stores: null for one 0.4 made, not sealed yet, which
852
- * reaches all its account holds, as then. One its MAC checked but that
853
- * does not read as a scope reaches nothing.
854
- */
855
- function readScope(stored) {
856
- if (stored === null) return null;
857
- let parsed = null;
858
- try {
859
- parsed = JSON.parse(stored);
860
- } catch {}
861
- return isCredentialScope(parsed) ? parsed : [];
862
- }
863
- /**
864
- * What a session reaches, as its caller holds it: its row's scope, an
865
- * enrollment code's, or else its binding's, never null, with its binding's
866
- * `reads` on the grants of the environments they list (`scopeWithReads`).
867
- * Binding creation gives each such environment a grant of its own, so the
868
- * scope itself says each one's project, with nothing to look up. A grant
869
- * without `reads` is use-only, there.
870
- */
871
- function sessionScope(row, binding, policy) {
872
- const scope = readScope(row.scope ?? binding.scope) ?? [];
873
- const projectOf = /* @__PURE__ */ new Map();
874
- for (const { projectId, environmentId } of scope) if (environmentId != null && projectId !== null) projectOf.set(environmentId, projectId);
875
- return scopeWithReads(scope, policy.reads, projectOf);
876
- }
877
- /**
878
- * A workload session's scope as its row stores it with 0.15's log: what its
879
- * uses hold (`sessionScope`), its binding's per-key reads included, so that
880
- * its object, all a 0.15 use decides on, is no wider than what 0.14 decides
881
- * on from its binding. The vault makes it from the binding's columns too,
882
- * for the session it signs in (T149).
883
- */
884
- function sealedSessionScope(scope, binding, policy) {
885
- return storedScope(sessionScope({ scope }, binding, policy), { reads: true });
886
- }
887
- /**
888
846
  * Whether the actor may give or take grants at this place: with
889
847
  * `grant.manage` there, from a project grant or an instance role whose
890
848
  * scope takes it in. A grant on a project reaches all its environments, so
@@ -914,22 +872,35 @@ function runsInstance(holder) {
914
872
  * normal column even in a protected environment, so a person there, who
915
873
  * holds its protected column, gives none what they do not hold themselves:
916
874
  * a Developer of a protected prod, who only uses it, gives no viewer there.
875
+ * A grant on a whole project reaches the environments it protects, so it
876
+ * takes holding the role in each of them too, as 0.14.7 did: a Developer
877
+ * of `market` gives developer on `market` while nothing there is
878
+ * protected, and only environment by environment once prod is (D241).
917
879
  */
918
880
  function givesService(holder, setting, role, place, kept) {
919
881
  if (mayManageAccess(holder, place)) return true;
920
882
  const policy = holder.policy ?? DEFAULT_POLICY;
921
- const definition = kept ?? definitionOf(policy, role);
883
+ const definition = kept ?? grantDefinition(policy, {
884
+ projectId: place.projectId,
885
+ environmentId: place.environmentId ?? null,
886
+ role
887
+ });
922
888
  if (definition === void 0 || definition.permissions.length === 0) return false;
923
889
  if (setting === null || holder.credentialScope != null || !inScope(setting, place)) return false;
924
890
  if (!definition.permissions.every((permission) => allows(holder, permission, place))) return false;
925
891
  const inEnvironments = definition.permissions.filter((permission) => !PROJECT_ONLY_PERMISSIONS.includes(permission));
926
892
  return protectedWithin(policy, place).every((there) => inEnvironments.every((permission) => allows(holder, permission, there)));
927
893
  }
928
- /** Whether `holder` gives a service account anything anywhere among `places`: whether they set any up. */
894
+ /**
895
+ * Whether `holder` gives a service account anything anywhere among
896
+ * `places`: whether they set any up. Where they manage access, they give
897
+ * any role; elsewhere, one of those `holder.policy` defines, which must
898
+ * then be every role, not only those they hold.
899
+ */
929
900
  function setsUpServices(holder, setting, places) {
930
901
  if (runsInstance(holder)) return true;
931
902
  const roles = Object.keys((holder.policy ?? DEFAULT_POLICY).roles);
932
- return places.some((place) => roles.some((role) => givesService(holder, setting, role, place)));
903
+ return places.some((place) => mayManageAccess(holder, place) || roles.some((role) => givesService(holder, setting, role, place)));
933
904
  }
934
905
  /**
935
906
  * Whether `holder`, the member `actor`, manages a service account: issues
@@ -970,7 +941,11 @@ function issuesCredential(holder, setting, actor, account, scope) {
970
941
  role
971
942
  }))
972
943
  };
973
- return scope.every(({ role, place, kept }) => givesService(holder, setting, role, place, kept) && ((kept ?? definitionOf(policy, role))?.permissions.every((permission) => allows(held, permission, place)) ?? false));
944
+ return scope.every(({ role, place, kept }) => givesService(holder, setting, role, place, kept) && ((kept ?? grantDefinition(policy, {
945
+ projectId: place.projectId,
946
+ environmentId: place.environmentId ?? null,
947
+ role
948
+ }))?.permissions.every((permission) => allows(held, permission, place)) ?? false));
974
949
  }
975
950
  /**
976
951
  * Whether the holder reads the whole log, the instance's own entries
@@ -997,4 +972,4 @@ function makesProjects(holder) {
997
972
  return holder.credentialScope == null && administers(holder.role) && environments === "all" && (projects === "all" || "except" in projects);
998
973
  }
999
974
  //#endregion
1000
- export { protects as $, delegableRoles as A, isInstanceRole as B, allows as C, definitionOf as D, credentialScopeInWords as E, holds as F, makesProjects as G, isScope as H, inScope as I, normalDefinition as J, managesService as K, instanceRoleGrants as L, grantKind as M, guarded as N, definitionProblem as O, heldColumns as P, protectedWithin as Q, isBuiltinRole as R, admits as S, covers as T, issuedGrant as U, isRole as V, issuesCredential as W, ownsInstance as X, normalScope as Y, ownsProject as Z, ROLES as _, EVERY_ENVIRONMENT as a, scopeDefinition as at, UNWRITTEN_FORK_MS as b, HANDLE_POLICY as c, sealedSessionScope as ct, MAX_PERSONAL_TOKEN_MINUTES as d, storedScope as dt, readScope as et, MAX_SCOPE_PLACES as f, unscoped as ft, PROJECT_ONLY_PERMISSIONS as g, PERMISSIONS as h, convertEveryProjectGrants as ht, EVERYWHERE as i, runsInstance as it, givesService as j, delegable as k, INSTANCE_ROLES as l, sessionScope as lt, NOTHING as m, withinCredential as mt, DELEGABLE_ROLES as n, readsWholeLog as nt, FIXED_ROLES as o, scopeInWords as ot, MAX_SERVICE_TOKEN_DAYS as p, useOnly as pt, mayManageAccess as q, DEVICE_TTL_SECONDS as r, roleGrants as rt, HANDLE_HOLDS as s, scopeWithReads as st, DEFAULT_POLICY as t, readsSensitive as tt, INSTANCE_ROLE_NAMES as u, setsUpServices as ut, ROLE_ID as v, assignableToEnvironment as w, administers as x, ROLE_NAMES as y, isCredentialScope as z };
975
+ export { protects as $, grantDefinition as A, isRole as B, covers as C, delegable as D, definitionProblem as E, inScope as F, managesService as G, issuedGrant as H, instanceRoleGrants as I, normalDefinition as J, mayManageAccess as K, isBuiltinRole as L, guarded as M, heldColumns as N, delegableRoles as O, holds as P, protectedWithin as Q, isCredentialScope as R, assignableToEnvironment as S, definitionOf as T, issuesCredential as U, isScope as V, makesProjects as W, ownsInstance as X, normalScope as Y, ownsProject as Z, UNWRITTEN_FORK_MS as _, EVERY_ENVIRONMENT as a, scopeInWords as at, admits as b, INSTANCE_ROLE_NAMES as c, unscoped as ct, NOTHING as d, convertEveryProjectGrants as dt, readsSensitive as et, PERMISSIONS as f, ROLE_NAMES as g, ROLE_ID as h, EVERYWHERE as i, scopeDefinition as it, grantKind as j, givesService as k, MAX_PERSONAL_TOKEN_MINUTES as l, useOnly as lt, ROLES as m, DELEGABLE_ROLES as n, roleGrants as nt, FIXED_ROLES as o, scopeWithReads as ot, PROJECT_ONLY_PERMISSIONS as p, narrowest as q, DEVICE_TTL_SECONDS as r, runsInstance as rt, INSTANCE_ROLES as s, setsUpServices as st, DEFAULT_POLICY as t, readsWholeLog as tt, MAX_SCOPE_PLACES as u, withinCredential as ut, USER_CODE as v, credentialScopeInWords as w, allows as x, administers as y, isInstanceRole as z };
@@ -200,6 +200,21 @@ declare function roleGrants(role: Role, permission: Permission, policy?: Policy)
200
200
  declare function assignableToEnvironment(role: Role, policy?: Policy): boolean;
201
201
  /** A project role's definition in `policy`, or undefined for none. */
202
202
  declare function definitionOf(policy: Policy, role: Role): RoleDefinition | undefined;
203
+ /**
204
+ * What a grant's role gives at the grant's place, as `policy` defines it:
205
+ * its definition, but nothing on an environment while the role holds a
206
+ * permission only a project takes (`assignableToEnvironment`), as a
207
+ * credential's scope never holds one there (`isCredentialScope`). Every
208
+ * reading of a grant's role goes through it, so that a role widened past
209
+ * what its environment grants take, around a grant hidden from the
210
+ * widening, gives that grant nothing until it is narrowed back:
211
+ *
212
+ * Eve: viewer-plus on market/dev reads market/dev
213
+ * viewer-plus widened to grant.manage Eve holds nothing at market/dev
214
+ */
215
+ declare function grantDefinition(policy: Policy, grant: GrantPlace & {
216
+ role: Role;
217
+ }): RoleDefinition | undefined;
203
218
  /**
204
219
  * A person's role on the whole instance: what they hold in every project
205
220
  * their scope covers, before any grant. Service accounts are always
@@ -461,6 +476,17 @@ type ScopeGrant = GrantPlace & {
461
476
  declare function issuedGrant(grant: GrantPlace & {
462
477
  role: Role;
463
478
  }, policy?: Policy, held?: Columns): ScopeGrant;
479
+ /**
480
+ * Of a grant issued anew and the one it takes the place of, what both
481
+ * hold, column by column, and the sensitive values only if both read them:
482
+ * a binding that replaces others keeps no more than they did, whatever its
483
+ * role holds now (0.14.7's `narrowest`).
484
+ *
485
+ * was viewer on market/dev: read, use / use
486
+ * now viewer, edited since: read / read, use
487
+ * kept read / use
488
+ */
489
+ declare function narrowest(now: ScopeGrant, before: ScopeGrant): ScopeGrant;
464
490
  /**
465
491
  * What `holder` holds at `place` in each column a credential's grant there
466
492
  * keeps (`issuedGrant`): `normal`, as if nothing were protected; `protected`,
@@ -497,32 +523,23 @@ declare function delegable(role: Role, policy?: Policy): boolean;
497
523
  declare function delegableRoles(policy?: Policy): Role[];
498
524
  /** The roles a personal token's scope may name, as they ship. */
499
525
  declare const DELEGABLE_ROLES: readonly Role[];
500
- /** What a handle reads and uses, and no more: it writes nothing. */
501
- declare const HANDLE_HOLDS: RoleDefinition;
502
- /**
503
- * 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
504
- * keeps what its person holds there, in each column, of reading and using
505
- * (`issuedGrant`, capped by `heldColumns`), whatever an Owner made of the
506
- * roles. `viewer` names a place its person reads, `contributor` one they
507
- * only use.
508
- *
509
- * an Owner, at a protected prod read, use / read, use
510
- * a Developer, at the same read, use / use
511
- */
512
- declare const HANDLE_POLICY: Policy;
513
526
  /**
514
527
  * The longest a personal token lasts: a week. It is for an afternoon's
515
528
  * script or agent, and whoever needs it longer makes another, as a person,
516
529
  * rather than keep one around.
517
530
  */
518
531
  declare const MAX_PERSONAL_TOKEN_MINUTES: number;
519
- /** The longest a service account's token lives, in days. The vault holds an issue to it (T149). */
520
- declare const MAX_SERVICE_TOKEN_DAYS = 366;
521
532
  /**
522
533
  * How long a `coffre login` code waits to be approved. The server expires it
523
534
  * then, and the CLI's sign-in hint says so before it has asked for one.
524
535
  */
525
536
  declare const DEVICE_TTL_SECONDS: number;
537
+ /**
538
+ * A device login's user code, as the app draws it and the vault takes it:
539
+ * eight letters in two fours, `BCDF-GHJK`, of an alphabet with no vowel, so
540
+ * that a code never spells a word, and no letter that reads as a digit.
541
+ */
542
+ declare const USER_CODE: RegExp;
526
543
  /**
527
544
  * A credential's scope, by path as the API names it, in words, each role
528
545
  * with its places: `developer on market/dev, api/dev; viewer on market/prod`.
@@ -629,7 +646,8 @@ type HeldKey = {
629
646
  * one its credential's scope lists, by the key's id, on a grant that covers
630
647
  * the place where the value is held, never the place a request names. A
631
648
  * rename therefore moves no listing, and no reference, fork or copy moves a
632
- * value under one. Nobody else's: their roles and the value's nature decide.
649
+ * value under one. Nobody else's: for them, whether their role reads where
650
+ * the key lives (the vault's `decide`), and the value's nature.
633
651
  * A plain value is no secret, use-only to nobody, so it is never asked of.
634
652
  *
635
653
  * api-prod lists STRIPE_WEBHOOK_SECRET's id at market/prod
@@ -656,52 +674,6 @@ declare function useOnly(holder: Holdings, key: HeldKey): boolean;
656
674
  declare function scopeWithReads(scope: CredentialScope, reads: Readonly<Record<string, {
657
675
  readonly keys?: readonly string[] | '*';
658
676
  }>> | undefined, projectOf: ReadonlyMap<string, string>): CredentialScope;
659
- /**
660
- * A scope as a token's or binding's row stores it, under its MAC: its
661
- * grants as JSON, by place, each with what its role held when it was
662
- * issued (`issuedGrant`), so that a role widened later widens no credential,
663
- * and, a service's, whether it reads the sensitive values there.
664
- */
665
- declare function storedScope(scope: CredentialScope, { reads }?: {
666
- reads?: boolean;
667
- }): string;
668
- /**
669
- * The scope a row stores: null for one 0.4 made, not sealed yet, which
670
- * reaches all its account holds, as then. One its MAC checked but that
671
- * does not read as a scope reaches nothing.
672
- */
673
- declare function readScope(stored: string | null): CredentialScope | null;
674
- /** What a workload binding's policy lists of reads, by environment id (`BindingPolicy['reads']`). */
675
- type ListedReads = Readonly<Record<string, {
676
- readonly keys?: readonly string[] | '*';
677
- }>>;
678
- /**
679
- * What a session reaches, as its caller holds it: its row's scope, an
680
- * enrollment code's, or else its binding's, never null, with its binding's
681
- * `reads` on the grants of the environments they list (`scopeWithReads`).
682
- * Binding creation gives each such environment a grant of its own, so the
683
- * scope itself says each one's project, with nothing to look up. A grant
684
- * without `reads` is use-only, there.
685
- */
686
- declare function sessionScope(row: {
687
- scope: string | null;
688
- }, binding: {
689
- scope: string | null;
690
- }, policy: {
691
- reads?: ListedReads;
692
- }): CredentialScope;
693
- /**
694
- * A workload session's scope as its row stores it with 0.15's log: what its
695
- * uses hold (`sessionScope`), its binding's per-key reads included, so that
696
- * its object, all a 0.15 use decides on, is no wider than what 0.14 decides
697
- * on from its binding. The vault makes it from the binding's columns too,
698
- * for the session it signs in (T149).
699
- */
700
- declare function sealedSessionScope(scope: string | null, binding: {
701
- scope: string | null;
702
- }, policy: {
703
- reads?: ListedReads;
704
- }): string;
705
677
  /**
706
678
  * Whether the actor may give or take grants at this place: with
707
679
  * `grant.manage` there, from a project grant or an instance role whose
@@ -738,9 +710,18 @@ type ServiceSetting = Scope;
738
710
  * normal column even in a protected environment, so a person there, who
739
711
  * holds its protected column, gives none what they do not hold themselves:
740
712
  * a Developer of a protected prod, who only uses it, gives no viewer there.
713
+ * A grant on a whole project reaches the environments it protects, so it
714
+ * takes holding the role in each of them too, as 0.14.7 did: a Developer
715
+ * of `market` gives developer on `market` while nothing there is
716
+ * protected, and only environment by environment once prod is (D241).
741
717
  */
742
718
  declare function givesService(holder: Holdings, setting: ServiceSetting | null, role: Role, place: Place, kept?: RoleDefinition): boolean;
743
- /** Whether `holder` gives a service account anything anywhere among `places`: whether they set any up. */
719
+ /**
720
+ * Whether `holder` gives a service account anything anywhere among
721
+ * `places`: whether they set any up. Where they manage access, they give
722
+ * any role; elsewhere, one of those `holder.policy` defines, which must
723
+ * then be every role, not only those they hold.
724
+ */
744
725
  declare function setsUpServices(holder: Holdings, setting: ServiceSetting | null, places: readonly Place[]): boolean;
745
726
  /** A service account as `managesService` weighs it: its live grants, where they are, and who admitted it. */
746
727
  type ServiceAccount = {
@@ -797,4 +778,4 @@ declare function readsWholeLog(holder: Holdings): boolean;
797
778
  */
798
779
  declare function makesProjects(holder: Holdings): boolean;
799
780
  //#endregion
800
- export { holds as $, ROLE_ID as A, unscoped as At, admits as B, NOTHING as C, scopeDefinition as Ct, Place as D, sessionScope as Dt, Permission as E, sealedSessionScope as Et, ScopeGrant as F, ConvertedGrant as Ft, definitionOf as G, assignableToEnvironment as H, ServiceAccount as I, EveryProjectGrant as It, delegableRoles as J, definitionProblem as K, ServiceSetting as L, Narrowed as Lt, Role as M, withinCredential as Mt, RoleDefinition as N, Conversion as Nt, Policy as O, setsUpServices as Ot, Scope as P, ConversionInput as Pt, heldColumns as Q, UNWRITTEN_FORK_MS as R, convertEveryProjectGrants as Rt, MAX_SERVICE_TOKEN_DAYS as S, runsInstance as St, PROJECT_ONLY_PERMISSIONS as T, scopeWithReads as Tt, covers as U, allows as V, credentialScopeInWords as W, grantKind as X, givesService as Y, guarded as Z, INSTANCE_ROLES as _, protects as _t, DEFAULT_POLICY as a, isRole as at, MAX_PERSONAL_TOKEN_MINUTES as b, readsWholeLog as bt, EVERYWHERE as c, issuesCredential as ct, Filter as d, mayManageAccess as dt, inScope as et, GrantPlace as f, normalDefinition as ft, Holdings as g, protectedWithin as gt, HeldKey as h, ownsProject as ht, CredentialScope as i, isInstanceRole as it, ROLE_NAMES as j, useOnly as jt, ROLES as k, storedScope as kt, EVERY_ENVIRONMENT as l, makesProjects as lt, HANDLE_POLICY as m, ownsInstance as mt, CallerKind as n, isBuiltinRole as nt, DELEGABLE_ROLES as o, isScope as ot, HANDLE_HOLDS as p, normalScope as pt, delegable as q, Columns as r, isCredentialScope as rt, DEVICE_TTL_SECONDS as s, issuedGrant as st, BuiltinRole as t, instanceRoleGrants as tt, FIXED_ROLES as u, managesService as ut, INSTANCE_ROLE_NAMES as v, readScope as vt, PERMISSIONS as w, scopeInWords as wt, MAX_SCOPE_PLACES as x, roleGrants as xt, InstanceRole as y, readsSensitive as yt, administers as z };
781
+ export { inScope as $, RoleDefinition as A, ConversionInput as At, assignableToEnvironment as B, Permission as C, scopeInWords as Ct, ROLE_ID as D, useOnly as Dt, ROLES as E, unscoped as Et, UNWRITTEN_FORK_MS as F, delegable as G, credentialScopeInWords as H, USER_CODE as I, grantDefinition as J, delegableRoles as K, administers as L, ScopeGrant as M, EveryProjectGrant as Mt, ServiceAccount as N, Narrowed as Nt, ROLE_NAMES as O, withinCredential as Ot, ServiceSetting as P, convertEveryProjectGrants as Pt, holds as Q, admits as R, PROJECT_ONLY_PERMISSIONS as S, scopeDefinition as St, Policy as T, setsUpServices as Tt, definitionOf as U, covers as V, definitionProblem as W, guarded as X, grantKind as Y, heldColumns as Z, InstanceRole as _, protects as _t, DEFAULT_POLICY as a, isScope as at, NOTHING as b, roleGrants as bt, EVERYWHERE as c, makesProjects as ct, Filter as d, narrowest as dt, instanceRoleGrants as et, GrantPlace as f, normalDefinition as ft, INSTANCE_ROLE_NAMES as g, protectedWithin as gt, INSTANCE_ROLES as h, ownsProject as ht, CredentialScope as i, isRole as it, Scope as j, ConvertedGrant as jt, Role as k, Conversion as kt, EVERY_ENVIRONMENT as l, managesService as lt, Holdings as m, ownsInstance as mt, CallerKind as n, isCredentialScope as nt, DELEGABLE_ROLES as o, issuedGrant as ot, HeldKey as p, normalScope as pt, givesService as q, Columns as r, isInstanceRole as rt, DEVICE_TTL_SECONDS as s, issuesCredential as st, BuiltinRole as t, isBuiltinRole as tt, FIXED_ROLES as u, mayManageAccess as ut, MAX_PERSONAL_TOKEN_MINUTES as v, readsSensitive as vt, Place as w, scopeWithReads as wt, PERMISSIONS as x, runsInstance as xt, MAX_SCOPE_PLACES as y, readsWholeLog as yt, allows as z };
package/dist/access.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { $ as holds, A as ROLE_ID, At as unscoped, B as admits, C as NOTHING, Ct as scopeDefinition, D as Place, Dt as sessionScope, E as Permission, Et as sealedSessionScope, F as ScopeGrant, Ft as ConvertedGrant, G as definitionOf, H as assignableToEnvironment, I as ServiceAccount, It as EveryProjectGrant, J as delegableRoles, K as definitionProblem, L as ServiceSetting, Lt as Narrowed, M as Role, Mt as withinCredential, N as RoleDefinition, Nt as Conversion, O as Policy, Ot as setsUpServices, P as Scope, Pt as ConversionInput, Q as heldColumns, R as UNWRITTEN_FORK_MS, Rt as convertEveryProjectGrants, S as MAX_SERVICE_TOKEN_DAYS, St as runsInstance, T as PROJECT_ONLY_PERMISSIONS, Tt as scopeWithReads, U as covers, V as allows, W as credentialScopeInWords, X as grantKind, Y as givesService, Z as guarded, _ as INSTANCE_ROLES, _t as protects, a as DEFAULT_POLICY, at as isRole, b as MAX_PERSONAL_TOKEN_MINUTES, bt as readsWholeLog, c as EVERYWHERE, ct as issuesCredential, d as Filter, dt as mayManageAccess, et as inScope, f as GrantPlace, ft as normalDefinition, g as Holdings, gt as protectedWithin, h as HeldKey, ht as ownsProject, i as CredentialScope, it as isInstanceRole, j as ROLE_NAMES, jt as useOnly, k as ROLES, kt as storedScope, l as EVERY_ENVIRONMENT, lt as makesProjects, m as HANDLE_POLICY, mt as ownsInstance, n as CallerKind, nt as isBuiltinRole, o as DELEGABLE_ROLES, ot as isScope, p as HANDLE_HOLDS, pt as normalScope, q as delegable, r as Columns, rt as isCredentialScope, s as DEVICE_TTL_SECONDS, st as issuedGrant, t as BuiltinRole, tt as instanceRoleGrants, u as FIXED_ROLES, ut as managesService, v as INSTANCE_ROLE_NAMES, vt as readScope, w as PERMISSIONS, wt as scopeInWords, x as MAX_SCOPE_PLACES, xt as roleGrants, y as InstanceRole, yt as readsSensitive, z as administers } from "./access-DqLJjnLM.js";
2
- export { BuiltinRole, CallerKind, Columns, type Conversion, type ConversionInput, type ConvertedGrant, CredentialScope, DEFAULT_POLICY, DELEGABLE_ROLES, DEVICE_TTL_SECONDS, EVERYWHERE, EVERY_ENVIRONMENT, type EveryProjectGrant, FIXED_ROLES, Filter, GrantPlace, HANDLE_HOLDS, HANDLE_POLICY, HeldKey, Holdings, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, InstanceRole, MAX_PERSONAL_TOKEN_MINUTES, MAX_SCOPE_PLACES, MAX_SERVICE_TOKEN_DAYS, NOTHING, type Narrowed, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, Permission, Place, Policy, ROLES, ROLE_ID, ROLE_NAMES, Role, RoleDefinition, Scope, ScopeGrant, ServiceAccount, ServiceSetting, UNWRITTEN_FORK_MS, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, definitionOf, definitionProblem, delegable, delegableRoles, givesService, grantKind, guarded, heldColumns, holds, inScope, instanceRoleGrants, isBuiltinRole, isCredentialScope, isInstanceRole, isRole, isScope, issuedGrant, issuesCredential, makesProjects, managesService, mayManageAccess, normalDefinition, normalScope, ownsInstance, ownsProject, protectedWithin, protects, readScope, readsSensitive, readsWholeLog, roleGrants, runsInstance, scopeDefinition, scopeInWords, scopeWithReads, sealedSessionScope, sessionScope, setsUpServices, storedScope, unscoped, useOnly, withinCredential };
1
+ import { $ as inScope, A as RoleDefinition, At as ConversionInput, B as assignableToEnvironment, C as Permission, Ct as scopeInWords, D as ROLE_ID, Dt as useOnly, E as ROLES, Et as unscoped, F as UNWRITTEN_FORK_MS, G as delegable, H as credentialScopeInWords, I as USER_CODE, J as grantDefinition, K as delegableRoles, L as administers, M as ScopeGrant, Mt as EveryProjectGrant, N as ServiceAccount, Nt as Narrowed, O as ROLE_NAMES, Ot as withinCredential, P as ServiceSetting, Pt as convertEveryProjectGrants, Q as holds, R as admits, S as PROJECT_ONLY_PERMISSIONS, St as scopeDefinition, T as Policy, Tt as setsUpServices, U as definitionOf, V as covers, W as definitionProblem, X as guarded, Y as grantKind, Z as heldColumns, _ as InstanceRole, _t as protects, a as DEFAULT_POLICY, at as isScope, b as NOTHING, bt as roleGrants, c as EVERYWHERE, ct as makesProjects, d as Filter, dt as narrowest, et as instanceRoleGrants, f as GrantPlace, ft as normalDefinition, g as INSTANCE_ROLE_NAMES, gt as protectedWithin, h as INSTANCE_ROLES, ht as ownsProject, i as CredentialScope, it as isRole, j as Scope, jt as ConvertedGrant, k as Role, kt as Conversion, l as EVERY_ENVIRONMENT, lt as managesService, m as Holdings, mt as ownsInstance, n as CallerKind, nt as isCredentialScope, o as DELEGABLE_ROLES, ot as issuedGrant, p as HeldKey, pt as normalScope, q as givesService, r as Columns, rt as isInstanceRole, s as DEVICE_TTL_SECONDS, st as issuesCredential, t as BuiltinRole, tt as isBuiltinRole, u as FIXED_ROLES, ut as mayManageAccess, v as MAX_PERSONAL_TOKEN_MINUTES, vt as readsSensitive, w as Place, wt as scopeWithReads, x as PERMISSIONS, xt as runsInstance, y as MAX_SCOPE_PLACES, yt as readsWholeLog, z as allows } from "./access-ERdGGHG7.js";
2
+ export { BuiltinRole, CallerKind, Columns, type Conversion, type ConversionInput, type ConvertedGrant, CredentialScope, DEFAULT_POLICY, DELEGABLE_ROLES, DEVICE_TTL_SECONDS, EVERYWHERE, EVERY_ENVIRONMENT, type EveryProjectGrant, FIXED_ROLES, Filter, GrantPlace, HeldKey, Holdings, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, InstanceRole, MAX_PERSONAL_TOKEN_MINUTES, MAX_SCOPE_PLACES, NOTHING, type Narrowed, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, Permission, Place, Policy, ROLES, ROLE_ID, ROLE_NAMES, Role, RoleDefinition, Scope, ScopeGrant, ServiceAccount, ServiceSetting, UNWRITTEN_FORK_MS, USER_CODE, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, definitionOf, definitionProblem, delegable, delegableRoles, givesService, grantDefinition, grantKind, guarded, heldColumns, holds, inScope, instanceRoleGrants, isBuiltinRole, isCredentialScope, isInstanceRole, isRole, isScope, issuedGrant, issuesCredential, makesProjects, managesService, mayManageAccess, narrowest, normalDefinition, normalScope, ownsInstance, ownsProject, protectedWithin, protects, readsSensitive, readsWholeLog, roleGrants, runsInstance, scopeDefinition, scopeInWords, scopeWithReads, setsUpServices, unscoped, useOnly, withinCredential };
package/dist/access.js CHANGED
@@ -1,2 +1,2 @@
1
- import { $ as protects, A as delegableRoles, B as isInstanceRole, C as allows, D as definitionOf, E as credentialScopeInWords, F as holds, G as makesProjects, H as isScope, I as inScope, J as normalDefinition, K as managesService, L as instanceRoleGrants, M as grantKind, N as guarded, O as definitionProblem, P as heldColumns, Q as protectedWithin, R as isBuiltinRole, S as admits, T as covers, U as issuedGrant, V as isRole, W as issuesCredential, X as ownsInstance, Y as normalScope, Z as ownsProject, _ as ROLES, a as EVERY_ENVIRONMENT, at as scopeDefinition, b as UNWRITTEN_FORK_MS, c as HANDLE_POLICY, ct as sealedSessionScope, d as MAX_PERSONAL_TOKEN_MINUTES, dt as storedScope, et as readScope, f as MAX_SCOPE_PLACES, ft as unscoped, g as PROJECT_ONLY_PERMISSIONS, h as PERMISSIONS, ht as convertEveryProjectGrants, i as EVERYWHERE, it as runsInstance, j as givesService, k as delegable, l as INSTANCE_ROLES, lt as sessionScope, m as NOTHING, mt as withinCredential, n as DELEGABLE_ROLES, nt as readsWholeLog, o as FIXED_ROLES, ot as scopeInWords, p as MAX_SERVICE_TOKEN_DAYS, pt as useOnly, q as mayManageAccess, r as DEVICE_TTL_SECONDS, rt as roleGrants, s as HANDLE_HOLDS, st as scopeWithReads, t as DEFAULT_POLICY, tt as readsSensitive, u as INSTANCE_ROLE_NAMES, ut as setsUpServices, v as ROLE_ID, w as assignableToEnvironment, x as administers, y as ROLE_NAMES, z as isCredentialScope } from "./access-CgQTlUMz.js";
2
- export { DEFAULT_POLICY, DELEGABLE_ROLES, DEVICE_TTL_SECONDS, EVERYWHERE, EVERY_ENVIRONMENT, FIXED_ROLES, HANDLE_HOLDS, HANDLE_POLICY, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, MAX_PERSONAL_TOKEN_MINUTES, MAX_SCOPE_PLACES, MAX_SERVICE_TOKEN_DAYS, NOTHING, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_ID, ROLE_NAMES, UNWRITTEN_FORK_MS, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, definitionOf, definitionProblem, delegable, delegableRoles, givesService, grantKind, guarded, heldColumns, holds, inScope, instanceRoleGrants, isBuiltinRole, isCredentialScope, isInstanceRole, isRole, isScope, issuedGrant, issuesCredential, makesProjects, managesService, mayManageAccess, normalDefinition, normalScope, ownsInstance, ownsProject, protectedWithin, protects, readScope, readsSensitive, readsWholeLog, roleGrants, runsInstance, scopeDefinition, scopeInWords, scopeWithReads, sealedSessionScope, sessionScope, setsUpServices, storedScope, unscoped, useOnly, withinCredential };
1
+ import { $ as protects, A as grantDefinition, B as isRole, C as covers, D as delegable, E as definitionProblem, F as inScope, G as managesService, H as issuedGrant, I as instanceRoleGrants, J as normalDefinition, K as mayManageAccess, L as isBuiltinRole, M as guarded, N as heldColumns, O as delegableRoles, P as holds, Q as protectedWithin, R as isCredentialScope, S as assignableToEnvironment, T as definitionOf, U as issuesCredential, V as isScope, W as makesProjects, X as ownsInstance, Y as normalScope, Z as ownsProject, _ as UNWRITTEN_FORK_MS, a as EVERY_ENVIRONMENT, at as scopeInWords, b as admits, c as INSTANCE_ROLE_NAMES, ct as unscoped, d as NOTHING, dt as convertEveryProjectGrants, et as readsSensitive, f as PERMISSIONS, g as ROLE_NAMES, h as ROLE_ID, i as EVERYWHERE, it as scopeDefinition, j as grantKind, k as givesService, l as MAX_PERSONAL_TOKEN_MINUTES, lt as useOnly, m as ROLES, n as DELEGABLE_ROLES, nt as roleGrants, o as FIXED_ROLES, ot as scopeWithReads, p as PROJECT_ONLY_PERMISSIONS, q as narrowest, r as DEVICE_TTL_SECONDS, rt as runsInstance, s as INSTANCE_ROLES, st as setsUpServices, t as DEFAULT_POLICY, tt as readsWholeLog, u as MAX_SCOPE_PLACES, ut as withinCredential, v as USER_CODE, w as credentialScopeInWords, x as allows, y as administers, z as isInstanceRole } from "./access-CF8UG59J.js";
2
+ export { DEFAULT_POLICY, DELEGABLE_ROLES, DEVICE_TTL_SECONDS, EVERYWHERE, EVERY_ENVIRONMENT, FIXED_ROLES, INSTANCE_ROLES, INSTANCE_ROLE_NAMES, MAX_PERSONAL_TOKEN_MINUTES, MAX_SCOPE_PLACES, NOTHING, PERMISSIONS, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_ID, ROLE_NAMES, UNWRITTEN_FORK_MS, USER_CODE, administers, admits, allows, assignableToEnvironment, convertEveryProjectGrants, covers, credentialScopeInWords, definitionOf, definitionProblem, delegable, delegableRoles, givesService, grantDefinition, grantKind, guarded, heldColumns, holds, inScope, instanceRoleGrants, isBuiltinRole, isCredentialScope, isInstanceRole, isRole, isScope, issuedGrant, issuesCredential, makesProjects, managesService, mayManageAccess, narrowest, normalDefinition, normalScope, ownsInstance, ownsProject, protectedWithin, protects, readsSensitive, readsWholeLog, roleGrants, runsInstance, scopeDefinition, scopeInWords, scopeWithReads, setsUpServices, unscoped, useOnly, withinCredential };
@@ -1,10 +1,22 @@
1
- import { d as checkContext, f as encodeAad, l as AAD_VERSION, p as ownerKey, t as KekRegistry, u as SecretContext } from "./registry-D7X-x202.js";
1
+ import { d as SecretContext, f as checkContext, m as ownerKey, p as encodeAad, t as KekRegistry, u as AAD_VERSION } from "./registry-B7_LUDsJ.js";
2
2
  //#region src/envelope.d.ts
3
3
  /**
4
- * Current envelope format version. Stored on every row so the format can change
5
- * without a bulk re-encryption.
4
+ * The envelope's format, stored on every row so that it can change without a
5
+ * bulk re-encryption. The two differ in what the wrap of a value's key
6
+ * names (`SecretContext`). In 1, all 0.14 wrote, its secret, a personal
7
+ * config's owner and whether it is sensitive. In 2 the version's number
8
+ * too, and whether the value is plain: without the number, a database
9
+ * writer could copy a secret's old version over its current one, and it
10
+ * would open.
11
+ *
12
+ * `seal` writes format 2 and `open` reads nothing else. Were format 1 still
13
+ * read, a row of 0.14's kept aside could be put back over any later version
14
+ * of its secret, relabelled 1, and open. The vault's adoption of a 0.14
15
+ * database wraps every key again under its number, with the registry's own
16
+ * `unwrap` and `wrap`: the ciphertext stays. From then on a format-1 row
17
+ * with a key to open is one nobody wrote.
6
18
  */
7
- export declare const ENVELOPE_VERSION = 1;
19
+ export declare const ENVELOPE_VERSION = 2;
8
20
  /**
9
21
  * One sealed secret value, exactly as it is stored in `secret_versions`.
10
22
  *
@@ -22,8 +34,11 @@ export type Envelope = {
22
34
  authTag: Buffer;
23
35
  ciphertext: Buffer;
24
36
  };
25
- /** The part of an envelope the data key produces: everything but the wrapped key. */
26
- export type Sealed = Pick<Envelope, 'envelopeVersion' | 'iv' | 'authTag' | 'ciphertext'>;
37
+ /**
38
+ * The part of an envelope the data key produces. It has no format of its
39
+ * own: an envelope's format is its wrap's, which whoever wraps the key says.
40
+ */
41
+ export type Sealed = Pick<Envelope, 'iv' | 'authTag' | 'ciphertext'>;
27
42
  /** A fresh data key. One per version, so no key ever encrypts two values. */
28
43
  export declare function freshDek(): Buffer;
29
44
  /**
@@ -41,13 +56,17 @@ export declare function encrypt(plaintext: Buffer, ctx: SecretIds, dek: Buffer):
41
56
  export declare function decrypt(envelope: Sealed, ctx: SecretIds, dek: Buffer): Buffer;
42
57
  /** What a value's own ciphertext binds: the secret's ids, never its owner or sensitivity, which only the wrap of its key does. */
43
58
  export type SecretIds = Pick<SecretContext, 'projectId' | 'environmentId' | 'secretId'>;
59
+ /** A version's context as 0.16 writes and reads it: its number is in the wrap. */
60
+ export type NumberedContext = SecretContext & {
61
+ version: number;
62
+ };
44
63
  /**
45
64
  * Encrypt a secret value under a fresh DEK, and wrap that DEK under the
46
65
  * registry's primary KEK: `encrypt` and the wrap in one, where both halves
47
66
  * are in one place.
48
67
  */
49
- export declare function seal(plaintext: Buffer, ctx: SecretContext, keks: KekRegistry): Promise<Envelope>;
50
- /** Unwrap the envelope's DEK under the registry and decrypt: `decrypt` and the unwrap in one. */
51
- export declare function open(envelope: Envelope, ctx: SecretContext, keks: KekRegistry): Promise<Buffer>;
68
+ export declare function seal(plaintext: Buffer, ctx: NumberedContext, keks: KekRegistry): Promise<Envelope>;
69
+ /** Unwrap the envelope's DEK under the registry and decrypt: `decrypt` and the unwrap in one. Format 2 only (`ENVELOPE_VERSION`). */
70
+ export declare function open(envelope: Envelope, ctx: NumberedContext, keks: KekRegistry): Promise<Buffer>;
52
71
  //#endregion
53
72
  export { AAD_VERSION, SecretContext, checkContext, encodeAad, ownerKey };
package/dist/envelope.js CHANGED
@@ -1,13 +1,25 @@
1
- import { a as AAD_VERSION, c as ownerKey, o as checkContext, s as encodeAad } from "./types-Cp3lB_-W.js";
1
+ import { c as encodeAad, l as ownerKey, o as AAD_VERSION, s as checkContext } from "./types-DwTO_b4H.js";
2
2
  import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
3
3
  //#region src/envelope.ts
4
4
  const IV_BYTES = 12;
5
5
  const TAG_BYTES = 16;
6
6
  /**
7
- * Current envelope format version. Stored on every row so the format can change
8
- * without a bulk re-encryption.
7
+ * The envelope's format, stored on every row so that it can change without a
8
+ * bulk re-encryption. The two differ in what the wrap of a value's key
9
+ * names (`SecretContext`). In 1, all 0.14 wrote, its secret, a personal
10
+ * config's owner and whether it is sensitive. In 2 the version's number
11
+ * too, and whether the value is plain: without the number, a database
12
+ * writer could copy a secret's old version over its current one, and it
13
+ * would open.
14
+ *
15
+ * `seal` writes format 2 and `open` reads nothing else. Were format 1 still
16
+ * read, a row of 0.14's kept aside could be put back over any later version
17
+ * of its secret, relabelled 1, and open. The vault's adoption of a 0.14
18
+ * database wraps every key again under its number, with the registry's own
19
+ * `unwrap` and `wrap`: the ciphertext stays. From then on a format-1 row
20
+ * with a key to open is one nobody wrote.
9
21
  */
10
- const ENVELOPE_VERSION = 1;
22
+ const ENVELOPE_VERSION = 2;
11
23
  /** A fresh data key. One per version, so no key ever encrypts two values. */
12
24
  function freshDek() {
13
25
  return randomBytes(32);
@@ -23,7 +35,6 @@ function encrypt(plaintext, ctx, dek) {
23
35
  cipher.setAAD(valueAad(ctx));
24
36
  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
25
37
  return {
26
- envelopeVersion: 1,
27
38
  iv,
28
39
  authTag: cipher.getAuthTag(),
29
40
  ciphertext
@@ -36,7 +47,6 @@ function encrypt(plaintext, ctx, dek) {
36
47
  * ciphertext across environments fail closed.
37
48
  */
38
49
  function decrypt(envelope, ctx, dek) {
39
- if (envelope.envelopeVersion !== 1) throw new Error(`unsupported envelope version: ${envelope.envelopeVersion}`);
40
50
  if (envelope.iv.length !== IV_BYTES) throw new Error("envelope IV has the wrong length");
41
51
  if (envelope.authTag.length !== TAG_BYTES) throw new Error("envelope auth tag has the wrong length");
42
52
  const decipher = createDecipheriv("aes-256-gcm", dek, envelope.iv);
@@ -57,12 +67,14 @@ function valueAad(ctx) {
57
67
  * are in one place.
58
68
  */
59
69
  async function seal(plaintext, ctx, keks) {
70
+ requireNumber(ctx);
60
71
  const dek = freshDek();
61
72
  try {
62
73
  const sealed = encrypt(plaintext, ctx, dek);
63
74
  const wrapped = await keks.wrap(dek, ctx);
64
75
  return {
65
76
  ...sealed,
77
+ envelopeVersion: 2,
66
78
  kekProvider: wrapped.kekProvider,
67
79
  kekId: wrapped.kekId,
68
80
  kekVersion: wrapped.kekVersion,
@@ -72,9 +84,10 @@ async function seal(plaintext, ctx, keks) {
72
84
  dek.fill(0);
73
85
  }
74
86
  }
75
- /** Unwrap the envelope's DEK under the registry and decrypt: `decrypt` and the unwrap in one. */
87
+ /** Unwrap the envelope's DEK under the registry and decrypt: `decrypt` and the unwrap in one. Format 2 only (`ENVELOPE_VERSION`). */
76
88
  async function open(envelope, ctx, keks) {
77
- if (envelope.envelopeVersion !== 1) throw new Error(`unsupported envelope version: ${envelope.envelopeVersion}`);
89
+ if (envelope.envelopeVersion !== 2) throw new Error(`unsupported envelope version: ${envelope.envelopeVersion}`);
90
+ requireNumber(ctx);
78
91
  const dek = await keks.unwrap({
79
92
  kekProvider: envelope.kekProvider,
80
93
  kekId: envelope.kekId,
@@ -87,5 +100,9 @@ async function open(envelope, ctx, keks) {
87
100
  dek.fill(0);
88
101
  }
89
102
  }
103
+ /** The type says it, and a caller that is not typed is told. */
104
+ function requireNumber(ctx) {
105
+ if (ctx.version === void 0) throw new Error("a value is sealed and opened under its version's number");
106
+ }
90
107
  //#endregion
91
108
  export { AAD_VERSION, ENVELOPE_VERSION, checkContext, decrypt, encodeAad, encrypt, freshDek, open, ownerKey, seal };