@cloudhal/release-verify 0.0.0-placeholder.0 → 0.10.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,82 @@
-# @cloudhal/release-verify (placeholder)
+# @cloudhal/release-verify
 
-This version only reserves the package name so that later versions can be published from CI with trusted publishing and npm provenance. It contains no code. Install a real version instead.
+Verifies a [Cloudhal](https://cloudhal.dev) release bundle before you deploy it. It follows [RFC-0046](https://github.com/cloudhal-dev/cloudhal/blob/main/docs/rfcs/0046-release-bundles.md) §2, §7 and §11a: hosts, tools and the `cloudhal` CLI share this one verifier. It runs on Workers, Node 24 and browsers.
+
+```ts
+import { releaseAssetUrls, verifyRelease } from "@cloudhal/release-verify";
+
+const release = await verifyRelease({
+  request: { version: "0.9.0" },             // what you asked for: a signed older release is refused
+  statement, signature, manifest,            // the exact downloaded bytes (Uint8Array)
+  tarball: () => fetchTarballStream(),       // opened twice: digest first, then entries
+  planVersion: 1,                            // the highest plan version your deployer supports
+});
+for await (const entry of release.entries()) {
+  // { worker, kind, path, type?, bytes }: verified against the signed manifest
+}
+// Activate the deployment only after the loop has finished without an error.
+```
+
+## What it checks
+
+1. **Sizes.** The statement is at most 4096 bytes, and the signature is exactly 64.
+2. **Signature.** Ed25519 over the exact statement bytes, with a trusted key for `signing.keyId`.
+3. **Request.** The statement is for the requested version and channel.
+4. **Statement.** Its schema, through the precompiled validator, plus RFC-0046 §2 invariants 1 to 3 and 6.
+5. **Manifest.**
+   - Its size and SHA-256 equal the statement's.
+   - Its schema and invariants 4 and 5.
+   - The `release-statement.sig` signature form.
+   - `planVersion`.
+   - Every listed path, and §7's limits.
+6. **Tarball.** Its size and SHA-256 equal the statement's.
+
+Then `entries()` re-reads the tarball. It refuses:
+- an entry the manifest does not list, or one whose size or SHA-256 differs from its listing;
+- a missing entry;
+- anything outside §7's tar format;
+- an unsafe path: `..`, `.`, an empty segment, a backslash, a control character, more than 512 bytes, or two paths that collide after case folding.
+
+There is no soft-fail mode. Every refusal is a `ReleaseVerifyError` with a stable `code` (`ERROR_CODES`).
+
+## Keys
+
+`PINNED_KEYS` holds the keys of [docs/security/release-signing-keys.md](https://github.com/cloudhal-dev/cloudhal/blob/main/docs/security/release-signing-keys.md) as they were when this version was published. It cannot learn about later revocations by itself.
+
+You can only reduce trust: pass `revoked: ["<keyId>"]` to withdraw a key. Passing your own `keys` map replaces the table, so treat that as a reviewed change.
+
+## Key list and yank list (RFC-0046 §9)
+
+`keys.json` (signed by an offline root) and `yanked.json` (signed by a yank key) live at `https://cloudhal.dev/.well-known/cloudhal/`, each with its `.sig`. Fetch all four on every run, verify them, and merge them into the keys you pin. They can only take trust away:
+
+```ts
+import { mergeTrust, PINNED_KEYS, verifyKeys, verifyRelease, verifyYanked } from "@cloudhal/release-verify";
+
+const keys = await verifyKeys({ document: keysJson, signature: keysSig });            // pinned root, fresh
+const yanked = await verifyYanked({ document: yankedJson, signature: yankedSig, keys }); // stale → stale-yank-list
+await verifyRelease({ ...input, keys: mergeTrust(PINNED_KEYS, { keys, yanked }), yanked });
+```
+
+- **Expiry.** A statement's `createdAt` must lie within its key's `[notBefore, notAfter]`. After `notAfter`, the key verifies only while a fresh `keys.json` lists it as `retiring`. With pinned keys alone, the release is refused with `key-expired`.
+- **Yanking.** A yanked version is refused (`yanked`), and a key that `yanked.json` revokes is refused (`key-revoked`).
+- **Keep state if you can.** Pass the `memory` you stored to `verifyKeys` and `verifyYanked`, and store `rememberYanks(yanked, keys, memory)` after every accepted pair. Refused:
+  - a list that goes back in `serial`, or drops a version or key you have already seen yanked or revoked (`stale-yank-list`);
+  - a `keys.json` older than the newest one you have seen (`key-list-invalid`), so a replayed list cannot bring back a revoked yank key;
+  - a list signed by a yank key a root list revoked or replaced (`yank-list-invalid`);
+  - a list from another yank key, unless a newer `keys.json` replaces the remembered one (`stale-yank-list`).
+
+  Without memory, a stolen yank key could undo yanks for you until the root rotates it. A `keys.json` lists at most one active yank key.
+- **Not yet published.** `PINNED_ROOTS` is empty until the root is generated. Until then `verifyKeys` refuses every list, unless you pass `roots`.
+
+## The second factor
+
+The Node-only subpath `@cloudhal/release-verify/attestation` checks the GitHub build-provenance attestation of the tarball, the manifest and the statement. It needs `gh` 2.68.0 or newer, signed in. It returns `verified` or `failed`, or `unavailable` when `gh` is missing, too old, or signed out.
+
+```ts
+import { verifyAttestation } from "@cloudhal/release-verify/attestation";
+const r = await verifyAttestation({ dir, version: "0.9.0", commit: release.statement.commit });
+```
+
+## Scopes
+
+`missingScopes(manifest, granted)` compares Cloudflare scope ids exactly, with one exception: `workers-scripts.admin` covers `workers-scripts.edit`, which manifests up to v0.9.0 name (RFC-0046 §3).

package/dist/src/attestation.d.ts

@@ -0,0 +1,42 @@
+export declare const MIN_GH_VERSION = "2.68.0";
+export declare const SIGNER_WORKFLOW = "cloudhal-dev/cloudhal/.github/workflows/bundle-build.yml";
+/** Every flag the verify call passes; the probe requires each in `gh attestation verify --help`. */
+export declare const ATTESTATION_FLAGS: readonly ["--repo", "--signer-workflow", "--source-ref", "--source-digest", "--deny-self-hosted-runners", "--bundle"];
+export type AttestationResult = {
+    readonly status: "verified";
+} | {
+    readonly status: "failed";
+    readonly file: string;
+    readonly reason: string;
+} | {
+    readonly status: "unavailable";
+    readonly reason: string;
+};
+export interface RunResult {
+    readonly code: number | null;
+    readonly signal: string | null;
+    readonly timedOut: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type Runner = (cmd: string, args: readonly string[], timeoutMs: number) => Promise<RunResult>;
+export interface AttestationOptions {
+    /** The directory holding the downloaded assets. */
+    readonly dir: string;
+    readonly version: string;
+    /** The verified statement's `commit` (40 hex), pinned with `--source-digest`. */
+    readonly commit: string;
+    readonly timeoutMs?: number;
+    /** For tests: how commands run (default: spawn, no shell). */
+    readonly run?: Runner;
+}
+/** The argument vector of the verify call for `file` (exact flags of §11a). */
+export declare function attestationArgs(file: string, commit: string, bundle?: string): string[];
+/** `a.b.c` ≥ `min`, comparing the numeric parts. */
+export declare function versionAtLeast(version: string, min: string): boolean;
+/** The version `gh --version` prints first (`gh version 2.102.0 (2026-09-30)`). */
+export declare function ghVersionOf(stdout: string): string | undefined;
+/** Verifies the attestation of the tarball, the manifest and the statement in `o.dir`. */
+export declare function verifyAttestation(o: AttestationOptions): Promise<AttestationResult>;
+/** Runs `cmd` without a shell; never throws for a non-zero exit. */
+export declare const spawnRunner: Runner;

package/dist/src/attestation.js

@@ -0,0 +1,180 @@
+/**
+ * The second factor (RFC-0046 §2, §9, §11a): the GitHub build-provenance attestation of a
+ * release's files, checked with `gh attestation verify`. Node only (it runs `gh`).
+ *
+ * - `unavailable` (nothing verified): `gh` is missing, older than 2.68.0 (the first release with
+ *   `--source-ref` and `--source-digest`), lacks one of the flags below in its `--help`, or is not
+ *   signed in. Callers decide what that means; the CLI refuses unless told to rely on one factor.
+ * - `failed`: any non-zero exit, a signal, or no exit within the timeout. Always a refusal.
+ * - `verified`: all three files (tarball, manifest, statement) verified.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { MANIFEST_FILE, STATEMENT_FILE, sigstoreName, tarballName } from "./limits.js";
+import { RELEASE_REPOSITORY, releaseAssetNames } from "./urls.js";
+
+export const MIN_GH_VERSION = "2.68.0";
+export const SIGNER_WORKFLOW = `${RELEASE_REPOSITORY}/.github/workflows/bundle-build.yml`;
+/** Every flag the verify call passes; the probe requires each in `gh attestation verify --help`. */
+export const ATTESTATION_FLAGS = [
+  "--repo",
+  "--signer-workflow",
+  "--source-ref",
+  "--source-digest",
+  "--deny-self-hosted-runners",
+  "--bundle",
+]         ;
+
+                               
+                                   
+                                                                                 
+                                                                
+
+                            
+                               
+                                 
+                             
+                          
+                          
+ 
+
+                      
+              
+                          
+                    
+                        
+
+                                     
+                                                     
+                       
+                           
+                                                                                   
+                          
+                              
+                                                                
+                        
+ 
+
+/** The argument vector of the verify call for `file` (exact flags of §11a). */
+export function attestationArgs(file        , commit        , bundle         )           {
+  return [
+    "attestation",
+    "verify",
+    file,
+    "--repo",
+    RELEASE_REPOSITORY,
+    "--signer-workflow",
+    SIGNER_WORKFLOW,
+    "--source-ref",
+    "refs/heads/main",
+    "--source-digest",
+    commit,
+    "--deny-self-hosted-runners",
+    ...(bundle ? ["--bundle", bundle] : []),
+  ];
+}
+
+/** `a.b.c` ≥ `min`, comparing the numeric parts. */
+export function versionAtLeast(version        , min        )          {
+  const a = version.split(".").map((x) => Number.parseInt(x, 10));
+  const b = min.split(".").map((x) => Number.parseInt(x, 10));
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (Number.isNaN(x)) return false;
+    if (x !== y) return x > y;
+  }
+  return true;
+}
+
+/** The version `gh --version` prints first (`gh version 2.102.0 (2026-09-30)`). */
+export function ghVersionOf(stdout        )                     {
+  const first = stdout.split("\n", 1)[0] ?? "";
+  const words = first.trim().split(" ");
+  return words[0] === "gh" && words[1] === "version" ? words[2] : undefined;
+}
+
+const ok = (r           ) => r.code === 0 && r.signal === null && !r.timedOut;
+
+async function probe(run        , timeoutMs        )                              {
+  const need = `gh ${MIN_GH_VERSION} or newer, signed in (gh auth login)`;
+  const v = await run("gh", ["--version"], timeoutMs).catch(() => undefined);
+  if (!v || !ok(v)) return `gh is not installed: install ${need}`;
+  const version = ghVersionOf(v.stdout);
+  if (!version || !versionAtLeast(version, MIN_GH_VERSION))
+    return `gh ${version ?? "(unknown version)"} is too old: install ${need}`;
+  const help = await run("gh", ["attestation", "verify", "--help"], timeoutMs).catch(
+    () => undefined,
+  );
+  const text = help ? `${help.stdout}\n${help.stderr}` : "";
+  const lacking = ATTESTATION_FLAGS.filter((f) => !text.includes(f));
+  if (!help || !ok(help) || lacking.length)
+    return `gh ${version} lacks gh attestation verify ${lacking.join(" ")}: install ${need}`;
+  const auth = await run("gh", ["auth", "status"], timeoutMs).catch(() => undefined);
+  if (!auth || !ok(auth)) return `gh is not signed in: run gh auth login`;
+  return undefined;
+}
+
+/** Verifies the attestation of the tarball, the manifest and the statement in `o.dir`. */
+export async function verifyAttestation(o                    )                             {
+  releaseAssetNames(o.version); // refuses a malformed version before anything runs
+  if (o.commit.length !== 40 || [...o.commit].some((c) => !"0123456789abcdef".includes(c)))
+    throw new TypeError("commit must be 40 lowercase hex characters");
+  const run = o.run ?? spawnRunner;
+  const timeoutMs = o.timeoutMs ?? 60_000;
+  const why = await probe(run, timeoutMs);
+  if (why) return { status: "unavailable", reason: why };
+  // Absolute paths, so no file name can ever be read by gh as a flag.
+  const dir = path.resolve(o.dir);
+  const bundle = path.join(dir, sigstoreName(o.version));
+  const withBundle = existsSync(bundle) ? bundle : undefined;
+  for (const name of [tarballName(o.version), MANIFEST_FILE, STATEMENT_FILE]) {
+    const file = path.join(dir, name);
+    const r = await run("gh", attestationArgs(file, o.commit, withBundle), timeoutMs).catch(
+      (e       )            => ({
+        code: null,
+        signal: null,
+        timedOut: false,
+        stdout: "",
+        stderr: e.message,
+      }),
+    );
+    if (!ok(r)) {
+      const reason = r.timedOut
+        ? `no answer within ${timeoutMs / 1000} s`
+        : r.signal
+          ? `stopped by ${r.signal}`
+          : r.stderr.trim().split("\n").pop() || `exit ${r.code}`;
+      return { status: "failed", file: name, reason };
+    }
+  }
+  return { status: "verified" };
+}
+
+/** Runs `cmd` without a shell; never throws for a non-zero exit. */
+export const spawnRunner         = (cmd, args, timeoutMs) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout.on("data", (c        ) => {
+      stdout += c.toString();
+    });
+    child.stderr.on("data", (c        ) => {
+      stderr += c.toString();
+    });
+    child.once("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+    child.once("close", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal, timedOut, stdout, stderr });
+    });
+  });

package/dist/src/crypto.d.ts

@@ -0,0 +1,15 @@
+/** Pure Ed25519 over the exact `message` bytes. */
+export declare function verifyEd25519(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+/** SHA-256 of `bytes`, lowercase hex. */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+export interface IncrementalSha256 {
+    update(chunk: Uint8Array): Promise<void>;
+    /** Lowercase hex; call once, after the last `update`. */
+    digest(): Promise<string>;
+}
+/** Workers' `crypto.DigestStream` (a WritableStream whose `digest` resolves on close). */
+export type DigestStreamConstructor = new (algorithm: string) => WritableStream<Uint8Array> & {
+    readonly digest: Promise<ArrayBuffer>;
+};
+/** An incremental SHA-256: `crypto.DigestStream` when the runtime has one, else @noble/hashes. */
+export declare function incrementalSha256(DigestStream?: DigestStreamConstructor | undefined): IncrementalSha256;

package/dist/src/crypto.js

@@ -0,0 +1,87 @@
+/**
+ * Ed25519 and SHA-256 on every runtime (RFC-0046 §11a): WebCrypto for Ed25519 and one-shot
+ * digests; for the streamed tarball, Workers' native `crypto.DigestStream` where it exists and
+ * otherwise `@noble/hashes` (audited, zero dependencies), because WebCrypto's `digest` cannot
+ * stream. test/crypto.test.ts checks both paths against the NIST vectors and `node:crypto`.
+ */
+import { sha256 as nobleSha256 } from "@noble/hashes/sha2.js";
+
+const toHex = (bytes            )         => {
+  let s = "";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+};
+
+/**
+ * `bytes` as WebCrypto's `BufferSource` under every consumer's lib settings: the same view when it
+ * is backed by an `ArrayBuffer`, else a copy (a `SharedArrayBuffer` is never handed to WebCrypto).
+ */
+function buffer(bytes            )                          {
+  return bytes.buffer instanceof ArrayBuffer
+    ? (bytes                           )
+    : new Uint8Array(bytes);
+}
+
+/** Pure Ed25519 over the exact `message` bytes. */
+export async function verifyEd25519(
+  publicKey            ,
+  message            ,
+  signature            ,
+)                   {
+  try {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      buffer(publicKey),
+      { name: "Ed25519" },
+      false,
+      ["verify"],
+    );
+    return await crypto.subtle.verify({ name: "Ed25519" }, key, buffer(signature), buffer(message));
+  } catch {
+    // A key that is not a valid Ed25519 point verifies nothing.
+    return false;
+  }
+}
+
+/** SHA-256 of `bytes`, lowercase hex. */
+export async function sha256Hex(bytes            )                  {
+  return toHex(new Uint8Array(await crypto.subtle.digest("SHA-256", buffer(bytes))));
+}
+
+                                    
+                                           
+                                                           
+                            
+ 
+
+/** Workers' `crypto.DigestStream` (a WritableStream whose `digest` resolves on close). */
+                                           
+                    
+                                                                            
+
+const nativeDigestStream = ()                                      =>
+  (globalThis                                                           ).crypto?.DigestStream;
+
+/** An incremental SHA-256: `crypto.DigestStream` when the runtime has one, else @noble/hashes. */
+export function incrementalSha256(
+  DigestStream                                      = nativeDigestStream(),
+)                    {
+  if (DigestStream) {
+    const stream = new DigestStream("SHA-256");
+    const writer = stream.getWriter();
+    return {
+      update: (chunk) => writer.write(chunk),
+      async digest() {
+        await writer.close();
+        return toHex(new Uint8Array(await stream.digest));
+      },
+    };
+  }
+  const h = nobleSha256.create();
+  return {
+    update: async (chunk) => {
+      h.update(chunk);
+    },
+    digest: async () => toHex(h.digest()),
+  };
+}

package/dist/src/documents.d.ts

@@ -0,0 +1,23 @@
+import type { ReleaseManifest } from "./generated/release-manifest.js";
+import type { ReleaseStatement } from "./generated/release-statement.js";
+/** The JSON document in `bytes`, or the refusal `code`. */
+export declare function parseJson(bytes: Uint8Array, code: "statement-invalid" | "manifest-invalid"): unknown;
+/** §2 step 4: the schema, then invariants 1, 2, 3 and 6. */
+export declare function checkStatementDoc(doc: unknown, serialisedBytes: number): ReleaseStatement;
+/** §2 step 3 (invariant 7): the statement is for the version and channel that were asked for. */
+export declare function checkRequested(doc: unknown, version: string, channel?: "stable" | "next"): void;
+/** §2 step 5 after the digest: the schema, invariants 4 and 5, the signature form, planVersion. */
+export declare function checkManifestDoc(doc: unknown, statement: ReleaseStatement, planVersion: number): ReleaseManifest;
+export type Worker = "site" | "admin";
+/** One part the manifest lists, by its tar path. */
+export interface ListedPart {
+    readonly worker: Worker | null;
+    readonly kind: "module" | "asset" | "starter";
+    /** The module path, the asset path (`/x`), or the starter's `starter/<file>`. */
+    readonly path: string;
+    readonly type?: string;
+    readonly bytes: number;
+    readonly sha256: string;
+}
+/** Every part the manifest lists, keyed by its tar path (`site/modules/x.mjs`, …). */
+export declare function listedParts(m: ReleaseManifest): Map<string, ListedPart>;