@coffre/core 0.10.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
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, randomBytes, timingSafeEqual } from "node:crypto";
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
  }
package/dist/vault.d.ts CHANGED
@@ -205,18 +205,26 @@ export interface Vault {
205
205
  }>>;
206
206
  /**
207
207
  * Sign the log up to its last entry, in an `audit.checkpoint` entry of
208
- * the vault's, if the chain recomputes, the vault's entries by their MACs,
209
- * and the prefix the last checkpoint signed is still there. The first
210
- * checkpoint of each hour recomputes from the first entry; the others
211
- * resume from the prefix the last one signed, which the vault recomputed
212
- * itself, while it still has every entry and ends at the hash it signed.
213
- * The vault reads the log itself: it takes nobody's word
214
- * for where it ends, or for what came before. It checks every
215
- * member's row too, as `access` would, and logs a `vault.tampered` for
216
- * 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.
217
224
  */
218
225
  checkpoint(): Promise<Outcome<{
219
226
  checkpoint: Checkpoint;
227
+ warning?: string;
220
228
  }>>;
221
229
  /**
222
230
  * What the vault's configuration says, which the app shows: the keys its
@@ -244,13 +252,18 @@ export interface Vault {
244
252
  */
245
253
  keyChecks(): Promise<KeyChecks>;
246
254
  /**
247
- * Check the whole log: the vault's entries by their MACs, every
248
- * checkpoint against the prefix it signed, the key batches accounted for,
249
- * and replay it to see that who is a member, and what they hold, follow
250
- * from it. The links and hashes of the chain are the caller's to
251
- * recompute through `upTo`, as the app does first; with none, the vault
252
- * recomputes them all itself. A verdict and nothing else, so anyone may
253
- * 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`).
254
267
  */
255
268
  verifyLog(input: VerifyLogInput): Promise<LogVerification>;
256
269
  }
@@ -656,22 +669,39 @@ export type VerifyLogInput = {
656
669
  * The last entry the app verified, every link and hash up to it
657
670
  * recomputed and its own entries checked by its key: the vault checks the
658
671
  * log still holds it, so between them both authors' entries are
659
- * 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
660
673
  * the app.
661
674
  */
662
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;
663
690
  };
664
691
  /**
665
- * Whether the vault's log holds, with the number of entries in it. On a
666
- * failure, the entry where it breaks, or null when the chain holds but the
667
- * members and grants do not follow from it. Then `fault` says which, as
668
- * facts the app can word with names: `reason` has only ids.
669
- * 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.
670
699
  */
671
700
  export type LogVerification = {
672
701
  ok: true;
673
702
  entries: number;
674
703
  pending?: number;
704
+ through?: number;
675
705
  } | {
676
706
  ok: false;
677
707
  failedAtSeq: number | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coffre/core",
3
- "version": "0.10.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.10.0"
92
+ "@coffre/conformance": "0.10.1"
93
93
  },
94
94
  "scripts": {
95
95
  "build": "tsdown",
package/src/kek/local.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual } from 'node:crypto';
1
+ import { createCipheriv, createDecipheriv, createSecretKey, randomBytes, timingSafeEqual, type KeyObject } from 'node:crypto';
2
2
  import type { SecretContext } from '../context.ts';
3
3
  import { encodeAad } from '../context.ts';
4
4
  import { checkOperation } from './cancellation.ts';
@@ -21,13 +21,14 @@ export class LocalKekProvider implements KekProvider {
21
21
  readonly keyId: string;
22
22
  readonly keyVersion: string;
23
23
 
24
- readonly #kek: Buffer;
24
+ /** Imported once: a raw key would be imported again for every key it wraps or opens. */
25
+ readonly #kek: KeyObject;
25
26
 
26
27
  constructor(kek: Buffer, keyId: string, keyVersion: string = '1') {
27
28
  if (kek.length !== KEK_BYTES) {
28
29
  throw new Error(`a local vault key must be ${KEK_BYTES} bytes, got ${kek.length}`);
29
30
  }
30
- this.#kek = kek;
31
+ this.#kek = createSecretKey(kek);
31
32
  this.keyId = keyId;
32
33
  this.keyVersion = keyVersion;
33
34
  }
package/src/vault.ts CHANGED
@@ -122,17 +122,24 @@ export interface Vault {
122
122
 
123
123
  /**
124
124
  * Sign the log up to its last entry, in an `audit.checkpoint` entry of
125
- * the vault's, if the chain recomputes, the vault's entries by their MACs,
126
- * and the prefix the last checkpoint signed is still there. The first
127
- * checkpoint of each hour recomputes from the first entry; the others
128
- * resume from the prefix the last one signed, which the vault recomputed
129
- * itself, while it still has every entry and ends at the hash it signed.
130
- * The vault reads the log itself: it takes nobody's word
131
- * for where it ends, or for what came before. It checks every
132
- * member's row too, as `access` would, and logs a `vault.tampered` for
133
- * each one changed around it: lists read rows without asking the vault.
134
- */
135
- checkpoint(): Promise<Outcome<{ checkpoint: Checkpoint }>>;
125
+ * the vault's, if the chain recomputes from the last checkpoint, the
126
+ * vault's entries by their MACs, and that checkpoint's prefix is still
127
+ * there, whole. The entry keeps the checkpoint's tally beside it: what a
128
+ * walk from the first entry has gathered by the prefix's end (the
129
+ * vault's keys, its key batches under way, who is a member and what they
130
+ * hold), so that the next checkpoint, and every verification, go on from
131
+ * there and read only what is new. A log longer than one walk, as after
132
+ * an upgrade from 0.10.0, is signed a stretch a call, behind its head,
133
+ * until the checkpoints catch up. Each call also rehashes a stretch of
134
+ * what was signed before, round and round, which an entry edited in place
135
+ * fails: then it refuses, and every verification reports the refusal.
136
+ * A rehash the database fails moves on next time, and `warning` says so;
137
+ * a refusal it would have cleared stands meanwhile. The vault reads the log itself: it takes nobody's word for where
138
+ * it ends, or for what came before. It checks every member's row too, as
139
+ * `access` would, and logs a `vault.tampered` for each one changed around
140
+ * it: lists read rows without asking the vault.
141
+ */
142
+ checkpoint(): Promise<Outcome<{ checkpoint: Checkpoint; warning?: string }>>;
136
143
  /**
137
144
  * What the vault's configuration says, which the app shows: the keys its
138
145
  * checkpoints verify under, by the key id each checkpoint names (the one
@@ -159,13 +166,18 @@ export interface Vault {
159
166
  */
160
167
  keyChecks(): Promise<KeyChecks>;
161
168
  /**
162
- * Check the whole log: the vault's entries by their MACs, every
163
- * checkpoint against the prefix it signed, the key batches accounted for,
164
- * and replay it to see that who is a member, and what they hold, follow
165
- * from it. The links and hashes of the chain are the caller's to
166
- * recompute through `upTo`, as the app does first; with none, the vault
167
- * recomputes them all itself. A verdict and nothing else, so anyone may
168
- * ask; the app asks for those who read the whole log (`readsWholeLog`).
169
+ * Check the log from a checkpoint's tally, the newest unless `from`
170
+ * names another, or the first entry: the vault's entries since by their
171
+ * MACs, every checkpoint among them against the prefix it signed, the key
172
+ * batches accounted for, and the members and grants replayed on from the
173
+ * tally to see that the rows follow. With `to`, a later checkpoint, the
174
+ * walk stops at the prefix it signed and must come to the tally it keeps:
175
+ * a stretch of the whole log, walked from the first entry a stretch at a
176
+ * time. The links and hashes of the chain are the caller's to recompute
177
+ * through `upTo`, as the app does first; with none, the vault recomputes
178
+ * them itself, no further than one walk. A verdict and nothing else, so
179
+ * anyone may ask; the app asks for those who read the whole log
180
+ * (`readsWholeLog`).
169
181
  */
170
182
  verifyLog(input: VerifyLogInput): Promise<LogVerification>;
171
183
  }
@@ -542,19 +554,35 @@ export type VerifyLogInput = {
542
554
  * The last entry the app verified, every link and hash up to it
543
555
  * recomputed and its own entries checked by its key: the vault checks the
544
556
  * log still holds it, so between them both authors' entries are
545
- * authenticated over the same prefix, and the vault leaves the links to
557
+ * authenticated over the same stretch, and the vault leaves the links to
546
558
  * the app.
547
559
  */
548
560
  upTo?: LogHead | null;
561
+ /**
562
+ * Where the vault's walk starts: the seq of one of its `audit.checkpoint`
563
+ * entries that keeps a tally, or `start`, the first entry. The newest
564
+ * such checkpoint when absent, and a vault older than 0.10.1 walks from
565
+ * the first entry whatever it says.
566
+ */
567
+ from?: number | 'start';
568
+ /**
569
+ * A later checkpoint's entry, whose prefix `upTo` is: the walk ends
570
+ * there, and must come to the tally it keeps. The members' rows and the
571
+ * key batches are as they are now, not then, so only a walk without one
572
+ * holds them to the log.
573
+ */
574
+ to?: number;
549
575
  };
550
576
 
551
577
  /**
552
- * Whether the vault's log holds, with the number of entries in it. On a
553
- * failure, the entry where it breaks, or null when the chain holds but the
554
- * members and grants do not follow from it. Then `fault` says which, as
555
- * facts the app can word with names: `reason` has only ids.
556
- * Full checks report live key batches in `pending`; overdue ones fail.
578
+ * Whether the vault's log holds, with the number of its entries through
579
+ * where the walk ended, `through`: `upTo`, the prefix `to` signed, or as
580
+ * far as one walk goes. On a failure, the entry where it breaks, or null
581
+ * when the chain holds but the members and grants do not follow from it.
582
+ * Then `fault` says which, as facts the app can word with names: `reason`
583
+ * has only ids. A walk that ends at the present reports live key batches in
584
+ * `pending`; overdue ones fail.
557
585
  */
558
586
  export type LogVerification =
559
- | { ok: true; entries: number; pending?: number }
587
+ | { ok: true; entries: number; pending?: number; through?: number }
560
588
  | { ok: false; failedAtSeq: number | null; reason: string; fault?: AccessFault };