alpha-gate 0.1.0

package/docs/maintain/updating.md

@@ -0,0 +1,92 @@
+# Updating Alpha Gate
+
+How to keep the tool itself up to date on your deployed instances.
+
+## How you learn about a release
+
+The deployed admin Worker runs a daily cron (12:00 UTC) that polls the npm registry for this
+package's latest version (`registry.npmjs.org/<name>/latest`) and compares it against its baked-in
+`TOOL_VERSION` — the version of the package that deployed it. When a newer version exists:
+
+- the admin dashboard shows an attention item: *Alpha Gate \<version> is available*, with a
+  release notes link;
+- the Settings page's **Self-update** row shows a `<version> available` tag; when the instance is
+  current it reads *up to date* with a last-checked time instead. A fresh deploy shows
+  *not checked yet* until the cron first fires, within 24 hours.
+
+If email is configured, the instance also sends one notice per new version to the `--email-from` address; route that mailbox to yourself to receive it.
+
+**The Worker only notifies — it never deploys itself.** Self-deployment would require a privileged
+Cloudflare API token on the edge, which the design forbids. Updating is always an operator-run
+`deploy`, so migrations happen with a human in the loop.
+
+## Update from npm
+
+```bash
+npx alpha-gate@latest deploy --instance <slug>
+```
+
+`@latest` fetches the newest published version; the rest is an ordinary re-deploy. To pin a
+specific version, name it: `npx alpha-gate@0.1.0 deploy --instance <slug>`.
+
+## Update from a clone
+
+```bash
+git pull
+./deploy/deploy.sh --instance <slug>
+```
+
+Re-running `deploy.sh` updates the instance in place. The clone runs whatever `main` you pulled,
+which may be ahead of the npm release.
+
+## What a re-deploy preserves
+
+A re-deploy is idempotent. It reuses the existing D1 database and R2 bucket, applies any pending
+migrations, and redeploys both Workers. Preserved across updates:
+
+- all data: users and their tokens, builds, channels, logs, the audit chain;
+- your email settings and Access secrets — they are remembered in the deploy state directory of the channel you deployed with (`.deploy/` in a clone, `~/.alpha-gate` for npm), so a bare re-run through that same channel keeps them. An update through the other channel finds no remembered flags and quietly reverts invites to copy-paste; pass `--email-provider`/`--email-from` (or `--access-team-domain`/`--access-aud`) again when you switch channels or want to change them. Pass
+  `--email-provider`/`--email-from` or `--access-team-domain`/`--access-aud` again only to change
+  them.
+
+Nothing about a routine update requires a backup, but taking one first is cheap — see
+[Backup](backup.md).
+
+## Breaking releases
+
+When an upgrade needs manual steps, the release is marked breaking. The dashboard banner adds
+*Includes breaking changes.* and the Settings tag reads `<version> available (breaking)`.
+
+**When the banner says breaking, read the release notes before you run deploy.** The banner's
+*Release notes* link points at the changelog; it lists the manual steps. Take a
+[backup](backup.md) before a breaking update.
+
+## Forks
+
+A fork should not track upstream's npm package. Point the update check at your own manifest by
+setting `UPDATE_MANIFEST_URL` when you deploy — the URL is baked into the Worker at deploy time and
+is read from the environment on every deploy run, so set it each time (or export it in your shell):
+
+```bash
+UPDATE_MANIFEST_URL=https://registry.npmjs.org/<your-package>/latest \
+  ./deploy/deploy.sh --instance <slug>
+```
+
+The URL can be your own package's `/latest` endpoint, or any static JSON in the shape of the
+repo's `release.json`:
+
+```json
+{
+  "latest": "0.1.0",
+  "min_supported": "0.1.0",
+  "notes_url": "https://<your-host>/CHANGELOG.md",
+  "breaking": false
+}
+```
+
+Keep `latest` in sync with your `package.json` version on every release; set `breaking: true` when
+an upgrade needs manual steps. Until the manifest URL resolves, the check fails quietly and the
+banner stays silent. Settings still shows a last-checked time — the timestamp records that the
+check ran, not that it found anything.
+
+Next: [Teardown](teardown.md)

package/docs/operate/add-users.md

@@ -0,0 +1,55 @@
+# Adding users
+
+How to create a user in the back office and get their private download link to them.
+
+## Add a user
+
+Open the **Users** page. The *Add user* form takes three fields:
+
+- Email — required.
+- Label — optional, a short note shown next to the email in the user list (e.g. "design partner").
+- Channel — optional, the channel the user is assigned to on creation. The default is "— none —".
+
+**A user with no channel receives no updates until you assign one.** The form warns about this, and the Overview page lists such users as routed nowhere. Leave the channel empty only if you mean to.
+
+Press *Create invite*.
+
+## The invite page
+
+Creating the user lands you on a page titled "Invite ready". It shows the private link and, when the invite was not emailed, a ready-to-send message:
+
+- *Private link* — the user's `https://<app-host>/get?token=<token>` URL, with a one-click *Copy link* button.
+- *Message to send* — your invite template filled in with the link, with a *Copy message* button. Edit the template under Settings in the *Invite email template* fieldset; it supports `{app_name}`, `{get_url}`, and `{token}`, and feeds both the copy-paste message and real email.
+
+The link is durable while the token is active: the user revisits it to re-download or re-activate. You can retrieve it any time from the *Invite link* section of the user's page — viewing it never changes the token. Replacing the link is a separate, explicit action (*Reissue* on the user's page).
+
+On a deployed workers.dev instance the link carries the public host. On local dev or a custom domain the admin cannot derive the public host, and On a deployed workers.dev instance the link carries the public host. On local dev or a custom domain the admin cannot derive the public host, so the link carries the admin host instead — a user cannot open that one. The *Invite link* section of the user's page warns when this is the case; the invite page shows no warning, so check the host before sending. — a user cannot open that one.
+
+## What the user sees
+
+The link opens the branded download page (`/get`) on the public host. It carries three things, in order:
+
+1. A *Download* button for the build their channel currently serves.
+2. An *Activate* button — a deep link of the form `<scheme>://activate?token=…` that hands the token to the installed app. The scheme comes from the *Activate URL scheme* setting and must match the URL scheme your app registers.
+3. The access key — the raw token, with the instruction to paste it in the app if Activate doesn't open it.
+
+Below that, the page lists the steps: download and install the app, launch it, click Activate (or paste the key) to connect updates. Wiring the app side of this is covered in [Activation](../integrate/activation.md).
+
+## Access requests
+
+The public host also serves a request page at `/access`: an email field and a *Request access* button. The page is public — any visitor can submit an email address; nothing is granted automatically.
+
+Submissions appear under **Requests** in the admin nav — a count chip shows when any are waiting, and the Overview lists them under *Needs attention*. Each request offers two actions:
+
+- *Invite* creates the user and shows the same invite page as *Add user*. If the email belongs to an existing user, Invite issues a fresh token — the old link and any activated install stop working until re-activated — and reactivates them if they were revoked. There is no confirmation step, unlike Reissue on the user's page.
+- *Dismiss* clears the request without creating a user.
+
+A user created from a request has no channel — open their page and assign one. Duplicate requests from the same email are grouped ("asked N times"); the requester sees a confirmation page but receives no email, so repeats are normal. Inviting or dismissing resolves every request from that email at once.
+
+## Sending the invite
+
+Copy-paste is the default and needs no setup: copy the link or the filled message from the invite page and send it however you already talk to the user — chat, email, anything..
+
+With email delivery configured, adding a user or inviting a request sends the invite automatically, and the invite page confirms it was emailed — the link shown is the same one they received. A failed send never blocks user creation; the page shows the failure reason and falls back to the copy-paste link. See [Email](email.md) to set it up.
+
+Next: [Publish a build](publish.md)

package/docs/operate/channels.md

@@ -0,0 +1,54 @@
+# Channels
+
+Release channels group users and builds: this page covers creating a channel, linking builds, assigning users, pinning a user to one build, and the guard against leaving any user with no servable build.
+
+## The model
+
+A channel serves its **highest available linked build** to every user assigned to it. Link order does not matter: the linked build with the largest build number that is not withdrawn is what the channel offers.
+
+Users and builds can be on several channels at once. A user on more than one channel is offered the highest available build across all of them — the user page's Channels section says so next to the list.
+
+Two states serve nothing. A build linked to no channel is offered to no one — unless a user is pinned to it, since a pin ignores channels. A user assigned to no channel (and not pinned) gets an empty feed, and their app reports up to date; the back office surfaces both: a "no channel" warning on the user, and "In no channel — offered to no one" on the build.
+
+## Create a channel
+
+On the Channels page, the Add channel section takes a name (`stable` and `beta` are typical) and the Create channel button creates it. Names are unique; a duplicate is rejected with a clear error.
+
+The Channels list shows what each channel is serving, with a **"serving nothing"** warning when no available build is linked.
+
+## Link builds
+
+Open the channel. The "Builds in this channel" section lists linked builds, each with an Unlink button. Below it, the "Builds to link" picker is a type-to-filter multi-select (type a build number or version); Link builds links every selected one.
+
+Linking is **additive** — it can only raise what the channel serves, so it never asks for confirmation. You can also put a build into a channel at publish time, with `--channel <name>` or the Upload page's Channel field; see [Publishing](publish.md).
+
+## Assign users
+
+On the same page, the "Users in this channel" section lists assigned users with their next-check verdict, each with an Unassign button. The "Users to assign" picker (type an email) is also multi-select; Assign users adds every selected one. Assigning is additive and needs no confirmation.
+
+You can also pick the first channel when creating a user — the Add user form has a Channel field. See [Add users](add-users.md).
+
+## Pinning
+
+A pin holds one user to one exact build. It lives on the user's page, in the Pin section: pick a build in the "Build to pin" picker and press Pin to build. **A pin overrides channels entirely** — while pinned, the user's channels are ignored, and Unpin restores normal channel flow.
+
+Sparkle cannot downgrade, which shapes two cases:
+
+- A pin below the build the user runs does not take effect through the updater. The feed still offers the pinned item; Sparkle discards anything lower than the installed version and reports up to date. A fresh install through the user's download link does serve the pinned build.
+- A pin to a withdrawn build serves nothing: the user gets an empty feed and does not fall back to their channels. The user page flags this ("pin serves nothing" on the next-check verdict, with "pinned build is withdrawn — unpin or re-pin") and the Pin section keeps the Unpin action.
+
+## The stranding guard
+
+Any change that could leave a user with no servable build (withdrawing a build, unlinking it from a channel, unassigning a user, pinning, unpinning) is confirmed, not blocked. When a user would be stranded, you get a confirmation page first. It names the action in plain words and **lists exactly which users** would be left with no available build; their apps will report up to date and receive nothing until a higher build reaches them. Confirm to proceed, or Cancel to return to the page you acted from.
+
+The remedy for a stranded user is one of: publish a higher build into their channel, assign a different channel, or adjust the pin.
+
+## Delete a channel
+
+The Delete channel action sits in the danger zone at the bottom of the channel's page and is **always confirmed**, even when nobody is stranded. Deleting unassigns every user and unlinks every build; the users and builds themselves are kept. When the deletion would strand anyone, the confirmation page includes that list.
+
+## Rollback
+
+Moving everyone off a bad build is not a channel operation. Sparkle cannot downgrade, so it is a roll-forward done at publish time: rebuild the previous good code with a higher build number, publish it into the affected channel, then withdraw the bad build. See [Rollback](publish.md#rollback).
+
+Next: [Publishing](publish.md)

package/docs/operate/email.md

@@ -0,0 +1,51 @@
+# Email
+
+How invites reach your users: copy-paste links by default, automated email through Cloudflare Email Service as the paid option.
+
+## The default: copy-paste
+
+Out of the box there is nothing to set up and **nothing leaves the Worker**. When you [add a user](add-users.md) or invite a request, the back office shows an invite page with two blocks, each with a one-click copy button:
+
+- **Private link** — the user's `/get` URL, with a Copy link button. The link is durable while the token is active; the user can revisit it.
+- **Message to send** — your invite template filled in for this user, with a Copy message button. Paste it into whatever you already use to reach them.
+
+The message body comes from the "Invite email template" on the Settings page; the same template feeds automated email once you enable it. In this mode the Email row on Settings reads "copy-paste links (no email sent)".
+
+## What automated email requires
+
+Automated delivery uses Cloudflare Email Service through a `send_email` binding on the admin Worker. It needs two things:
+
+1. The **Workers Paid** plan.
+2. A real, onboarded sending domain: in the Cloudflare dashboard, under Email → Email Routing, you add and verify SPF/DKIM DNS records for a zone you control.
+
+A `*.workers.dev` hostname cannot be the sending domain — you do not control its DNS. An account with no domain of its own stays on copy-paste. The sending domain does not need to serve the Workers — the instance can stay on `*.workers.dev`; the domain only needs to be onboarded for email in the same account.
+
+## Enable it
+
+Re-run deploy with the email flags:
+
+```bash
+./deploy/deploy.sh --instance <slug> --email-provider cloudflare --email-from alpha@<your-sending-domain>
+# from npm:
+npx alpha-gate deploy --instance <slug> --email-provider cloudflare --email-from alpha@<your-sending-domain>
+```
+
+`--email-from` is required when `--email-provider` is `cloudflare`. The deploy adds the `EMAIL` send_email binding to the admin Worker and sets the From address. The flags are remembered: a later bare re-run (`--instance <slug>` alone) keeps them, so you pass them again only when the address or provider changes. One asymmetry: there is currently no flag that turns email back off — `--email-provider none` reads as "not passed" and the remembered provider wins..
+
+After the deploy, reload Settings. The Email row should read "sending via Cloudflare" with your From address.
+
+## Test it
+
+Once email is active, Settings shows a "Test email delivery" section. Enter a recipient (it defaults to you) and press **Send test email**. It sends one email immediately and shows the exact result, so you can debug delivery without creating a user. If the send fails, run `wrangler tail` on the admin Worker to see the full provider error.
+
+## When a send fails
+
+A failed or misconfigured send **never blocks creating the user**. The user is written first; delivery is attempted after. If the email does not send, the invite page says so, names the reason, and still shows the link and message for you to send manually — the copy-paste path is always available.
+
+Misconfiguration behaves the same way. If the provider is set to Cloudflare but the `EMAIL` binding or the From address is missing, invites fall back to copy-paste instead of erroring. Settings flags this state as "misconfigured — falling back to copy-paste" and lists exactly what is missing.
+
+## The state-directory caveat
+
+The email flags live only in the local deploy state directory (`.deploy/` in a clone, `~/.alpha-gate` from npm), not in the database. If you lose that directory, a bare re-run of deploy regenerates everything else but quietly reverts invites to copy-paste. Pass `--email-provider cloudflare --email-from <address>` once more to restore delivery. The Email row on Settings is where you would notice the reversion.
+
+Next: [Backup](../maintain/backup.md)

package/docs/operate/monitoring.md

@@ -0,0 +1,56 @@
+# Monitoring
+
+This page explains how to read the back office: which build each user gets, what their apps have done, and whether the recorded history is intact.
+
+## The Overview
+
+The **Serving now** map draws one row per channel: the channel, the build it serves (its highest available linked build), and the audience. The audience cell summarizes the users on that channel — `all up to date`, or counts like `2 will update · 1 pinned`, or `1 faulted` when something is wrong. A channel with users but no available build shows `serving nothing — no build linked` and its users get an `empty feed`. Below the channels sits the **off the map** row: users routed nowhere (no channel, no pin) whose tokens work but whose checks resolve to nothing. **The map is computed from the same data and rules the public Worker resolves with, refined by each user's last-reported installed build — so what you see here is the effective outcome of their next check.**
+
+**Needs attention** lists every current fault as a cause in prose plus exactly one remedy link:
+
+- a stranded user (installed above everything their channels offer) → `Roll forward →`
+- a pin that serves nothing (withdrawn, or below the installed build) → `Review pin →`
+- a channel serving nothing to its users → `Link a build →`
+- users with no channel → `Assign a channel →` (or `Review users →` for several)
+- access requests waiting → `Review requests →`
+- an audit chain mismatch → `Inspect audit →`
+- a newer Alpha Gate release → `Details →` (update and re-deploy the instance)
+
+When nothing is wrong the section reads "Nothing needs attention — every active user is served."
+
+**Recent** merges tester activity and your own actions into one feed, newest first: lines like "mira@studio.dev checked — on **#1499**" sit next to "you withdrew build 1500". Under the feed, the audit chain status line reports `audit chain intact · N entries` (or a mismatch warning); it is the same judgment the Audit page shows.
+
+The page header carries the last-publish line: the newest build, the channels it went to (or "— in no channel"), and when. If that line does not match what you meant to ship, start there.
+
+## The Users list
+
+Each row answers the question you would otherwise have to reconstruct: what does this user's next update check do. The **Next check** column states it with its cause:
+
+| Next check shows | Meaning |
+| --- | --- |
+| gets `#1500 · v1.3.0` | Offered this build. A `pinned` tag means the pin decides; `critical` means Sparkle treats it as required. |
+| up to date · `#1500` | The served build is the one they already run. |
+| — not served while revoked | Revoked; checks receive a renewal notice until you reactivate. |
+| `no channel` | Assigned to no channel — resolves to nothing. |
+| `no build` | Their channels carry no available build. |
+| `pin serves nothing` | The pinned build was withdrawn; unpin or re-pin. |
+| `pin below installed` | The pin sits under their installed build; Sparkle cannot downgrade. |
+| `stranded` | Installed above everything their channels offer; roll forward. |
+
+**Installed** is the build number the user's app last reported. **Last seen** is their most recent event of any kind. Filter the list by status, channel, `needs attention`, `pinned`, or `show hidden`.
+
+## Activity
+
+The Activity page lists every check, download, and update: when, which user, which event, which build. Filter by user (any part of the email), event, or build number; the page shows the latest 100 events, so narrow with the filters when you need older ones. Entries older than 90 days are pruned daily. **The Downloads and Updates counts on the Builds page are computed from this log, so they cover the last 90 days — they are not all-time totals.**
+
+## Audit
+
+The Audit page lists every admin action: when, the actor, the action slug (for example `client.revoke`), the target, the request IP, and the Cloudflare Ray ID. Targets are emails and build numbers, not database row ids, so rows stay readable on their own. Filter by actor or action; the page shows the latest 200 actions.
+
+Each row is hash-chained to the one before it, and a daily job anchors the chain head to an append-only object in R2 (and emails it when email is configured). The status line above the table reports the live verdict: `chain intact · N entries · anchored`, `not yet anchored` before the first anchor has run, or `CHAIN MISMATCH — the log diverged from its last anchor`. **A mismatch means rows were edited, removed, or rebuilt.** Compare the log against the anchored copies in R2 and your Cloudflare account audit logs, Compare the log against the anchored copies in R2, the emailed anchors, and your Cloudflare account audit logs. The admin interface cannot rewrite any of them; overwriting the R2 copies would take Cloudflare account access, and even that cannot reach the emailed anchors or the account audit logs..
+
+## Activity vs Audit
+
+Activity records what your testers' apps did; Audit records what you did.
+
+Next: [Troubleshooting](../maintain/troubleshooting.md)

package/docs/operate/publish.md

@@ -0,0 +1,90 @@
+# Publish builds
+
+Ship a build with one command, from the browser, or from CI, and roll back a bad release.
+
+## The one command
+
+```bash
+./publish.sh MyApp.dmg --channel beta              # from a clone
+npx alpha-gate publish MyApp.dmg --channel beta    # from npm, same flags
+```
+
+The artifact is a `.dmg` or a signed `.app` `.zip`. Before you run it:
+
+- The artifact is already built, code-signed with Developer ID, notarized, and stapled. `publish.sh` does not build or notarize.
+- The app inside has an integer `CFBundleVersion` that increases every release. The server rejects non-integers; override a bad value with `--build-number <n>`.
+- Sparkle's `sign_update` is findable. The script auto-discovers it under Xcode's DerivedData; otherwise pass `--sign-update <path>`.
+
+What it does, in order:
+
+1. Reads `CFBundleShortVersionString`, `CFBundleVersion`, and `LSMinimumSystemVersion` from the app inside the artifact (mounting a DMG, or reading the plist out of a zip) and prints what it read.
+2. Pre-checks the build number and channel against the running instance, so a duplicate build number or a mistyped channel name fails in a second instead of after a multi-minute upload.
+3. Signs the artifact with `sign_update` to produce the Sparkle EdDSA signature.
+4. Uploads. Over 90 MB it switches to the register path on its own: it puts the bytes into R2 with your own `wrangler` auth, then registers the metadata. No extra token.
+
+When exactly one instance is deployed, the script targets it automatically; otherwise pass `--instance <slug>` or `--admin-url <url>`. Channels are named on the command line (`--channel beta`, never a database id); the channel must already exist (see [Channels](channels.md)). **One signed DMG serves both first-install and updates** — the `/get` download and the Sparkle enclosure are the same artifact, signed once.
+
+## The service token, the first time
+
+The admin Worker sits behind Cloudflare Access, so `publish.sh` authenticates with an Access service token. On the first publish to a real instance the script prints the steps and prompts for the credentials:
+
+1. Cloudflare Zero Trust → Access → Service Auth → "Create service token".
+2. On the admin Access application, add a policy (Action: Service Auth) allowing it.
+
+It stores the Client ID and Secret in your login Keychain, keyed by instance; every later run reads them without prompting. Pass `--reset-token` to forget the stored pair and enter a new one. Publishing to a `localhost` dev admin needs no token.
+
+## Useful flags
+
+| Flag | What it does |
+|---|---|
+| `--channel <name>` | link the build to a channel by name |
+| `--instance <slug>` | pick the instance when more than one is deployed |
+| `--admin-url <url>` | target an admin Worker directly (CI, or no local deploy state) |
+| `--sign-update <path>` | where `sign_update` lives (or set `$SIGN_UPDATE`); set `ED_SIGNATURE=<sig>` to skip signing entirely |
+| `--build-number <n>` | override the `CFBundleVersion` read from the app |
+| `--short-version <s>` | override the `CFBundleShortVersionString` read from the app |
+| `--min-os <version>` | override the `LSMinimumSystemVersion` read from the app |
+| `--critical` | mark the build as a critical update |
+| `--reset-token` | forget the stored service token and prompt again |
+| `--dry-run` | read and validate the artifact, print what would be published, upload nothing |
+
+## Browser upload
+
+The admin Upload page publishes without the script, up to the 90 MB upload ceiling; a larger archive takes the register path, which only the one command handles for you. Picking an archive autofills the version, build number, and minimum macOS from the app's `Info.plist`; the fields stay editable. **Autofill works only for a signed `.app` `.zip`** — a `.dmg` or `.tar` can't be read in the browser, so type those fields yourself.
+
+The page has two modes: New release and Roll back. Roll back shows the current highest build number and enforces it as a floor: a build number at or below it is rejected.
+
+## CI
+
+The same script runs headless on a macOS runner. Put the service token in the environment and pass `--admin-url`:
+
+```bash
+export CF_ACCESS_CLIENT_ID=<client-id>
+export CF_ACCESS_CLIENT_SECRET=<client-secret>
+./publish.sh dist/MyApp.dmg \
+  --admin-url https://alpha-gate-<slug>-admin.<account>.workers.dev --channel beta
+```
+
+A runner without a readable app bundle (a bare zip) passes `--build-number` and `--short-version` and sets `ED_SIGNATURE` from its own `sign_update` step. `.github/workflows/publish.yml` in the repository is a template: the publish step is complete, the build step is a deliberate placeholder — replace it with your app's build, sign, and notarize, then enable the tag trigger.
+
+## Rollback
+
+Sparkle cannot downgrade: an update below the installed version is never offered, so you cannot re-serve the old build as-is. Withdrawing a bad version is a roll-forward:
+
+1. Rebuild the previous good code with a **higher** `build_number` (keep the old `short_version`). Publish it into the affected channel — the Upload page's Roll back mode shows the current highest build as the floor and rejects anything at or below it.
+2. Open the bad build from the Builds list and withdraw it; the Withdraw action is in the danger zone on the build's page. Because the higher build exists, no one is stranded — installed apps move to the roll-forward build on their next check, and the serving map on the Overview page shows the switch immediately.
+
+## Verify end to end
+
+1. The build appears on the admin Builds page, with download and update counts.
+2. Invite yourself (see [Add users](add-users.md)), open your `/get?token=` link, install, activate, and let the app check for updates.
+3. The Activity log shows a `check` carrying your installed build, then a `download` or `update`. Activity older than 90 days is pruned, so the counts on builds cover the last 90 days, not all time.
+4. Ask the feed directly:
+
+   ```bash
+   curl "https://<app-host>/appcast?token=<TOKEN>" — leave `installed` off (or pass your real installed build number): a made-up value is recorded as that user's installed build in the admin until the app's next real check.
+   ```
+
+   The response should list an `<item>` for your build.
+
+Next: [Monitoring](monitoring.md)

package/docs/operate/remove-users.md

@@ -0,0 +1,47 @@
+# Removing users
+
+How to take access away, and how to give it back, using the actions on a user's page.
+
+All four actions live in the **Access** section at the bottom of the user's page (Users → click the email). Every one records an audit entry.
+
+## Revoke
+
+**Revoke access…** cuts the user off. What actually happens:
+
+- Their private download link stops working immediately. Every download routes through the gate, so there is no cached or pre-signed URL that keeps serving.
+- Their installed app stops receiving updates. On the next update check, Sparkle shows a reactivation notice instead of an update — an informational item, never an error. You can customize its title and message under Settings → "Access notice (revoked or unknown tokens)".
+
+Revoke is always confirmed before it runs, and it is **reversible**: the token is kept, not deleted. The user's page shows a `revoked` tag and warns that the invite link is dead until you reactivate.
+
+Revoking an already-revoked user does nothing and says so.
+
+## Reactivate
+
+**Reactivate** is the inverse of revoke. The stored token becomes valid again, so the same invite link starts working and the installed app resumes receiving updates on its next check. Nothing needs to be re-sent — the link the user already has is the one that revives.
+
+## Reissue
+
+**Reissue link…** rotates the token. Use it when a link leaked or was lost.
+
+- The old link stops working immediately.
+- The installed app's session dies with it — the app asks the user to re-activate.
+- A new invite link is minted. It must reach the user: it is emailed when email delivery is configured, otherwise the back office shows the link and message for you to copy and send.
+
+Reissue is always confirmed, because it kills a working setup even when nothing was wrong with it.
+
+For a revoked user the button reads **Reactivate with a fresh link…** and does both at once: it restores access and mints a new link, while the old link and any installed app token stay dead. (Reissue alone on a revoked user would mint a link that does not work — the flow prevents that.)
+
+## Hide
+
+**Hide from list** declutters the Users list. It does not touch access: a hidden user keeps downloading and updating exactly as before. The user's page shows a quiet `hidden` tag.
+
+The Users list has a "show hidden" checkbox that brings hidden users back into view; when some are hidden, the list also links to them ("N hidden not shown — show them"). **Unhide from list** reverses it.
+
+## Which one when
+
+- Pausing someone temporarily → **Revoke**.
+- They came back → **Reactivate** (same link keeps working).
+- Their link leaked or was lost → **Reissue**.
+- They left for good → **Revoke**, then **Hide** to keep the list clean.
+
+Next: [Channels](channels.md)

package/docs/setup/cloudflare-account.md

@@ -0,0 +1,41 @@
+# Prepare a Cloudflare account
+
+What to set up on Cloudflare before your first deploy, and what you can skip.
+
+## The free tier is enough
+
+Alpha Gate runs on Workers, D1, and R2, all covered by the free tier. There is **nothing to pre-create**: `deploy.sh` provisions the D1 database and R2 bucket itself. Sign up at cloudflare.com and move on.
+
+## Authenticate wrangler once
+
+The deploy CLI drives your account through wrangler. Grant it access from the machine you deploy from:
+
+```bash
+npx wrangler login        # opens a browser; grants this machine access to your account
+```
+
+For CI, set `CLOUDFLARE_API_TOKEN` instead of an interactive login.
+
+## Use a dedicated account (recommended)
+
+Whoever can open this account's Cloudflare dashboard can read the D1 database and R2 bucket
+directly, and the database rows include every tester's access token — the secret behind their
+`/get` link and update feed. **A dashboard user could therefore impersonate any tester.** Testers
+themselves never touch the database; the tokens are generated server-side when you add a tester, and
+a tester's app only talks to the public Worker. If other people share your Cloudflare account, put
+Alpha Gate in its own account so dashboard access does not equal tester access.
+
+## Set up Zero Trust now
+
+After deploy, you lock the admin behind Cloudflare Access, which lives in Cloudflare Zero Trust. The first time you open Zero Trust, Cloudflare makes you pick a **team name** and add a **payment method** before you can create Access applications — even on the free Zero Trust plan. You are not charged on the free plan, You are not charged on the free plan, whose 50-user limit counts only Zero Trust logins such as your admin email, not testers..
+
+Do this once now, at dash.cloudflare.com → Zero Trust, so the Access step after deploy does not stall on account setup.
+
+## What you do not need
+
+- No custom domain and no DNS. Everything runs on `*.workers.dev`.
+- No API token for deployment; `wrangler login` covers it (CI is the exception, above).
+
+One caveat for later: sending invite email automatically requires a real sending domain you control — a `*.workers.dev` hostname cannot be one. Copy-paste invite links work without it. See [Email](../operate/email.md).
+
+Next: [Deploy](deploy.md)

package/docs/setup/deploy.md

@@ -0,0 +1,84 @@
+# Deploy
+
+This page covers the first deploy of an instance, locking the admin behind Cloudflare Access, verifying the result, updating in place, and running more than one instance.
+
+## Run the deploy
+
+Both distribution forms take the same flags:
+
+```bash
+npx alpha-gate deploy --instance myalpha        # from npm; state in ~/.alpha-gate
+./deploy/deploy.sh --instance myalpha           # from a clone; state in .deploy/
+```
+
+The `--instance` slug (lowercase letters, digits, hyphens) namespaces every resource. To rehearse without touching your account, add `--dry-run` — wrangler is mocked and nothing is created.
+
+A run proceeds in four stages: a read-only preflight (Node ≥ 20, wrangler auth; any failure prints a `→` fix line), an inspect pass that reports which resources already exist, a confirm prompt ("Apply these changes?") showing the exact commands, then apply: create the D1 database and R2 bucket, apply migrations, and deploy both Workers. The command is idempotent; re-running updates in place.
+
+The run ends by printing two URLs; until Access is wired it also shows the dashboard checklist covering the Access step below.:
+
+- the app URL (`https://alpha-gate-myalpha.<account>.workers.dev`) — the public host your users and the Sparkle feed use;
+- the admin URL (`https://alpha-gate-myalpha-admin.<account>.workers.dev`) — the back office.
+
+### Guided first init
+
+On the first deploy of an instance, any branding value you do not pass as a flag is prompted (interactive runs only; `--yes` and `--dry-run` skip the prompts); press Enter to accept the default; press Enter to accept the default.
+
+- App name (`--app-name`).
+- Activate URL scheme (`--activate-scheme`) — **must match a `CFBundleURLSchemes` entry in your macOS app's Info.plist**, because the download page builds the activation deep link from it.
+- Short blurb (`--blurb`) and accent colour (`--accent`), both optional branding.
+
+These seed the instance so `/get` is correct immediately. After first init the admin Settings page owns these values; later deploys do not prompt for them.
+
+## Lock the admin behind Cloudflare Access
+
+**The admin URL rejects every request until you complete this step** — the Worker fails closed while the Access secrets are unset. Enabling Access is what makes the admin usable. It is the one manual dashboard action; there is no wrangler command for enabling Access. It is the one manual dashboard action; there is no wrangler command for enabling Access.
+
+The first time you use Zero Trust, Cloudflare makes you pick a team name and, even on the free Zero Trust plan, add a payment method before you can create Access applications. Cloudflare makes you pick a team name and, even on the free Zero Trust plan, add a payment method before you can create Access applications. You are not charged on the free plan, which covers up to 50 seats — only the admin emails you allowlist into Access count against it, never your testers (they authenticate with tokens, not Access).
+
+1. Dashboard → Workers & Pages → the `alpha-gate-myalpha-admin` Worker → Settings → Domains & Routes → enable Cloudflare Access. Cloudflare creates a self-hosted Access application for the admin hostname.
+2. Edit that application's policy: action Allow, include Emails → your email, identity method One-time PIN. Cloudflare emails a login code; no external identity provider is needed.
+3. Feed two values back to deploy, which sets them as secrets and redeploys for you:
+   - Team domain — Zero Trust → Settings, e.g. `yourteam.cloudflareaccess.com` (the bare domain, no `https://`).
+   - AUD tag — Access → Applications → your app → Overview → Application Audience (AUD).
+
+```bash
+./deploy/deploy.sh --instance myalpha \
+  --access-team-domain yourteam.cloudflareaccess.com --access-aud <AUD>
+```
+
+An interactive first deploy offers this at the end of the run: it prints the dashboard steps, waits, then probes the admin URL to detect the team domain from the login redirect and prompts for the AUD — no re-run needed.
+
+The Worker verifies the Access JWT itself and fails closed: while these secrets are unset, every admin request is rejected.
+
+## Verify
+
+- Open the admin URL and log in with the one-time PIN. The root path redirects to `/admin`, the Overview page; the serving map shows each channel and what it offers (empty until you publish).
+- Open the app URL's `/get` without a token. It returns a generic 404. That is by design — no token, nothing leaked.
+- Open Settings. The "This instance" panel shows the Instance slug, the Email status, and your Access team and Access AUD, confirming the secrets landed.
+
+## Update in place
+
+From npm:
+
+```bash
+npx alpha-gate@latest deploy --instance myalpha
+```
+
+From a clone: `git pull`, then re-run `./deploy/deploy.sh --instance myalpha`.
+
+Either way the existing D1 database and R2 bucket are reused, pending migrations are applied, and both Workers are redeployed. Users, their tokens, builds, channels, and logs are preserved. **Email and Access settings are remembered** — a bare re-run keeps them; pass the flags again only to change them.
+
+A daily cron polls the npm registry for a newer Alpha Gate release. When one exists, the Overview shows a banner ("Alpha Gate <version> is available") and Settings shows it in the Self-update row, along with when the last check ran. A fork can point `$UPDATE_MANIFEST_URL` at its own package or a static `release.json` at deploy time.
+
+## Multiple instances
+
+Re-run with another slug:
+
+```bash
+./deploy/deploy.sh --instance staging
+```
+
+Every resource is independent per instance: the D1 database, the R2 bucket, both Workers, the Access application, and the local state under `.deploy/<slug>.*` (or `~/.alpha-gate` for the npm form). Repeat the Access step for each instance.
+
+Next: [Sparkle integration (Swift)](../integrate/sparkle-swift.md)