alpha-gate 0.1.0

package/docs/README.md

@@ -0,0 +1,54 @@
+# Alpha Gate documentation
+
+Alpha Gate is a self-hosted distribution gate for notarized macOS apps updated via Sparkle: private,
+per-tester download links and update feeds, served from your own Cloudflare account. These pages are
+task-oriented; the architecture and its invariants live in [PRINCIPLES](PRINCIPLES.md).
+
+The journey, in order:
+
+## Set up
+
+| Page | Covers |
+|---|---|
+| [Install](setup/install.md) | The CLI from npm or a clone; running both Workers locally, no account needed |
+| [Prepare a Cloudflare account](setup/cloudflare-account.md) | wrangler login, the Zero Trust bootstrap, what you can skip |
+| [Deploy](setup/deploy.md) | The first deploy, locking the admin behind Access, verifying, updating in place, multiple instances |
+
+## Integrate your app
+
+| Page | Covers |
+|---|---|
+| [Sparkle in Swift](integrate/sparkle-swift.md) | The EdDSA key, Info.plist, the runtime per-user feed URL; official Sparkle references |
+| [Sparkle in Go](integrate/sparkle-go.md) | Pure-Go via [go-sparkle](https://github.com/alex-ivanov/go-sparkle), or framework bindings — and where they differ |
+| [Activation](integrate/activation.md) | The token, the activate deep link, why it is out-of-band, both sides of the wiring |
+
+## Operate
+
+| Page | Covers |
+|---|---|
+| [Add users](operate/add-users.md) | Inviting, the invite page, access requests, what the user sees |
+| [Remove users](operate/remove-users.md) | Revoke, reactivate, reissue, hide — and which one to reach for |
+| [Channels](operate/channels.md) | Grouping who gets what: linking builds, assigning users, pinning, the stranding guard |
+| [Publish](operate/publish.md) | The one-command publish, the browser upload, CI, rollback, end-to-end verification |
+| [Monitoring](operate/monitoring.md) | Reading the Overview, the Next-check column, Activity, and the audit chain |
+| [Email](operate/email.md) | Copy-paste invites by default; Cloudflare email as the optional paid add-on |
+
+## Maintain
+
+| Page | Covers |
+|---|---|
+| [Backup](maintain/backup.md) | What is irreplaceable, the one-command dump, restoring |
+| [Migrate to a new account](maintain/migrate-account.md) | The planned cutover a hostname change requires |
+| [Updating the tool](maintain/updating.md) | The release banner, updating from npm or a clone, breaking releases |
+| [Teardown](maintain/teardown.md) | Removing an instance, and the two steps that stay manual |
+| [Troubleshooting](maintain/troubleshooting.md) | Symptoms → causes → fixes, across deploy, publishing, and the feed |
+
+## Reference
+
+- [PRINCIPLES](PRINCIPLES.md) — the architecture, the hard constraints, and the invariants that must
+  keep holding. Read it before changing core behavior.
+- [CONTRIBUTING](../CONTRIBUTING.md) — the developer guide: conventions, testing, adding a feature.
+
+New here? The shortest useful path is [Install](setup/install.md) →
+[Deploy](setup/deploy.md) → [Sparkle in Swift](integrate/sparkle-swift.md) →
+[Add users](operate/add-users.md) → [Publish](operate/publish.md).

package/docs/UPLOADING.md

@@ -0,0 +1,14 @@
+# Uploading builds
+
+This guide was split into task pages. Start at the [documentation index](README.md).
+
+Where its sections went:
+
+| Was | Now |
+|---|---|
+| Wire Sparkle into your app | [integrate/sparkle-swift.md](integrate/sparkle-swift.md) (Go apps: [integrate/sparkle-go.md](integrate/sparkle-go.md)) |
+| Activation, the token, the deep link | [integrate/activation.md](integrate/activation.md) |
+| Create a channel | [operate/channels.md](operate/channels.md) |
+| Invite a user, getting the link to users | [operate/add-users.md](operate/add-users.md) |
+| Publish (one command, browser, CI), verify, rollback | [operate/publish.md](operate/publish.md) |
+| Troubleshooting | [maintain/troubleshooting.md](maintain/troubleshooting.md) |

package/docs/integrate/activation.md

@@ -0,0 +1,56 @@
+# Activation
+
+How the per-user token reaches your app, and what to implement on the app side and the admin side.
+
+## Why the token is out-of-band
+
+The build is generic and signed once. **The token is never embedded in the binary** — embedding it would break the notarization seal and force a signing pass per user. Instead, every user installs the same artifact, and the token, the user's only credential, reaches the app at runtime through a deep link or a paste. The token never sits in Sparkle's static configuration either: `SUFeedURL` stays unset, and your app holds the token and builds the per-user feed URL from it at check time (see [Sparkle in Swift](sparkle-swift.md)). (see [Sparkle in Swift](sparkle-swift.md)).
+
+## What the token is
+
+A token is 32 characters of Crockford base32 (digits and letters, excluding I, L, O, U), carrying 160 bits of entropy. One token exists per user, and it gates the download, the appcast, and the `/get` page alike. Lookup is forgiving: case, whitespace, hyphens, and the confusable characters O (read as 0) and I/L (read as 1) are normalized, so a hand-typed paste still matches.
+
+The token travels in URLs (`/get?token=`, `/appcast?token=`, `/download?token=`), which means it appears in Cloudflare's own request logs. That is an accepted trade-off for a private alpha. Two mitigations apply: an unknown token is indistinguishable from a revoked one (the same generic 404 on `/get` and `/download`, the same renewal notice on `/appcast`), so a response never confirms that a token exists, and the `/get` page sets `Referrer-Policy: no-referrer`, so the token never leaks through a Referer header.
+
+## The activate URL scheme
+
+The user's `/get` page shows two buttons, Download and Activate. Activate links to `<scheme>://activate?token=<token>`. The scheme comes from the **Activate URL scheme** field in admin Settings and must equal the scheme your app registers in its `Info.plist` under `CFBundleURLTypes → CFBundleURLSchemes`. If the two differ, clicking Activate opens nothing on the user's machine, because macOS finds no handler for the URL.
+
+## App side
+
+First launch has no token, so show an activate prompt with two ways in:
+
+- **Deep link.** Handle `<scheme>://activate?token=<token>`: store the token in the Keychain, then start the updater.
+- **Paste.** The `/get` page prints the raw key under the buttons ("Access key — paste it in the app if Activate doesn't open it"), so keep a text field that accepts it. You do not need to clean the input; the server normalizes case, whitespace, hyphens, and the O/I/L confusables.
+
+An illustrative handler (AppKit; lives in your app):
+
+```swift
+func application(_ application: NSApplication, open urls: [URL]) {
+    for url in urls where url.host == "activate" {
+        guard let token = URLComponents(url: url, resolvingAgainstBaseURL: false)?
+            .queryItems?.first(where: { $0.name == "token" })?.value
+        else { continue }
+        Keychain.token = token   // your Keychain wrapper
+        startUpdateChecks()      // safe now: a feed URL exists
+    }
+}
+```
+
+Do not start update checks before a token exists; with no feed URL, Sparkle errors. The delegate that turns the stored token into the per-user feed URL is covered in [Sparkle in Swift](sparkle-swift.md) and [Sparkle in a Go app](sparkle-go.md).
+
+## Lifecycle: revoke, reactivate, reissue
+
+Revoking a user cuts access at once: `/download` returns 404, and the next update check receives an informational renewal notice instead of a build. The notice is a Sparkle item with no enclosure, so it can never be installed. It shows the title and message configured in Settings, displays as version "Access renewal", and links to the public `/access` page where the user can request access again. An active user is never shown this notice.
+
+Because the token was never in the binary, the installed app recovers **without a reinstall**:
+
+- **Reactivate** restores access on the existing link and token; updates resume on the app's next check.
+- **Reissue** replaces the link and invalidates the token the installed app holds. The old link stops working; the user opens the new `/get` link and activates again, by deep link or paste. The old link stops working; the user opens the new `/get` link and activates again, by deep link or paste.
+
+## Admin side: where the scheme is set
+
+- **Guided first deploy.** On a fresh database, `./deploy/deploy.sh` prompts for the Activate URL scheme (default `myapp`), along with the app name, blurb, and accent colour.
+- **Settings.** The admin Settings page has the *Activate URL scheme* field under *App activation*, next to the Sparkle public key. The `/get` page reads the scheme on every request, so a correction applies to every existing invite link immediately.
+
+Next: [Add users](../operate/add-users.md)

package/docs/integrate/sparkle-go.md

@@ -0,0 +1,106 @@
+# Sparkle in a Go app
+
+How to wire a Go macOS app to Alpha Gate. There are two routes: a pure-Go client that speaks the
+Sparkle wire format ([alex-ivanov/go-sparkle](https://github.com/alex-ivanov/go-sparkle) — no
+framework, works in any Go app), and cgo bindings around the real `Sparkle.framework`
+([abemedia/go-sparkle](https://github.com/abemedia/go-sparkle), which needs a Cocoa run loop). The
+server side is identical either way.
+
+## Route 1: pure Go (alex-ivanov/go-sparkle)
+
+A stdlib-only re-implementation of the Sparkle client: appcast parse, ed25519 verify, download,
+and the macOS `.app` swap + relaunch. Signatures and keys are byte-identical with Sparkle's own
+tooling, and token-gated feeds are built in — which is exactly what an Alpha Gate feed is.
+
+```bash
+go get github.com/alex-ivanov/go-sparkle
+```
+
+Configure it with the feed URL template; the `<TOKEN>` and `<CFBundleVersion>` placeholders do
+what the Swift page's delegate methods do:
+
+```go
+up := sparkle.New(sparkle.Config{
+    FeedURL:          "https://<your-app-host>/appcast?token=<TOKEN>&installed=<CFBundleVersion>",
+    PublicEDKey:      "<base64 ed25519 public key>", // the same key as SUPublicEDKey
+    InstalledVersion: 42,                            // your build number
+    OSVersion:        "14.4",                        // filters sparkle:minimumSystemVersion
+})
+
+rel, err := up.Check(ctx, token)  // nil when up to date
+if rel != nil {
+    path, err := up.Download(ctx, rel, token) // length + ed25519 verified before returning
+    app, err := sparkle.Apply(path)           // swap the .app in place + relaunch
+}
+```
+
+The token is percent-encoded into the query (which is where Alpha Gate reads it) and also sent as
+an `Authorization: Bearer` header, which Alpha Gate ignores — only the query parameter authenticates. `Apply` handles both `.zip` and `.dmg` artifacts, so whatever
+you [publish](../operate/publish.md) installs unchanged.
+
+Differences from framework Sparkle worth knowing with an Alpha Gate feed:
+
+- **Revocation is quiet.** Framework Sparkle shows revoked users the renewal notice
+  ([activation](activation.md)); the pure-Go client filters that notice item out (it has no
+  enclosure), so `Check` returns nil and a revoked app reads as up to date forever. No error is
+  raised and no download is attempted. If you want a visible "renew access" moment, detect it
+  yourself: treat the enclosure-less notice item in the fetched appcast as the signal (an active
+  token never receives one), or probe `/get?token=` and treat its 404 as revoked.
+- **`--critical` has no effect** on this client — critical updates are on its not-implemented
+  list, so a critical build installs like any other.
+
+### A pure-Go release pipeline
+
+The library's `cmd/sign_update` is a drop-in replacement for Sparkle's `sign_update` — same flags,
+same key format, same output, and on macOS it reads the login Keychain exactly where Sparkle's
+`generate_keys` stores the key. `publish.sh` accepts it directly:
+
+```bash
+go install github.com/alex-ivanov/go-sparkle/cmd/sign_update@latest
+./publish.sh MyApp.zip --channel beta --sign-update "$(command -v sign_update)"
+```
+
+You can also mint the keypair without installing Sparkle at all: `sparkle keygen` (from
+`cmd/sparkle`) prints the base64 public key to embed and writes the private key file — keys are
+interchangeable with Sparkle's. The [backup warning](../maintain/backup.md) applies to that key
+file exactly as it does to the Keychain copy.
+
+## Route 2: framework bindings (abemedia/go-sparkle)
+
+If your Go app already runs a Cocoa UI (webview, Qt, Wails), you can drive the real
+`Sparkle.framework` through [abemedia/go-sparkle](https://github.com/abemedia/go-sparkle) —
+cgo bindings around Sparkle 2.7.0 via the legacy `SUUpdater` class. You get Sparkle's own UI and
+the renewal-notice display, at the cost of shipping the framework:
+
+1. Place `Sparkle.framework` (from the [official releases](https://github.com/sparkle-project/Sparkle/releases))
+   in `YourApp.app/Contents/Frameworks/`.
+2. Build with `CGO_LDFLAGS='-Wl,-rpath,@loader_path/../Frameworks' go build .`
+
+There is no delegate support, so compose the full feed URL in Go and set it on **every launch**,
+before any check — Sparkle persists the URL to user defaults, and re-setting it overwrites a stale
+token or build number:
+
+```go
+import sparkle "github.com/abemedia/go-sparkle"
+
+sparkle.SetFeedURL("https://<your-app-host>/appcast?token=" + token + "&installed=" + build)
+```
+
+## Info.plist and the deep link (both routes)
+
+A Go `.app` bundle's `Info.plist` is yours to author (tools like
+[appify](https://github.com/machinebox/appify) scaffold it). The keys match the
+[Swift page's table](sparkle-swift.md): an integer `CFBundleVersion`, your activate scheme in
+`CFBundleURLSchemes`, no `SUFeedURL`. `SUPublicEDKey` matters to route 2; route 1 takes the key in
+its `Config` instead.
+
+macOS delivers `myapp://activate?token=…` as an Apple Event (`kAEGetURL`), not in `os.Args`, so a
+Go app needs a small Objective-C shim via cgo: register the handler early
+(`applicationWillFinishLaunching`), pass the URL to an `//export`-ed Go function, store the token,
+then configure the updater. A worked example of the pattern:
+[Handling macOS URL schemes with Go](https://blakewilliams.me/posts/handling-macos-url-schemes-with-go);
+Wails v3 ships a [ready-made example](https://pkg.go.dev/github.com/wailsapp/wails/v3/examples/single-instance-url-scheme).
+Keep a paste field as the fallback — the `/get` page shows the raw key
+(see [activation](activation.md)).
+
+Next: [the token and activation flow](activation.md)

package/docs/integrate/sparkle-swift.md

@@ -0,0 +1,63 @@
+# Sparkle 2 in a Swift app
+
+How to wire Sparkle 2 into a native macOS app so its updates flow through your Alpha Gate instance.
+
+## What differs from stock Sparkle
+
+One thing: the update feed is per-user. Each user's token selects their channel, pin, and build, so there is no single appcast URL to bake into the app. You leave `SUFeedURL` unset and supply the feed URL at runtime through the updater delegate (below). Everything else (installing the framework, the updater controller, the check-for-updates menu item) is standard Sparkle 2; follow the [official setup guide](https://sparkle-project.org/documentation/) and come back here for the feed.
+
+Keep two hosts straight. The app's feed points at the App Worker: the `app_url` in your deploy state (`.deploy/<slug>.state.json` in a clone, `~/.alpha-gate/<slug>.state.json` from npm). Publishing talks to the admin Worker, a different hostname.
+
+The token is never embedded in the binary — embedding it would break the notarization seal. The build is generic and signed once; the token reaches the app out of band on first launch (see [Activation](activation.md)).
+
+The admin's **App setup** page shows this whole section personalized for your instance, with your activate scheme and saved public key filled in.
+
+## Generate the EdDSA key (once)
+
+Use `generate_keys` from Sparkle 2's `bin/` directory:
+
+```bash
+./bin/generate_keys                          # stores the PRIVATE key in your login Keychain; prints the PUBLIC key
+./bin/generate_keys -x sparkle_private.pem   # export the private key (for backup, or CI secrets)
+```
+
+The private key is what `sign_update` uses at publish time. The Worker never holds it; it only stores the signature string each build produces.
+
+**The private key is unrecoverable — back it up now.** It lives only in your login Keychain. If you lose it (laptop dies, Keychain wiped), every already-installed app rejects all future updates: Sparkle verifies each download against the public key baked into the app, and you cannot produce a matching signature without the private key. Run `./bin/generate_keys -x sparkle_private.pem` and store that file somewhere safe and off the laptop, such as a password manager or an encrypted backup. This is the single most important thing to back up in the whole system.
+
+## Info.plist keys
+
+| Key | Value |
+|---|---|
+| `SUPublicEDKey` | the public key `generate_keys` printed; Sparkle verifies every download against it |
+| `SUFeedURL` | leave unset — the feed is per-user, supplied at runtime |
+| `CFBundleURLTypes` → `CFBundleURLSchemes` | your activate scheme, e.g. `myapp`; must equal the *Activate URL scheme* in admin Settings |
+| `SURequireSignedFeed` | off / unset — incompatible with per-user feeds (a signed feed would put the signing key on the edge); the per-archive EdDSA still blocks tampering |
+| `CFBundleVersion` | a positive integer that increases every release (Sparkle's compare key); see below |
+| `CFBundleShortVersionString` | the human version (e.g. `1.4.0`) shown in the update dialog |
+
+**`CFBundleVersion` must be a positive integer that increases every release.** It becomes `build_number` (Sparkle's `sparkle:version`), which Sparkle compares numerically and the server requires to be an integer. `CFBundleShortVersionString` can be anything: `1.4.0`, a git describe. If your build sets `CFBundleVersion` to something non-integer (e.g. `0.0.3` or a hash), publishing rejects it — fix the build, or override per-publish with `--build-number <n>`.
+
+## Supply the feed URL at runtime
+
+Implement the updater delegate so each check carries the token and the installed build:
+
+```swift
+func feedURLString(for updater: SPUUpdater) -> String? {
+    guard let token = Keychain.token else { return nil }   // no token yet → the check will fail; gate checks on activation (see below)
+    return "https://<APP_WORKER_HOST>/appcast?token=\(token)"
+}
+func feedParameters(for updater: SPUUpdater, sendingSystemProfile: Bool) -> [[String: String]] {
+    let build = Bundle.main.object(forInfoDictionaryKey: "CFBundleVersion") as? String ?? "0"
+    return [["key": "installed", "value": build]]          // powers the admin's "current version" + stranded detection
+}
+```
+
+`<APP_WORKER_HOST>` is the `app_url` host from your deploy state. `Keychain.token` is illustrative — read the token from wherever your activation flow stored it. **Do not start update checks before a token exists**: with no feed, Sparkle errors. The guard does not skip the check — it only keeps a tokenless request from ever reaching the server; hold off enabling automatic checks (or calling checkForUpdates) until activation has stored the token.
+
+## References
+
+- Sparkle basic setup (framework, updater controller): <https://sparkle-project.org/documentation/>
+- Keys and signing (`generate_keys`, `sign_update`): <https://sparkle-project.org/documentation/publishing/>
+
+Next: [Activation](activation.md)

package/docs/maintain/backup.md

@@ -0,0 +1,52 @@
+# Backup and restore
+
+This page covers what to back up, how the backup command works, and how to restore a dump into a fresh instance.
+
+## What matters
+
+The irreplaceable state lives in D1: users and their tokens, build metadata, channels, logs, and the audit chain. R2 holds the archive bytes, which you re-create by publishing the same artifacts again, the branding images, which you re-upload on the Settings page, and the daily audit-chain anchors, which are append-only tamper evidence that a fresh instance starts over. So a backup is a D1 dump; everything else in R2 is either re-creatable or restarts clean.
+
+Two things live only in your login Keychain, in neither D1 nor the local deploy state:
+
+- The Sparkle private key. **Export it now** — run `generate_keys -x sparkle_private.pem` from Sparkle 2's `bin/` directory and store the file off the laptop, in a password manager or an encrypted backup. If you lose the key, every already-installed app rejects all future updates: Sparkle verifies each download against the public key baked into the app, and no matching signature can be produced without the private key. No dump restores this.
+- The Access service token, which `publish.sh` stores on first use. This one is recreatable: make a new one in Cloudflare Zero Trust (Access → Service Auth), include it in the Service Auth policy on the admin Access application, and re-enter it by passing `--reset-token` on your next publish.
+
+## The backup command
+
+```bash
+./deploy/backup.sh --instance <slug>          # from a clone
+npx alpha-gate backup --instance <slug>       # from npm
+```
+
+Both forms export the remote D1 database to `<slug>-<timestamp>.sql` in the state directory — `.deploy/` in a clone, `~/.alpha-gate` from npm. Pass `--out <dir>` to write somewhere else:
+
+```bash
+./deploy/backup.sh --instance <slug> --out ~/secure-backups
+```
+
+Run it before a risky change, or on a schedule with cron or launchd. The dump path is the last line the command prints on stdout, so a scheduled job can capture it with `tail -n 1`. This is the same export `teardown.sh` takes before destroying an instance.
+
+**The dump contains your testers' live access tokens.** Anyone who reads it can download your builds as any tester. Keep it off the laptop, in private storage, and prune old copies.
+
+## Restore
+
+Restore in this order: create the empty database, import the dump into it, then deploy. Importing
+into an already-deployed instance fails — the deploy has applied migrations, and the dump replays
+`d1_migrations` and every table, so the import hits conflicts and rolls back.
+
+```bash
+npx wrangler d1 create alpha-gate-<slug>                                    # the empty database
+npx wrangler d1 execute alpha-gate-<slug> --remote --file <slug>-<timestamp>.sql
+./deploy/deploy.sh --instance <slug>                                        # deploy on top
+```
+
+The deploy finds the restored database, sees its migrations already recorded, and skips first-init
+prompts because your settings came back with the dump. Keep the `--remote` flag on the import:
+without it, wrangler applies the dump to a local development copy and the deployed instance is
+unchanged. Users keep their existing tokens and `/get` links after the restore while the hostname stays the same. Restoring under a different instance slug or account changes the hostname, which breaks every link you already sent and every installed app's feed URL — that move is a planned cutover, not a restore (see [Migrate to another account](migrate-account.md)).
+
+## Losing the local state directory
+
+The state directory (`.deploy/` or `~/.alpha-gate`, overridden by `$ALPHA_GATE_HOME`) is not a backup target. Re-running `deploy.sh` regenerates it: configs, resolved ids, URLs, and the Access wiring are re-derived from the live resources. The one exception is email — **those flags are remembered only in the state directory**, so after losing it pass `--email-provider` and `--email-from` once more. A bare re-run without them quietly reverts invites to copy-paste links.
+
+Next: [Migrate to another account](migrate-account.md)

package/docs/maintain/migrate-account.md

@@ -0,0 +1,95 @@
+# Migrate an instance to a different Cloudflare account
+
+How to move a running instance to another Cloudflare account without stranding the apps your users already installed.
+
+## Why this is more than backup and restore
+
+The Workers run on `*.workers.dev`, and that hostname embeds the account: the app Worker serves at `https://alpha-gate-<instance>.<account>.workers.dev`. A new account means a new `<account>` label, so the app hostname changes. Every installed app has the old host baked into the feed URL its code builds (see [Sparkle integration](../integrate/sparkle-swift.md)) — it checks the old host and knows nothing about the new one.
+
+The database restores cleanly ([backup](backup.md) covers the dump), but restoring alone does not move your users. Until each app installs a build whose feed URL points at the new host, it depends on the old instance. Tear down the old instance before that update has landed and **installed apps stop updating**; the only recovery is asking every user to reinstall by hand. So treat the move as a planned cutover, not a restore.
+
+## The order that works
+
+Nothing below interrupts the old instance until the last step. Users keep updating throughout. (The `npx alpha-gate <cmd>` form takes the same flags as the `./deploy/*.sh` wrappers shown here.)
+
+1. **Keep the old instance running** and take a fresh dump:
+
+   ```bash
+   ./deploy/backup.sh --instance <slug>     # → .deploy/<slug>-<timestamp>.sql
+   ```
+
+   The dump contains your testers' live access tokens — handle it like a secret.
+
+2. **Log wrangler into the new account, create the database there, and restore into it while it
+   is still empty** (importing after a deploy fails on migration conflicts — see
+   [backup](backup.md)):
+
+   ```bash
+   npx wrangler login                        # the NEW account
+   npx wrangler d1 create alpha-gate-<slug>
+   npx wrangler d1 execute alpha-gate-<slug> --remote --file .deploy/<slug>-<timestamp>.sql
+   ```
+
+   The same slug is fine: a different account means a different `<account>` label, so the
+   hostnames cannot collide. Users, tokens, channels, build metadata, logs, and the audit chain
+   all carry over. Archive bytes do not — R2 is not in the dump, so the restored build rows have
+   nothing downloadable behind them yet. Step 7 fixes that.
+
+3. **Deploy on top of the restored database:**
+
+   ```bash
+   ./deploy/deploy.sh --instance <slug>
+   ```
+
+   The deploy finds the database, sees its migrations already recorded, and skips the first-init
+   prompts — your app name, activate scheme, and branding came back with the dump.
+
+4. **Redo the two manual Access steps** for the new account: enable Cloudflare Access on the new admin hostname and allowlist your email, exactly as in [deploy](../setup/deploy.md). Both values change, because Zero Trust teams are per account. Feed them back:
+
+   ```bash
+   ./deploy/deploy.sh --instance <slug> \
+     --access-team-domain <team>.cloudflareaccess.com --access-aud <AUD>
+   ```
+
+5. **Create a service token in the new account's Zero Trust** (with a Service Auth policy on the new admin Access application, as in [publish](../operate/publish.md)). Your Keychain still holds the old account's token under this slug, so on the first publish to the new instance pass `--reset-token`; `publish.sh` prompts for the new Client ID and Secret and stores them.
+
+6. **Check email carried over, if you used it.** The flags ride in the slug's local state, so the step-3 deploy reuses them and prints `(reusing email: …)`. If that line is missing (a different machine, a lost state directory), pass the flags once — this can ride on the same run as step 4:
+
+   ```bash
+   ./deploy/deploy.sh --instance <slug> --email-provider cloudflare --email-from alpha@<sending-domain>
+   ```
+
+7. Ship the cutover release. Rebuild your app so its feed URL points at the new app host (`https://alpha-gate-<slug>.<new-account>.workers.dev`), give it a higher `CFBundleVersion`, and publish the artifact to both instances:
+
+   ```bash
+   # to the OLD instance — installed apps still check there
+   ./publish.sh MyApp.dmg --channel <name> \
+     --admin-url https://alpha-gate-<slug>-admin.<old-account>.workers.dev
+
+   # to the NEW instance — gives the restored data a downloadable top build
+   ./publish.sh MyApp.dmg --channel <name> --instance <slug> --reset-token
+   ```
+
+   Local state for the slug now points at the new account, so the old instance must be addressed with `--admin-url`; that publish prompts for the old account's service token, which still exists in the old Zero Trust. Every app that installs this build starts checking the new host, where its restored token is already valid.
+
+8. **Watch the new instance's Activity page** until your users appear there. Each updated app's next check shows up as a `check` entry carrying its installed build (see [monitoring](../operate/monitoring.md)). Users who have not updated yet are still on the old instance — leave it running until the checks you care about have moved.
+
+9. **Tear down the old instance.** Teardown acts on whichever account wrangler is logged into, and you are currently logged into the new one — log back into the old account first:
+
+   ```bash
+   npx wrangler login                         # the OLD account
+   ./deploy/teardown.sh --instance <slug> --dry-run   # confirm it targets the old resources
+   ./deploy/teardown.sh --instance <slug>
+   ```
+
+   It archives the old D1 first — one more backup. [Teardown](teardown.md) covers the closing checklist (empty the R2 bucket, remove the old Access application). Teardown also removes the slug's local state files, which by now describe the NEW instance — take a copy of the state directory first, and log wrangler back into the new account when you are done.
+
+## Next time: a custom domain on the app Worker
+
+Both Workers serve on whatever hostname the request arrives on; the one `workers.dev` assumption is the invite-link derivation (`src/lib/hosts.ts`), so `/get` links keep using the `workers.dev` app host even after you attach a domain. If you attach a domain you control to the app Worker (a Cloudflare dashboard action; the account needs a zone for that domain) and bake that hostname into your app's feed URL from day one, the host in installed apps never changes. A future account move is then deploy, restore, redo Access, and re-point the domain at the new account's Worker — steps 7 and 8 disappear. Do it before the first build ships with a `workers.dev` feed URL.
+
+## Invite links
+
+Every `/get?token=` link you already sent embeds the old host, so those links die with the old instance. The tokens themselves survive the restore unchanged: activated apps are unaffected, because the token rides in the feed URL the app builds, not in the link. Only users who have not yet redeemed an invite need a fresh link — open each user's page on the new admin, which shows the current `/get?token=` link, and re-send it (see [add users](../operate/add-users.md)). The links the admin shows are derived from the `workers.dev` naming contract (`src/lib/hosts.ts`), so they point at the new host as soon as the new admin is up.
+
+Next: [Teardown](teardown.md)

package/docs/maintain/teardown.md

@@ -0,0 +1,46 @@
+# Teardown
+
+How to remove an Alpha Gate instance completely — both Workers, the database, the local state, and the two steps you finish by hand.
+
+## The command
+
+```bash
+./deploy/teardown.sh --instance <slug>               # confirm, archive the database, destroy
+./deploy/teardown.sh --instance <slug> --dry-run     # rehearse: print the plan, touch nothing
+./deploy/teardown.sh --instance <slug> --no-archive  # destroy without the database backup
+./deploy/teardown.sh --instance <slug> --yes         # skip the confirmation prompt (CI)
+```
+
+From npm the same flags apply: `npx alpha-gate teardown --instance <slug>`. `--archive-dir <dir>` writes the database archive somewhere other than the state directory.
+
+You need wrangler authentication (`npx wrangler login`, once per machine). The command prints the full destructive plan before touching anything, then asks you to **type the instance name** to confirm. Any other input aborts with nothing deleted. A non-interactive run without `--yes` refuses instead of hanging.
+
+## What it does
+
+The steps run in this order:
+
+1. Archives the database first, while it still exists, to `<state-dir>/<slug>-<timestamp>.sql`. The state directory is `.deploy/` in a git clone, `~/.alpha-gate` for the npm install. This is the same dump [backup](backup.md) produces and **it contains your testers' live access tokens** — move it to private storage or shred it. If the export fails, teardown stops and nothing is destroyed; fix the error, or re-run with `--no-archive` to destroy without a backup.
+2. Deletes the app Worker (`alpha-gate-<slug>`) and the admin Worker (`alpha-gate-<slug>-admin`). Workers that are already gone are tolerated, so re-running after a partial teardown works — pass `--no-archive` on the re-run if the database was already deleted, since the archive step has nothing left to export.
+3. Deletes the R2 bucket, but only if it is already empty. A non-empty bucket is left in place and reported.
+4. Deletes the D1 database.
+5. Removes the local configs from the state directory: `<slug>.app.toml`, `<slug>.admin.toml`, `<slug>.state.json`.
+
+A `--dry-run` prints the same plan and step lines but runs no wrangler commands and deletes no files.
+
+## What stays manual
+
+Two things pure wrangler cannot do, printed as the closing checklist:
+
+- Empty and delete a non-empty R2 bucket: dashboard → R2 → the bucket → delete. This line appears only when the bucket survived; an empty bucket was already deleted for you.
+- **Remove the Cloudflare Access application** for `alpha-gate-<slug>-admin`: Zero Trust → Access → Applications. Until you do, a dead application lingers in your Zero Trust account.
+
+Teardown also does not touch the Access service token. publish.sh had you create one the first time you published to this instance (a CI runner may hold another); remove them under Zero Trust → Access → Service Auth., remove it under Zero Trust → Access → Service Auth.
+
+## What survives on your Mac
+
+Teardown never touches the Keychain. Two secrets stay in your login Keychain:
+
+- The **Sparkle private key**. Its public half (`SUPublicEDKey`) is baked into every build you shipped, and if the key is lost, **every already-installed app rejects all updates** — even from a fresh instance later. Keep it unless you are retiring the app for good. See [Sparkle integration](../integrate/sparkle-swift.md).
+- The Access service token that `publish.sh` stored, keyed by instance. It is a credential for the Access application you are deleting, so it becomes useless once that application is gone; a future instance takes a new one via `./publish.sh <file> --reset-token`.
+
+Delete them from your login Keychain by hand if you want them gone: the service token is two items under the service `alpha-gate-access` (`<slug>-client-id` and `<slug>-client-secret`); the Sparkle key is the item `generate_keys` created (search for "sparkle").

package/docs/maintain/troubleshooting.md

@@ -0,0 +1,102 @@
+# Troubleshooting
+
+Symptoms, their causes, and their fixes, grouped by area.
+
+## Deploy and access
+
+### The admin returns 403 after it worked before
+
+The Access secrets stored on the Worker are usually stale. The Worker verifies the Access JWT itself and fails closed, so wrong or unset secrets reject every admin request.
+
+- **You renamed your Zero Trust team.** The team domain changed to `<new-team>.cloudflareaccess.com`; the AUD usually stays. Re-run deploy with the new domain:
+
+  ```bash
+  ./deploy/deploy.sh --instance <slug> --access-team-domain <new-team>.cloudflareaccess.com
+  ```
+
+- **You deleted and recreated the Access application.** The AUD changed. Re-run with the new one:
+
+  ```bash
+  ./deploy/deploy.sh --instance <slug> --access-aud <new-aud>
+  ```
+
+Where to find both values is covered in [Deploy](../setup/deploy.md).
+
+### `deploy.sh` stops at preflight
+
+Preflight is read-only and prints what failed with a `→` fix line under it. The two common causes: Node is older than 20, or wrangler is not authenticated — run `npx wrangler login`, or set `CLOUDFLARE_API_TOKEN` in CI. Fix what the line says and re-run; deploy is idempotent.
+
+### Opening the admin origin redirects to `/admin`
+
+Expected. `GET /` on the admin Worker answers 302 to `/admin`; the back office lives under that path. Nothing to fix.
+
+## Publishing
+
+### "build number … is not a positive integer"
+
+The app's `CFBundleVersion` is not an integer (for example `0.0.3` or a git hash). It becomes `build_number`, which Sparkle compares numerically, so the server requires an integer. Fix the build so `CFBundleVersion` is a monotonic integer, or override for this publish:
+
+```bash
+./publish.sh MyApp.dmg --build-number <n>
+```
+
+### `publish.sh` reads the wrong or old version
+
+The script reads the app inside the artifact and prints what it read. Two causes:
+
+- The app inside the DMG is a symlink. The script refuses to follow it — it would read your installed copy instead. Build the DMG with a real copy of the app.
+- The DMG was built from a stale app. Rebuild the DMG.
+
+### "Build number N already exists"
+
+`build_number` is unique and permanent — it must increase every release anyway. Publish with a higher number.
+
+### HTTP 302, or "Access rejected the service token"
+
+Access redirected the request to its login page instead of admitting the service token. An email one-time-PIN policy alone does not admit service tokens.
+
+- Add a second policy on the admin Access application with action **Service Auth** that includes your token.
+- If the stored credentials are wrong, re-enter them with `./publish.sh <artifact> --reset-token`.
+- Confirm the token lives in the same Cloudflare account as the Access application.
+
+The service-token setup is covered in [Publish](../operate/publish.md).
+
+### `hdiutil: Resource busy`
+
+Normally handled — `publish.sh` mounts the DMG at a random mount point. If you mounted the DMG manually, eject it first.
+
+## The feed and testers
+
+### A user gets no updates
+
+Check these in order:
+
+- **No channel anywhere.** A user with no channel receives nothing, and a build linked to no channel is served to no one through channel resolution (a pin can still serve it). Attach both to a channel — see [Channels](../operate/channels.md).
+- **Pinned below what they run.** Sparkle cannot downgrade — an item below the installed version is never offered. A pin below the installed build never lands — the pin overrides the channel, and Sparkle ignores the lower item. Roll forward: republish that code under a higher build number and re-pin, or unpin so channel resolution resumes.
+- **Revoked token.** The feed serves an informational "Access renewal" notice instead of an update. Once you reissue and the user re-activates, updates resume without a reinstall.
+
+### `/get` returns 404
+
+An unknown or revoked token gets An unknown, malformed, or revoked token gets the identical generic 404.. **This is by design** — the response reveals nothing about whether a token exists. Compare the token against the link on that user's page in the admin; a revoked user needs a reissued link.
+
+## Local dev
+
+### Local state is stuck (migrations fail, stale data)
+
+Wipe the local D1/R2 state and start clean:
+
+```bash
+./deploy/dev.sh --reset
+```
+
+When local migrations fail, the CLI prints this hint itself: retry with `--reset` — a stuck local state can block them.
+
+### "port 8787 is already in use"
+
+An orphaned `workerd` from a prior Ctrl-C'd run usually still holds the port; wrangler does not report the collision itself, so the CLI checks before starting. Free the port or pick another:
+
+```bash
+pkill -f workerd
+# or
+./deploy/dev.sh --port <n>
+```