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

package/dist/src/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@cloudhal/release-verify` (RFC-0046 §11a): the one verifier of Cloudhal release bundles for
+ * hosts, tools and the CLI. Worker-safe: WebCrypto Ed25519, `DecompressionStream`, and an
+ * incremental SHA-256 (`crypto.DigestStream`, else @noble/hashes). The second factor, the GitHub
+ * build attestation, is the Node-only subpath `@cloudhal/release-verify/attestation`.
+ */
+export { type IncrementalSha256, incrementalSha256, sha256Hex, verifyEd25519 } from "./crypto.js";
+export type { ListedPart, Worker } from "./documents.js";
+export { ERROR_CODES, ReleaseVerifyError, type ReleaseVerifyErrorCode } from "./errors.js";
+export type { ListedKey, ReleaseKeys as KeyListDocument } from "./generated/release-keys.js";
+export type { ReleaseManifest } from "./generated/release-manifest.js";
+export type { ReleaseStatement } from "./generated/release-statement.js";
+export type { ReleaseYankList } from "./generated/release-yank-list.js";
+export { type KeyStatus, PINNED_KEYS, type ReleaseKey, type ReleaseKeys } from "./keys.js";
+export { channelOf, LIMITS, MANIFEST_FILE, SIGNATURE_FILE, STATEMENT_FILE, sigstoreName, tarballName, } from "./limits.js";
+export { foldPath, type PathKind, unsafePathReason } from "./paths.js";
+export { IMPLIED_SCOPES, missingScopes } from "./scopes.js";
+export type { ByteSource } from "./tar.js";
+export { addMonths, KEYS_FILE, mergeTrust, PINNED_ROOTS, type RootKeys, TRUST_BASE_URL, type VerifiedKeyList, type VerifiedYankList, verifyKeys, verifyYanked, YANKED_FILE, yankOf, } from "./trust.js";
+export { RELEASE_REPOSITORY, releaseAssetNames, releaseAssetUrls } from "./urls.js";
+export { type VerifiedEntry, type VerifiedRelease, type VerifyReleaseInput, verifyRelease, } from "./verify.js";
+export { rememberYanks, type YankMemory } from "./yank-memory.js";

package/dist/src/index.js

@@ -0,0 +1,48 @@
+/**
+ * `@cloudhal/release-verify` (RFC-0046 §11a): the one verifier of Cloudhal release bundles for
+ * hosts, tools and the CLI. Worker-safe: WebCrypto Ed25519, `DecompressionStream`, and an
+ * incremental SHA-256 (`crypto.DigestStream`, else @noble/hashes). The second factor, the GitHub
+ * build attestation, is the Node-only subpath `@cloudhal/release-verify/attestation`.
+ */
+export {                         incrementalSha256, sha256Hex, verifyEd25519 } from "./crypto.js";
+                                                         
+export { ERROR_CODES, ReleaseVerifyError,                             } from "./errors.js";
+                                                                                             
+                                                                       
+                                                                         
+                                                                        
+export {                 PINNED_KEYS,                                   } from "./keys.js";
+export {
+  channelOf,
+  LIMITS,
+  MANIFEST_FILE,
+  SIGNATURE_FILE,
+  STATEMENT_FILE,
+  sigstoreName,
+  tarballName,
+} from "./limits.js";
+export { foldPath,                unsafePathReason } from "./paths.js";
+export { IMPLIED_SCOPES, missingScopes } from "./scopes.js";
+                                           
+export {
+  addMonths,
+  KEYS_FILE,
+  mergeTrust,
+  PINNED_ROOTS,
+                
+  TRUST_BASE_URL,
+                       
+                        
+  verifyKeys,
+  verifyYanked,
+  YANKED_FILE,
+  yankOf,
+} from "./trust.js";
+export { RELEASE_REPOSITORY, releaseAssetNames, releaseAssetUrls } from "./urls.js";
+export {
+                     
+                       
+                          
+  verifyRelease,
+} from "./verify.js";
+export { rememberYanks,                 } from "./yank-memory.js";

package/dist/src/keys.d.ts

@@ -0,0 +1,28 @@
+export type KeyStatus = "active" | "retiring" | "revoked";
+export interface ReleaseKey {
+    /** The raw 32-byte Ed25519 public key, base64. */
+    readonly publicKey: string;
+    readonly status: KeyStatus;
+    /** The key signs statements created in `[notBefore, notAfter]` (RFC 3339, UTC). */
+    readonly notBefore?: string;
+    readonly notAfter?: string;
+    /**
+     * Set by `mergeTrust` when a fresh, root-signed `keys.json` lists this key (and does not revoke
+     * it). Only then may a `retiring` key verify after its `notAfter` (RFC-0046 §9).
+     */
+    readonly listed?: boolean;
+}
+export type ReleaseKeys = Readonly<Record<string, ReleaseKey>>;
+export declare const PINNED_KEYS: ReleaseKeys;
+/** The raw public key `keyId` verifies with and its record, or a refusal (unknown, revoked, malformed). */
+export declare function trustedKey(keys: ReleaseKeys, revoked: readonly string[], keyId: string): {
+    raw: Uint8Array;
+    key: ReleaseKey;
+};
+/**
+ * RFC-0046 §9's expiry rule for the key that signed a statement created at `createdAt`: it must
+ * lie within the key's `[notBefore, notAfter]`, and after `notAfter` the key verifies only while a
+ * fresh `keys.json` lists it as `retiring` (`listed`). Pinned keys alone refuse after `notAfter`.
+ */
+export declare function checkKeyWindow(keyId: string, key: ReleaseKey, createdAt: string, now: Date): void;
+export declare function fromBase64(s: string): Uint8Array | undefined;

package/dist/src/keys.js

@@ -0,0 +1,84 @@
+/**
+ * The release keys this package trusts (RFC-0046 §9, §11a): the table of
+ * docs/security/release-signing-keys.md, kept equal to it by test/package.test.ts.
+ *
+ * `PINNED_KEYS` is frozen into each published version and cannot learn about a revocation by
+ * itself. A caller may only reduce trust: `revoked` withdraws key ids. A caller that trusts a key
+ * outside this table passes a whole `keys` map, which is a reviewed change on its side. Once the
+ * signed `keys.json` of #226 exists, it feeds the same reduce-only path.
+ */
+import { refuse } from "./errors.js";
+
+                                                          
+
+                             
+                                                    
+                             
+                             
+                                                                                     
+                              
+                             
+     
+                                                                                                  
+                                                                                   
+     
+                            
+ 
+
+                                                               
+
+export const PINNED_KEYS              = Object.freeze({
+  "cloudhal-release-2026a": Object.freeze({
+    publicKey: "7az3pPc4oT0AOfRcdfOZZQkM6XAGHo2jXEdDZ1qEVR8=",
+    status: "active",
+    notBefore: "2026-11-12T00:00:00Z",
+    notAfter: "2027-11-12T00:00:00Z",
+  }),
+});
+
+/** The raw public key `keyId` verifies with and its record, or a refusal (unknown, revoked, malformed). */
+export function trustedKey(
+  keys             ,
+  revoked                   ,
+  keyId        ,
+)                                       {
+  const key = Object.hasOwn(keys, keyId) ? keys[keyId] : undefined;
+  if (!key) return refuse("key-unknown", `no trusted release key ${keyId}`);
+  if (key.status === "revoked" || revoked.includes(keyId))
+    return refuse("key-revoked", `release key ${keyId} is revoked`);
+  const raw = fromBase64(key.publicKey);
+  if (raw?.length !== 32)
+    return refuse("key-unknown", `the trusted key ${keyId} is not a 32-byte Ed25519 key`);
+  return { raw, key };
+}
+
+/**
+ * RFC-0046 §9's expiry rule for the key that signed a statement created at `createdAt`: it must
+ * lie within the key's `[notBefore, notAfter]`, and after `notAfter` the key verifies only while a
+ * fresh `keys.json` lists it as `retiring` (`listed`). Pinned keys alone refuse after `notAfter`.
+ */
+export function checkKeyWindow(keyId        , key            , createdAt        , now      )       {
+  const created = Date.parse(createdAt);
+  if (key.notBefore !== undefined && created < Date.parse(key.notBefore))
+    refuse("key-expired", `${keyId} was not yet valid when this release was created`);
+  if (key.notAfter === undefined) return;
+  const notAfter = Date.parse(key.notAfter);
+  if (created > notAfter)
+    refuse("key-expired", `${keyId} had expired when this release was created`);
+  if (now.getTime() > notAfter && !(key.status === "retiring" && key.listed === true))
+    refuse(
+      "key-expired",
+      `${keyId} expired on ${key.notAfter.slice(0, 10)}; a fresh keys.json must list it as retiring`,
+    );
+}
+
+export function fromBase64(s        )                         {
+  try {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  } catch {
+    return undefined;
+  }
+}

package/dist/src/limits.d.ts

@@ -0,0 +1,24 @@
+/**
+ * RFC-0046 §1 asset names and §7's normative limits. `scripts/release-bundle/manifest.ts` (the
+ * producer) holds the same numbers; test/package.test.ts keeps the two equal.
+ */
+export declare const LIMITS: {
+    readonly manifestBytes: 1900000;
+    readonly statementBytes: 4096;
+    readonly tarballBytes: 104857600;
+    readonly partBytes: number;
+    readonly assetBytes: number;
+    readonly assetsPerWorker: 20000;
+    readonly tarEntries: 30000;
+};
+/** The largest decompressed tar a release may hold: every part at its limit is far beyond it. */
+export declare const MAX_TAR_BYTES: number;
+/** The longest path, in UTF-8 bytes, a manifest listing or a tar entry may carry (§11a). */
+export declare const MAX_PATH_BYTES = 512;
+export declare const STATEMENT_FILE = "release-statement.json";
+export declare const SIGNATURE_FILE = "release-statement.sig";
+export declare const MANIFEST_FILE = "manifest.json";
+export declare const tarballName: (version: string) => string;
+export declare const sigstoreName: (version: string) => string;
+/** `X.Y.Z-<pre>` ⇔ `next` (§2 invariant 3, §6). */
+export declare const channelOf: (version: string) => "stable" | "next";

package/dist/src/limits.js

@@ -0,0 +1,30 @@
+/**
+ * RFC-0046 §1 asset names and §7's normative limits. `scripts/release-bundle/manifest.ts` (the
+ * producer) holds the same numbers; test/package.test.ts keeps the two equal.
+ */
+export const LIMITS = {
+  manifestBytes: 1_900_000,
+  statementBytes: 4096,
+  tarballBytes: 104_857_600,
+  partBytes: 64 * 1024 * 1024,
+  assetBytes: 25 * 1024 * 1024,
+  assetsPerWorker: 20_000,
+  tarEntries: 30_000,
+}         ;
+
+/** The largest decompressed tar a release may hold: every part at its limit is far beyond it. */
+export const MAX_TAR_BYTES = 1024 * 1024 * 1024;
+
+/** The longest path, in UTF-8 bytes, a manifest listing or a tar entry may carry (§11a). */
+export const MAX_PATH_BYTES = 512;
+
+export const STATEMENT_FILE = "release-statement.json";
+export const SIGNATURE_FILE = "release-statement.sig";
+export const MANIFEST_FILE = "manifest.json";
+export const tarballName = (version        )         => `cloudhal-release-${version}.tar.gz`;
+export const sigstoreName = (version        )         =>
+  `cloudhal-release-${version}.sigstore.json`;
+
+/** `X.Y.Z-<pre>` ⇔ `next` (§2 invariant 3, §6). */
+export const channelOf = (version        )                    =>
+  version.includes("-") ? "next" : "stable";

package/dist/src/paths.d.ts

@@ -0,0 +1,14 @@
+/** `module` and `entry` paths are relative; an `asset` path is `/<relative path>` (§3). */
+export type PathKind = "module" | "asset" | "entry";
+/** Why `path` is unsafe as a `kind` path, or undefined when it is safe. */
+export declare function unsafePathReason(path: string, kind: PathKind): string | undefined;
+/** Refuses `path` (named `where` in the message) unless it is safe as a `kind` path. */
+export declare function checkPath(path: string, kind: PathKind, where: string): void;
+/**
+ * Case folding as case-insensitive file systems apply it, approximately: NFC, lower, upper, lower
+ * again, NFC (so "ß", "ẞ" and "SS" meet, and so do "ΐ" and "Ϊ́"). Two listed paths that fold
+ * equal would collide on disk.
+ */
+export declare const foldPath: (path: string) => string;
+/** Refuses two `paths` that are equal after case folding. */
+export declare function checkNoFoldedDuplicates(paths: Iterable<string>, where: string): void;

package/dist/src/paths.js

@@ -0,0 +1,59 @@
+/**
+ * Entry-path safety (RFC-0046 §11a): every path in the manifest's listings and every tar entry
+ * name is checked before any byte of that entry is used. One pass over the characters plus a
+ * `split("/")`, no regular expression, so the check is linear in the path's length (AGENTS.md
+ * rule 13). A failure is the refusal `entry-path`.
+ */
+import { refuse } from "./errors.js";
+import { MAX_PATH_BYTES } from "./limits.js";
+
+/** `module` and `entry` paths are relative; an `asset` path is `/<relative path>` (§3). */
+                                                    
+
+const utf8 = new TextEncoder();
+
+/** Why `path` is unsafe as a `kind` path, or undefined when it is safe. */
+export function unsafePathReason(path        , kind          )                     {
+  if (utf8.encode(path).length > MAX_PATH_BYTES) return `longer than ${MAX_PATH_BYTES} bytes`;
+  for (let i = 0; i < path.length; i++) {
+    const c = path.charCodeAt(i);
+    if (c < 0x20 || c === 0x7f) return "a control character";
+    if (c === 0x5c) return "a backslash";
+  }
+  let rel = path;
+  if (kind === "asset") {
+    if (!path.startsWith("/")) return "an asset path that does not start with /";
+    rel = path.slice(1);
+  } else if (path.startsWith("/")) return "a leading /";
+  for (const segment of rel.split("/")) {
+    if (segment === "") return "an empty segment";
+    if (segment === "." || segment === "..") return `a ${segment} segment`;
+  }
+  return undefined;
+}
+
+/** Refuses `path` (named `where` in the message) unless it is safe as a `kind` path. */
+export function checkPath(path        , kind          , where        )       {
+  const reason = unsafePathReason(path, kind);
+  if (reason) refuse("entry-path", `${where}: ${JSON.stringify(path)} has ${reason}`);
+}
+
+/**
+ * Case folding as case-insensitive file systems apply it, approximately: NFC, lower, upper, lower
+ * again, NFC (so "ß", "ẞ" and "SS" meet, and so do "ΐ" and "Ϊ́"). Two listed paths that fold
+ * equal would collide on disk.
+ */
+export const foldPath = (path        )         =>
+  path.normalize("NFC").toLowerCase().toUpperCase().toLowerCase().normalize("NFC");
+
+/** Refuses two `paths` that are equal after case folding. */
+export function checkNoFoldedDuplicates(paths                  , where        )       {
+  const seen = new Map                ();
+  for (const p of paths) {
+    const f = foldPath(p);
+    const other = seen.get(f);
+    if (other !== undefined)
+      refuse("entry-path", `${where}: ${JSON.stringify(other)} and ${JSON.stringify(p)} collide`);
+    seen.set(f, p);
+  }
+}

package/dist/src/scopes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The scopes rule of RFC-0046 §3: scope ids are compared exactly, with one exception. Workers
+ * Admin (`workers-scripts.admin`) covers Workers Editor (`workers-scripts.edit`), which manifests
+ * up to and including v0.9.0 name; an Editor cannot create the Workers a release installs (#225).
+ */
+export declare const IMPLIED_SCOPES: Readonly<Record<string, readonly string[]>>;
+/** The manifest's `requiredScopes` that `granted` does not hold, in the manifest's order. */
+export declare function missingScopes(manifest: {
+    readonly requiredScopes: readonly string[];
+}, granted: Iterable<string>): string[];

package/dist/src/scopes.js

@@ -0,0 +1,22 @@
+/**
+ * The scopes rule of RFC-0046 §3: scope ids are compared exactly, with one exception. Workers
+ * Admin (`workers-scripts.admin`) covers Workers Editor (`workers-scripts.edit`), which manifests
+ * up to and including v0.9.0 name; an Editor cannot create the Workers a release installs (#225).
+ */
+export const IMPLIED_SCOPES                                              = Object.freeze({
+  "workers-scripts.admin": Object.freeze(["workers-scripts.edit"]),
+});
+
+/** The manifest's `requiredScopes` that `granted` does not hold, in the manifest's order. */
+export function missingScopes(
+  manifest                                                ,
+  granted                  ,
+)           {
+  const held = new Set        ();
+  for (const s of granted) {
+    held.add(s);
+    const implied = Object.hasOwn(IMPLIED_SCOPES, s) ? IMPLIED_SCOPES[s] : undefined;
+    for (const i of implied ?? []) held.add(i);
+  }
+  return manifest.requiredScopes.filter((s) => !held.has(s));
+}

package/dist/src/tar.d.ts

@@ -0,0 +1,31 @@
+export type ByteSource = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array;
+/** The chunks of `source`, whatever its form. */
+export declare function chunksOf(source: ByteSource): AsyncGenerator<Uint8Array>;
+/** Refuses a gzip stream whose first ten bytes are not the fixed header (§7). */
+export declare function checkGzipHeader(head: Uint8Array): void;
+/**
+ * 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 declare function gunzip(source: ByteSource, max?: number): AsyncGenerator<Uint8Array>;
+export interface TarEntry {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}
+/**
+ * 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 declare function needsPax(path: string): boolean;
+/**
+ * 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 declare function ustarName(path: string): string;
+/**
+ * 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 declare function readTar(source: AsyncIterable<Uint8Array>, mtime: number, admit: (path: string, size: number) => void): AsyncGenerator<TarEntry>;