@coffre/core 0.10.0 → 0.10.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.
- package/dist/kek.js +3 -2
- package/dist/vault.d.ts +52 -22
- package/package.json +2 -2
- package/src/kek/local.ts +4 -3
- package/src/vault.ts +53 -25
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
|
|
209
|
-
*
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
*
|
|
213
|
-
*
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
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
|
|
248
|
-
*
|
|
249
|
-
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
252
|
-
*
|
|
253
|
-
*
|
|
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
|
|
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
|
|
666
|
-
*
|
|
667
|
-
*
|
|
668
|
-
*
|
|
669
|
-
*
|
|
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.
|
|
3
|
+
"version": "0.10.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": {
|
|
@@ -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.
|
|
92
|
+
"@coffre/conformance": "0.10.2"
|
|
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
|
-
|
|
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
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
134
|
-
|
|
135
|
-
|
|
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
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
168
|
-
*
|
|
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
|
|
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
|
|
553
|
-
*
|
|
554
|
-
*
|
|
555
|
-
*
|
|
556
|
-
*
|
|
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 };
|