@coffre/core 0.14.0 → 0.14.2

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.
@@ -517,8 +517,14 @@ export type Principal = {
517
517
  * looks up coffre's own credentials.
518
518
  */
519
519
  export interface IdentityVerifier {
520
+ /**
521
+ * `recall`: the request reads values, and has the vault check, before it
522
+ * answers, an answer about its caller kept from an earlier request
523
+ * (server accesses.ts): a verifier that asks the vault may give that one.
524
+ */
520
525
  verify(token: string, request?: {
521
526
  sourceIp: string | null;
527
+ recall?: boolean;
522
528
  }): Promise<Principal>;
523
529
  }
524
530
  /** Access delivers the JWT to the origin in this header. */
package/dist/schemas.d.ts CHANGED
@@ -39,11 +39,11 @@ export declare const principalType: z.ZodEnum<{
39
39
  }>;
40
40
  export declare const principalId: z.ZodString;
41
41
  export declare const instanceRole: z.ZodEnum<{
42
- member: "member";
43
- auditor: "auditor";
44
42
  developer: "developer";
45
- admin: "admin";
43
+ auditor: "auditor";
46
44
  owner: "owner";
45
+ member: "member";
46
+ admin: "admin";
47
47
  }>;
48
48
  /** A project role's id: one coffre ships, or one an Owner made (`ROLE_ID`). Which the instance defines, its policy says. */
49
49
  export declare const roleId: z.ZodString;
package/dist/vault.d.ts CHANGED
@@ -93,9 +93,17 @@ export declare function checkpointVerifier(publicKey: string): Promise<(checkpoi
93
93
  * the vault has already logged. Only a fault (a bug, the store down) throws.
94
94
  */
95
95
  export interface Vault {
96
- /** Unwrap data keys for `principal`: all of them, or none. */
96
+ /**
97
+ * Unwrap data keys for `principal`: all of them, or none. Given the
98
+ * revision of an answer of `access` the app decided the read on
99
+ * (`accessRevision`), only while the principal's access is still that
100
+ * one, under their row and the head the decision holds: otherwise it
101
+ * refuses `access_changed` and logs no read, and says, by naming it back,
102
+ * that it checked. A vault older than 0.14.1 names none: it checked none.
103
+ */
97
104
  unwrap(input: UnwrapInput): Promise<Outcome<{
98
105
  keys: string[];
106
+ accessRevision?: string;
99
107
  }>>;
100
108
  /**
101
109
  * Wrap fresh data keys for new versions `principal` writes: all, or none.
@@ -141,6 +149,7 @@ export interface Vault {
141
149
  }>>;
142
150
  /**
143
151
  * What one principal holds right now: the app asks once per request,
152
+ * unless the request reads values on an answer it kept (`accessRevision`),
144
153
  * and at sign-in for each verified email. A decision, its rows checked:
145
154
  * lists of who holds what read the rows themselves, and need not ask.
146
155
  * A person the vault's `owners` names who is no Owner of all of it
@@ -344,6 +353,14 @@ export type RefusalCode =
344
353
  * when another came since: asked again, it is weighed as the policy is now.
345
354
  */
346
355
  'policy_changed' |
356
+ /**
357
+ * A read decided on an earlier answer of `access` about its principal
358
+ * (`accessRevision`) that is not theirs now: nothing was read, and no
359
+ * read logged; with a key service, the intent it logged is closed, each
360
+ * key refused.
361
+ * Asked again on the answer now, it is decided as they are now.
362
+ */
363
+ 'access_changed' |
347
364
  /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
348
365
  'log_broken' |
349
366
  /**
@@ -469,6 +486,13 @@ export type Through = {
469
486
  export type UnwrapInput = Correlation & Through & {
470
487
  principal: string;
471
488
  purpose: Purpose;
489
+ /**
490
+ * The revision of the answer of `access` the app decided this read on,
491
+ * kept from an earlier request (`Access.revision`): the vault refuses
492
+ * `access_changed` unless its answer now has the same. Absent when the
493
+ * app asked this request.
494
+ */
495
+ accessRevision?: string;
472
496
  /**
473
497
  * That a `copy` keeps each sensitive value sensitive in what it writes:
474
498
  * the vault opens a sensitive value to copy for a person only when told
@@ -567,7 +591,20 @@ export type Access = {
567
591
  by: string | null;
568
592
  /** The instance's policy, which every decision about them reads: absent from a vault older than 0.10, which decides as it ships. */
569
593
  policy?: Policy;
594
+ /**
595
+ * The answer, in a word (`accessRevision`): the app keeps the answer
596
+ * between requests, and a read it decides on the kept one names it, which
597
+ * the vault refuses unless its answer now has the same. Absent from a
598
+ * vault older than 0.14.1, whose answers the app keeps for nothing.
599
+ */
600
+ revision?: string;
570
601
  };
602
+ /**
603
+ * An answer of `access` in a word: equal for two answers that say the same,
604
+ * whatever order the rows came back in, and different for any change to
605
+ * what they say, a grant lapsed, the policy's or the member's.
606
+ */
607
+ export declare function accessRevision(access: Access): string;
571
608
  /**
572
609
  * One place: a role to hold there, with an optional end, or null for none.
573
610
  * An environment's place names its project too.
package/dist/vault.js CHANGED
@@ -67,6 +67,25 @@ function handsBack(read) {
67
67
  return !(read.purpose === "copy" && read.keepsSensitive === true);
68
68
  }
69
69
  /**
70
+ * An answer of `access` in a word: equal for two answers that say the same,
71
+ * whatever order the rows came back in, and different for any change to
72
+ * what they say, a grant lapsed, the policy's or the member's.
73
+ */
74
+ function accessRevision(access) {
75
+ const { revision: _, grants, ...rest } = access;
76
+ const facts = canonical({
77
+ ...rest,
78
+ grants: grants.map(canonical).sort()
79
+ });
80
+ return createHash("sha256").update(facts).digest("base64url").slice(0, 32);
81
+ }
82
+ /** A value as JSON whose every object's keys are sorted, at every depth. */
83
+ function canonical(value) {
84
+ if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
85
+ if (typeof value === "object" && value !== null) return `{${Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
86
+ return JSON.stringify(value);
87
+ }
88
+ /**
70
89
  * A policy's revision, as a decision made from it names it: its newest
71
90
  * `policy.change` (null for none), and the slug of each environment it
72
91
  * protects, by id, which a scoped instance role's filters match, and
@@ -84,4 +103,4 @@ function policyRevision(seq, policy) {
84
103
  /** A revision as `policyRevision` writes it. */
85
104
  const POLICY_REVISION = /^(none|[1-9][0-9]{0,15})\.[0-9a-f]{16}$/;
86
105
  //#endregion
87
- export { ACCESS_ACTIONS, POLICY_REVISION, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision, verifyCheckpoint };
106
+ export { ACCESS_ACTIONS, POLICY_REVISION, accessRevision, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision, verifyCheckpoint };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coffre/core",
3
- "version": "0.14.0",
3
+ "version": "0.14.2",
4
4
  "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -83,14 +83,14 @@
83
83
  "jose": "6.2.3",
84
84
  "oauth4webapi": "3.8.8",
85
85
  "zod": "4.4.3",
86
- "@coffre/client": "0.14.0"
86
+ "@coffre/client": "0.14.2"
87
87
  },
88
88
  "devDependencies": {
89
89
  "@hegeldev/hegel": "0.4.7",
90
90
  "@types/node": "26.1.1",
91
91
  "tsdown": "0.23.0",
92
92
  "typescript": "5.9.3",
93
- "@coffre/conformance": "0.14.0"
93
+ "@coffre/conformance": "0.14.2"
94
94
  },
95
95
  "scripts": {
96
96
  "build": "tsdown",
@@ -32,7 +32,12 @@ export type Principal =
32
32
  * looks up coffre's own credentials.
33
33
  */
34
34
  export interface IdentityVerifier {
35
- verify(token: string, request?: { sourceIp: string | null }): Promise<Principal>;
35
+ /**
36
+ * `recall`: the request reads values, and has the vault check, before it
37
+ * answers, an answer about its caller kept from an earlier request
38
+ * (server accesses.ts): a verifier that asks the vault may give that one.
39
+ */
40
+ verify(token: string, request?: { sourceIp: string | null; recall?: boolean }): Promise<Principal>;
36
41
  }
37
42
 
38
43
  /** Access delivers the JWT to the origin in this header. */
package/src/vault.ts CHANGED
@@ -25,8 +25,15 @@ export { describeAccessFault, type AccessFault, type FaultGrant, type FaultNames
25
25
  * the vault has already logged. Only a fault (a bug, the store down) throws.
26
26
  */
27
27
  export interface Vault {
28
- /** Unwrap data keys for `principal`: all of them, or none. */
29
- unwrap(input: UnwrapInput): Promise<Outcome<{ keys: string[] }>>;
28
+ /**
29
+ * Unwrap data keys for `principal`: all of them, or none. Given the
30
+ * revision of an answer of `access` the app decided the read on
31
+ * (`accessRevision`), only while the principal's access is still that
32
+ * one, under their row and the head the decision holds: otherwise it
33
+ * refuses `access_changed` and logs no read, and says, by naming it back,
34
+ * that it checked. A vault older than 0.14.1 names none: it checked none.
35
+ */
36
+ unwrap(input: UnwrapInput): Promise<Outcome<{ keys: string[]; accessRevision?: string }>>;
30
37
  /**
31
38
  * Wrap fresh data keys for new versions `principal` writes: all, or none.
32
39
  * `seqs` are the `key.wrap` entries, one per key, which the app's
@@ -69,6 +76,7 @@ export interface Vault {
69
76
 
70
77
  /**
71
78
  * What one principal holds right now: the app asks once per request,
79
+ * unless the request reads values on an answer it kept (`accessRevision`),
72
80
  * and at sign-in for each verified email. A decision, its rows checked:
73
81
  * lists of who holds what read the rows themselves, and need not ask.
74
82
  * A person the vault's `owners` names who is no Owner of all of it
@@ -260,6 +268,14 @@ export type RefusalCode =
260
268
  * when another came since: asked again, it is weighed as the policy is now.
261
269
  */
262
270
  | 'policy_changed'
271
+ /**
272
+ * A read decided on an earlier answer of `access` about its principal
273
+ * (`accessRevision`) that is not theirs now: nothing was read, and no
274
+ * read logged; with a key service, the intent it logged is closed, each
275
+ * key refused.
276
+ * Asked again on the answer now, it is decided as they are now.
277
+ */
278
+ | 'access_changed'
263
279
  /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
264
280
  | 'log_broken'
265
281
  /**
@@ -370,6 +386,13 @@ export type Through = { credentialScope?: CredentialScope | null; caller: Caller
370
386
  export type UnwrapInput = Correlation & Through & {
371
387
  principal: string;
372
388
  purpose: Purpose;
389
+ /**
390
+ * The revision of the answer of `access` the app decided this read on,
391
+ * kept from an earlier request (`Access.revision`): the vault refuses
392
+ * `access_changed` unless its answer now has the same. Absent when the
393
+ * app asked this request.
394
+ */
395
+ accessRevision?: string;
373
396
  /**
374
397
  * That a `copy` keeps each sensitive value sensitive in what it writes:
375
398
  * the vault opens a sensitive value to copy for a person only when told
@@ -452,8 +475,36 @@ export type Access = {
452
475
  by: string | null;
453
476
  /** The instance's policy, which every decision about them reads: absent from a vault older than 0.10, which decides as it ships. */
454
477
  policy?: Policy;
478
+ /**
479
+ * The answer, in a word (`accessRevision`): the app keeps the answer
480
+ * between requests, and a read it decides on the kept one names it, which
481
+ * the vault refuses unless its answer now has the same. Absent from a
482
+ * vault older than 0.14.1, whose answers the app keeps for nothing.
483
+ */
484
+ revision?: string;
455
485
  };
456
486
 
487
+ /**
488
+ * An answer of `access` in a word: equal for two answers that say the same,
489
+ * whatever order the rows came back in, and different for any change to
490
+ * what they say, a grant lapsed, the policy's or the member's.
491
+ */
492
+ export function accessRevision(access: Access): string {
493
+ const { revision: _, grants, ...rest } = access;
494
+ const facts = canonical({ ...rest, grants: grants.map(canonical).sort() });
495
+ return createHash('sha256').update(facts).digest('base64url').slice(0, 32);
496
+ }
497
+
498
+ /** A value as JSON whose every object's keys are sorted, at every depth. */
499
+ function canonical(value: unknown): string {
500
+ if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
501
+ if (typeof value === 'object' && value !== null) {
502
+ const entries = Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
503
+ return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
504
+ }
505
+ return JSON.stringify(value);
506
+ }
507
+
457
508
  /**
458
509
  * One place: a role to hold there, with an optional end, or null for none.
459
510
  * An environment's place names its project too.