alpha-gate 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+Notable changes to Alpha Gate (the tool). The deployed instance's daily self-update check polls the
+npm registry's `latest` for this package and compares it against its `TOOL_VERSION`; the
+dashboard/Settings link here for notes. `release.json` is only the static-manifest fallback for
+`$UPDATE_MANIFEST_URL` overrides — keep its `latest` in sync with `package.json`'s `version`.
+
+## 0.1.0
+
+- **Back office redesign** ("quiet instrument"): the serving map makes the resolver visible; the
+  Users list answers "what does each tester get next?"; confirm-name-and-return feedback loop;
+  reversible revoke (Reactivate); searchable comboboxes; light/system/dark theme toggle.
+- **Publishing simplified to one command**: `./publish.sh <artifact>` handles `.dmg` and signed
+  `.app.zip`, links channels by name, auto-picks the instance, pre-checks the build number, and
+  handles the >90 MB register path itself. (`publish-dmg.sh` and `ci-publish.sh` removed.)
+- **Storage lifecycle**: per-build size + bucket total on the Builds page; purge a withdrawn build's
+  archive to reclaim R2 space (the record is kept).
+- **Deploy**: remembers email/Access inputs across re-runs (no silent revert); derives the Access
+  team domain from the enablement redirect; reason-bearing admin 403; real `--help`.
+- **Security**: service tokens are scoped to the publish surface only (decision 0006 enforced).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandr Ivanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# Alpha Gate
+
+A lightweight, self-hosted distribution gate for a notarized macOS app updated via **Sparkle**. It gates
+downloads and the per-user Sparkle update feed behind a token, manages clients / builds / release
+channels / pins / rollbacks from an admin back office behind **Cloudflare Access**, and runs entirely on
+**Cloudflare (Workers + D1 + R2)** within the free tier — no custom domain, deployable to any account from
+one script, with many isolated instances per account.
+
+> Status: feature-complete and tested — 376 worker + 93 deploy-CLI tests, all offline; `tsc` (both
+> configs) and Biome clean.
+
+## Features
+
+- **One private link per user** (`/get?token=`) → download + an `myapp://activate` deep link + the
+  pasteable key. The token is the only credential; users never log in.
+- **Per-request Sparkle appcast** generated from the database — gating, re-download, channels, pinning,
+  rollback, and revocation notices all fall out of one resolver.
+- **Release channels, pinning, and rollback** (roll-forward, since Sparkle can't downgrade).
+- **Publish a signed `.dmg` or `.zip`** from a one-command script, CI, or the browser — all converging on
+  one upload endpoint; the Worker never signs and never holds a signing key.
+- **Admin behind Cloudflare Access** (one-time-PIN email allowlist) with defense-in-depth JWT
+  verification, and a **tamper-evident, hash-chained audit log**.
+- **Free-tier**: D1 + R2 + Workers, no custom domain. Copy-paste invites by default; Cloudflare email is
+  an optional, paid add-on (it needs a real domain).
+
+## How it works
+
+The same code deploys **twice**, switched by a `ROLE` var, onto two `workers.dev` hostnames that share one
+D1 database and one R2 bucket:
+
+```
+   macOS app ──► /appcast?token=   ┌─────────────────────────┐
+   (Sparkle)    /download?token=   │  App Worker (public)     │──┐
+                                   │  • token gate, resolver  │  │   ┌── D1 (clients, builds,
+   User ──────► /get?token=        │  • binary stream from R2 │  ├──►│   channels, access_log, audit)
+   (browser)    landing page       └─────────────────────────┘  │   └── R2 (build archives, branding)
+                                                                 │
+   Admin ─────► /admin             ┌─────────────────────────┐  │
+   (Cloudflare  [Cloudflare Access]│  Admin Worker (gated)    │──┘
+    Access)     ───────────────────│  • clients/builds/channels, validates the Access JWT
+                                   └─────────────────────────┘
+```
+
+Why two Workers: on `workers.dev`, Cloudflare Access protects an entire hostname, so the public routes
+(which Sparkle must reach) and the gated admin must live on separate hostnames. Both are host-agnostic
+(they derive their origin from the request), so they run on bare `*.workers.dev` URLs with no config. Full
+rationale and the invariants behind the design: [`docs/PRINCIPLES.md`](docs/PRINCIPLES.md).
+
+## Quick start
+
+From npm — no clone, a pinned versioned release:
+
+```bash
+npx wrangler login                       # once, interactive
+npx alpha-gate deploy --instance myalpha # provision D1 + R2, deploy both Workers (idempotent)
+npx alpha-gate publish MyApp.dmg --channel beta
+```
+
+Or from a git clone (contributors, or to run unreleased `main`):
+
+```bash
+git clone <your-fork> alpha-gate && cd alpha-gate && npm install
+./deploy/deploy.sh --instance myalpha    # the deploy/*.sh wrappers = the same CLI
+```
+
+Then lock the admin behind Cloudflare Access and re-run deploy with your team domain + AUD. The full,
+step-by-step path — install, prepare the account, deploy, Access, verify — starts at
+**[docs/setup/install.md](docs/setup/install.md)**.
+
+To ship builds: wire Sparkle into your app ([Swift](docs/integrate/sparkle-swift.md) or
+[Go](docs/integrate/sparkle-go.md)), [add users](docs/operate/add-users.md), and
+[publish](docs/operate/publish.md). Once set up, publishing is one command:
+
+```bash
+./publish.sh MyApp.dmg --channel beta
+```
+
+It reads the version from the app, signs with Sparkle's `sign_update`, links the channel by name, and
+picks the instance automatically when only one is deployed.
+
+## Develop
+
+Everything runs **offline** — no Cloudflare account, no network — inside the Workers runtime via
+`@cloudflare/vitest-pool-workers` (Miniflare simulates D1/R2/cron with isolated per-test storage).
+
+```bash
+npm run check     # the full gate: biome + tsc (both configs) + tests
+npm test          # tests only (offline)
+./deploy/dev.sh   # run BOTH Workers locally, seeded (app :8787, admin :8788); --role app|admin for one
+```
+
+Conventions, architecture, and how to add a feature: [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Documentation
+
+| Doc | What |
+|---|---|
+| [`docs/README.md`](docs/README.md) | The documentation index: setup, integrate, operate, maintain. |
+| [`docs/PRINCIPLES.md`](docs/PRINCIPLES.md) | The durable architecture & product principles and hard constraints. |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Developer guide: conventions, architecture, testing, adding a feature. |
+| [`CLAUDE.md`](CLAUDE.md) | Working guidance for AI assistants in this repo. |
+
+## Project structure
+
+```
+src/
+  worker.ts          # entrypoint — reads env.ROLE, mounts app|admin, exports fetch + scheduled
+  core/              # PURE logic (no I/O): resolver, no-build, appcast XML, audit hash-chain, tokens, version
+  views/             # pure hono/jsx pages (public + admin/, incl. injected client scripts)
+  db/                # raw D1 prepared statements, one module per table (no ORM)
+  r2/                # R2 archive + branding access (never presigns)
+  auth/              # token gate + Cloudflare Access JWT verifier
+  services/          # audit, email, self-update, anchor, branding (orchestration over db/r2/core)
+  routes/{app,admin} # Hono handlers; deps injected, never bindings directly
+  deploy/            # deploy/teardown/dev CLI: core/ (pure) + seams/ (wrangler,fs,io,clock) + commands/
+migrations/          # 0001–0010 D1 schema (SQL)
+deploy/              # thin bash wrappers (deploy.sh, teardown.sh, dev.sh) → the TS CLI; backup.sh (D1 dump)
+publish.sh           # ONE publish command (dmg | .app.zip | CI); .github/workflows/ has a sample
+bin/alpha-gate.mjs   # the npm entrypoint: npx alpha-gate deploy|dev|publish|backup|teardown
+test/                # unit/ integration/ cuj/ + support/ (offline vitest-pool-workers)
+docs/                # the docs: setup/ integrate/ operate/ maintain/ + PRINCIPLES (index: docs/README.md)
+site/                # the marketing page (static HTML + screenshots; see site/README.md)
+```
+
+## Security notes
+
+- The token travels in URLs, so it appears in Cloudflare's own request logs (accepted for a private
+  alpha); `/get` sets `Referrer-Policy: no-referrer` and bad tokens get a generic 404 (no existence leak).
+- The Sparkle feed is **not** signed (`SURequireSignedFeed` off) — incompatible with per-user dynamic
+  feeds; the per-archive EdDSA signature still blocks tampered binaries.
+- The admin JWT verifier is **fail-closed** (RS256-pinned, `aud`/`iss` + expiry checked); service tokens
+  are accepted only on the upload/register routes.
+- Admin actions are recorded in a **hash-chained, daily-anchored** audit log; pair it with Cloudflare's
+  Access and Audit logs for full who/when.
+- Account-level caveat: anyone with Cloudflare dashboard access to the account can read D1/R2 directly;
+  install into a dedicated account if that isolation matters.
+
+More on the security model and the invariants: [`docs/PRINCIPLES.md`](docs/PRINCIPLES.md).

package/bin/alpha-gate.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// The `alpha-gate` command (npm bin). One entry point over the two implementation styles:
+//   deploy | dev | teardown  → the TypeScript CLI (src/deploy/cli.ts), run via tsx.
+//   publish | backup         → the bash scripts (publish.sh, deploy/backup.sh) — macOS publish tools.
+// Everything resolves from the package root (this file's dir), so it works from an npx cache install.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const [command, ...rest] = process.argv.slice(2);
+
+const HELP = `alpha-gate — self-hosted Cloudflare distribution gate for a Sparkle-updated macOS app
+
+usage: alpha-gate <command> [options]
+
+  deploy     provision + deploy an instance (D1 + R2 + both Workers); re-run to update
+  dev        run locally on Miniflare (both Workers), no Cloudflare account
+  publish    publish a signed build (.dmg | .app.zip) — macOS
+  backup     dump an instance's D1 database to a .sql file
+  teardown   archive + destroy an instance
+
+Run \`alpha-gate <command> --help\` for a command's options.
+State lives in ~/.alpha-gate (override with $ALPHA_GATE_HOME).`;
+
+if (command === undefined || command === "--help" || command === "-h") {
+  console.log(HELP);
+  process.exit(command === undefined ? 1 : 0);
+}
+
+// tsx is a dependency; resolve its bin from the package's node_modules so we don't rely on `npx`.
+function runTsxCli(args) {
+  const tsxBin = path.join(
+    ROOT,
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "tsx.cmd" : "tsx",
+  );
+  const cli = path.join(ROOT, "src", "deploy", "cli.ts");
+  const bin = existsSync(tsxBin) ? tsxBin : "tsx";
+  return spawn(bin, [cli, ...args], { stdio: "inherit", cwd: ROOT });
+}
+
+function runScript(scriptRelPath, args) {
+  return spawn("bash", [path.join(ROOT, scriptRelPath), ...args], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+}
+
+let child;
+switch (command) {
+  case "deploy":
+  case "dev":
+  case "teardown":
+    child = runTsxCli([command, ...rest]);
+    break;
+  case "publish":
+    child = runScript("publish.sh", rest);
+    break;
+  case "backup":
+    child = runScript("deploy/backup.sh", rest);
+    break;
+  default:
+    console.error(`unknown command: ${command}\n`);
+    console.error(HELP);
+    process.exit(1);
+}
+
+child.on("exit", (code) => process.exit(code ?? 0));
+child.on("error", (err) => {
+  console.error(`failed to run '${command}': ${err.message}`);
+  process.exit(1);
+});

package/deploy/backup.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Back up an Alpha Gate instance's D1 database to a timestamped .sql dump — the same export teardown
+# takes before destroying, minus the destruction. Run it on a schedule (cron/launchd) or before a
+# risky change. R2 archives are NOT included: they're large and re-uploadable by re-publishing; this
+# captures the irreplaceable state (clients + their tokens, builds, channels, logs, audit chain).
+#
+#   ./deploy/backup.sh --instance myalpha [--out ./backups]
+#
+# The dump contains LIVE per-user tokens — store it somewhere private (NOT the repo) and delete old
+# copies. Restore into a fresh instance:  wrangler d1 execute <db> --remote --file <dump>.sql
+# (see docs/maintain/backup.md → Backup & recovery).
+set -euo pipefail
+
+INSTANCE=""; OUT=""
+need() { [ "$#" -ge 2 ] || { echo "missing value for $1" >&2; exit 1; }; }
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --instance) need "$@"; INSTANCE="$2"; shift 2 ;;
+    --out)      need "$@"; OUT="$2"; shift 2 ;;
+    -h|--help)  sed -n '2,12p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+[ -n "${INSTANCE}" ] || { echo "usage: ./deploy/backup.sh --instance <slug> [--out <dir>]" >&2; exit 1; }
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=deploy/lib/statedir.sh
+. "${ROOT}/deploy/lib/statedir.sh"
+RES="alpha-gate-${INSTANCE}"
+OUT="${OUT:-$(alpha_gate_state_dir "${ROOT}")}"
+mkdir -p "${OUT}"
+STAMP="$(date -u +%Y%m%d-%H%M%S)"
+FILE="${OUT}/${INSTANCE}-${STAMP}.sql"
+
+echo "Exporting ${RES} → ${FILE} (this reads the REMOTE database)…" >&2
+if npx wrangler d1 export "${RES}" --remote --output "${FILE}"; then
+  BYTES="$(wc -c < "${FILE}" | tr -d ' ')"
+  echo "✓ backed up ${BYTES} bytes to ${FILE}" >&2
+  echo "  This dump contains live tokens — keep it private and prune old copies." >&2
+  echo "${FILE}"
+else
+  echo "backup failed — is wrangler logged in (npx wrangler login) and is '${INSTANCE}' deployed?" >&2
+  rm -f "${FILE}"
+  exit 1
+fi

package/deploy/deploy.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Provision and deploy one Alpha Gate instance (§19). Thin wrapper → the TypeScript deploy CLI
+# (src/deploy/cli.ts), which replaced the hand-rolled bash orchestration: it shells out to wrangler
+# with typed argv (no scraping/quoting surface), validates every command's output, is idempotent and
+# resumable, and is unit-tested. The flags and UX are unchanged:
+#
+#   ./deploy/deploy.sh --instance <slug> [--app-name … --activate-scheme … --blurb … --accent …]
+#                      [--access-team-domain … --access-aud …]
+#                      [--email-provider none|cloudflare --email-from …] [--yes] [--dry-run]
+#
+# First init is guided (prompts for app config when interactive); Access is two-phase (it shows the
+# dashboard step, waits, then collects the AUD). Requires `npm install` once (provides tsx + wrangler).
+# To roll back to the previous pure-bash implementation: `git log -- deploy/deploy.sh`.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# Run the local tsx binary directly, not via `npx` (avoids a registry round-trip and a nested
+# npm-exec deadlock when the CLI shells out to wrangler — see deploy/dev.sh). npx tsx is the fallback.
+TSX="${ROOT}/node_modules/.bin/tsx"
+[ -x "${TSX}" ] && exec "${TSX}" "${ROOT}/src/deploy/cli.ts" deploy "$@"
+exec npx tsx "${ROOT}/src/deploy/cli.ts" deploy "$@"

package/deploy/dev.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Run Alpha Gate LOCALLY (§23 local surface) — Miniflare-backed D1 + R2, no Cloudflare account. Thin
+# wrapper → the TypeScript CLI (src/deploy/cli.ts). By default it starts BOTH Workers so the whole
+# system is live from one command: the App on :8787 and the gated admin on :8788 (the dev-only auth
+# shim, src/dev/admin-entry.ts; DEV_ADMIN=1, never deployable).
+#
+#   ./deploy/dev.sh                       # both Workers (app :8787, admin :8788)
+#   ./deploy/dev.sh --role app            # just the App Worker
+#   ./deploy/dev.sh --role admin --port 8788   # just the admin
+#   ./deploy/dev.sh --reset --no-seed     # flags pass through
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# Run the local tsx binary DIRECTLY, not via `npx`: `npx` can stall on a registry round-trip, and
+# running under npx/npm-exec makes the child `npx wrangler` a NESTED npm-exec that can deadlock on
+# npm's lock — a silent hang where `wrangler dev` never binds. Fall back to `npx tsx` only when the
+# local binary is missing (run `npm install`).
+TSX="${ROOT}/node_modules/.bin/tsx"
+CLI=(npx tsx "${ROOT}/src/deploy/cli.ts")
+[ -x "${TSX}" ] && CLI=("${TSX}" "${ROOT}/src/deploy/cli.ts")
+
+# A picked role (or --help) is a single-Worker run — hand straight to the CLI, unchanged behavior.
+for arg in "$@"; do
+  case "$arg" in
+    --role|-h|--help) exec "${CLI[@]}" dev "$@" ;;
+  esac
+done
+
+# Default: BOTH Workers. The app runs in the background (it shares Miniflare state via .wrangler/state),
+# the admin in the foreground so Ctrl-C stops the session. Derive the admin port as app_port+1.
+APP_PORT=8787
+for ((i=1; i<=$#; i++)); do
+  if [ "${!i}" = "--port" ]; then j=$((i+1)); APP_PORT="${!j:-8787}"; fi
+done
+ADMIN_PORT=$((APP_PORT + 1))
+
+echo "Starting BOTH Workers — App :${APP_PORT}, Admin :${ADMIN_PORT}. Ctrl-C stops both." >&2
+
+# Shutdown: kill the background app CLI, then whatever is listening on our two ports (precisely our
+# workerds — they re-parent to init so a process-tree walk can't reach them, but they hold the port).
+# Best-effort: like the single-role path, wrangler can leave a workerd briefly orphaned; the CLI's
+# start-time port-in-use guard catches any residual on the next run and tells you to `pkill -f workerd`.
+"${CLI[@]}" dev "$@" &
+APP_PID=$!
+cleanup() {
+  kill "${APP_PID}" 2>/dev/null || true
+  for p in "${APP_PORT}" "${ADMIN_PORT}"; do
+    for pid in $(lsof -ti tcp:"${p}" 2>/dev/null); do kill -9 "${pid}" 2>/dev/null || true; done
+  done
+}
+trap cleanup EXIT INT TERM
+
+# Give the app a moment to apply migrations/seed before the admin migrates the same DB (avoids a race
+# on the shared SQLite file). Then the admin in the foreground — no --reset/--no-seed (already done).
+sleep 4
+"${CLI[@]}" dev --role admin --port "${ADMIN_PORT}"

package/deploy/lib/statedir.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Resolve where per-instance deploy state lives — the bash mirror of src/deploy/core/paths.ts, so the
+# publish/backup/dev scripts read the same `.deploy` the CLI wrote. Source it, then call
+# alpha_gate_state_dir <package-root>. Order: $ALPHA_GATE_HOME > (<root>/.git present ? <root>/.deploy
+# : ~/.alpha-gate).
+alpha_gate_state_dir() {
+  local root="$1"
+  if [ -n "${ALPHA_GATE_HOME:-}" ]; then printf '%s' "${ALPHA_GATE_HOME}"; return; fi
+  if [ -d "${root}/.git" ]; then printf '%s/.deploy' "${root}"; return; fi
+  printf '%s/.alpha-gate' "${HOME:-.}"
+}

package/deploy/teardown.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Destroy one Alpha Gate instance (§21). Thin wrapper → the TypeScript CLI (src/deploy/cli.ts). By
+# default it ARCHIVES the database first (wrangler d1 export to .deploy/<slug>-<ts>.sql); pass
+# --no-archive to skip. Confirmed by typing the instance name (or --yes). Same flags/UX as before:
+#
+#   ./deploy/teardown.sh --instance <slug> [--no-archive] [--archive-dir <dir>] [--yes] [--dry-run]
+#
+# The R2 bucket (if non-empty) and the Cloudflare Access app are finished by hand — pure wrangler can't
+# remove them; the CLI prints exactly what's left. Roll back: `git log -- deploy/teardown.sh`.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# Run the local tsx binary directly, not via `npx` (avoids a registry round-trip and a nested
+# npm-exec deadlock when the CLI shells out to wrangler — see deploy/dev.sh). npx tsx is the fallback.
+TSX="${ROOT}/node_modules/.bin/tsx"
+[ -x "${TSX}" ] && exec "${TSX}" "${ROOT}/src/deploy/cli.ts" teardown "$@"
+exec npx tsx "${ROOT}/src/deploy/cli.ts" teardown "$@"

package/docs/ONBOARDING.md

@@ -0,0 +1,16 @@
+# Onboarding
+
+This guide was split into task pages. Start at the [documentation index](README.md).
+
+Where its sections went:
+
+| Was | Now |
+|---|---|
+| Prerequisites, two ways to run the tooling | [setup/install.md](setup/install.md) |
+| Prepare your Cloudflare account | [setup/cloudflare-account.md](setup/cloudflare-account.md) |
+| Deploy, Access, service token, verify | [setup/deploy.md](setup/deploy.md) |
+| Email | [operate/email.md](operate/email.md) |
+| Backup & recovery | [maintain/backup.md](maintain/backup.md) |
+| Multiple instances, updating in place | [setup/deploy.md](setup/deploy.md), [maintain/updating.md](maintain/updating.md) |
+| Teardown | [maintain/teardown.md](maintain/teardown.md) |
+| Troubleshooting | [maintain/troubleshooting.md](maintain/troubleshooting.md) |

package/docs/PRINCIPLES.md

@@ -0,0 +1,195 @@
+# Alpha Gate — principles & constraints
+
+The durable ideas behind Alpha Gate: the invariants that must keep holding, and the hard constraints
+that shaped the design. This replaces the original `design/` spec (now in git history). It is the
+reference to read before changing core behavior — operational how-to lives in the task pages
+(index: [README](README.md)); the developer workflow in [CONTRIBUTING](../CONTRIBUTING.md).
+
+> Legacy note: many code comments cite `§N` (e.g. `§8`, `§11`). Those referred to sections of the old
+> `design/DESIGN.md`; the durable content is distilled here. Treat the markers as historical anchors.
+
+## What it is
+
+A self-hosted distribution gate for a notarized macOS app updated via **Sparkle**. It gates downloads
+and the per-user Sparkle update feed behind a token, with an admin back office for clients, builds,
+release channels, pins, and rollbacks. It runs entirely on **Cloudflare (Workers + D1 + R2)** within the
+free tier, deployable to any account from one script, with many isolated instances per account.
+
+## Architecture
+
+**Two Workers, one dataset.** The same code deploys twice, switched by a `ROLE` var, onto two
+`workers.dev` hostnames that share one D1 database and one R2 bucket:
+
+- **App Worker (public)** — token gate, the per-request resolver, the appcast, binary streaming, the
+  `/get` landing page. Sparkle and users reach it freely.
+- **Admin Worker (gated)** — the back office and all mutations; its **whole hostname** sits behind
+  Cloudflare Access.
+
+**Why split.** On `workers.dev`, Cloudflare Access protects an entire hostname — there is no reliable
+per-path gating. The public routes must stay open for Sparkle, so the admin cannot share that hostname.
+Splitting gives a fully public app and a fully gated admin over one shared dataset.
+
+**Host-agnostic.** Both Workers derive their origin from the incoming request, so they run on bare
+`*.workers.dev` URLs with **no custom domain, DNS, or zone**. The admin/app host pair follows a fixed
+naming contract (`alpha-gate-<instance>` and `alpha-gate-<instance>-admin`), which is how the admin
+derives the public `/get` link host (`src/lib/hosts.ts`).
+
+**The pivotal decision:** the appcast is **generated per request** from D1. Gating, re-download,
+channels, pinning, rollback, and revocation notices all fall out of one resolver, so there is a single
+source of truth (`src/core/resolver.ts`) the runtime, the download target, and the admin previews share.
+
+## Hard constraints (the ones that bite repeatedly)
+
+- **Sparkle cannot downgrade.** An item below the installed version is never offered. So "rollback" is
+  always a **roll-forward**: rebuild the previous good code with a *higher* `build_number`. The same
+  no-downgrade rule means pinning below, or moving a user to a channel whose top build is lower than
+  what they run, won't take effect until a higher build exists.
+
+- **`build_number` is the machine-comparable monotonic key** (Sparkle's `sparkle:version`);
+  `short_version` is the human string (`sparkle:shortVersionString`). They diverge during a rollback.
+  `build_number` must be a **positive integer** and must increase on every publish. Build metadata lives
+  in D1 (the resolver queries by channel/status/version); R2 holds only the archive bytes.
+
+- **Workers never sign and never hold a signing key.** All signatures — Developer ID + notarization,
+  Sparkle EdDSA, any feed signature — are produced on **macOS** at publish time. The Worker only stores
+  the bytes plus the fixed EdDSA string per archive. `SURequireSignedFeed` is **off**: it is incompatible
+  with per-user dynamic feeds (it would put the signing key on the edge); the per-archive EdDSA still
+  blocks tampered binaries.
+
+- **The token is never embedded in the binary.** Embedding would break the notarization seal. The build
+  is generic and signed once; the token reaches the app out-of-band via deep link
+  (`myapp://activate?token=`) or paste on first launch.
+
+- **Never hand out raw R2 or pre-signed URLs.** Every download routes through `/download?token=` so
+  access logging and instant revocation hold.
+
+- **The "no-build" state is surfaced, never silently blocked.** A user with no servable build (no
+  available build in their channels, no channel at all, or pinned to a withdrawn build) gets an
+  **empty appcast** — Sparkle stays "up to date". A user *stranded under no-downgrade* (their
+  channel's top is below what they run) still receives that top item — the resolver never reads the
+  installed build; Sparkle itself discards the lower item, with the same quiet "up to date" result.
+  Admin actions that would create either state (withdraw, unlink, unassign, pin/unpin) are not
+  blocked; they show which users would be affected and proceed on explicit confirmation. The remedy
+  is roll-forward, reassignment, or unpin.
+
+## The artifact model
+
+The update enclosure is **format-agnostic**. Storage and the appcast assume nothing about the file: the
+enclosure `type` is `application/octet-stream`, the URL is the extension-less `/download?…&via=update`,
+and `/download` sends a `Content-Disposition` filename from the object key. So either a signed **`.zip`**
+or a signed **`.dmg`** can be the Sparkle update artifact — Sparkle verifies the EdDSA, sees the filename,
+and picks the right installer. A single signed DMG can serve both first-install and update.
+
+R2 keys are built in exactly one place (`src/r2/keys.ts`): archives at
+`build/<build_number>/<sanitized-filename>` (append-only; `build_number` is unique), branding at
+`branding/icon` / `branding/header`, and an append-only audit anchor head.
+
+## Security model
+
+- **Admin auth is fail-closed.** The admin Worker verifies the Cloudflare Access JWT itself
+  (RS256-pinned, `aud`/`iss` + expiry checked) as defense-in-depth on top of edge Access. Any error
+  rejects. With the Access secrets unset, every admin request is denied. Service tokens are accepted on
+  **only** the publish surface — the build upload/register routes plus the read-only
+  `/admin/publish-info` pre-check — so a leaked CI credential is bounded to publishing.
+
+- **Token-in-URL trade-off.** The token travels in URLs, so it appears in Cloudflare's own request logs
+  (accepted for a private alpha). Mitigations: `/get` sets `Referrer-Policy: no-referrer`, and unknown
+  tokens get a generic 404 (no existence leak).
+
+- **Tamper-evident audit.** Every admin mutation is recorded in a **hash-chained** log, anchored daily to
+  an append-only R2 object (and emailed when email is configured). A divergence from the last anchor —
+  edit, truncation, rebuild — is flagged. Pair it with Cloudflare's Access auth logs and account Audit
+  logs, which an attacker with account access cannot rewrite.
+
+- **Account-level caveat.** Anyone with Cloudflare dashboard access to the account can read D1/R2
+  directly. Install into a dedicated account if that isolation matters.
+
+- **Branding inputs that reach a raw sink are validated.** The accent colour is interpolated raw into a
+  public `<style>`, so it is constrained to a hex value (rejected on write, coerced on read). Uploaded
+  branding images are raster-only (SVG is a stored-XSS vector when served from the app origin).
+
+## The back office
+
+The admin UI follows a few durable rules ("quiet instrument"), so changes should preserve them:
+
+- **The resolver is visible.** The Overview serving map (channel → build → audience, plus an
+  exhaustive *off the map* row), the Users list's **Next check** column, and every detail page's
+  verdict strip are all computed by the same pure core the runtime uses (`core/verdict.ts` over
+  `core/resolver.ts`) — the UI can never disagree with what Sparkle actually receives. "Which build
+  does this user get, and why not?" must always be answerable on the page where you'd act on it.
+- **Exception-only state.** Healthy states render as silence. `critical` is the single filled tag;
+  withdrawn/revoked/pinned/hidden are quiet outlined tags; every fault is amber and carries its
+  cause and a remedy. Builds are written exactly one way everywhere: the mono lockup
+  `#1500 · v1.2.1` — never a DB row id.
+- **The feedback loop closes.** Mutations 303 back to the page the operator acted from (validated
+  `return_to`) with a flash slug the target page renders; free text never rides in the URL.
+  Confirmation pages name their subject in operator words and Cancel returns to the origin.
+  Destructive actions (revoke, reissue, delete channel) are always confirmed; revoke is reversible
+  (**Reactivate** restores the same link). Stale forms are clear 400s *before* any write.
+- **The audit chain means "something changed".** No-op re-posts (double submit, stale tab) are
+  flash no-ops, not phantom audit rows; audit targets are human identifiers (emails, build
+  numbers). The Audit page and Overview show the chain's live integrity via the same
+  `assessChain` judgment the daily anchor records.
+- **One vocabulary on operator surfaces:** user, channel, request. (URLs and DB keep `stream` /
+  `pending` as stable contracts; only copy changed.)
+- **Entity pickers are comboboxes over native selects.** Wherever a user or build is picked
+  (pin, link, assign), the markup is a plain `<select>` that works with JavaScript disabled; the
+  self-contained enhancer (`views/admin/combobox.tsx`) turns it into a type-to-filter combobox —
+  multi-select (chips) on the channel page, whose batch routes accept repeated ids. New pickers
+  should reuse it, not grow bare selects.
+- **Theme follows the OS by default**, with a light/system/dark override (sidebar toggle → `theme`
+  cookie → `data-theme` on `<html>`). The dark tokens exist once (`darkRules` in the admin layout)
+  and apply both via `prefers-color-scheme` and via the forced attribute — never fork them.
+
+## Email
+
+Copy-paste invites are the **free-tier default**: with no email configured, every invite/notice is a
+link the admin sends manually (the invite page has a one-click copy). Automated delivery uses Cloudflare
+Email Service via the admin Worker's `send_email` binding — which requires **Workers Paid + a real,
+onboarded sending domain** (SPF/DKIM DNS). **A `*.workers.dev` hostname cannot be that domain** (you
+don't control its DNS), so a no-custom-domain instance must use copy-paste. Delivery sits behind an
+`EmailSender` seam, so another provider (e.g. a single-sender transactional service that needs no domain)
+can be added without touching the call sites. A misconfigured email setup falls back to copy-paste rather
+than erroring, and a failed send never 500s — the page surfaces the reason and the link.
+
+## Design for testability
+
+I/O lives at the edges; the logic is **pure**. The resolver, the no-build computation, validation, the
+audit hash-chain, and appcast XML generation are plain functions over plain data (no bindings), so most
+logic is testable with zero runtime. Handlers and services receive a `Deps` object (db, r2, clock,
+access, email, fetch) and never import bindings directly, so every seam is swappable in tests. `Date` /
+`Date.now()` are forbidden outside the two clock seams — `lib/clock.ts` for the Workers,
+`deploy/seams/clock.ts` for the deploy CLI (a lint rule enforces it) — so time-dependent behavior takes
+a seeded clock. The suites run **offline**: the Worker suite in the Workers runtime
+(`@cloudflare/vitest-pool-workers` / Miniflare), the deploy-CLI suite in plain Node. What those can't
+simulate — the real Access JWT, Cloudflare email delivery, bucket-lock, an end-to-end Sparkle client —
+sits behind injectable seams and is the only thing needing a throwaway deploy.
+
+**Client-side scripts gotcha.** The admin's small browser scripts (table sort/filter, upload autofill)
+serialize **pure** functions into the page via `Function.prototype.toString()` so the browser runs the
+exact tested code. A serialized function must reference **nothing** at module scope: a module-level
+constant, or an esbuild runtime helper (`__name`, `__spreadValues`, `__async`, …), would be `undefined`
+in the browser and throw. There is an identity shim for `__name`; a unit-test regex fails the build if
+any other helper leaks in. Keep those functions self-contained (no inner-closure references, no spread/
+async/`**`) and the contract holds.
+
+## Operating principles
+
+- **One idempotent script.** `deploy.sh` provisions D1 + R2, applies migrations, and deploys both
+  Workers; re-running updates in place with data preserved. Deployment is **pure wrangler** — no API
+  token, DNS, or zone. The two things a script can't do (enable Access on the admin hostname; create a
+  service token) are printed as a one-time checklist.
+- **Everything is namespaced by the instance slug**, so one account holds many independent instances
+  (separate D1, R2, Workers, Access app, and per-slug state).
+- **Two install channels, one CLI.** The same commands run from an npm install (`npx alpha-gate …`,
+  the `bin`) or a git clone (`./deploy/*.sh`). The only difference is where per-instance state lives:
+  `~/.alpha-gate` for npm (the package files sit in the ephemeral npm cache), `<repo>/.deploy` for a
+  clone; `$ALPHA_GATE_HOME` overrides. So the rendered wrangler config uses **absolute** paths into the
+  package for `main` and `migrations_dir` (`core/paths.ts` resolves the state dir; keep the two — code
+  root vs state dir — distinct).
+- **The self-update banner checks the npm registry.** The deployed Worker's daily cron polls
+  `registry.npmjs.org/<name>/latest` and compares against its baked-in `TOOL_VERSION` (= the deploying
+  package's version); the upgrade signals travel in `package.json`'s `alphaGate` field. It only
+  **notifies** — a Worker never deploys itself (that would need a privileged Cloudflare API token on
+  the edge, which the "no API token / hold no privileged creds" posture forbids). Updating stays an
+  operator-run, human-in-the-loop `deploy` (safe for migrations).