@cloudhal/release-verify 0.0.0-stage → 0.10.0

package/dist/src/tar.js

@@ -0,0 +1,398 @@
+/**
+ * Streams a release tarball (RFC-0046 §7) without holding it whole. It accepts exactly what the
+ * producer (`scripts/release-bundle/tar.ts`) writes and refuses everything else (`tar-format`):
+ *
+ * - gzip with the fixed header (no flags, mtime 0, OS 255), decompressed by `DecompressionStream`;
+ * - ustar headers with a valid checksum, `ustar\0` + `00`, mode 0644, uid/gid 0, no owner names,
+ *   link name or prefix, the release's mtime, and typeflag `0` (or `x` with a single PAX `path`
+ *   record for the entry that follows); links, directories and every other type are refused;
+ * - two or more zero blocks, and nothing but zeros, at the end.
+ */
+import { ReleaseVerifyError, refuse } from "./errors.js";
+import { LIMITS, MAX_TAR_BYTES } from "./limits.js";
+
+                                                                                             
+
+/** The chunks of `source`, whatever its form. */
+export async function* chunksOf(source            )                             {
+  if (source instanceof Uint8Array) {
+    yield source;
+    return;
+  }
+  if (typeof (source                              ).getReader === "function") {
+    const reader = (source                              ).getReader();
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        yield value;
+      }
+    } finally {
+      await reader.cancel().catch(() => {});
+    }
+  }
+  yield* source                             ;
+}
+
+const GZIP_FIXED = [0x1f, 0x8b, 8, 0, 0, 0, 0, 0];
+
+/** Refuses a gzip stream whose first ten bytes are not the fixed header (§7). */
+export function checkGzipHeader(head            )       {
+  if (head.length < 10) refuse("tar-format", "the tarball is not gzip");
+  for (let i = 0; i < GZIP_FIXED.length; i++)
+    if (head[i] !== GZIP_FIXED[i]) refuse("tar-format", "the tarball's gzip header is not fixed");
+  if (head[9] !== 255) refuse("tar-format", "the tarball's gzip OS byte is not 255");
+}
+
+/**
+ * `source` as a ReadableStream we own: errors from the source itself are remembered (so they
+ * reach the caller unchanged, never as a tamper code), and `release()` cancels the caller's
+ * stream or ends its iterator, whatever state the pipe is in.
+ */
+function sourceStream(source            ) {
+  let failure                                ;
+  let release                     ;
+  let pull                                           ;
+  if (typeof (source                              ).getReader === "function") {
+    const reader = (source                              ).getReader();
+    pull = async () => {
+      const r = await reader.read();
+      return r.done ? { done: true, value: undefined } : { done: false, value: r.value };
+    };
+    release = () => reader.cancel().catch(() => {});
+  } else {
+    const it = (
+      source instanceof Uint8Array
+        ? (async function* () {
+            yield source;
+          })()
+        : (source                             )
+    )[Symbol.asyncIterator]();
+    pull = () => it.next();
+    release = async () => {
+      await it.return?.()?.catch?.(() => {});
+    };
+  }
+  let released = false;
+  const once = async () => {
+    if (released) return;
+    released = true;
+    await release();
+  };
+  const stream = new ReadableStream            ({
+    async pull(c) {
+      try {
+        const next = await pull();
+        if (next.done) c.close();
+        else c.enqueue(next.value);
+      } catch (error) {
+        failure = { error };
+        throw error;
+      }
+    },
+    cancel: once,
+  });
+  return { stream, release: once, failure: () => failure };
+}
+
+/** Errors the stream unless its first ten bytes are the fixed gzip header (§7). */
+function gzipHeaderCheck()                                          {
+  const head           = [];
+  return new TransformStream({
+    transform(chunk, c) {
+      if (head.length < 10) {
+        for (const b of chunk.subarray(0, 10 - head.length)) head.push(b);
+        if (head.length === 10) checkGzipHeader(Uint8Array.from(head));
+      }
+      c.enqueue(chunk);
+    },
+    flush() {
+      if (head.length < 10) checkGzipHeader(Uint8Array.from(head));
+    },
+  });
+}
+
+/**
+ * The decompressed bytes of a gzip `source` whose header is the fixed one. Every exit (the end, a
+ * refusal, a consumer that stops early) cancels the chain and releases the caller's stream.
+ */
+export async function* gunzip(
+  source            ,
+  max         = MAX_TAR_BYTES,
+)                             {
+  const src = sourceStream(source);
+  const reader = src.stream
+    .pipeThrough(gzipHeaderCheck())
+    // Typed through explicitly: lib.dom and @types/node disagree on DecompressionStream's chunk types.
+    .pipeThrough(
+      new DecompressionStream("gzip")                                                      ,
+    )
+    .getReader();
+  let total = 0;
+  try {
+    for (;;) {
+      // The reader's own result type: not every lib names `ReadableStreamReadResult`.
+      let next                                         ;
+      try {
+        next = await reader.read();
+      } catch (e) {
+        const failed = src.failure();
+        if (failed) throw failed.error; // the source's own error, unchanged
+        if (e instanceof ReleaseVerifyError) throw e;
+        return refuse("tar-format", `the tarball is not valid gzip (${(e         ).message})`);
+      }
+      if (next.done) return;
+      total += next.value.length;
+      if (total > max)
+        refuse("limit-exceeded", `the tarball decompresses to more than ${max} bytes`);
+      yield next.value;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+    await src.release();
+  }
+}
+
+/** A FIFO of byte chunks that hands out exact lengths. */
+class ByteQueue {
+          chunks               = [];
+          offset = 0;
+  length = 0;
+  push(chunk            )       {
+    if (chunk.length === 0) return;
+    this.chunks.push(chunk);
+    this.length += chunk.length;
+  }
+  take(n        )             {
+    const out = new Uint8Array(n);
+    let at = 0;
+    while (at < n) {
+      const head = this.chunks[0]              ;
+      const part = head.subarray(this.offset, this.offset + (n - at));
+      out.set(part, at);
+      at += part.length;
+      this.offset += part.length;
+      if (this.offset === head.length) {
+        this.chunks.shift();
+        this.offset = 0;
+      }
+    }
+    this.length -= n;
+    return out;
+  }
+}
+
+const dec = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+
+function str(h            , at        , len        )         {
+  const s = h.subarray(at, at + len);
+  const end = s.indexOf(0);
+  try {
+    return dec.decode(end >= 0 ? s.subarray(0, end) : s);
+  } catch {
+    return refuse("tar-format", "a tar header field is not UTF-8");
+  }
+}
+
+/** An octal field: 1 to 11 digits, NUL- or space-terminated (anchored and bounded: linear). */
+function num(h            , at        , len        , what        )         {
+  const s = str(h, at, len).trim();
+  if (!/^[0-7]{1,11}$/.test(s)) refuse("tar-format", `a tar header has a bad ${what} field`);
+  return Number.parseInt(s, 8);
+}
+
+function checksumOk(h            )          {
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += i >= 148 && i < 156 ? 0x20 : (h[i]          );
+  return num(h, 148, 8, "checksum") === sum;
+}
+
+                  
+                                                                
+                            
+                        
+                           
+ 
+
+function checkHeader(h            , mtime        )         {
+  if (!checksumOk(h)) refuse("tar-format", "a tar header has a bad checksum");
+  if (str(h, 257, 6) !== "ustar" || h[262] !== 0 || str(h, 263, 2) !== "00")
+    refuse("tar-format", "a tar header is not ustar");
+  const flag = h[156] === 0 ? "0" : String.fromCharCode(h[156]          );
+  if (flag !== "0" && flag !== "x") refuse("tar-format", `a tar entry has type ${flag}`);
+  if (num(h, 100, 8, "mode") !== 0o644) refuse("tar-format", "a tar entry's mode is not 0644");
+  if (num(h, 108, 8, "uid") !== 0 || num(h, 116, 8, "gid") !== 0)
+    refuse("tar-format", "a tar entry's uid or gid is not 0");
+  if (num(h, 136, 12, "mtime") !== mtime)
+    refuse("tar-format", "a tar entry's mtime is not the release's createdAt");
+  if (str(h, 157, 100) || str(h, 265, 32) || str(h, 297, 32) || str(h, 345, 155))
+    refuse("tar-format", "a tar entry has a link name, an owner name or a prefix");
+  const field = h.subarray(0, 100);
+  const end = field.indexOf(0);
+  return { name: end >= 0 ? field.subarray(0, end) : field, size: num(h, 124, 12, "size"), flag };
+}
+
+/** The `path` of a PAX header holding exactly one `path` record. */
+function paxPath(data            )         {
+  let text        ;
+  try {
+    text = dec.decode(data);
+  } catch {
+    return refuse("tar-format", "a PAX header is not UTF-8");
+  }
+  const sp = text.indexOf(" ");
+  const len = Number(text.slice(0, sp));
+  if (sp < 1 || len !== data.length || !text.endsWith("\n") || !text.startsWith(`${len} path=`))
+    refuse("tar-format", "a PAX header is not a single path record");
+  return text.slice(sp + 6, -1);
+}
+
+                           
+                        
+                             
+ 
+
+const padded = (size        ) => Math.ceil(size / 512) * 512;
+const isZero = (b            ) => b.every((x) => x === 0);
+
+/** A tar stream read in exact lengths. */
+class TarReader {
+                   q = new ByteQueue();
+                   it                           ;
+  constructor(source                           ) {
+    this.it = source[Symbol.asyncIterator]();
+  }
+  /** Ends the source early (a refusal or a consumer that stopped): its own cleanup runs. */
+  async close()                {
+    await this.it.return?.();
+  }
+  /** Buffers at least `n` bytes; false when the stream ends first. */
+  async fill(n        )                   {
+    while (this.q.length < n) {
+      const next = await this.it.next();
+      if (next.done) return false;
+      this.q.push(next.value);
+    }
+    return true;
+  }
+  /** Exactly `n` bytes, or the refusal of a truncated archive. */
+  async take(n        )                      {
+    if (!(await this.fill(n))) refuse("tar-format", "the tar archive is truncated");
+    return this.q.take(n);
+  }
+  /** Everything left in the stream must be zeros, and with `zeros` already read, 1024 or more. */
+  async checkEnd(zeros        )                {
+    let trailing = zeros;
+    do {
+      const rest = this.q.take(this.q.length);
+      if (!isZero(rest)) refuse("tar-format", "the tar archive has data after its end");
+      trailing += rest.length;
+    } while (await this.fill(1));
+    if (trailing < 1024) refuse("tar-format", "the tar archive does not end with two zero blocks");
+  }
+}
+
+const utf8 = new TextEncoder();
+
+/**
+ * Whether `path` needs a PAX `path` record: longer than the 100-byte ustar name field in UTF-8,
+ * or not printable ASCII. The producer (scripts/release-bundle/tar.ts) imports this rule.
+ */
+export function needsPax(path        )          {
+  if (utf8.encode(path).length > 100) return true;
+  for (let i = 0; i < path.length; i++) {
+    const c = path.charCodeAt(i);
+    if (c < 0x20 || c > 0x7e) return true;
+  }
+  return false;
+}
+
+/**
+ * The ustar name field of `path`: its longest suffix whose UTF-8 is at most 100 bytes, cut on a
+ * code-point boundary (so it is valid UTF-8). For a path of at most 100 ASCII bytes that is the
+ * path itself. One byte-based rule for the producer, which imports it, and the verifier.
+ */
+export function ustarName(path        )         {
+  const points = Array.from(path);
+  let bytes = 0;
+  let i = points.length;
+  while (i > 0) {
+    const n = utf8.encode(points[i - 1]          ).length;
+    if (bytes + n > 100) break;
+    bytes += n;
+    i--;
+  }
+  return points.slice(i).join("");
+}
+
+const sameBytes = (a            , b            ) =>
+  a.length === b.length && a.every((x, i) => x === b[i]);
+
+/** The path of a file header: the PAX path when one came first, else its own ASCII name. */
+function entryPath(name            , pax               )         {
+  if (pax !== null) {
+    if (!needsPax(pax)) refuse("tar-format", `${pax}: a PAX record for a name that needs none`);
+    if (!sameBytes(name, utf8.encode(ustarName(pax))))
+      refuse("tar-format", `${pax}: the ustar name is not the end of the PAX path`);
+    return pax;
+  }
+  let path = "";
+  for (const c of name) {
+    if (c < 0x20 || c > 0x7e)
+      refuse("tar-format", "a tar name that is not ASCII has no PAX record");
+    path += String.fromCharCode(c);
+  }
+  return path;
+}
+
+/** The next file header with its PAX path applied, or null at the first zero block. */
+async function nextHeader(
+  r           ,
+  mtime        ,
+)                                                 {
+  let pax                = null;
+  for (;;) {
+    const h = await r.take(512);
+    if (isZero(h)) {
+      if (pax !== null) refuse("tar-format", "a PAX header ends the archive");
+      return null;
+    }
+    const { name, size, flag } = checkHeader(h, mtime);
+    if (size > LIMITS.partBytes)
+      refuse("limit-exceeded", `a tar entry is above ${LIMITS.partBytes} bytes`);
+    if (flag === "0") return { path: entryPath(name, pax), size };
+    if (pax !== null) refuse("tar-format", "two PAX headers in a row");
+    if (!sameBytes(name, utf8.encode("././@PaxHeader")))
+      refuse("tar-format", "a PAX header is not named ././@PaxHeader");
+    if (size > 4096) refuse("tar-format", "a PAX header is too large");
+    pax = paxPath((await r.take(padded(size))).subarray(0, size));
+  }
+}
+
+/**
+ * The entries of a decompressed tar stream, in archive order. `admit(path, size)` runs on each
+ * entry's header, before its bytes are buffered, so an unlisted or oversized entry is refused
+ * without reading it into memory.
+ */
+export async function* readTar(
+  source                           ,
+  mtime        ,
+  admit                                      ,
+)                           {
+  const r = new TarReader(source);
+  let count = 0;
+  try {
+    for (;;) {
+      const header = await nextHeader(r, mtime);
+      if (!header) break;
+      if (++count > LIMITS.tarEntries)
+        refuse("limit-exceeded", `the tarball has more than ${LIMITS.tarEntries} entries`);
+      admit(header.path, header.size);
+      const data = await r.take(padded(header.size));
+      yield { path: header.path, bytes: data.subarray(0, header.size) };
+    }
+    await r.checkEnd(512);
+  } finally {
+    await r.close();
+  }
+}

package/dist/src/trust.d.ts

@@ -0,0 +1,67 @@
+import type { ReleaseKeys as KeyListDocument } from "./generated/release-keys.js";
+import type { ReleaseYankList } from "./generated/release-yank-list.js";
+import { type ReleaseKeys } from "./keys.js";
+import { type YankMemory } from "./yank-memory.js";
+/** Root keys: they sign only `keys.json`. Pinned at the root ceremony; empty until then. */
+export type RootKeys = Readonly<Record<string, {
+    readonly publicKey: string;
+}>>;
+/**
+ * The offline root's public key (docs/security/release-signing-keys.md, kept equal by
+ * test/package.test.ts), pinned at the owner's root ceremony on 2026-11-15. It signs only
+ * `keys.json`; a rotation of the root is a new pinned entry in a reviewed release.
+ */
+export declare const PINNED_ROOTS: RootKeys;
+export declare const KEYS_FILE = "keys.json";
+export declare const YANKED_FILE = "yanked.json";
+/** Where the lists live (RFC-0046 §9); `<file>.sig` next to each. */
+export declare const TRUST_BASE_URL = "https://cloudhal.dev/.well-known/cloudhal/";
+export interface VerifiedKeyList {
+    readonly document: KeyListDocument;
+    /** SHA-256 of the exact bytes, for logs. */
+    readonly sha256: string;
+}
+export interface VerifiedYankList {
+    readonly document: ReleaseYankList;
+    readonly sha256: string;
+}
+/** `iso` plus `months` calendar months (UTC), clamped to the target month's last day (01-31 + 1 → 02-28/29). */
+export declare function addMonths(iso: string, months: number): number;
+/** Verifies `keys.json` (see the file comment); throws a `ReleaseVerifyError`. */
+export declare function verifyKeys(input: {
+    document: Uint8Array;
+    signature: Uint8Array;
+    roots?: RootKeys;
+    now?: Date;
+    /** A consumer's `YankMemory`: a `keys.json` older than the newest one seen is refused. */
+    memory?: YankMemory;
+}): Promise<VerifiedKeyList>;
+/**
+ * Verifies `yanked.json` against a verified key list (see the file comment). A consumer that can
+ * keep state passes its `memory` and stores `rememberYanks(result, keys, memory)` (yank-memory.ts):
+ * a replayed older `keys.json`, a revoked or replaced yank key, a lower serial or a dropped entry
+ * is refused. A stateless consumer (a Worker) cannot detect a replay or an un-yank: for it, a
+ * stolen yank key can un-yank and un-revoke until the root rotates the yank key.
+ */
+export declare function verifyYanked(input: {
+    document: Uint8Array;
+    signature: Uint8Array;
+    keys: VerifiedKeyList;
+    now?: Date;
+    memory?: YankMemory;
+}): Promise<VerifiedYankList>;
+/**
+ * `pinned` reduced by a verified key list and yank list (RFC-0046 §9). For each pinned key: a
+ * listing with another public key or another role revokes it; otherwise the stricter status wins
+ * and the window narrows to the intersection; `listed` records that a fresh list names it. A
+ * revocation in either list revokes it. Keys the lists name but `pinned` lacks are not added.
+ */
+export declare function mergeTrust(pinned: ReleaseKeys, lists?: {
+    keys?: VerifiedKeyList;
+    yanked?: VerifiedYankList;
+}): ReleaseKeys;
+/** The yank entry for `version`, if the verified list yanks it. */
+export declare function yankOf(yanked: VerifiedYankList | undefined, version: string): {
+    reason: string;
+    yankedAt: string;
+} | undefined;