@cloudhal/release-verify 0.0.0-stage → 0.10.1

package/dist/src/documents.js

@@ -0,0 +1,167 @@
+/**
+ * The statement and the manifest (RFC-0046 §2 steps 1 to 5): sizes, the Ed25519 signature with a
+ * trusted key, the binding to the request (invariant 7), both precompiled validators, the
+ * invariants the schemas cannot express, and the manifest's listings (paths and §7 limits).
+ */
+import { refuse } from "./errors.js";
+                                                                       
+                                                                         
+import { validateReleaseManifest, validateReleaseStatement } from "./generated/validators.js";
+import { channelOf, LIMITS, MANIFEST_FILE, SIGNATURE_FILE, tarballName } from "./limits.js";
+import { checkNoFoldedDuplicates, checkPath } from "./paths.js";
+
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/** The JSON document in `bytes`, or the refusal `code`. */
+export function parseJson(
+  bytes            ,
+  code                                          ,
+)          {
+  try {
+    return JSON.parse(utf8.decode(bytes));
+  } catch {
+    return refuse(
+      code,
+      `${code === "statement-invalid" ? "the statement" : "the manifest"} is not UTF-8 JSON`,
+    );
+  }
+}
+
+const firstError = (errors                                                      ) =>
+  errors?.[0] ? `${errors[0].instancePath || "/"} ${errors[0].message ?? ""}`.trim() : "invalid";
+
+/** §2 step 4: the schema, then invariants 1, 2, 3 and 6. */
+export function checkStatementDoc(doc         , serialisedBytes        )                   {
+  if (!validateReleaseStatement(doc))
+    refuse("statement-invalid", `the statement: ${firstError(validateReleaseStatement.errors)}`);
+  const s = doc;
+  if (s.manifest.name !== MANIFEST_FILE)
+    refuse("statement-invalid", `statement.manifest.name is not ${MANIFEST_FILE}`);
+  if (s.tarball.name !== tarballName(s.version))
+    refuse("statement-invalid", `statement.tarball.name is not ${tarballName(s.version)}`);
+  if (s.manifest.bytes > LIMITS.manifestBytes)
+    refuse("statement-invalid", `the manifest is above ${LIMITS.manifestBytes} bytes`);
+  if (s.channel !== channelOf(s.version))
+    refuse("statement-invalid", `channel ${s.channel} does not match version ${s.version}`);
+  if (serialisedBytes > LIMITS.statementBytes)
+    refuse("statement-too-large", `the statement is above ${LIMITS.statementBytes} bytes`);
+  return s;
+}
+
+/** §2 step 3 (invariant 7): the statement is for the version and channel that were asked for. */
+export function checkRequested(doc         , version        , channel                    )       {
+  const s = (doc ?? {})                                            ;
+  if (s.version !== version)
+    refuse("wrong-version", `the statement is for ${String(s.version)}, not ${version}`);
+  const want = channel ?? channelOf(version);
+  if (s.channel !== want)
+    refuse("wrong-channel", `the statement is for channel ${String(s.channel)}, not ${want}`);
+}
+
+/** §2 step 5 after the digest: the schema, invariants 4 and 5, the signature form, planVersion. */
+export function checkManifestDoc(
+  doc         ,
+  statement                  ,
+  planVersion        ,
+)                  {
+  if (!validateReleaseManifest(doc))
+    refuse("manifest-invalid", `the manifest: ${firstError(validateReleaseManifest.errors)}`);
+  const m = doc;
+  if (m.signing.keyId !== statement.signing.keyId)
+    refuse("statement-manifest-mismatch", "the statement and the manifest name different keys");
+  for (const k of ["version", "channel", "securityRelease", "commit", "createdAt"]         )
+    if (m[k] !== statement[k])
+      refuse("statement-manifest-mismatch", `the statement's ${k} is not the manifest's`);
+  // A project key never signs the legacy manifest.sig form (§1).
+  if (m.signing.signature !== SIGNATURE_FILE)
+    refuse("manifest-invalid", `the manifest does not name ${SIGNATURE_FILE}`);
+  if (m.planVersion > planVersion)
+    refuse("plan-version-unsupported", `planVersion ${m.planVersion} is above ${planVersion}`);
+  checkListings(m);
+  return m;
+}
+
+                                      
+
+/** One part the manifest lists, by its tar path. */
+                             
+                                 
+                                                
+                                                                                   
+                        
+                         
+                         
+                          
+ 
+
+/** Every part the manifest lists, keyed by its tar path (`site/modules/x.mjs`, …). */
+export function listedParts(m                 )                          {
+  const out = new Map                    ();
+  for (const worker of ["site", "admin"]         ) {
+    const w = m.workers[worker];
+    for (const mod of w.modules)
+      out.set(`${worker}/modules/${mod.path}`, { worker, kind: "module", ...mod });
+    for (const f of w.assets.files)
+      out.set(`${worker}/assets${f.path}`, {
+        worker,
+        kind: "asset",
+        path: f.path,
+        bytes: f.bytes,
+        sha256: f.sha256,
+      });
+  }
+  if (m.starter.kind === "bundle") {
+    const s = m.starter;
+    out.set(s.path, {
+      worker: null,
+      kind: "starter",
+      path: s.path,
+      bytes: s.bytes,
+      sha256: s.sha256,
+    });
+  }
+  return out;
+}
+
+/** One Worker's listings: module and asset paths, `mainModule`, folded names and §7's limits. */
+function checkWorker(m                 , worker        )         {
+  const w = m.workers[worker];
+  for (const mod of w.modules) {
+    checkPath(mod.path, "module", `${worker} module`);
+    if (mod.bytes > LIMITS.partBytes)
+      refuse("limit-exceeded", `${worker} module ${mod.path} is above ${LIMITS.partBytes} bytes`);
+  }
+  checkNoFoldedDuplicates(
+    w.modules.map((x) => x.path),
+    `${worker} modules`,
+  );
+  checkPath(w.mainModule, "module", `${worker} mainModule`);
+  if (!w.modules.some((x) => x.path === w.mainModule))
+    refuse("manifest-invalid", `${worker} mainModule ${w.mainModule} is not a listed module`);
+  const files = w.assets.files;
+  if (files.length > LIMITS.assetsPerWorker)
+    refuse("limit-exceeded", `${worker}: more than ${LIMITS.assetsPerWorker} assets`);
+  for (const f of files) {
+    checkPath(f.path, "asset", `${worker} asset`);
+    if (f.bytes > LIMITS.assetBytes)
+      refuse("limit-exceeded", `${worker} asset ${f.path} is above ${LIMITS.assetBytes} bytes`);
+  }
+  checkNoFoldedDuplicates(
+    files.map((x) => x.path),
+    `${worker} assets`,
+  );
+  return w.modules.length + files.length;
+}
+
+/** Paths (§11a) and §7's limits over every listing, before the tarball is read. */
+function checkListings(m                 )       {
+  let parts = checkWorker(m, "site") + checkWorker(m, "admin");
+  if (m.starter.kind === "bundle") {
+    checkPath(m.starter.path, "entry", "starter");
+    if (m.starter.bytes > LIMITS.partBytes)
+      refuse("limit-exceeded", `the starter is above ${LIMITS.partBytes} bytes`);
+    parts++;
+  }
+  if (parts > LIMITS.tarEntries)
+    refuse("limit-exceeded", `the manifest lists more than ${LIMITS.tarEntries} parts`);
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The refusals of RFC-0046 §11a. Each `code` is public API: consumers branch on it, so a code is
+ * never renamed or reused. There is no warning level: every one of them refuses the release.
+ */
+export declare const ERROR_CODES: readonly ["statement-too-large", "signature-size", "key-unknown", "key-revoked", "signature-invalid", "wrong-version", "wrong-channel", "statement-invalid", "manifest-mismatch", "manifest-invalid", "statement-manifest-mismatch", "plan-version-unsupported", "tarball-mismatch", "tar-format", "entry-path", "entry-unlisted", "entry-mismatch", "entry-missing", "limit-exceeded", "key-expired", "yanked", "key-list-invalid", "key-list-expired", "yank-list-invalid", "stale-yank-list"];
+export type ReleaseVerifyErrorCode = (typeof ERROR_CODES)[number];
+export declare class ReleaseVerifyError extends Error {
+    readonly name = "ReleaseVerifyError";
+    readonly code: ReleaseVerifyErrorCode;
+    constructor(code: ReleaseVerifyErrorCode, message: string);
+}
+/** Throws the refusal `code`; typed `never` so checks read as guards. */
+export declare function refuse(code: ReleaseVerifyErrorCode, message: string): never;

package/dist/src/errors.js

@@ -0,0 +1,48 @@
+/**
+ * The refusals of RFC-0046 §11a. Each `code` is public API: consumers branch on it, so a code is
+ * never renamed or reused. There is no warning level: every one of them refuses the release.
+ */
+export const ERROR_CODES = [
+  "statement-too-large",
+  "signature-size",
+  "key-unknown",
+  "key-revoked",
+  "signature-invalid",
+  "wrong-version",
+  "wrong-channel",
+  "statement-invalid",
+  "manifest-mismatch",
+  "manifest-invalid",
+  "statement-manifest-mismatch",
+  "plan-version-unsupported",
+  "tarball-mismatch",
+  "tar-format",
+  "entry-path",
+  "entry-unlisted",
+  "entry-mismatch",
+  "entry-missing",
+  "limit-exceeded",
+  // RFC-0046 §9 (#226): expiry, the key list and the yank list.
+  "key-expired",
+  "yanked",
+  "key-list-invalid",
+  "key-list-expired",
+  "yank-list-invalid",
+  "stale-yank-list",
+]         ;
+
+                                                                  
+
+export class ReleaseVerifyError extends Error {
+                    name = "ReleaseVerifyError";
+           code                        ;
+  constructor(code                        , message        ) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** Throws the refusal `code`; typed `never` so checks read as guards. */
+export function refuse(code                        , message        )        {
+  throw new ReleaseVerifyError(code, message);
+}

package/dist/src/generated/release-keys.d.ts

@@ -0,0 +1,67 @@
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ * Source: packages/core-contracts/schemas/release-{manifest,statement,keys,yank-list}.schema.json
+ * (run `pnpm gen`; packages/release-verify/scripts/gen-validators.ts)
+ */
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ * Source: packages/core-contracts/schemas/*.schema.json  (run `pnpm gen`)
+ */
+/**
+ * Version of this contract. Readers reject unknown versions; migrations move documents forward one version at a time.
+ *
+ * This interface was referenced by `ReleaseKeys`'s JSON-Schema
+ * via the `definition` "SchemaVersion".
+ */
+export type SchemaVersion = 1;
+/**
+ * RFC 3339 / ISO 8601 instant in UTC.
+ *
+ * This interface was referenced by `ReleaseKeys`'s JSON-Schema
+ * via the `definition` "Timestamp".
+ */
+export type Timestamp = string;
+/**
+ * This interface was referenced by `ReleaseKeys`'s JSON-Schema
+ * via the `definition` "KeyId".
+ */
+export type KeyId = string;
+/**
+ * cloudhal.release-keys@1 (RFC-0046 §9): the root-signed list of Cloudhal's release and yank keys, published as keys.json at https://cloudhal.dev/.well-known/cloudhal/keys.json next to keys.json.sig (a raw 64-byte Ed25519 signature by the offline root over the exact bytes). A consumer uses it only to reduce trust in the keys it pins: revoke, mark retiring, narrow a validity window; it never adds a key. Canonical bytes as for the release statement.
+ */
+export interface ReleaseKeys {
+    schemaVersion: SchemaVersion;
+    format: "cloudhal.release-keys@1";
+    issuedAt: Timestamp;
+    /**
+     * RFC 3339 / ISO 8601 instant in UTC.
+     */
+    expires: string;
+    signing: {
+        /**
+         * The root key that signed this list.
+         */
+        keyId: string;
+        algorithm: "Ed25519";
+        signature: "keys.json.sig";
+    };
+    /**
+     * @maxItems 64
+     */
+    keys: ListedKey[];
+}
+/**
+ * This interface was referenced by `ReleaseKeys`'s JSON-Schema
+ * via the `definition` "ListedKey".
+ */
+export interface ListedKey {
+    keyId: KeyId;
+    /**
+     * The raw 32-byte Ed25519 public key, base64.
+     */
+    publicKey: string;
+    role: "release" | "yank";
+    notBefore: Timestamp;
+    notAfter: Timestamp;
+    status: "active" | "retiring" | "revoked";
+}

package/dist/src/generated/release-keys.js

@@ -0,0 +1,72 @@
+/* eslint-disable */
+/* biome-ignore-all lint: generated */
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ * Source: packages/core-contracts/schemas/release-{manifest,statement,keys,yank-list}.schema.json
+ * (run `pnpm gen`; packages/release-verify/scripts/gen-validators.ts)
+ */
+/* biome-ignore-all lint: generated */
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ * Source: packages/core-contracts/schemas/*.schema.json  (run `pnpm gen`)
+ */
+
+/**
+ * Version of this contract. Readers reject unknown versions; migrations move documents forward one version at a time.
+ *
+ * This interface was referenced by `ReleaseKeys`'s JSON-Schema
+ * via the `definition` "SchemaVersion".
+ */
+                              
+/**
+ * RFC 3339 / ISO 8601 instant in UTC.
+ *
+ * This interface was referenced by `ReleaseKeys`'s JSON-Schema
+ * via the `definition` "Timestamp".
+ */
+                               
+/**
+ * This interface was referenced by `ReleaseKeys`'s JSON-Schema
+ * via the `definition` "KeyId".
+ */
+                           
+
+/**
+ * cloudhal.release-keys@1 (RFC-0046 §9): the root-signed list of Cloudhal's release and yank keys, published as keys.json at https://cloudhal.dev/.well-known/cloudhal/keys.json next to keys.json.sig (a raw 64-byte Ed25519 signature by the offline root over the exact bytes). A consumer uses it only to reduce trust in the keys it pins: revoke, mark retiring, narrow a validity window; it never adds a key. Canonical bytes as for the release statement.
+ */
+                              
+                               
+                                    
+                      
+     
+                                        
+     
+                  
+            
+       
+                                          
+       
+                  
+                         
+                               
+    
+     
+                 
+     
+                    
+ 
+/**
+ * This interface was referenced by `ReleaseKeys`'s JSON-Schema
+ * via the `definition` "ListedKey".
+ */
+                            
+               
+     
+                                                
+     
+                    
+                           
+                       
+                      
+                                            
+ 

package/dist/src/generated/release-manifest.d.ts

@@ -0,0 +1,211 @@
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ * Source: packages/core-contracts/schemas/release-{manifest,statement,keys,yank-list}.schema.json
+ * (run `pnpm gen`; packages/release-verify/scripts/gen-validators.ts)
+ */
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ * Source: packages/core-contracts/schemas/*.schema.json  (run `pnpm gen`)
+ */
+/**
+ * Version of this contract. Readers reject unknown versions; migrations move documents forward one version at a time.
+ *
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "SchemaVersion".
+ */
+export type SchemaVersion = 1;
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "CloudhalVersion".
+ */
+export type CloudhalVersion = string;
+/**
+ * RFC 3339 / ISO 8601 instant in UTC.
+ *
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "Timestamp".
+ */
+export type Timestamp = string;
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "MigrationName".
+ */
+export type MigrationName = string;
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "BindingName".
+ */
+export type BindingName = string;
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "Sha256Hex".
+ */
+export type Sha256Hex = string;
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "SecretName".
+ */
+export type SecretName = "BETTER_AUTH_SECRET" | "MCP_STATE_KEY" | "CLOUDHAL_PREVIEW_SECRET" | "CLOUDHAL_PURGE_TOKEN" | "CLOUDHAL_DEPLOY_TOKEN" | "CLOUDHAL_SETUP_TOKEN" | "CLOUDHAL_COMMENTS_KEY";
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "ScopeId".
+ */
+export type ScopeId = string;
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "Capability".
+ */
+export type Capability = "account" | "workers" | "d1" | "r2" | "analytics" | "domains";
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "SiteId".
+ */
+export type SiteId = string;
+/**
+ * cloudhal.release-manifest@1 (RFC-0046): the manifest of one Cloudhal release bundle, published as the release asset manifest.json next to the gzip tarball cloudhal-release-<version>.tar.gz. A project release is signed through release-statement.json, which pins this file's SHA-256 and size (signing.signature = release-statement.sig); the legacy form manifest.sig, a raw 64-byte Ed25519 signature over these exact bytes, is for development keys only. It describes every built Worker module and static asset by size and SHA-256, the binding templates, feature levels, migration range and rollback facts a remote deployer needs to install, update or refuse a version without running a build. Portable on purpose: it references common only for SchemaVersion and Timestamp; every other definition is local.
+ */
+export interface ReleaseManifest {
+    schemaVersion: SchemaVersion;
+    format: "cloudhal.release-manifest@1";
+    version: CloudhalVersion;
+    channel: "stable" | "next";
+    securityRelease: boolean;
+    commit: string;
+    createdAt: Timestamp;
+    contracts: {
+        schemaVersion: 1;
+    };
+    levels: {
+        schedules: number;
+        gates: number;
+    };
+    migrations: {
+        first: MigrationName;
+        last: MigrationName;
+        count: number;
+        /**
+         * @minItems 1
+         */
+        names: [MigrationName, ...MigrationName[]];
+        compatibleWithPrevious: boolean;
+    };
+    durableObjects: {
+        bindings: {
+            name: BindingName;
+            className: string;
+            migration: string;
+        }[];
+        lifecycleChange: boolean;
+    };
+    runtime: {
+        compatibilityDate: string;
+        compatibilityFlags: string[];
+    };
+    toolchain: {
+        [k: string]: string | undefined;
+    };
+    theme: {
+        name: string;
+        version: string;
+        blockTypes: string[];
+        settingsSha256: Sha256Hex;
+        designSha256: Sha256Hex;
+    };
+    skills: {
+        name: string;
+        sha256: Sha256Hex;
+    }[];
+    workers: {
+        site: WorkerArtifact;
+        admin: WorkerArtifact;
+    };
+    bindingTemplates: {
+        site: BindingTemplate;
+        admin: BindingTemplate;
+    };
+    requiredScopes: ScopeId[];
+    optionalScopes: ScopeId[];
+    requiredCapabilities: Capability[];
+    optionalCapabilities: Capability[];
+    starter: {
+        kind: "admin-api";
+    } | {
+        kind: "bundle";
+        path: string;
+        bytes: number;
+        sha256: Sha256Hex;
+        siteId: SiteId;
+    };
+    features: {
+        adminSitesAcceptsSiteId: boolean;
+        healthReportsVersion: boolean;
+        mediaTransformVar: boolean;
+        [k: string]: boolean | undefined;
+    };
+    planVersion: number;
+    signing: {
+        keyId: string;
+        algorithm: "Ed25519";
+        signature: "manifest.sig" | "release-statement.sig";
+    };
+}
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "WorkerArtifact".
+ */
+export interface WorkerArtifact {
+    mainModule: string;
+    /**
+     * @minItems 1
+     */
+    modules: [
+        {
+            path: string;
+            type: "esm" | "cjs" | "wasm" | "text" | "data";
+            bytes: number;
+            sha256: Sha256Hex;
+        },
+        ...{
+            path: string;
+            type: "esm" | "cjs" | "wasm" | "text" | "data";
+            bytes: number;
+            sha256: Sha256Hex;
+        }[]
+    ];
+    assets: {
+        count: number;
+        bytes: number;
+        /**
+         * @maxItems 20000
+         */
+        files: {
+            path: string;
+            bytes: number;
+            sha256: Sha256Hex;
+            assetHash: string;
+            contentType: string;
+        }[];
+        headers: string;
+        config?: {
+            not_found_handling?: "none" | "404-page" | "single-page-application";
+            run_worker_first?: string[];
+        };
+    };
+    bindingTemplate?: "site" | "admin";
+}
+/**
+ * This interface was referenced by `ReleaseManifest`'s JSON-Schema
+ * via the `definition` "BindingTemplate".
+ */
+export interface BindingTemplate {
+    bindings: {
+        name: BindingName;
+        type: "d1" | "r2_bucket" | "assets" | "service" | "durable_object_namespace" | "analytics_engine" | "analytics_sql" | "ratelimit" | "ai_search" | "send_email" | "ai" | "browser";
+        required: boolean;
+        aliases?: BindingName[];
+    }[];
+    vars: BindingName[];
+    secrets: SecretName[];
+    cache?: boolean;
+    cron?: string;
+}