[Madraka]

What

This is a docs-only design addendum to RFC-0046, new §11, for the two consumer tools #227 asks for. They are written up here first, and the code follows once the owner accepts this. No code, contract or package changes.

• §11a @cloudhal/release-verify: the shared reference implementation of §2's steps and §7's limits.
  • Runtimes: Workers, Node 24 and browsers.
  • Runtime dependencies:
    • @noble/hashes for incremental SHA-256 where Workers' DigestStream is absent;
    • Ajv's standalone runtime helpers plus the ajv-formats date-time check, because the generated validators import them;
    • nothing constructs Ajv at runtime, and a test fails on any other import.
  • Keys: PINNED_KEYS with reduce-only trust.
  • entry-path safety: a linear scanner refuses .., ., empty segments, backslashes, control characters, overlong paths and case-fold duplicates.
  • Two-pass tarball API: the tarball's digest is checked first, then entries are yielded one at a time, each only once it is verified.
  • Stable error codes, which are public API.
  • missingScopes: exact matching plus §3's one rule, that admin covers edit.
  • releaseAssetUrls: all five assets, including the Sigstore bundle.
  • Attestation subpath: an availability check first; the exact flags with --bundle; any non-zero exit counts as failed.
• §11b cloudhal deploy --release:

  • It deploys the CLI's own version only.

  • It refuses with release-unavailable when there is no published bundle, and never falls back to a local build.

  • Revocation: it ships only after Release signing phase 2: signed keys.json and yanked.json, key expiry, KMS custody (RFC-0046 §9) #226's signed keys.json, which it fetches on every run, refusing hard when the fetch fails.

  • Order: verify, then the tarball digest, then the attestation, then extraction, then wrangler.

  • The second factor is required unless --allow-single-factor is given.

  • Extraction goes into a fresh directory, with resolve checks and exclusive create.

  • Wrangler runs with no_bundle and module types taken from the manifest.

  • What --release means (option B, the owner's choice): it installs the official standard theme of this CLI's version. It does not build the project.

  • Theme check: these are compared byte for byte with this CLI version's own starter:

    • src/, public/, astro.config.mjs and tsconfig.json;
    • root build inputs the starter does not have, which must be absent: skills/, jsconfig.json, any PostCSS config, and a postcss key in package.json.

    The list was checked against the installed Astro 7.4.7 and Vite 8.3.5. vite.config.* is not loaded, because Astro passes configFile: false. .DS_Store, Thumbs.db and desktop.ini are skipped by exact name.

    • CRLF is normalised to LF, so a Windows checkout of an unmodified starter passes.
    • Missing and extra files both count as differences.
    • On any difference, the CLI refuses and lists the files.

  • --discard-local-theme: deploys the official theme anyway and lists what is not deployed. The flag is never implied.

  • Older projects: a project whose starter files come from an older version needs the flag. cloudhal starter sync is named for later and is out of scope.

  • Config: build-class cloudhal.json keys are refused, and the flag does not cover them. These are comments.available, and media.transform unless features.mediaTransformVar is true.

    • The table classes every key and sub-key, with no fallback class. search and comments.rateLimit are deploy.
    • A type mapped over ProjectConfig and tests over OWN_KEYS and the integration's option sub-keys fail on any key left unclassed.

  • Wrangler: the installed wrangler must be at least manifest.toolchain.wrangler. The starter's ^4.158.0 range is not trusted.

  • The gh probe requires gh 2.68.0 or later, the first version with --source-ref/--source-digest, plus every flag in --help. An older gh counts as unavailable, which --allow-single-factor covers.

Open points (defaults in bold)

1. @noble/hashes for SHA-256 outside Workers (audited, zero-dependency, pinned exactly). Workers use the native crypto.DigestStream. Our own ~120-line SHA-256 would be new cryptographic code in the trust package.
2. --release takes only the CLI's own version, until §10's runtime configuration lands.
3. When gh is unavailable, the CLI refuses. --allow-single-factor continues on the release key alone and says so; it is never implied. A failed attestation is always a refusal.
4. The full-tarball test is opt-in (CLOUDHAL_RELEASE_ASSETS), in its own CI job that downloads v0.9.0. The 7.2 MB tarball is never committed. The committed fixtures are the real statement, signature and manifest.
5. What notAfter means for releases a key already signed is Release signing phase 2: signed keys.json and yanked.json, key expiry, KMS custody (RFC-0046 §9) #226's decision 6. Until then there is no key-expired code, and PINNED_KEYS carries no dates.
6. Real theme/skills values in later manifests are not part of this change. Consumers ignore the placeholders.
7. With --from, a keys.json must be fresh. It is refused when its signed issuedAt is more than 30 days old, so an old list cannot replay trust from before a revocation. This needs Release signing phase 2: signed keys.json and yanked.json, key expiry, KMS custody (RFC-0046 §9) #226's format to carry issuedAt; online runs always fetch the current list.

Revised done-when for #227

The issue's "cloudhal deploy --release 0.9.x" can't be met: CLI 0.9.x has no --release, and --release takes only the CLI's own version. Proposed instead:

• @cloudhal/release-verify is published, with provenance, from release.yml. Its tests pass on the real v0.9.0 statement, signature and manifest: a flipped byte, a wrong key, a revoked key, a wrong version and a wrong channel are all refused. The opt-in CI job verifies the real v0.9.0 tarball.

• cloudhal deploy --release in the first CLI version that ships it deploys that version's verified bundle. It refuses:

  • a tampered or unverified bundle;
  • a missing bundle (release-unavailable);
  • a project whose src/, public/, astro.config.mjs or skills/ differ from the starter, unless --discard-local-theme is given;
  • a keys.json that can't be fetched or doesn't verify.

  It depends on Release signing phase 2: signed keys.json and yanked.json, key expiry, KMS custody (RFC-0046 §9) #226's keys.json.

Owner steps when the code lands

• Publish a placeholder @cloudhal/[email protected] (README only, --tag placeholder), then npm deprecate it.
• Add the trusted-publisher entry (release.yml, the npm-publish environment). The first real version then comes from release.yml with --provenance. A version published by hand would have none, and planPublish would skip it afterwards.
• The package joins the fixed group in .changeset/config.json (ADR-0013); that edit is part of the code PR.

Notes

• The §3 scopes rule that missingScopes cites came in with fix(release): require workers-scripts.admin in the release manifest (#225) #229. This branch is rebased onto main after fix(release): require workers-scripts.admin in the release manifest (#225) #229 merged (c41a4d7).

Refs #227

🤖 Generated with Claude Code