@intellectual-frontiers/grc 0.0.0-stage → 0.1.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.
@@ -0,0 +1,551 @@
1
+ // Spec: 0001-grc FR-006
2
+ /**
3
+ * Evidence: JSON's canonical form and the digest it gives, a hash-chained ledger, a manifest of files and a deterministic bundle (commons
4
+ * 0001-grc FR-006 to FR-009). The kernel holds no key: a manifest's signature is made and checked by functions the caller gives.
5
+ *
6
+ * - `canonicalize` writes RFC 8785's JSON Canonicalization Scheme: object members sorted by the UTF-16 code units of their names, numbers
7
+ * as ECMAScript writes them, strings with JSON's minimal escapes, no white space; `evidenceDigest` is the SHA-256 of its UTF-8 (FR-006).
8
+ * - A ledger is append-only and hash-chained: entry `seq` (from 1) holds the digest of the entry before (64 zeros for the first), its time,
9
+ * kind, subject and evidence digest, and its own `digest`, the SHA-256 of the canonical form of the rest. It is written as JSON lines,
10
+ * and `verifyLedger` names the first entry that was changed, removed, inserted or reordered (FR-007). Removing the last entries leaves a
11
+ * valid chain, so a signature covers a head (`LedgerHead`) that `verifyLedger` is then given.
12
+ * - A manifest lists files by path, size and SHA-256 in the byte order of their paths; `verifyManifest` names each file missing, extra or
13
+ * different, and `verifyManifestSignature` checks its bytes with a `VerifySignature` the caller gives (FR-008).
14
+ * - A bundle is a gzip of a ustar archive whose first entry is the manifest (then its signature, if any), the same bytes every time for the
15
+ * same files; `readBundle` gives the files back only where the manifest (and the signature, if a verifier is given) holds (FR-009).
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { canonicalize, evidenceDigest } from "./evidence.ts";
20
+ * canonicalize({ b: 1, a: 2.0 }); // { kind: "ok", value: '{"a":2,"b":1}' }
21
+ * await evidenceDigest({ a: 2, b: 1 }); // the same digest as for { b: 1, a: 2.0 }
22
+ * ```
23
+ *
24
+ * @module
25
+ */
26
+ import {
27
+ absurd,
28
+ type Decoder,
29
+ type DecodeError,
30
+ array,
31
+ formatDecodeError,
32
+ integer,
33
+ object,
34
+ refine,
35
+ string,
36
+ err,
37
+ ok,
38
+ type Result,
39
+ } from "@intellectual-frontiers/core";
40
+ import {
41
+ type ArchiveError,
42
+ type Files,
43
+ concat,
44
+ filesOf,
45
+ gunzip,
46
+ gzip,
47
+ isSafePath,
48
+ sortedPaths,
49
+ tar,
50
+ tarHeader,
51
+ untar,
52
+ } from "@intellectual-frontiers/formats/archive";
53
+ import { type Instant, type SubjectRef, instantDecoder } from "./grc.ts";
54
+ import { type Sha256, sha256, sha256Of } from "@intellectual-frontiers/crypto/sha256";
55
+
56
+ // ---------------------------------------------------------------------------------------------------------------------------- JCS (FR-006)
57
+
58
+ /** Why a value has no canonical JSON form: where it is (`$.a[2]`) and what it is. */
59
+ export type CanonicalError = { readonly kind: "canonical"; readonly path: string; readonly reason: string };
60
+
61
+ function memberPath(path: string, key: string): string {
62
+ return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
63
+ }
64
+
65
+ function isPlainObject(v: object): boolean {
66
+ const proto: unknown = Object.getPrototypeOf(v);
67
+ return proto === Object.prototype || proto === null;
68
+ }
69
+
70
+ function canonicalText(value: unknown, path: string, parents: Set<object>, out: string[]): CanonicalError | undefined {
71
+ const fail = (reason: string): CanonicalError => ({ kind: "canonical", path, reason });
72
+ if (value === null) out.push("null");
73
+ else if (typeof value === "boolean") out.push(value ? "true" : "false");
74
+ else if (typeof value === "number") {
75
+ if (!Number.isFinite(value)) return fail(`${String(value)} is not a JSON number`);
76
+ out.push(JSON.stringify(value));
77
+ } else if (typeof value === "string") {
78
+ if (!value.isWellFormed()) return fail("the string holds a lone surrogate");
79
+ out.push(JSON.stringify(value));
80
+ } else if (typeof value === "object") {
81
+ if (parents.has(value)) return fail("the value refers to itself");
82
+ parents.add(value);
83
+ if (Array.isArray(value)) {
84
+ out.push("[");
85
+ for (let i = 0; i < value.length; i++) {
86
+ if (i > 0) out.push(",");
87
+ const item: unknown = value[i];
88
+ if (item === undefined) return { kind: "canonical", path: `${path}[${i}]`, reason: "an array holds nothing here" };
89
+ const e = canonicalText(item, `${path}[${i}]`, parents, out);
90
+ if (e !== undefined) return e;
91
+ }
92
+ out.push("]");
93
+ } else {
94
+ if (!isPlainObject(value)) return fail("only plain objects are JSON objects");
95
+ const keys = Object.keys(value).sort();
96
+ out.push("{");
97
+ let first = true;
98
+ for (const key of keys) {
99
+ const member: unknown = Reflect.get(value, key);
100
+ if (member === undefined) continue;
101
+ if (!key.isWellFormed()) return fail(`the member name ${JSON.stringify(key)} holds a lone surrogate`);
102
+ out.push(first ? "" : ",", JSON.stringify(key), ":");
103
+ first = false;
104
+ const e = canonicalText(member, memberPath(path, key), parents, out);
105
+ if (e !== undefined) return e;
106
+ }
107
+ out.push("}");
108
+ }
109
+ parents.delete(value);
110
+ } else return fail(`a ${typeof value} is not JSON`);
111
+ return undefined;
112
+ }
113
+
114
+ /**
115
+ * A value's canonical JSON text (RFC 8785): plain objects, arrays, strings, finite numbers, booleans and `null`. An object member whose
116
+ * value is `undefined` is left out, as `JSON.stringify` leaves it; anything else that is not JSON (a non-finite number, a lone surrogate,
117
+ * a `Date`, a class instance, a cycle, a hole) is an error naming where it is.
118
+ */
119
+ export function canonicalize(value: unknown): Result<string, CanonicalError> {
120
+ const out: string[] = [];
121
+ const e = canonicalText(value, "$", new Set(), out);
122
+ return e === undefined ? ok(out.join("")) : err(e);
123
+ }
124
+
125
+ /** A value's canonical JSON as UTF-8 bytes. */
126
+ export function canonicalBytes(value: unknown): Result<Uint8Array, CanonicalError> {
127
+ const r = canonicalize(value);
128
+ return r.kind === "ok" ? ok(new TextEncoder().encode(r.value)) : r;
129
+ }
130
+
131
+ /** The address of a piece of evidence: the SHA-256 of its canonical JSON, the same on every runtime. */
132
+ export async function evidenceDigest(value: unknown): Promise<Result<Sha256, CanonicalError>> {
133
+ const r = canonicalize(value);
134
+ return r.kind === "ok" ? ok(await sha256(r.value)) : r;
135
+ }
136
+
137
+ // ---------------------------------------------------------------------------------------------------------------------------- ledger (FR-007)
138
+
139
+ /** The digest the first entry of a ledger names as the one before it: 64 zeros. */
140
+ export const GENESIS: Sha256 = "0".repeat(64) as Sha256; // 64 hexadecimal digits by construction
141
+
142
+ /** What is appended to a ledger: when, what kind of record (`observation`, `assessment`), about what, and the digest of the evidence. */
143
+ export type LedgerRecord = { readonly at: Instant; readonly kind: string; readonly subject: SubjectRef; readonly evidence: Sha256 };
144
+
145
+ /** One entry of a ledger: a record with its place, the digest of the entry before it and its own digest. */
146
+ export type LedgerEntry = LedgerRecord & { readonly seq: number; readonly prev: Sha256; readonly digest: Sha256 };
147
+
148
+ /** The last entry a ledger is known to have reached (what a signature covers): `{ seq: 0, digest: GENESIS }` for an empty one. */
149
+ export type LedgerHead = { readonly seq: number; readonly digest: Sha256 };
150
+
151
+ /** The digest an entry must carry: the SHA-256 of the canonical JSON of every field but `digest`. */
152
+ export async function entryDigest(e: Omit<LedgerEntry, "digest">): Promise<Result<Sha256, CanonicalError>> {
153
+ return evidenceDigest({
154
+ seq: e.seq,
155
+ prev: e.prev,
156
+ at: e.at,
157
+ kind: e.kind,
158
+ subject: { kind: e.subject.kind, id: e.subject.id },
159
+ evidence: e.evidence,
160
+ });
161
+ }
162
+
163
+ /** The head of a ledger: its last entry's place and digest. */
164
+ export function ledgerHead(entries: readonly LedgerEntry[]): LedgerHead {
165
+ const last = entries.at(-1);
166
+ return last === undefined ? { seq: 0, digest: GENESIS } : { seq: last.seq, digest: last.digest };
167
+ }
168
+
169
+ /** The ledger with one record appended; an error where the record has no canonical form (a lone surrogate in its kind or subject). */
170
+ export async function appendEntry(
171
+ entries: readonly LedgerEntry[],
172
+ record: LedgerRecord,
173
+ ): Promise<Result<readonly LedgerEntry[], CanonicalError>> {
174
+ const head = ledgerHead(entries);
175
+ const body = {
176
+ seq: head.seq + 1,
177
+ prev: head.digest,
178
+ at: record.at,
179
+ kind: record.kind,
180
+ subject: record.subject,
181
+ evidence: record.evidence,
182
+ };
183
+ const d = await entryDigest(body);
184
+ return d.kind === "ok" ? ok([...entries, { ...body, digest: d.value }]) : d;
185
+ }
186
+
187
+ /** A ledger as JSON lines: each entry's canonical JSON and a line feed. */
188
+ export function ledgerLines(entries: readonly LedgerEntry[]): string {
189
+ return entries
190
+ .map((e) => {
191
+ const r = canonicalize(e);
192
+ return `${r.kind === "ok" ? r.value : JSON.stringify(e)}\n`;
193
+ })
194
+ .join("");
195
+ }
196
+
197
+ const sha256Decoder: Decoder<Sha256> = (input, path = "$") => {
198
+ const s = typeof input === "string" && /^[0-9a-f]{64}$/.test(input) ? sha256Of(input) : undefined;
199
+ return s === undefined
200
+ ? err({ kind: "decode", path, expected: "a SHA-256 (64 lower-case hexadecimal digits)", found: typeof input })
201
+ : ok(s);
202
+ };
203
+
204
+ /** A ledger entry as its JSON holds it. */
205
+ export const ledgerEntryDecoder: Decoder<LedgerEntry> = object({
206
+ seq: refine(integer, "positive", (n) => n >= 1),
207
+ prev: sha256Decoder,
208
+ at: instantDecoder,
209
+ kind: string,
210
+ subject: object({ kind: string, id: string }),
211
+ evidence: sha256Decoder,
212
+ digest: sha256Decoder,
213
+ });
214
+
215
+ /** Why the text of a ledger could not be read: the line (from 1) and what is wrong there. */
216
+ export type LedgerParseError = { readonly kind: "ledger-line"; readonly line: number; readonly error: DecodeError };
217
+
218
+ /** A ledger parse error as one sentence. */
219
+ export function formatLedgerParseError(e: LedgerParseError): string {
220
+ return `line ${e.line}: ${formatDecodeError(e.error)}`;
221
+ }
222
+
223
+ /** A ledger from its JSON lines (blank lines skipped), each decoded; the chain is checked by `verifyLedger`. */
224
+ export function parseLedger(text: string): Result<readonly LedgerEntry[], LedgerParseError> {
225
+ const entries: LedgerEntry[] = [];
226
+ const lines = text.split("\n");
227
+ for (const [i, raw] of lines.entries()) {
228
+ const line = raw.replace(/\r$/, "");
229
+ if (line.trim() === "") continue;
230
+ let value: unknown;
231
+ try {
232
+ value = JSON.parse(line);
233
+ } catch (e) {
234
+ return err({
235
+ kind: "ledger-line",
236
+ line: i + 1,
237
+ error: { kind: "decode", path: "$", expected: "JSON", found: e instanceof Error ? e.message : String(e) },
238
+ });
239
+ }
240
+ const r = ledgerEntryDecoder(value);
241
+ if (r.kind === "err") return err({ kind: "ledger-line", line: i + 1, error: r.error });
242
+ entries.push(r.value);
243
+ }
244
+ return ok(entries);
245
+ }
246
+
247
+ /** The kind of tampering a broken ledger shows. */
248
+ export type Tampering = "changed" | "removed" | "inserted" | "reordered";
249
+
250
+ /** Where a ledger breaks: the place (from 1) of the first entry that was changed, removed, inserted or reordered, and why that is said. */
251
+ export type LedgerBreak = { readonly kind: Tampering; readonly seq: number; readonly reason: string };
252
+
253
+ /** A ledger break as one sentence. */
254
+ export function formatLedgerBreak(b: LedgerBreak): string {
255
+ return `entry ${b.seq} was ${b.kind}: ${b.reason}`;
256
+ }
257
+
258
+ /**
259
+ * The ledger's head where every entry's digest is the digest of its content, its `seq` its place and its `prev` the digest of the entry
260
+ * before it (and, where a `head` is given, the ledger reaches it with that digest); else the first break. Entry N edited in place is
261
+ * `changed` at N (edited and re-hashed, it is found at N + 1's link and still named N); entry N gone is `removed` at N; a forged entry
262
+ * slipped in at N is `inserted` at N; two entries swapped are `reordered` at the first of them.
263
+ */
264
+ export async function verifyLedger(entries: readonly LedgerEntry[], head?: LedgerHead): Promise<Result<LedgerHead, LedgerBreak>> {
265
+ const brk = (kind: Tampering, seq: number, reason: string): Result<never, LedgerBreak> => err({ kind, seq, reason });
266
+ for (const [i, e] of entries.entries()) {
267
+ const place = i + 1;
268
+ const d = await entryDigest(e);
269
+ if (d.kind === "err" || d.value !== e.digest) return brk("changed", place, "its digest is not the SHA-256 of its content");
270
+ if (e.seq > place) {
271
+ return entries.slice(i + 1).some((x) => x.seq === place)
272
+ ? brk("reordered", place, `entry ${e.seq} stands where entry ${place} should`)
273
+ : brk("removed", place, e.seq === place + 1 ? `entry ${place} is missing` : `entries ${place} to ${e.seq - 1} are missing`);
274
+ }
275
+ if (e.seq < place) {
276
+ const beforePrevious = i >= 2 ? entries[i - 2]?.digest : GENESIS;
277
+ return e.prev === beforePrevious
278
+ ? brk("inserted", Math.max(place - 1, 1), `it is not in the chain: entry ${place} links past it`)
279
+ : brk("inserted", place, `it repeats the place ${e.seq}`);
280
+ }
281
+ const previous = i === 0 ? GENESIS : (entries[i - 1]?.digest ?? GENESIS);
282
+ if (e.prev !== previous)
283
+ return i === 0
284
+ ? brk("changed", 1, "it does not begin the chain")
285
+ : brk("changed", place - 1, `entry ${place} names another digest for it`);
286
+ }
287
+ if (head !== undefined) {
288
+ if (entries.length < head.seq) return brk("removed", entries.length + 1, `the ledger ends before its head, entry ${head.seq}`);
289
+ const at = head.seq === 0 ? GENESIS : entries[head.seq - 1]?.digest;
290
+ if (at !== head.digest) return brk("changed", Math.max(head.seq, 1), "its digest is not the head's");
291
+ }
292
+ return ok(ledgerHead(entries));
293
+ }
294
+
295
+ // ---------------------------------------------------------------------------------------------------------------------------- manifest (FR-008)
296
+
297
+ /** One file of a manifest. */
298
+ export type ManifestEntry = { readonly path: string; readonly size: number; readonly sha256: Sha256 };
299
+
300
+ /** Files by path, size and SHA-256, in the byte order of their UTF-8 paths. */
301
+ export type Manifest = { readonly files: readonly ManifestEntry[] };
302
+
303
+ /** The manifest of some files. */
304
+ export async function manifestOf(files: Files): Promise<Manifest> {
305
+ const out: ManifestEntry[] = [];
306
+ for (const path of sortedPaths(files.keys())) {
307
+ const data = files.get(path) ?? new Uint8Array();
308
+ out.push({ path, size: data.length, sha256: await sha256(data) });
309
+ }
310
+ return { files: out };
311
+ }
312
+
313
+ /** A manifest's bytes: its canonical JSON (RFC 8785) and a line feed. These are the bytes a signature covers. */
314
+ export function manifestBytes(m: Manifest): Uint8Array {
315
+ const r = canonicalize({ files: m.files.map((f) => ({ path: f.path, size: f.size, sha256: f.sha256 })) });
316
+ // A manifest's strings are paths and digests; a path with a lone surrogate is written as UTF-8 would replace it.
317
+ return new TextEncoder().encode(`${r.kind === "ok" ? r.value : JSON.stringify(m)}\n`);
318
+ }
319
+
320
+ /** Why a manifest could not be read. */
321
+ export type ManifestError =
322
+ | { readonly kind: "manifest-decode"; readonly error: DecodeError }
323
+ | { readonly kind: "manifest-order"; readonly path: string }
324
+ | { readonly kind: "manifest-unsafe-path"; readonly path: string };
325
+
326
+ /** A manifest error as one sentence. */
327
+ export function formatManifestError(e: ManifestError): string {
328
+ switch (e.kind) {
329
+ case "manifest-decode":
330
+ return `the manifest does not decode: ${formatDecodeError(e.error)}`;
331
+ case "manifest-order":
332
+ return `the manifest lists ${JSON.stringify(e.path)} out of byte order or twice`;
333
+ case "manifest-unsafe-path":
334
+ return `the manifest lists a path that would leave its folder: ${JSON.stringify(e.path)}`;
335
+ default:
336
+ return absurd(e);
337
+ }
338
+ }
339
+
340
+ const manifestDecoder: Decoder<Manifest> = object({
341
+ files: array(object({ path: string, size: refine(integer, "size", (n) => n >= 0), sha256: sha256Decoder })),
342
+ });
343
+
344
+ /** A manifest from its bytes (or text), each path checked safe and the list checked in strict byte order. */
345
+ export function parseManifest(input: Uint8Array | string): Result<Manifest, ManifestError> {
346
+ const text = typeof input === "string" ? input : new TextDecoder().decode(input);
347
+ let value: unknown;
348
+ try {
349
+ value = JSON.parse(text);
350
+ } catch (e) {
351
+ return err({
352
+ kind: "manifest-decode",
353
+ error: { kind: "decode", path: "$", expected: "JSON", found: e instanceof Error ? e.message : String(e) },
354
+ });
355
+ }
356
+ const r = manifestDecoder(value);
357
+ if (r.kind === "err") return err({ kind: "manifest-decode", error: r.error });
358
+ const paths = r.value.files.map((f) => f.path);
359
+ const sorted = sortedPaths(paths);
360
+ for (const [i, p] of paths.entries()) {
361
+ if (!isSafePath(p)) return err({ kind: "manifest-unsafe-path", path: p });
362
+ if (sorted[i] !== p || (i > 0 && paths[i - 1] === p)) return err({ kind: "manifest-order", path: p });
363
+ }
364
+ return r;
365
+ }
366
+
367
+ /** One way files differ from their manifest. */
368
+ export type ManifestMismatch =
369
+ | { readonly kind: "missing"; readonly path: string }
370
+ | { readonly kind: "extra"; readonly path: string }
371
+ | {
372
+ readonly kind: "different";
373
+ readonly path: string;
374
+ readonly expected: { readonly size: number; readonly sha256: Sha256 };
375
+ readonly actual: { readonly size: number; readonly sha256: Sha256 };
376
+ };
377
+
378
+ /** A mismatch as one sentence. */
379
+ export function formatManifestMismatch(m: ManifestMismatch): string {
380
+ switch (m.kind) {
381
+ case "missing":
382
+ return `${m.path} is in the manifest but not among the files`;
383
+ case "extra":
384
+ return `${m.path} is among the files but not in the manifest`;
385
+ case "different":
386
+ return `${m.path} is not the file the manifest lists (${m.actual.size} bytes, ${m.actual.sha256})`;
387
+ default:
388
+ return absurd(m);
389
+ }
390
+ }
391
+
392
+ /** Whether files are exactly what the manifest lists; else every file missing, extra or different, in the byte order of their paths. */
393
+ export async function verifyManifest(m: Manifest, files: Files): Promise<Result<Manifest, readonly ManifestMismatch[]>> {
394
+ const listed = new Map(m.files.map((f) => [f.path, f]));
395
+ const out: ManifestMismatch[] = [];
396
+ for (const path of sortedPaths(new Set([...listed.keys(), ...files.keys()]))) {
397
+ const want = listed.get(path);
398
+ const data = files.get(path);
399
+ if (want === undefined) out.push({ kind: "extra", path });
400
+ else if (data === undefined) out.push({ kind: "missing", path });
401
+ else {
402
+ const sum = await sha256(data);
403
+ if (sum !== want.sha256 || data.length !== want.size)
404
+ out.push({
405
+ kind: "different",
406
+ path,
407
+ expected: { size: want.size, sha256: want.sha256 },
408
+ actual: { size: data.length, sha256: sum },
409
+ });
410
+ }
411
+ }
412
+ return out.length === 0 ? ok(m) : err(out);
413
+ }
414
+
415
+ /** A check of a signature over a message, with a key the caller holds (an in-toto/DSSE verifier, `ssh-keygen -Y verify`, ...). */
416
+ export type VerifySignature = (message: Uint8Array, signature: Uint8Array) => boolean | Promise<boolean>;
417
+
418
+ /** A signer of a message, with a key the caller holds. */
419
+ export type Sign = (message: Uint8Array) => Uint8Array | Promise<Uint8Array>;
420
+
421
+ /** Why a signed manifest is refused. */
422
+ export type SignatureError = { readonly kind: "unsigned" } | { readonly kind: "bad-signature"; readonly reason: string } | ManifestError;
423
+
424
+ /** The manifest its bytes hold, where the signature over those exact bytes verifies; a verifier that throws is a bad signature. */
425
+ export async function verifyManifestSignature(
426
+ bytes: Uint8Array,
427
+ signature: Uint8Array,
428
+ verify: VerifySignature,
429
+ ): Promise<Result<Manifest, SignatureError>> {
430
+ let good: boolean;
431
+ try {
432
+ good = await verify(bytes, signature);
433
+ } catch (e) {
434
+ return err({ kind: "bad-signature", reason: e instanceof Error ? e.message : String(e) });
435
+ }
436
+ if (!good) return err({ kind: "bad-signature", reason: "the signature does not verify" });
437
+ return parseManifest(bytes);
438
+ }
439
+
440
+ // ---------------------------------------------------------------------------------------------------------------------------- bundle (FR-009)
441
+
442
+ /** The path of a bundle's manifest, its first entry. */
443
+ export const BUNDLE_MANIFEST = "MANIFEST.json";
444
+
445
+ /** The path of a bundle manifest's signature, its second entry where there is one. */
446
+ export const BUNDLE_SIGNATURE = "MANIFEST.json.sig";
447
+
448
+ /** What a bundle read back holds: its manifest, its files (the manifest and signature left out), and whether its signature verified. */
449
+ export type Bundle = {
450
+ readonly manifest: Manifest;
451
+ readonly files: Files;
452
+ readonly signature:
453
+ { readonly kind: "none" } | { readonly kind: "verified" } | { readonly kind: "unverified"; readonly bytes: Uint8Array };
454
+ };
455
+
456
+ /** Why a bundle could not be written or read. */
457
+ export type BundleError =
458
+ | { readonly kind: "archive"; readonly error: ArchiveError }
459
+ | { readonly kind: "reserved-path"; readonly path: string }
460
+ | { readonly kind: "no-manifest" }
461
+ | { readonly kind: "mismatch"; readonly mismatches: readonly ManifestMismatch[] }
462
+ | SignatureError;
463
+
464
+ /** A bundle error as one sentence. */
465
+ export function formatBundleError(e: BundleError): string {
466
+ switch (e.kind) {
467
+ case "archive":
468
+ return `the bundle's archive: ${e.error.kind}`;
469
+ case "reserved-path":
470
+ return `${e.path} is the bundle's own and cannot be one of its files`;
471
+ case "no-manifest":
472
+ return `the bundle does not begin with ${BUNDLE_MANIFEST}`;
473
+ case "mismatch":
474
+ return `the bundle's files are not its manifest's: ${e.mismatches.map(formatManifestMismatch).join("; ")}`;
475
+ case "unsigned":
476
+ return "the bundle has no signature";
477
+ case "bad-signature":
478
+ return `the bundle's signature: ${e.reason}`;
479
+ case "manifest-decode":
480
+ case "manifest-order":
481
+ case "manifest-unsafe-path":
482
+ return formatManifestError(e);
483
+ default:
484
+ return absurd(e);
485
+ }
486
+ }
487
+
488
+ function tarEntry(path: string, data: Uint8Array): Result<Uint8Array, BundleError> {
489
+ const h = tarHeader(path, data.length, false);
490
+ if (h === undefined) return err({ kind: "archive", error: { kind: "too-long", path } });
491
+ return ok(concat([h, data, new Uint8Array((512 - (data.length % 512)) % 512)]));
492
+ }
493
+
494
+ /**
495
+ * A bundle of files: a gzip of a ustar archive whose first entry is the manifest, then its signature where a signer is given, then the
496
+ * files (their folders first) in byte order, every time and date fixed, so the same files (and a deterministic signer) give the same bytes.
497
+ */
498
+ export async function writeBundle(files: Files, options: { readonly sign?: Sign } = {}): Promise<Result<Uint8Array, BundleError>> {
499
+ for (const reserved of [BUNDLE_MANIFEST, BUNDLE_SIGNATURE])
500
+ if (files.has(reserved)) return err({ kind: "reserved-path", path: reserved });
501
+ const manifest = manifestBytes(await manifestOf(files));
502
+ const head = tarEntry(BUNDLE_MANIFEST, manifest);
503
+ if (head.kind === "err") return head;
504
+ const parts = [head.value];
505
+ if (options.sign !== undefined) {
506
+ const sig = tarEntry(BUNDLE_SIGNATURE, await options.sign(manifest));
507
+ if (sig.kind === "err") return sig;
508
+ parts.push(sig.value);
509
+ }
510
+ const rest = tar(files);
511
+ if (rest.kind === "err") return err({ kind: "archive", error: rest.error });
512
+ parts.push(rest.value);
513
+ return ok(gzip(concat(parts)));
514
+ }
515
+
516
+ /**
517
+ * A bundle's files, where its first entry is a manifest the files match exactly (one added, removed or changed is named); with `verify`,
518
+ * also where its signature verifies over the manifest's bytes (a bundle with none is then refused as unsigned).
519
+ */
520
+ export async function readBundle(
521
+ data: Uint8Array,
522
+ options: { readonly verify?: VerifySignature } = {},
523
+ ): Promise<Result<Bundle, BundleError>> {
524
+ const unzipped = await gunzip(data);
525
+ if (unzipped.kind === "err") return err({ kind: "archive", error: unzipped.error });
526
+ const entries = untar(unzipped.value);
527
+ if (entries.kind === "err") return err({ kind: "archive", error: entries.error });
528
+ const first = entries.value[0];
529
+ if (first === undefined || first.kind !== "file" || first.path !== BUNDLE_MANIFEST) return err({ kind: "no-manifest" });
530
+ const all = filesOf(entries.value);
531
+ const signature = all.get(BUNDLE_SIGNATURE);
532
+ let manifest: Result<Manifest, SignatureError>;
533
+ if (options.verify !== undefined) {
534
+ if (signature === undefined) return err({ kind: "unsigned" });
535
+ manifest = await verifyManifestSignature(first.data, signature, options.verify);
536
+ } else manifest = parseManifest(first.data);
537
+ if (manifest.kind === "err") return manifest;
538
+ const files = new Map([...all].filter(([p]) => p !== BUNDLE_MANIFEST && p !== BUNDLE_SIGNATURE));
539
+ const checked = await verifyManifest(manifest.value, files);
540
+ if (checked.kind === "err") return err({ kind: "mismatch", mismatches: checked.error });
541
+ return ok({
542
+ manifest: manifest.value,
543
+ files,
544
+ signature:
545
+ signature === undefined
546
+ ? { kind: "none" }
547
+ : options.verify !== undefined
548
+ ? { kind: "verified" }
549
+ : { kind: "unverified", bytes: signature },
550
+ });
551
+ }