@coffre/core 0.9.0 → 0.10.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.
package/dist/kek.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { deriveLogKey } from "./audit.js";
2
- import { i as KekUnavailableError, n as KekBadClaimError, o as checkContext, r as KekCancelledError, s as encodeAad, t as DEK_BYTES } from "./types-E1Sz50n6.js";
3
- import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
2
+ import { i as KekUnavailableError, n as KekBadClaimError, o as checkContext, r as KekCancelledError, s as encodeAad, t as DEK_BYTES } from "./types-Cp3lB_-W.js";
3
+ import { createCipheriv, createDecipheriv, createHash, createHmac, createSecretKey, randomBytes, timingSafeEqual } from "node:crypto";
4
4
  //#region src/kek/cancellation.ts
5
5
  function checkOperation(operation, uncertain = false) {
6
6
  if (operation !== void 0 && (operation.signal.aborted || Date.now() >= operation.deadline)) throw new KekCancelledError(uncertain);
@@ -66,10 +66,11 @@ var LocalKekProvider = class LocalKekProvider {
66
66
  provider = "local";
67
67
  keyId;
68
68
  keyVersion;
69
+ /** Imported once: a raw key would be imported again for every key it wraps or opens. */
69
70
  #kek;
70
71
  constructor(kek, keyId, keyVersion = "1") {
71
72
  if (kek.length !== KEK_BYTES) throw new Error(`a local vault key must be ${KEK_BYTES} bytes, got ${kek.length}`);
72
- this.#kek = kek;
73
+ this.#kek = createSecretKey(kek);
73
74
  this.keyId = keyId;
74
75
  this.keyVersion = keyVersion;
75
76
  }
@@ -426,7 +427,8 @@ function encryptionContext(ctx) {
426
427
  "coffre:project": ctx.projectId,
427
428
  "coffre:environment": ctx.environmentId,
428
429
  "coffre:secret": ctx.secretId,
429
- ...ctx.owner === void 0 ? {} : { "coffre:owner": ctx.owner }
430
+ ...ctx.owner === void 0 ? {} : { "coffre:owner": ctx.owner },
431
+ ...ctx.sensitive === true ? { "coffre:sensitive": "true" } : {}
430
432
  };
431
433
  }
432
434
  /**
package/dist/recipe.d.ts CHANGED
@@ -94,13 +94,14 @@ export declare function randomValue(encoding: Encoding, bytes: number, random?:
94
94
  export declare function generate(recipe: Recipe): Promise<Generated>;
95
95
  /**
96
96
  * What a write of generated values sends, by key: each value with how it
97
- * was made, and for a regenerate the version it replaces, which the server
98
- * holds it to.
97
+ * was made, for a regenerate the version it replaces, which the server
98
+ * holds it to, and who sees it, where the write says.
99
99
  */
100
100
  export type GeneratedWrite = Record<string, {
101
101
  value: string;
102
102
  generated: Generation;
103
103
  replaces?: string;
104
+ sensitivity?: 'secret' | 'sensitive';
104
105
  }>;
105
106
  /**
106
107
  * A value made by the recipe for `key`, as a write sends it, and for a key
@@ -11,9 +11,12 @@
11
11
  * names would mean that renaming an environment or a secret key makes every
12
12
  * existing ciphertext permanently undecryptable.
13
13
  *
14
- * A personal config's values are bound to their owner too, `owner`, which
15
- * only the vault's wrap of the data key carries (docs/design/forking.md,
16
- * section 4): a forged owner column fails to open, rather than granting.
14
+ * A personal config's values are bound to their owner too, `owner`, and a
15
+ * sensitive value to being one, `sensitive`, which only the vault's wrap of
16
+ * the data key carries (docs/design/forking.md, section 4;
17
+ * docs/design/credential-proxy.md, section 2): a forged owner or sensitivity
18
+ * column fails to open, rather than granting. The value's own ciphertext
19
+ * binds the ids alone, so a version made sensitive keeps its ciphertext.
17
20
  */
18
21
  type SecretContext = {
19
22
  projectId: string;
@@ -21,13 +24,15 @@ type SecretContext = {
21
24
  secretId: string;
22
25
  /** A personal config's owner, as `ownerKey` hashes them. */
23
26
  owner?: string;
27
+ /** A sensitive value's: never handed back to a person (`sensitive` in @coffre/core/vault). Absent otherwise, never false. */
28
+ sensitive?: true;
24
29
  };
25
30
  /**
26
31
  * Version prefix for the AAD encoding. If the encoding ever changes, this
27
32
  * changes with it, and old ciphertexts keep decrypting under the old rule.
28
33
  */
29
34
  declare const AAD_VERSION = "coffre.aad.v1";
30
- /** Throw unless every field is a lowercase UUID, and an owner a lowercase SHA-256. */
35
+ /** Throw unless every field is a lowercase UUID, an owner a lowercase SHA-256, and `sensitive` true if there. */
31
36
  declare function checkContext(ctx: SecretContext): void;
32
37
  /**
33
38
  * A personal config's owner as its values' context binds them: the SHA-256
package/dist/schemas.d.ts CHANGED
@@ -45,6 +45,8 @@ export declare const instanceRole: z.ZodEnum<{
45
45
  member: "member";
46
46
  admin: "admin";
47
47
  }>;
48
+ /** A project role's id: one coffre ships, or one an Owner made (`ROLE_ID`). Which the instance defines, its policy says. */
49
+ export declare const roleId: z.ZodString;
48
50
  /** Which projects or environments a scope takes in, by slug: `all`, `{ only: [...] }` or `{ except: [...] }`. */
49
51
  export declare const scopeFilter: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodObject<{
50
52
  only: z.ZodArray<z.ZodString>;
package/dist/schemas.js CHANGED
@@ -1,4 +1,4 @@
1
- import { i as INSTANCE_ROLE_NAMES } from "./access-B1wpMzEB.js";
1
+ import { m as ROLE_ID, s as INSTANCE_ROLE_NAMES } from "./access-Dl13x6mB.js";
2
2
  import { PROJECT_PAGES } from "./pages.js";
3
3
  import { z } from "zod";
4
4
  //#region src/schemas.ts
@@ -47,6 +47,8 @@ function shownMember(member) {
47
47
  const principalType = z.enum(["user", "service"]);
48
48
  const principalId = z.string().trim().min(1).max(320);
49
49
  const instanceRole = z.enum(INSTANCE_ROLE_NAMES);
50
+ /** A project role's id: one coffre ships, or one an Owner made (`ROLE_ID`). Which the instance defines, its policy says. */
51
+ const roleId = z.string().regex(ROLE_ID, "a role is named by lowercase letters, digits and dashes, 2 to 32, starting with a letter");
50
52
  /** Which projects or environments a scope takes in, by slug: `all`, `{ only: [...] }` or `{ except: [...] }`. */
51
53
  const scopeFilter = z.union([
52
54
  z.literal("all"),
@@ -61,4 +63,4 @@ const scopeInput = z.object({
61
63
  const grantId = z.string().uuid();
62
64
  const emailAddress = z.string().email().max(320);
63
65
  //#endregion
64
- export { PERSONAL_SUFFIX, TOMBSTONE, displayName, emailAddress, environmentPath, environmentSlug, folderName, grantId, instanceRole, isTombstone, personalOf, principalId, principalType, scopeFilter, scopeInput, secretKey, shownMember, slug, tombstoneOf };
66
+ export { PERSONAL_SUFFIX, TOMBSTONE, displayName, emailAddress, environmentPath, environmentSlug, folderName, grantId, instanceRole, isTombstone, personalOf, principalId, principalType, roleId, scopeFilter, scopeInput, secretKey, shownMember, slug, tombstoneOf };
@@ -9,12 +9,13 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
9
9
  function assertUuid(value, field) {
10
10
  if (typeof value !== "string" || !UUID_RE.test(value)) throw new Error(`context.${field} must be a lowercase UUID, got: ${String(value)}`);
11
11
  }
12
- /** Throw unless every field is a lowercase UUID, and an owner a lowercase SHA-256. */
12
+ /** Throw unless every field is a lowercase UUID, an owner a lowercase SHA-256, and `sensitive` true if there. */
13
13
  function checkContext(ctx) {
14
14
  assertUuid(ctx.projectId, "projectId");
15
15
  assertUuid(ctx.environmentId, "environmentId");
16
16
  assertUuid(ctx.secretId, "secretId");
17
17
  if (ctx.owner !== void 0 && (typeof ctx.owner !== "string" || !OWNER_RE.test(ctx.owner))) throw new Error(`context.owner must be a lowercase SHA-256, got: ${String(ctx.owner)}`);
18
+ if (ctx.sensitive !== void 0 && ctx.sensitive !== true) throw new Error(`context.sensitive is true or absent, got: ${String(ctx.sensitive)}`);
18
19
  }
19
20
  const OWNER_RE = /^[0-9a-f]{64}$/;
20
21
  /**
@@ -34,7 +35,7 @@ function ownerKey(member) {
34
35
  */
35
36
  function encodeAad(ctx) {
36
37
  checkContext(ctx);
37
- return Buffer.from(`${AAD_VERSION}|${ctx.projectId}|${ctx.environmentId}|${ctx.secretId}${ctx.owner === void 0 ? "" : `|owner:${ctx.owner}`}`, "utf8");
38
+ return Buffer.from(`${AAD_VERSION}|${ctx.projectId}|${ctx.environmentId}|${ctx.secretId}${ctx.owner === void 0 ? "" : `|owner:${ctx.owner}`}${ctx.sensitive === true ? "|sensitive" : ""}`, "utf8");
38
39
  }
39
40
  //#endregion
40
41
  //#region src/kek/types.ts
package/dist/vault.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { S as ServiceSetting, a as GrantPlace, b as Scope, l as InstanceRole, t as CredentialScope, y as Role } from "./access-CONhKG2P.js";
1
+ import { D as RoleDefinition, E as Role, O as Scope, S as Policy, j as ServiceSetting, m as InstanceRole, r as CredentialScope, u as GrantPlace } from "./access-CF4noOjL.js";
2
2
  //#region src/access-fault.d.ts
3
3
  /**
4
4
  * Why the vault's members and grants do not follow from its log, as facts
@@ -100,21 +100,20 @@ export interface Vault {
100
100
  /**
101
101
  * Wrap fresh data keys for new versions `principal` writes: all, or none.
102
102
  * `seqs` are the `key.wrap` entries, one per key, which the app's
103
- * `secret.write` entries name as related.
103
+ * `secret.write` entries name as related. `sensitive` says, per key,
104
+ * whether its wrap binds it as sensitive: a vault older than 0.10 answers
105
+ * none, binding none, and the app stores no sensitive version it wrapped.
104
106
  */
105
- wrap(input: WrapInput): Promise<Outcome<{
106
- wrapped: WrappedKey[];
107
- seqs: number[];
108
- }>>;
107
+ wrap(input: WrapInput): Promise<Outcome<Wrapped>>;
109
108
  /**
110
109
  * Wrap existing data keys again for new versions of the same secrets,
111
- * under the current key: restoring an old value. It needs a write grant,
112
- * not a read one, since the key never leaves the vault.
110
+ * under the current key: restoring an old value, or making one stricter.
111
+ * It needs a write grant, not a read one, since the key never leaves the
112
+ * vault. A new version is never less sensitive than the one it is made
113
+ * from, or than its secret's newest: a value is made looser only by
114
+ * being written again (`invalid`).
113
115
  */
114
- rewrap(input: RewrapInput): Promise<Outcome<{
115
- wrapped: WrappedKey[];
116
- seqs: number[];
117
- }>>;
116
+ rewrap(input: RewrapInput): Promise<Outcome<Wrapped>>;
118
117
  /**
119
118
  * Make secrets references to others: whoever can read the holder's
120
119
  * environment reads the source through it (docs/design/environments.md).
@@ -179,20 +178,53 @@ export interface Vault {
179
178
  setSettings(input: SetSettingsInput): Promise<Outcome<{
180
179
  settings: Settings;
181
180
  }>>;
181
+ /**
182
+ * The instance's access policy (`Policy` in @coffre/core/access): its
183
+ * roles, as an Owner edited and made them, and its protected
184
+ * environments, as the vault's newest `policy.change` says, by its MAC.
185
+ * As it ships, before any. A vault older than 0.10 has none, and the app
186
+ * decides as it ships.
187
+ */
188
+ policy(): Promise<Policy>;
189
+ /**
190
+ * Change the policy by one change, its own `policy.change` entry, which
191
+ * names it and what it was (docs/design/roles.md):
192
+ * - a project or instance role defined, or put back as it ships (null),
193
+ * or, one an Owner made, deleted while no grant names it: an Owner of
194
+ * the whole instance, and never the Owner role, nor the instance's
195
+ * Member;
196
+ * - environments of one project protected, by whoever manages its
197
+ * environments, before their rows exist too (a fork's); or
198
+ * unprotected, by an Owner of the whole instance.
199
+ * The policy after it, and the newest `policy.change`, which it is as of:
200
+ * the change's own, when it changed anything.
201
+ */
202
+ changePolicy(input: ChangePolicyInput): Promise<Outcome<{
203
+ policy: Policy;
204
+ seq: number | null;
205
+ }>>;
182
206
  /**
183
207
  * Sign the log up to its last entry, in an `audit.checkpoint` entry of
184
- * the vault's, if the chain recomputes, the vault's entries by their MACs,
185
- * and the prefix the last checkpoint signed is still there. The first
186
- * checkpoint of each hour recomputes from the first entry; the others
187
- * resume from the prefix the last one signed, which the vault recomputed
188
- * itself, while it still has every entry and ends at the hash it signed.
189
- * The vault reads the log itself: it takes nobody's word
190
- * for where it ends, or for what came before. It checks every
191
- * member's row too, as `access` would, and logs a `vault.tampered` for
192
- * each one changed around it: lists read rows without asking the vault.
208
+ * the vault's, if the chain recomputes from the last checkpoint, the
209
+ * vault's entries by their MACs, and that checkpoint's prefix is still
210
+ * there, whole. The entry keeps the checkpoint's tally beside it: what a
211
+ * walk from the first entry has gathered by the prefix's end (the
212
+ * vault's keys, its key batches under way, who is a member and what they
213
+ * hold), so that the next checkpoint, and every verification, go on from
214
+ * there and read only what is new. A log longer than one walk, as after
215
+ * an upgrade from 0.10.0, is signed a stretch a call, behind its head,
216
+ * until the checkpoints catch up. Each call also rehashes a stretch of
217
+ * what was signed before, round and round, which an entry edited in place
218
+ * fails: then it refuses, and every verification reports the refusal.
219
+ * A rehash the database fails moves on next time, and `warning` says so;
220
+ * a refusal it would have cleared stands meanwhile. The vault reads the log itself: it takes nobody's word for where
221
+ * it ends, or for what came before. It checks every member's row too, as
222
+ * `access` would, and logs a `vault.tampered` for each one changed around
223
+ * it: lists read rows without asking the vault.
193
224
  */
194
225
  checkpoint(): Promise<Outcome<{
195
226
  checkpoint: Checkpoint;
227
+ warning?: string;
196
228
  }>>;
197
229
  /**
198
230
  * What the vault's configuration says, which the app shows: the keys its
@@ -220,13 +252,18 @@ export interface Vault {
220
252
  */
221
253
  keyChecks(): Promise<KeyChecks>;
222
254
  /**
223
- * Check the whole log: the vault's entries by their MACs, every
224
- * checkpoint against the prefix it signed, the key batches accounted for,
225
- * and replay it to see that who is a member, and what they hold, follow
226
- * from it. The links and hashes of the chain are the caller's to
227
- * recompute through `upTo`, as the app does first; with none, the vault
228
- * recomputes them all itself. A verdict and nothing else, so anyone may
229
- * ask; the app asks for those who read the whole log (`readsWholeLog`).
255
+ * Check the log from a checkpoint's tally, the newest unless `from`
256
+ * names another, or the first entry: the vault's entries since by their
257
+ * MACs, every checkpoint among them against the prefix it signed, the key
258
+ * batches accounted for, and the members and grants replayed on from the
259
+ * tally to see that the rows follow. With `to`, a later checkpoint, the
260
+ * walk stops at the prefix it signed and must come to the tally it keeps:
261
+ * a stretch of the whole log, walked from the first entry a stretch at a
262
+ * time. The links and hashes of the chain are the caller's to recompute
263
+ * through `upTo`, as the app does first; with none, the vault recomputes
264
+ * them itself, no further than one walk. A verdict and nothing else, so
265
+ * anyone may ask; the app asks for those who read the whole log
266
+ * (`readsWholeLog`).
230
267
  */
231
268
  verifyLog(input: VerifyLogInput): Promise<LogVerification>;
232
269
  }
@@ -255,11 +292,11 @@ export type RefusalCode =
255
292
  /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
256
293
  'bad_claim' |
257
294
  /**
258
- * A person asked for values to be handed back, where people get stand-ins
259
- * (`people: 'stand-ins'`): their apps use values through the credential
260
- * proxy instead, and only service accounts read them.
295
+ * A person asked for a sensitive value to be handed back (`handsBack`):
296
+ * nobody sees one, Owners included. Their apps use it through the
297
+ * credential proxy, and service accounts read it.
261
298
  */
262
- 'stand_ins' |
299
+ 'sensitive' |
263
300
  /**
264
301
  * The project or environment was deleted for good: nothing under it is
265
302
  * opened or wrapped again, whatever grant would cover it.
@@ -283,6 +320,11 @@ export type RefusalCode =
283
320
  'last_owner' |
284
321
  /** Well-formed, but not something the rules allow: a project role on an environment, a service account with an instance role. */
285
322
  'invalid' |
323
+ /**
324
+ * A change to the policy weighed from one revision of it (`revision`)
325
+ * when another came since: asked again, it is weighed as the policy is now.
326
+ */
327
+ 'policy_changed' |
286
328
  /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
287
329
  'log_broken' |
288
330
  /**
@@ -315,6 +357,20 @@ export type SecretRef = {
315
357
  version: number;
316
358
  /** `market/prod/DATABASE_URL`. */
317
359
  path: string;
360
+ /**
361
+ * Whether the version is sensitive: its value is never handed back to a
362
+ * person, on any credential of theirs, only used for them or read by a
363
+ * service account. Its data key's wrap binds it, so a version written
364
+ * sensitive opens as nothing else. Absent, or false, for a secret or a
365
+ * plain value.
366
+ */
367
+ sensitive?: boolean;
368
+ };
369
+ /** What a wrap or rewrap answers: each key as wrapped, its entry, and whether its wrap binds it sensitive. */
370
+ export type Wrapped = {
371
+ wrapped: WrappedKey[];
372
+ seqs: number[];
373
+ sensitive: boolean[];
318
374
  };
319
375
  /** A wrapped data key and the key encryption key that wrapped it; `bytes` is base64. */
320
376
  export type WrappedKey = {
@@ -341,17 +397,21 @@ export type KeyChecks = {
341
397
  /**
342
398
  * Why someone reads: shown in the log, and the same rules apply to each. A
343
399
  * fork reads to `copy`. The credential proxy reads to `use`, a value it
344
- * injects into a request and never hands back, or to `expose`, one the
345
- * deployment lets people's apps hold. Where people get stand-ins
346
- * (`people: 'stand-ins'`), a person opens nothing to `reveal`, `run` or
347
- * `compare` (`HANDED_BACK`).
400
+ * injects into a request and never hands back, or to `expose`, one it
401
+ * gives a person's app as it is (`coffre run`'s plan).
348
402
  */
349
403
  export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
350
404
  /**
351
- * What a person never opens where people get stand-ins: values handed back
352
- * to them, and a dry run's `compare`, which tells them whether a guess was right.
405
+ * Whether a read hands values back to whoever asked, which a person never
406
+ * gets of a sensitive value: every purpose but the proxy's `use` and a
407
+ * fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
408
+ * `compare` included, which tells them whether a guess was right, and any
409
+ * purpose a later app may name.
353
410
  */
354
- export declare const HANDED_BACK: readonly Purpose[];
411
+ export declare function handsBack(read: {
412
+ purpose: string;
413
+ keepsSensitive?: boolean;
414
+ }): boolean;
355
415
  /** Ties the vault's entries to the app's request and audit rows. */
356
416
  type Correlation = {
357
417
  requestId?: string | null;
@@ -379,6 +439,13 @@ export type Through = {
379
439
  export type UnwrapInput = Correlation & Through & {
380
440
  principal: string;
381
441
  purpose: Purpose;
442
+ /**
443
+ * That a `copy` keeps each sensitive value sensitive in what it writes:
444
+ * the vault opens a sensitive value to copy for a person only when told
445
+ * so, which an app older than 0.10, that would write it as a secret
446
+ * anyone with read sees, never says.
447
+ */
448
+ keepsSensitive?: boolean;
382
449
  /**
383
450
  * `via` reads a source's current version through a reference: the vault
384
451
  * checks the reader's grants on the holder's environment, as its
@@ -468,6 +535,8 @@ export type Access = {
468
535
  /** When the status last changed, and who changed it; null for strangers. */
469
536
  since: string | null;
470
537
  by: string | null;
538
+ /** The instance's policy, which every decision about them reads: absent from a vault older than 0.10, which decides as it ships. */
539
+ policy?: Policy;
471
540
  };
472
541
  /**
473
542
  * One place: a role to hold there, with an optional end, or null for none.
@@ -524,6 +593,48 @@ export type SetSettingsInput = Correlation & Through & {
524
593
  actor: string;
525
594
  settings: Settings;
526
595
  };
596
+ /** One change to the policy (`changePolicy`). */
597
+ export type PolicyChange = {
598
+ kind: 'role';
599
+ role: Role;
600
+ definition: RoleDefinition | null;
601
+ } | {
602
+ kind: 'instance-role';
603
+ role: InstanceRole;
604
+ definition: RoleDefinition | null;
605
+ } | {
606
+ kind: 'protect';
607
+ projectId: string;
608
+ environmentIds: string[];
609
+ protected: boolean;
610
+ };
611
+ /**
612
+ * A policy's revision, as a decision made from it names it: its newest
613
+ * `policy.change` (null for none), and the slug of each environment it
614
+ * protects, by id, which a scoped instance role's filters match, and
615
+ * which a rename or a deletion changes with no `policy.change` of its own
616
+ * (docs/design/roles.md, "What changes the policy"). Equal revisions decide
617
+ * alike.
618
+ *
619
+ * 57.3f9a0c2e81b4d7a6 change 57, prod protected as `prod`
620
+ * 57.b20e94d1c6a8f305 change 57, prod renamed `staging`
621
+ */
622
+ export declare function policyRevision(seq: number | bigint | null, policy: Pick<Policy, 'protectedIn'>): string;
623
+ /** A revision as `policyRevision` writes it. */
624
+ export declare const POLICY_REVISION: RegExp;
625
+ export type ChangePolicyInput = Correlation & Through & {
626
+ actor: string;
627
+ change: PolicyChange;
628
+ /**
629
+ * The policy the caller decided from, as its revision
630
+ * (`policyRevision`): its newest `policy.change` and the rows of the
631
+ * environments it protects. Refused, `policy_changed`, unless the policy
632
+ * under the vault's head is still that one, so that a request carries on
633
+ * from the policy it made (`seq`) only where nothing came between, and a
634
+ * change previewed is made as previewed. Unchecked when absent.
635
+ */
636
+ revision?: string;
637
+ };
527
638
  /**
528
639
  * A prefix of the log the vault signed: every entry up to `seq`, the last
529
640
  * of which has `hash`, which pins every byte before it. Kept as the vault's
@@ -558,22 +669,39 @@ export type VerifyLogInput = {
558
669
  * The last entry the app verified, every link and hash up to it
559
670
  * recomputed and its own entries checked by its key: the vault checks the
560
671
  * log still holds it, so between them both authors' entries are
561
- * authenticated over the same prefix, and the vault leaves the links to
672
+ * authenticated over the same stretch, and the vault leaves the links to
562
673
  * the app.
563
674
  */
564
675
  upTo?: LogHead | null;
676
+ /**
677
+ * Where the vault's walk starts: the seq of one of its `audit.checkpoint`
678
+ * entries that keeps a tally, or `start`, the first entry. The newest
679
+ * such checkpoint when absent, and a vault older than 0.10.1 walks from
680
+ * the first entry whatever it says.
681
+ */
682
+ from?: number | 'start';
683
+ /**
684
+ * A later checkpoint's entry, whose prefix `upTo` is: the walk ends
685
+ * there, and must come to the tally it keeps. The members' rows and the
686
+ * key batches are as they are now, not then, so only a walk without one
687
+ * holds them to the log.
688
+ */
689
+ to?: number;
565
690
  };
566
691
  /**
567
- * Whether the vault's log holds, with the number of entries in it. On a
568
- * failure, the entry where it breaks, or null when the chain holds but the
569
- * members and grants do not follow from it. Then `fault` says which, as
570
- * facts the app can word with names: `reason` has only ids.
571
- * Full checks report live key batches in `pending`; overdue ones fail.
692
+ * Whether the vault's log holds, with the number of its entries through
693
+ * where the walk ended, `through`: `upTo`, the prefix `to` signed, or as
694
+ * far as one walk goes. On a failure, the entry where it breaks, or null
695
+ * when the chain holds but the members and grants do not follow from it.
696
+ * Then `fault` says which, as facts the app can word with names: `reason`
697
+ * has only ids. A walk that ends at the present reports live key batches in
698
+ * `pending`; overdue ones fail.
572
699
  */
573
700
  export type LogVerification = {
574
701
  ok: true;
575
702
  entries: number;
576
703
  pending?: number;
704
+ through?: number;
577
705
  } | {
578
706
  ok: false;
579
707
  failedAtSeq: number | null;
package/dist/vault.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { createHash } from "node:crypto";
1
2
  //#region src/checkpoint.ts
2
3
  /** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
3
4
  function checkpointMessage(checkpoint) {
@@ -55,13 +56,32 @@ const ACCESS_ACTIONS = [
55
56
  "access.revoke"
56
57
  ];
57
58
  /**
58
- * What a person never opens where people get stand-ins: values handed back
59
- * to them, and a dry run's `compare`, which tells them whether a guess was right.
59
+ * Whether a read hands values back to whoever asked, which a person never
60
+ * gets of a sensitive value: every purpose but the proxy's `use` and a
61
+ * fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
62
+ * `compare` included, which tells them whether a guess was right, and any
63
+ * purpose a later app may name.
60
64
  */
61
- const HANDED_BACK = [
62
- "reveal",
63
- "run",
64
- "compare"
65
- ];
65
+ function handsBack(read) {
66
+ if (read.purpose === "use") return false;
67
+ return !(read.purpose === "copy" && read.keepsSensitive === true);
68
+ }
69
+ /**
70
+ * A policy's revision, as a decision made from it names it: its newest
71
+ * `policy.change` (null for none), and the slug of each environment it
72
+ * protects, by id, which a scoped instance role's filters match, and
73
+ * which a rename or a deletion changes with no `policy.change` of its own
74
+ * (docs/design/roles.md, "What changes the policy"). Equal revisions decide
75
+ * alike.
76
+ *
77
+ * 57.3f9a0c2e81b4d7a6 change 57, prod protected as `prod`
78
+ * 57.b20e94d1c6a8f305 change 57, prod renamed `staging`
79
+ */
80
+ function policyRevision(seq, policy) {
81
+ const places = Object.values(policy.protectedIn).flat().map(({ environmentId, slug }) => `${environmentId}=${slug ?? ""}`).sort();
82
+ return `${seq === null ? "none" : String(seq)}.${createHash("sha256").update(places.join("\n")).digest("hex").slice(0, 16)}`;
83
+ }
84
+ /** A revision as `policyRevision` writes it. */
85
+ const POLICY_REVISION = /^(none|[1-9][0-9]{0,15})\.[0-9a-f]{16}$/;
66
86
  //#endregion
67
- export { ACCESS_ACTIONS, HANDED_BACK, checkpointMessage, checkpointVerifier, describeAccessFault, verifyCheckpoint };
87
+ export { ACCESS_ACTIONS, POLICY_REVISION, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision, verifyCheckpoint };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coffre/core",
3
- "version": "0.9.0",
3
+ "version": "0.10.1",
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": {
@@ -89,7 +89,7 @@
89
89
  "@types/node": "26.1.1",
90
90
  "tsdown": "0.23.0",
91
91
  "typescript": "5.9.3",
92
- "@coffre/conformance": "0.9.0"
92
+ "@coffre/conformance": "0.10.1"
93
93
  },
94
94
  "scripts": {
95
95
  "build": "tsdown",
@@ -11,7 +11,7 @@ import {
11
11
  type GrantPlace,
12
12
  type InstanceRole,
13
13
  type Place,
14
- type Role,
14
+ type BuiltinRole as Role,
15
15
  type Scope,
16
16
  } from './access.ts';
17
17