@coffre/core 0.14.5 → 0.15.0
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/{access-BrdZKp1d.js → access-CgQTlUMz.js} +88 -1
- package/dist/{access-qkMZa-6Z.d.ts → access-DqLJjnLM.d.ts} +62 -1
- package/dist/access.d.ts +2 -2
- package/dist/access.js +2 -2
- package/dist/identity.d.ts +102 -2
- package/dist/identity.js +410 -161
- package/dist/mcp.d.ts +3 -2
- package/dist/mcp.js +6 -2
- package/dist/merkle.d.ts +456 -0
- package/dist/merkle.js +964 -0
- package/dist/schemas.d.ts +11 -3
- package/dist/schemas.js +12 -2
- package/dist/vault.d.ts +1151 -2
- package/dist/vault.js +274 -1
- package/dist/{workloads-CW2dK4AW.d.ts → workloads-D049JH0M.d.ts} +9 -1
- package/dist/workloads.d.ts +2 -2
- package/dist/workloads.js +9 -1
- package/package.json +8 -3
- package/src/access.ts +87 -0
- package/src/answers.ts +209 -0
- package/src/audit/leaf.ts +81 -0
- package/src/audit/merkle.ts +13 -0
- package/src/audit/note.ts +187 -0
- package/src/audit/pair.ts +86 -0
- package/src/audit/tiles.ts +197 -0
- package/src/audit/tree.ts +163 -0
- package/src/audit/verify.ts +393 -0
- package/src/audit/witness.ts +50 -0
- package/src/identity/index.ts +2 -0
- package/src/identity/profile-rules.ts +147 -0
- package/src/identity/run-proof.ts +159 -0
- package/src/identity/workloads.ts +11 -0
- package/src/mcp.ts +6 -2
- package/src/schemas.ts +11 -0
- package/src/vault.ts +931 -0
package/dist/merkle.d.ts
ADDED
|
@@ -0,0 +1,456 @@
|
|
|
1
|
+
//#region src/audit/tree.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* RFC 9162's Merkle tree (Certificate Transparency 2.0, the same tree as RFC
|
|
4
|
+
* 6962), byte for byte: a leaf hashes as SHA-256(0x00 || data), a node as
|
|
5
|
+
* SHA-256(0x01 || left || right), and a tree of n leaves splits at the largest
|
|
6
|
+
* power of two below n. Go's golang.org/x/mod/sumdb/tlog checks what this
|
|
7
|
+
* produces (packages/core/test/go, docs/design/audit-tree.md).
|
|
8
|
+
*
|
|
9
|
+
* Every hash here comes from `Nodes`, which answers for perfect subtrees only
|
|
10
|
+
* (2^level leaves starting at leaf index·2^level). Tiles store those; a proof
|
|
11
|
+
* never needs another kind.
|
|
12
|
+
*
|
|
13
|
+
* Sizes and indexes are plain numbers: exact to 2^53 leaves, 285,000 years at
|
|
14
|
+
* 1,000 a second. No bitwise operator touches them, since JavaScript's cut to
|
|
15
|
+
* 32 bits, and a log passes 2^32 leaves in 50 days at that rate.
|
|
16
|
+
*/
|
|
17
|
+
export type Hash = Buffer;
|
|
18
|
+
export declare const HASH_SIZE = 32;
|
|
19
|
+
export declare function leafHash(data: Uint8Array): Hash;
|
|
20
|
+
export declare function nodeHash(left: Hash, right: Hash): Hash;
|
|
21
|
+
/** The head of the empty tree: SHA-256 of nothing. */
|
|
22
|
+
export declare const EMPTY_ROOT: Hash;
|
|
23
|
+
/** The hash of the perfect subtree of 2^level leaves starting at leaf index·2^level. */
|
|
24
|
+
export type Nodes = (level: number, index: number) => Hash;
|
|
25
|
+
export declare const isPowerOfTwo: (n: number) => boolean;
|
|
26
|
+
/** MTH(D[start:start+n]): the hash of any range, from the perfect subtrees it decomposes into. */
|
|
27
|
+
export declare function rangeHash(nodes: Nodes, start: number, n: number): Hash;
|
|
28
|
+
/** The tree head: MTH of the first `size` leaves. */
|
|
29
|
+
export declare function treeHash(nodes: Nodes, size: number): Hash;
|
|
30
|
+
/** RFC 9162 2.1.3.1, PATH(m, D[n]): the inclusion proof of leaf m in the tree of n leaves, leaf to root. */
|
|
31
|
+
export declare function inclusionProof(nodes: Nodes, m: number, n: number): Hash[];
|
|
32
|
+
/** RFC 9162 2.1.4.1, PROOF(m, D[n]): that the tree of m leaves is a prefix of the tree of n. */
|
|
33
|
+
export declare function consistencyProof(nodes: Nodes, m: number, n: number): Hash[];
|
|
34
|
+
/** RFC 9162 2.1.3.2: whether `proof` shows `leaf` at index m of the tree of n leaves whose head is `root`. */
|
|
35
|
+
export declare function verifyInclusion(leaf: Hash, m: number, n: number, proof: readonly Hash[], root: Hash): boolean;
|
|
36
|
+
/** RFC 9162 2.1.4.2: whether `proof` shows the tree of m leaves (head `first`) a prefix of the tree of n (head `second`). */
|
|
37
|
+
export declare function verifyConsistency(m: number, n: number, first: Hash, second: Hash, proof: readonly Hash[]): boolean;
|
|
38
|
+
//#endregion
|
|
39
|
+
//#region src/audit/note.d.ts
|
|
40
|
+
/**
|
|
41
|
+
* Signed checkpoints in the C2SP formats the transparency ecosystem shares
|
|
42
|
+
* (tlog-checkpoint inside a signed note), so a Go sumdb client, a
|
|
43
|
+
* transparency-dev witness or Sigstore's tooling reads them as they are:
|
|
44
|
+
*
|
|
45
|
+
* coffre.example/audit/uses origin: which log
|
|
46
|
+
* 1048576 tree size
|
|
47
|
+
* 4Ht6…= tree head, base64
|
|
48
|
+
* upto 2026102600000001048599 extension: every number at or below it is final
|
|
49
|
+
* at 1793048700000 extension: when it was signed, ms since the epoch
|
|
50
|
+
* floor 1793048697000 extension: the floor of `at` its barrier set
|
|
51
|
+
* prev 1793048696500 extension: the floor of the pair signed before it
|
|
52
|
+
*
|
|
53
|
+
* — coffre.example/audit/uses Az3g… key ID (4 bytes) and Ed25519 signature, base64
|
|
54
|
+
*
|
|
55
|
+
* `upto` is what turns a gap in the numbers from "maybe deleted" into "never
|
|
56
|
+
* was": every number at or below it is in the tree or will never appear.
|
|
57
|
+
* `floor` is the lowest `at` a use may still be written with once its barrier
|
|
58
|
+
* ran: the database's row of it is unsigned, so the signer holds it here and
|
|
59
|
+
* the next barrier must find it no lower (HotPathOne.tla's BarrierChecksFloor).
|
|
60
|
+
* `prev` is the floor of the pair the signer signed just before, so that a pair
|
|
61
|
+
* is provably the first past a time from its own note: its floor at or past
|
|
62
|
+
* it, its `prev` below. Retention cuts a day there (Seal.tla's CutFirst); a
|
|
63
|
+
* writer who deletes rows cannot make a later pair pass for it.
|
|
64
|
+
* Ed25519 through WebCrypto, which Node and Workers both have.
|
|
65
|
+
*/
|
|
66
|
+
export type Checkpoint = {
|
|
67
|
+
origin: string;
|
|
68
|
+
size: number;
|
|
69
|
+
root: Hash;
|
|
70
|
+
upto: bigint;
|
|
71
|
+
at: number;
|
|
72
|
+
floor: number;
|
|
73
|
+
prev: number;
|
|
74
|
+
};
|
|
75
|
+
/** The largest number a log entry may carry: Postgres's bigint. */
|
|
76
|
+
export declare const MAX_NUMBER: bigint;
|
|
77
|
+
export declare function checkpointBody(c: Checkpoint): string;
|
|
78
|
+
/** The checkpoint a note's text holds; throws on anything else, byte for byte, since the database is a writer's to shape. */
|
|
79
|
+
export declare function parseCheckpoint(text: string): Checkpoint;
|
|
80
|
+
export type NoteSigner = {
|
|
81
|
+
name: string;
|
|
82
|
+
id: Buffer;
|
|
83
|
+
publicKey: Buffer;
|
|
84
|
+
/** Go's note verifier key: `<name>+<key ID, hex>+<base64(0x01 || public key)>`. */
|
|
85
|
+
verifierKey: string;
|
|
86
|
+
sign(message: Uint8Array): Promise<Buffer>;
|
|
87
|
+
};
|
|
88
|
+
export type NoteVerifier = {
|
|
89
|
+
name: string;
|
|
90
|
+
id: Buffer;
|
|
91
|
+
verify(message: Uint8Array, signature: Uint8Array): Promise<boolean>;
|
|
92
|
+
};
|
|
93
|
+
/** A signer named `name`, from a 32-byte Ed25519 seed. */
|
|
94
|
+
export declare function noteSigner(name: string, seed: Uint8Array): Promise<NoteSigner>;
|
|
95
|
+
export declare function noteVerifier(verifierKey: string): Promise<NoteVerifier>;
|
|
96
|
+
/** A signed note: the text, a blank line, then one signature line per signer. */
|
|
97
|
+
export declare function signNote(text: string, signers: readonly NoteSigner[]): Promise<string>;
|
|
98
|
+
/** Adds a signature (a witness's cosignature) to a signed note. */
|
|
99
|
+
export declare function cosignNote(note: string, signer: NoteSigner): Promise<string>;
|
|
100
|
+
/**
|
|
101
|
+
* A signed note's text and signature lines, read as strictly as Go's
|
|
102
|
+
* note.Open, so that a note stored in the database opens here only if every
|
|
103
|
+
* Go reader and C2SP witness would open it too. Throws on anything else.
|
|
104
|
+
*/
|
|
105
|
+
export declare function splitNote(note: string): {
|
|
106
|
+
text: string;
|
|
107
|
+
signatures: {
|
|
108
|
+
name: string;
|
|
109
|
+
id: Buffer;
|
|
110
|
+
signature: Buffer;
|
|
111
|
+
}[];
|
|
112
|
+
};
|
|
113
|
+
/**
|
|
114
|
+
* The note's text if `verifier` signed it, else null; null for anything that
|
|
115
|
+
* is not a signed note too. As Go's note.Open given this one key, the first
|
|
116
|
+
* signature line that names this key decides: if it does not verify, the
|
|
117
|
+
* whole note is invalid, whatever other lines say; later lines by the key are
|
|
118
|
+
* ignored. (Given several keys, Go also refuses a bad line
|
|
119
|
+
* by any of them; each tree's note is opened with its own key alone.)
|
|
120
|
+
*/
|
|
121
|
+
export declare function openNote(note: string, verifier: NoteVerifier): Promise<string | null>;
|
|
122
|
+
/** A checkpoint if `verifier` signed it and it names that key's log as its origin, else null. */
|
|
123
|
+
export declare function openCheckpoint(note: string, verifier: NoteVerifier): Promise<Checkpoint | null>;
|
|
124
|
+
//#endregion
|
|
125
|
+
//#region src/audit/pair.d.ts
|
|
126
|
+
/**
|
|
127
|
+
* 0.15's log is two growing trees, one per retention class (W212, by numbers):
|
|
128
|
+
* `changes`, kept for good, and `uses`, dropped by day. Each is a standard log
|
|
129
|
+
* with its own origin and key, so any C2SP witness or Go's tlog reads either
|
|
130
|
+
* one alone. They stay one log by moving as one pair:
|
|
131
|
+
*
|
|
132
|
+
* - one tick signs both, with the same `upto`, `at` and `floor`;
|
|
133
|
+
* - the signer remembers both in one record, before the database has either;
|
|
134
|
+
* - one statement writes both;
|
|
135
|
+
* - opening, each tick and witnesses check both, as one value.
|
|
136
|
+
*
|
|
137
|
+
* So no state anywhere holds one head without the other, and a fork of either
|
|
138
|
+
* tree is a fork of the pair.
|
|
139
|
+
*/
|
|
140
|
+
export declare const TREES: readonly ["changes", "uses"];
|
|
141
|
+
export type TreeName = (typeof TREES)[number];
|
|
142
|
+
export type Pair = {
|
|
143
|
+
upto: bigint;
|
|
144
|
+
at: number;
|
|
145
|
+
floor: number;
|
|
146
|
+
prev: number;
|
|
147
|
+
changes: Checkpoint;
|
|
148
|
+
uses: Checkpoint;
|
|
149
|
+
};
|
|
150
|
+
/** The pair as it is stored, remembered and published: each tree's signed note. */
|
|
151
|
+
export type PairNotes = {
|
|
152
|
+
changes: string;
|
|
153
|
+
uses: string;
|
|
154
|
+
};
|
|
155
|
+
export type PairSigners = Record<TreeName, NoteSigner>;
|
|
156
|
+
export type PairVerifiers = Record<TreeName, NoteVerifier>;
|
|
157
|
+
/** A tree's origin: the log's own, then the tree's name. */
|
|
158
|
+
export declare const treeOrigin: (origin: string, tree: TreeName) => string;
|
|
159
|
+
/** The two trees' keys, derived from one 32-byte signing seed, each under its own origin. */
|
|
160
|
+
export declare function pairSigners(origin: string, seed: Uint8Array): Promise<PairSigners>;
|
|
161
|
+
export declare function pairVerifiers(keys: Record<TreeName, string>): Promise<PairVerifiers>;
|
|
162
|
+
export type Heads = Record<TreeName, {
|
|
163
|
+
size: number;
|
|
164
|
+
root: Hash;
|
|
165
|
+
}>;
|
|
166
|
+
/**
|
|
167
|
+
* One tick's signatures: both heads, at one `upto`, `at`, `floor` (the floor of `at` its barrier set; 0 at genesis) and
|
|
168
|
+
* `prev` (the floor of the pair signed before it; 0 at genesis).
|
|
169
|
+
*/
|
|
170
|
+
export declare function signPair(signers: PairSigners, upto: bigint, at: number, heads: Heads, floor?: number, prev?: number): Promise<{
|
|
171
|
+
pair: Pair;
|
|
172
|
+
notes: PairNotes;
|
|
173
|
+
}>;
|
|
174
|
+
/** The pair two notes make, if each is signed by its tree's key and both name the same `upto`, `at`, `floor` and `prev`; else null. */
|
|
175
|
+
export declare function openPair(notes: PairNotes, verifiers: PairVerifiers): Promise<Pair | null>;
|
|
176
|
+
/** Whether two pairs are the same heads: same place, same sizes and roots in both trees. Not `at`: callers that need one signing compare it too. */
|
|
177
|
+
export declare const samePair: (a: Pair, b: Pair) => boolean;
|
|
178
|
+
/** The one record the signer remembers, holding both notes. */
|
|
179
|
+
export declare function encodePair(notes: PairNotes): string;
|
|
180
|
+
export declare function decodePair(record: string): PairNotes | null;
|
|
181
|
+
//#endregion
|
|
182
|
+
//#region src/audit/leaf.d.ts
|
|
183
|
+
/**
|
|
184
|
+
* A leaf is a whole entry: its tree, its number, then every column of its row
|
|
185
|
+
* in the table's order, its MAC included. The number is sealed with the
|
|
186
|
+
* entry, so a sealed entry cannot be renumbered, and the tree is too, so an
|
|
187
|
+
* entry moved from one tree to the other is no longer its leaf. Anyone who
|
|
188
|
+
* holds the public keys can check rows against the trees; the MAC key matters
|
|
189
|
+
* only until an entry is sealed.
|
|
190
|
+
*
|
|
191
|
+
* "coffre.audit.leaf.v1" 0x0a tree 0x0a number(8 bytes, big-endian) count(4)
|
|
192
|
+
* then per column: tag(1) length(4) bytes
|
|
193
|
+
* tag 0 null (length 0), 1 bytes, 2 text (UTF-8), 3 integer (decimal text)
|
|
194
|
+
*
|
|
195
|
+
* Every column is tagged and length-prefixed, so the encoding is injective:
|
|
196
|
+
* no two rows share their bytes, whatever their values. A change to it is a
|
|
197
|
+
* new format, never an edit of this one (test/vectors/audit-tree.json pins it).
|
|
198
|
+
*/
|
|
199
|
+
export declare const LEAF_FORMAT = "coffre.audit.leaf.v1";
|
|
200
|
+
export type LeafValue = Uint8Array | string | bigint | number | null;
|
|
201
|
+
export declare function leafData(tree: TreeName, number: bigint, columns: readonly LeafValue[]): Buffer;
|
|
202
|
+
/**
|
|
203
|
+
* What an entry's MAC covers: its tree and every column but its number,
|
|
204
|
+
* which the database takes, and the MAC itself, the same tagged encoding as
|
|
205
|
+
* a leaf's. The tree is in it (Seal.tla's KindInMac): a change moved into
|
|
206
|
+
* the uses table before its tick would otherwise be sealed into the uses
|
|
207
|
+
* tree, and pruned with the uses.
|
|
208
|
+
*
|
|
209
|
+
* "coffre.log.mac.v1" 0x0a tree 0x0a column count(4), then the columns as a leaf's
|
|
210
|
+
*/
|
|
211
|
+
export declare const MAC_FORMAT = "coffre.log.mac.v1";
|
|
212
|
+
export declare function macData(tree: TreeName, columns: readonly LeafValue[]): Buffer;
|
|
213
|
+
/** The leaf hash of an entry. */
|
|
214
|
+
export declare const entryLeaf: (tree: TreeName, number: bigint, columns: readonly LeafValue[]) => Hash;
|
|
215
|
+
//#endregion
|
|
216
|
+
//#region src/audit/tiles.d.ts
|
|
217
|
+
/**
|
|
218
|
+
* The tree's storage: tiles, as Go's sumdb and C2SP tlog-tiles lay them out,
|
|
219
|
+
* of height 8. The tile at (level t, index i) holds up to 256 hashes: the
|
|
220
|
+
* nodes at tree level 8t numbered i·256 onwards, concatenated. A level-0 tile
|
|
221
|
+
* holds leaf hashes; a level-1 tile, the roots of 256-leaf subtrees; and so
|
|
222
|
+
* on. Any perfect subtree's hash is in one tile or is at most 128 hashes away
|
|
223
|
+
* from one, so a proof reads one tile per 8 levels: 4 tiles at 2^32 leaves.
|
|
224
|
+
*
|
|
225
|
+
* A tile's hashes never change once written, only grow (the partial tile at
|
|
226
|
+
* the tree's right edge), so a tile is read for any older tree size by taking
|
|
227
|
+
* its prefix.
|
|
228
|
+
*/
|
|
229
|
+
export declare const HEIGHT = 8;
|
|
230
|
+
export declare const WIDTH = 256;
|
|
231
|
+
export type TileKey = {
|
|
232
|
+
level: number;
|
|
233
|
+
index: number;
|
|
234
|
+
};
|
|
235
|
+
export type Tile = TileKey & {
|
|
236
|
+
hashes: Buffer;
|
|
237
|
+
};
|
|
238
|
+
export declare const tileKey: (level: number, index: number) => string;
|
|
239
|
+
/** Which tile, and where in it, holds what node (level, index) is computed from. */
|
|
240
|
+
export declare function tileOf(level: number, index: number): {
|
|
241
|
+
tile: TileKey;
|
|
242
|
+
offset: number;
|
|
243
|
+
count: number;
|
|
244
|
+
};
|
|
245
|
+
/**
|
|
246
|
+
* The leaves a tile's hashes stand for: [first, end). Tiles are partitioned by
|
|
247
|
+
* it (a level-0 tile by the 256 leaves it holds), so retention drops whole
|
|
248
|
+
* ranges of them instead of deleting rows.
|
|
249
|
+
*/
|
|
250
|
+
export declare function tileLeaves(t: TileKey): {
|
|
251
|
+
first: number;
|
|
252
|
+
end: number;
|
|
253
|
+
};
|
|
254
|
+
/**
|
|
255
|
+
* Whether a tile is still read once retention has cut the tree below leaf
|
|
256
|
+
* `cut`: proofs of leaves at or above the cut, and consistency proofs from
|
|
257
|
+
* sizes at or above it, read only tiles that reach past it, which at each
|
|
258
|
+
* level is the tile holding the cut and those after it. Every tile wholly
|
|
259
|
+
* below the cut can go, at every level: about one tile per level stays
|
|
260
|
+
* where a day of tiles would.
|
|
261
|
+
*/
|
|
262
|
+
export declare const keptAbove: (t: TileKey, cut: number) => boolean;
|
|
263
|
+
/** A `Nodes` over a set of tiles, keyed by `tileKey`: each node from the hashes of its tile. */
|
|
264
|
+
export declare function nodesFrom(tiles: ReadonlyMap<string, Buffer>): Nodes;
|
|
265
|
+
/** The tiles a computation over `Nodes` reads: run it once against a recorder, then fetch them all in one query. */
|
|
266
|
+
export declare function tilesFor(compute: (nodes: Nodes) => unknown): TileKey[];
|
|
267
|
+
export declare function tileMap(tiles: readonly Tile[]): Map<string, Buffer>;
|
|
268
|
+
/** The tiles at the right edge of a tree of `size` leaves, one per level, with their widths: all the state appending needs. */
|
|
269
|
+
export declare function edgeOf(size: number): (TileKey & {
|
|
270
|
+
width: number;
|
|
271
|
+
})[];
|
|
272
|
+
/**
|
|
273
|
+
* The tree's growing edge, in memory: the partial tile at each level.
|
|
274
|
+
* Appending leaves fills level 0; each tile that fills up pushes its root into
|
|
275
|
+
* the level above. What changed comes back as tiles to write: every tile
|
|
276
|
+
* filled, and every partial edge tile that grew.
|
|
277
|
+
*/
|
|
278
|
+
export declare class Edge {
|
|
279
|
+
size: number;
|
|
280
|
+
private tiles;
|
|
281
|
+
private constructor();
|
|
282
|
+
static empty(): Edge;
|
|
283
|
+
/** From the stored edge tiles of a tree of `size` leaves (`edgeOf(size)`), each cut to its width. */
|
|
284
|
+
static load(size: number, stored: ReadonlyMap<string, Buffer>): Edge;
|
|
285
|
+
/** A copy to append to, so a failed write leaves this edge at the head it was. */
|
|
286
|
+
clone(): Edge;
|
|
287
|
+
append(leaves: readonly Hash[]): Tile[];
|
|
288
|
+
/** The tree head now. */
|
|
289
|
+
root(): Hash;
|
|
290
|
+
/**
|
|
291
|
+
* The tile at the right edge of each level, as it stands. With the tiles an append filled, they hold every node a
|
|
292
|
+
* proof of a leaf that append added reads: the tile of the leaf's ancestor at each level is one of them, and so is
|
|
293
|
+
* every tile to its right.
|
|
294
|
+
*/
|
|
295
|
+
edgeTiles(): Tile[];
|
|
296
|
+
}
|
|
297
|
+
/** Go's tile path, `tile/8/<L>/<N>[.p/<W>]`, N in groups of three digits (x001/x234/067). */
|
|
298
|
+
export declare function tilePath(t: TileKey, width: number): string;
|
|
299
|
+
export declare function parseTilePath(path: string): (TileKey & {
|
|
300
|
+
width: number;
|
|
301
|
+
}) | null;
|
|
302
|
+
//#endregion
|
|
303
|
+
//#region src/audit/verify.d.ts
|
|
304
|
+
/**
|
|
305
|
+
* The two trees, verified from what the database holds and the pairs held
|
|
306
|
+
* outside it (the signer's, a witness's, an archive's). It walks the entries
|
|
307
|
+
* in number order from a start it trusts, never one the database picks: the
|
|
308
|
+
* genesis pair, or a pair the caller verified before (`from`). On the way it
|
|
309
|
+
* rebuilds both trees and requires every stored pair and every pair held
|
|
310
|
+
* outside, both heads each: so every sealed entry is there, unchanged, at its
|
|
311
|
+
* place and in its tree, nothing was added, and the database shows the one
|
|
312
|
+
* history the outside pairs saw. A database that ends before an outside pair
|
|
313
|
+
* lost entries or checkpoints.
|
|
314
|
+
*
|
|
315
|
+
* It needs the trees' public keys alone. What an entry's columns mean (its
|
|
316
|
+
* MAC, its request ID) is the caller's to check, through `check`, which sees
|
|
317
|
+
* every entry walked, in number order. The cost is the entries since the
|
|
318
|
+
* start: a caller that keeps the `head` it verified walks only what came
|
|
319
|
+
* after (R25).
|
|
320
|
+
*
|
|
321
|
+
* Retention (plan PR 7, formal/Seal.tla) drops days of uses, and the uses
|
|
322
|
+
* tree's tiles, below a cut that a retention change names; changes are kept
|
|
323
|
+
* for good. With `cut`, which says whether a change is one and its cut, the
|
|
324
|
+
* walk takes the newest retention change (the reader's `retention`), requires
|
|
325
|
+
* it sealed in the changes tree, never merely held (CutSealed), and walks the
|
|
326
|
+
* changes tree from the start but the uses tree from that cut: from the cut's
|
|
327
|
+
* uses head, which the kept tiles at its edge must give, through the
|
|
328
|
+
* checkpoint at the cut, which must hold that head. A use at or below the cut
|
|
329
|
+
* is not walked: a straggler (one of the next day's, numbered below it) can go
|
|
330
|
+
* unseen until its own day does.
|
|
331
|
+
*/
|
|
332
|
+
export type LogEntry = {
|
|
333
|
+
tree: TreeName;
|
|
334
|
+
number: bigint;
|
|
335
|
+
at: number;
|
|
336
|
+
columns: readonly LeafValue[];
|
|
337
|
+
};
|
|
338
|
+
/** A checkpoint row: one pair's two notes, at the `upto` the row says. */
|
|
339
|
+
export type StoredPair = {
|
|
340
|
+
upto: bigint;
|
|
341
|
+
notes: PairNotes;
|
|
342
|
+
};
|
|
343
|
+
export type LogReader = {
|
|
344
|
+
/** The rows above `after`, by `upto`, at most `limit`. */
|
|
345
|
+
pairs(after: bigint, limit: number): Promise<StoredPair[]>;
|
|
346
|
+
/** The row at exactly `upto`, if any. */
|
|
347
|
+
pair(upto: bigint): Promise<StoredPair | null>;
|
|
348
|
+
/**
|
|
349
|
+
* The entries numbered in (after, upto], by number, both trees. Uses are
|
|
350
|
+
* read from `floor`, the floor of `at` signed in the pair at `after`, when
|
|
351
|
+
* the caller gives it: a reader that takes it from its rows lets a writer
|
|
352
|
+
* hide what lies above (FloorChecked). With `limit`, the first that many.
|
|
353
|
+
*/
|
|
354
|
+
entries(after: bigint, upto: bigint, options?: {
|
|
355
|
+
floor?: number;
|
|
356
|
+
limit?: number;
|
|
357
|
+
}): Promise<LogEntry[]>;
|
|
358
|
+
tiles(tree: TreeName, keys: readonly TileKey[]): Promise<Tile[]>;
|
|
359
|
+
/** The newest retention change, if any, and its leaf index in the changes tree (plan PR 7). */
|
|
360
|
+
retention?(): Promise<{
|
|
361
|
+
entry: LogEntry;
|
|
362
|
+
index: number;
|
|
363
|
+
} | null>;
|
|
364
|
+
};
|
|
365
|
+
/** Where retention cut the uses tree: the pair at `upto`, signed at `at`, whose uses head every later one extends. */
|
|
366
|
+
export type Cut = {
|
|
367
|
+
upto: bigint;
|
|
368
|
+
at: number;
|
|
369
|
+
uses: {
|
|
370
|
+
size: number;
|
|
371
|
+
root: Hash;
|
|
372
|
+
};
|
|
373
|
+
};
|
|
374
|
+
export type Verdict = {
|
|
375
|
+
ok: boolean;
|
|
376
|
+
problems: string[];
|
|
377
|
+
/** Rows walked, entries sealed under them, entries above the newest. */
|
|
378
|
+
checkpoints: number;
|
|
379
|
+
sealed: number;
|
|
380
|
+
unsealed: number;
|
|
381
|
+
/** The newest pair walked, when the walk found nothing wrong: the `from` of the next one. */
|
|
382
|
+
head: PairNotes | null;
|
|
383
|
+
/** `head` opened, as the walk opened it: its place and time without its signatures checked again. */
|
|
384
|
+
headPair: Pair | null;
|
|
385
|
+
/**
|
|
386
|
+
* Whether the database ends before a pair held outside: deleted entries or
|
|
387
|
+
* checkpoints, or the signer's own write a moment away (it remembers a pair
|
|
388
|
+
* before the database holds it), which a caller may tell apart by asking
|
|
389
|
+
* again a tick later.
|
|
390
|
+
*/
|
|
391
|
+
behind: boolean;
|
|
392
|
+
/**
|
|
393
|
+
* Whether more than `above` entries lie above the newest pair: the walk
|
|
394
|
+
* checked that many and stopped short of the head, which is no problem
|
|
395
|
+
* of the log (a checkpointer behind), and no verdict on the rest either.
|
|
396
|
+
*/
|
|
397
|
+
capped: boolean;
|
|
398
|
+
};
|
|
399
|
+
type Options = {
|
|
400
|
+
verifiers: PairVerifiers;
|
|
401
|
+
from?: PairNotes;
|
|
402
|
+
/**
|
|
403
|
+
* The database's newest row, as the caller read it in the walk's own
|
|
404
|
+
* snapshot, to start from instead of `from`: its row is not read again,
|
|
405
|
+
* nor the rows above it, which there are none of (PR 8 review r3).
|
|
406
|
+
*/
|
|
407
|
+
newest?: StoredPair;
|
|
408
|
+
anchors?: readonly PairNotes[];
|
|
409
|
+
check?: (entry: LogEntry) => string | null;
|
|
410
|
+
/** Whether a change is a retention change, and the cut it names; null for any other entry. */
|
|
411
|
+
cut?: (entry: LogEntry) => Cut | null;
|
|
412
|
+
/**
|
|
413
|
+
* The most entries above the newest pair a walk checks, for a caller bound
|
|
414
|
+
* in time: past it, `capped`, and the rest unread. A checkpointer stalled,
|
|
415
|
+
* or a writer's planted rows, grow what lies there without bound.
|
|
416
|
+
*/
|
|
417
|
+
above?: number;
|
|
418
|
+
};
|
|
419
|
+
export declare function verifyLog(reader: LogReader, opts: Options): Promise<Verdict>;
|
|
420
|
+
/** Both trees' edges at a pair, from their tiles; throws unless each gives its signed head. */
|
|
421
|
+
export declare function loadEdges(reader: Pick<LogReader, 'tiles'>, pair: Pair): Promise<Record<TreeName, Edge>>;
|
|
422
|
+
/** A consistency proof between two sizes of one tree, from its tiles. */
|
|
423
|
+
export declare function proveConsistency(reader: Pick<LogReader, 'tiles'>, tree: TreeName, from: number, to: number): Promise<Hash[]>;
|
|
424
|
+
//#endregion
|
|
425
|
+
//#region src/audit/witness.d.ts
|
|
426
|
+
/**
|
|
427
|
+
* A witness of the pair, as transparency-dev's and Sigsum's witnesses work on
|
|
428
|
+
* one log: it holds the newest pair it has seen, and cosigns a new one only if
|
|
429
|
+
* both trees prove they extend what it holds. So the log cannot show two
|
|
430
|
+
* parties two histories (a split view) and get both witnessed, in either tree.
|
|
431
|
+
* The witness's Durable Object runs this, and so do the tests.
|
|
432
|
+
*
|
|
433
|
+
* It takes both notes in one request and answers for both: a pair whose
|
|
434
|
+
* changes head extends the one held while its uses head forks is refused
|
|
435
|
+
* whole. (A standard C2SP witness takes one origin; given each tree's note,
|
|
436
|
+
* it checks that tree alone, which is all it needs to.)
|
|
437
|
+
*/
|
|
438
|
+
export type WitnessState = {
|
|
439
|
+
pair: Pair;
|
|
440
|
+
notes: PairNotes;
|
|
441
|
+
} | null;
|
|
442
|
+
/** `cosigned`: the pair as the witness cosigned it; none from an archive, which stores what it is sent and checks nothing. */
|
|
443
|
+
export type WitnessAnswer = {
|
|
444
|
+
ok: true;
|
|
445
|
+
cosigned?: PairNotes;
|
|
446
|
+
} | {
|
|
447
|
+
ok: false;
|
|
448
|
+
reason: string;
|
|
449
|
+
};
|
|
450
|
+
/** Consistency proofs from the sizes the witness holds to the new pair's, one per tree. */
|
|
451
|
+
export type PairProofs = Record<TreeName, readonly Hash[]>;
|
|
452
|
+
export declare function witnessPair(state: WitnessState, notes: PairNotes, proofs: PairProofs, log: PairVerifiers, self: NoteSigner): Promise<{
|
|
453
|
+
state: WitnessState;
|
|
454
|
+
answer: WitnessAnswer;
|
|
455
|
+
}>;
|
|
456
|
+
//#endregion
|