everyapp 0.2.2 → 0.3.0-rc.2

package/skills/everyapp/setup/remote-mcp.md

@@ -0,0 +1,199 @@
+# A remote MCP server as an MCP app
+
+Any remote MCP server that speaks Streamable HTTP (a docs search, a
+company's API, a SaaS tool's MCP endpoint) can become an MCP app of the
+Gateway's: `pnpm everyapp mcp add <url>` registers it, the Gateway serves its
+tools on its own `/mcp` to every member it is granted to as `<id>_<tool>`,
+holds the server's credential itself (a Gateway setting, never sent to an AI
+client), sends it only to the server's origin, and attributes, audits and
+counts every call like an app's. A read-only connection sees only the tools
+whose risk is `read`. At the end the person has the app on, its credential
+set and pinned to the server's origin, the people who need it granted, and
+one tool call through the Gateway's `/mcp` that worked.
+
+## Settings
+
+| NAME                                                                                  | required or optional                          | what it holds                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<ID>_MCP_TOKEN` (the app id upper-cased, `-` as `_`; `--secret` picks another name ending in `_MCP_TOKEN`) | required, unless the server takes no credential (`--auth none`) | What the server's docs call its API key, token or password. `--auth bearer` sends it as `Authorization: Bearer <value>`; `--auth header --header X-Api-Key` as `X-Api-Key: <value>`; `--auth basic` takes `user:password` and sends HTTP Basic. |
+
+The name is a Gateway setting like any provider key, set with
+`pnpm everyapp secret set <NAME>` (any name ending in `_MCP_TOKEN` goes to the
+Gateway; nothing else is accepted for it). When it is set, the CLI pins it to
+the origin of the MCP app that declares it (`https://treg.to` for
+`https://treg.to/mcp/`): the Gateway sends a credential only to the origin it
+was set for. A server re-pointed or re-added at another address needs its
+credential set again; only the operator (the Cloudflare login) can, so an
+owner or admin who changes an app in the Gateway never moves a credential.
+`mcp list` and `mcp show` say "needs setup" until it is set and pinned.
+
+`--auth oauth` is accepted and recorded, but the Gateway doesn't sign in to
+MCP servers with OAuth this week: such an app serves no tools ("OAuth: not
+supported yet"). If an OAuth server also takes an API key, add it with
+`--auth bearer` instead.
+
+## Costs and plans
+
+Every App charges nothing for an MCP app. The server's provider charges what
+it charges for its calls (its own plan and limits apply; read them on its
+site). Every forwarded call is counted in the organization's usage as
+`mcp:<id>`, and an owner or admin can cap an app's calls per month in Admin →
+Usage (off by default): past the cap a tool answers a tool error naming it
+until the next UTC month.
+
+## Only a person can
+
+- Create an account with the server's provider and accept its terms, when it
+  has any.
+- Create the API key or token on the provider's dashboard and type it at the
+  hidden prompt.
+- Decide who gets the app beyond the owners and admins (Admin → Apps → Manage
+  access), and whether a tool the server says is safe should count as a write
+  (you suggest; they decide).
+- Decide to replace a credential the Gateway already holds.
+
+## Before you start
+
+1. `pnpm everyapp status --json`: `data.installed` and `data.claimed` are
+   true; `data.gatewayUrl` is `https://<gateway host>`. Not installed, or no
+   owner: [gateway.md](gateway.md) first.
+2. The server's MCP address and how it authenticates, from its docs: an
+   `https://` URL (often ending in `/mcp`) that speaks Streamable HTTP. An old
+   HTTP+SSE-only endpoint (a separate `/sse` URL from 2024) isn't served. The
+   credential is usually an API key sent as a bearer token; some servers read
+   a header of their own (`X-Api-Key`); public servers take none. The
+   Gateway follows no redirects, so use the address the server answers at,
+   not one that redirects to it.
+3. `pnpm everyapp mcp list --json`: the server isn't added already (no entry
+   in `data.apps` with its `url`). The id is the domain's name, the label
+   before its suffix (`https://mcp.deepwiki.com/mcp` → `deepwiki`,
+   `https://treg.to/mcp/` → `treg`), or `--name <id>` (lowercase letters,
+   digits and hyphens, at most 32 characters); it is the tools' prefix, so
+   keep it short.
+
+## Steps
+
+One step per message: give the step, wait for the words it ends with
+("done", "I have it"), then the next.
+
+1. **You:** add it. `pnpm everyapp mcp add <url> --auth bearer --json` (or
+   `--auth header --header <name>`, `--auth basic`; nothing for a public
+   server), with `--name <id>` when the host name makes a poor id and
+   `--risk read` for a server that only reads and doesn't say so in its tool
+   annotations (`--risk write` treats every tool as a write). The app is on
+   at once for the person running it (when they are a member), the owners
+   and the admins. The `done` event's `data.id`, `data.key` (null for
+   `--auth none`; else the credential's `name` and whether it is `set` and
+   `bound` to the URL's origin) and `data.probe` (what one look at the server
+   from this machine found, without the credential) say what happened.
+   `PROVIDER_KEY_UNSET` means the credential comes next.
+   `REMOTE_MCP_PROBE_FAILED` and `REMOTE_MCP_WANTS_OAUTH` are warnings, never
+   refusals: a 401 with `--auth none` means the server wants a credential
+   (`pnpm everyapp mcp remove <id>`, then the same add with `--auth bearer`), a
+   redirect means another address, and "Couldn't reach" may be this
+   machine's network only (the Gateway fetches from Cloudflare).
+2. **Person:** the credential. They create the key on the provider's
+   dashboard, then, in a second terminal in the `every-app` folder:
+   `pnpm everyapp secret set <NAME>` (the name from step 1, for example
+   `pnpm everyapp secret set TREG_MCP_TOKEN`) and paste it at the hidden
+   prompt (for `--auth basic`, `user:password`). It ends with
+   `Set <NAME> on the Gateway`. When the person runs `mcp add` themselves at
+   a terminal, it asks `Set <NAME> now?` right after adding and, on yes, shows
+   the same hidden prompt (`secret set`'s own); No leaves it for `secret set`.
+   The README's other two ways work as for any `secret set` (a pipe into
+   `pnpm everyapp secret set <NAME> --json`, or the hidden read then
+   `--from-env <VAR>`); `mcp add <url> --auth bearer --from-env <VAR> --json`
+   takes the variable at the add itself, read before anything is written.
+   Wait for "done".
+3. **Person:** who gets it. The owners, the admins and whoever added it have
+   it already. Anyone else: Admin → Apps → the app's row → **Manage access**.
+   A member sees its tools after granting, in a client connected to the
+   Gateway (the next step).
+4. **Person:** connect an AI client to the Gateway if theirs isn't yet:
+   `claude mcp add --transport http everyapp https://<gateway host>/mcp`,
+   then `/mcp` → **everyapp** → **Authenticate** in Claude Code (other clients:
+   the same URL; mcp.md beside this folder, "Connecting a person").
+
+## Verify
+
+1. `pnpm everyapp mcp show <id> --json`: `data.status` is `"on"` (not
+   `"needs setup"`), `data.key.set` and `data.key.bound` are true and
+   `data.key.boundOrigin` is the URL's origin (all three skipped for
+   `--auth none`: `data.key` is null). `data.snapshot` is null until the
+   Gateway lists the tools, on the first request to its `/mcp` after the add
+   (or within the hour). From the checkout root,
+   `pnpm everyapp secret list --json` agrees: the name is in
+   `data.gateway.names`, its `data.gateway.mcpCredentials` entry has
+   `set: true`, and the app has left `data.apps` (it is listed there only
+   while it needs setup, with `setup.command` the `secret set` that sets it
+   up).
+2. One tool call through the Gateway: in the person's connected client, ask
+   for something the server does ("use <id> to …", or "list the tools <id>
+   offers"); the client shows a call to an `<id>_<tool>` tool and its
+   answer. On a Gateway with many tools the client may list them compactly:
+   then it finds them with `everyapp_search_tools` (`{ "app": "<id>" }`) and
+   runs one through `everyapp_call_read`. Then
+   `pnpm everyapp mcp show <id> --json` again: `data.snapshot.tools` is the
+   count listed and `data.tools[]` has each with its `name`, `serverName`,
+   `risk` and `source` (`hint`: the server's annotation; `default`: no
+   annotation, counted as a write; `app`: the `--risk` default;
+   `override`: yours).
+3. Risks, with the person: a tool the server marks read-only is callable by
+   every connection; one without a hint is a write (hidden from read-only
+   connections); one marked destructive is hidden from every client until
+   approvals exist. Change one with
+   `pnpm everyapp mcp tool <id> <tool> --risk read|write|destructive --json`
+   (`--risk annotations` drops the override), or leave a tool out entirely
+   with `--off`; the Gateway lists the tools again on first use.
+4. Logs, when a call fails: README's path (**Workers & Pages** →
+   `every-app-gateway` → **Observability** → **Live**). The remote proxy logs
+   each failed upstream call as `mcp.remote.upstream_failed` with the status
+   (never the credential), and a first-use pin as
+   `mcp.remote.credential_bound` (names from the design,
+   docs/design/2026-10-mcp-by-url.md; not checked against a live Gateway
+   here, unverified).
+
+## If it fails
+
+| error or symptom                                                       | meaning                                                                                                     | what to do                                                                                                                         |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `SECRET_VALUE_REQUIRED` from `secret set --json`                       | Nothing was piped and there is no terminal to prompt in                                                     | One of the README's three ways: the person's own terminal, a pipe, or `--from-env`                                                  |
+| `SECRET_EMPTY`                                                         | The `--from-env` variable is empty or not exported in that shell (from `mcp add --from-env`, nothing was added) | The hidden read (README's third way) in that same terminal first, then rerun                                                     |
+| `REMOTE_MCP_URL_REFUSED`                                               | Not `https://`, an IP address, the Gateway's own host or app domain, or a provider the Gateway holds a key for | The server's own MCP address, by host name, over https                                                                              |
+| `REMOTE_MCP_EXISTS`                                                    | That id is an MCP app already                                                                               | `pnpm everyapp mcp show <id>`; another address is `mcp remove <id>` then `mcp add` again, or another `--name`                       |
+| `REMOTE_MCP_SECRET_TAKEN`                                              | Another MCP app at another origin uses that credential name                                                 | `--secret <OTHER>_MCP_TOKEN`: one credential name per origin                                                                        |
+| `REMOTE_MCP_INVALID`                                                   | A bad id, risk, header or credential name, or flags that say two things                                     | As the message says                                                                                                                 |
+| `PROVIDER_APP_UNKNOWN`                                                 | The id isn't an MCP app here                                                                                | `pnpm everyapp mcp list` for the ids                                                                                                |
+| `REMOTE_MCP_SECRET_BOUND_ELSEWHERE` from `mcp add`, or `needs setup` in `mcp list` or `mcp show` with the key set | The credential is pinned to another origin (`data.key.boundOrigin`): it was set for an earlier server | `pnpm everyapp secret set <NAME>` again (Steps 2)                                                                  |
+| `REMOTE_MCP_TOOL_NOT_LISTED` from `mcp tool`                           | The tool's name isn't in the last listing: the override was kept under that name, as the server's           | `pnpm everyapp mcp show <id>` for both names, then `mcp tool` with the right one                                                    |
+| `REMOTE_MCP_SECRET_UNDECLARED` from `secret set`                       | No MCP app declares that name (a typo, or set before `mcp add`)                                             | Check the name with `mcp show <id>`; `mcp add` first                                                                                |
+| `REMOTE_MCP_WANTS_OAUTH`                                               | The server wants OAuth, which the Gateway doesn't do yet                                                    | If it also takes an API key: `--auth bearer` and set the key; otherwise it can't be served this week                                |
+| `REMOTE_MCP_GATEWAY_OUTDATED`                                          | The Gateway predates MCP apps by URL                                                                        | `pnpm everyapp update`, then Verify                                                                                                 |
+| `data.snapshot.status` `error`, `lastError` naming 401                  | The server rejected the credential                                                                          | A fresh key from the provider, `secret set` again, then `pnpm everyapp mcp refresh <id>`                                            |
+| `lastError` naming a redirect or a timeout                             | The address redirects, or the server is slow or down                                                        | The address it redirects to (remove, add again); a slow server: retry later                                                        |
+| The tools changed on the server, not on the Gateway                    | The Gateway's snapshot is up to an hour old                                                                 | `pnpm everyapp mcp refresh <id>`                                                                                                    |
+| A tool is missing for one person only                                  | Their connection is read-only (write tools hidden), or they weren't granted the app                         | Admin → Apps → Manage access; a read & write connection                                                                            |
+
+## Rerun, rotate, remove
+
+- **Rerun.** `mcp add` refuses an id that exists (`REMOTE_MCP_EXISTS`), so a
+  rerun starts from Verify. `secret set` replaces; `mcp tool` and
+  `mcp refresh` can run again.
+- **Rotate.** A new key on the provider's dashboard, then Steps 2 again: the
+  Gateway uses the new value on its next request. A value that went through
+  the chat is compromised: rotate it.
+- **Off, and back on.** `pnpm everyapp mcp off <id> --json` stops serving it
+  and keeps everyone's access, tokens and the snapshot;
+  `pnpm everyapp mcp on <id> --json` serves it again at once.
+- **Remove.** `pnpm everyapp mcp remove <id> --json`: a tombstone, with
+  everyone's access, its tokens and its place in AI connections gone (adding
+  it again starts fresh). The credential and its pin stay;
+  `pnpm everyapp secret unset <NAME> --json` removes both (it asks; with
+  `--json` add `--yes` only once the person said so). Then revoke the key on
+  the provider's side.
+
+## Sources
+
+- docs/design/2026-10-mcp-by-url.md (the remote block, the credential family and its pin, the proxy, the defaults taken)
+- In code: `packages/sdk/src/internal/remoteMcp.ts` (the URL, id, auth and risk rules: `remoteMcpUrlProblem`, `remoteMcpIdFromUrl`, `remoteToolRisk`), `packages/sdk/src/internal/gatewaySettings.ts` (`isRemoteMcpSecretName`: any name ending in `_MCP_TOKEN` is the Gateway's), `packages/sdk/src/internal/appSettings.ts` (the `remote-mcp` setting kind naming this file), `packages/perimeter/src/registry/remoteMcpApps.ts` (`planRemoteMcpAppAdd` and its refusals), `packages/cli/src/commands/provider/index.ts` (`mcp add`, `show`, `tool`, the probe's warnings), `packages/cli/src/lib/gateway/remoteMcpApps.ts` (the rows, the pin in `remote_mcp_credentials`), `packages/cli/src/commands/secret/index.ts` (the pin on `secret set`, dropped on `secret unset`), `apps/every-app-gateway/src/db/remote-mcp.schema.ts` (migration 0011)
+- https://modelcontextprotocol.io/specification (Streamable HTTP transport, tool annotations `readOnlyHint` and `destructiveHint`, authorization with `resource_metadata`)

package/skills/everyapp/setup/signin-apple.md

@@ -0,0 +1,178 @@
+# Sign in with Apple on the Gateway
+
+Read [README.md](README.md) first: the rules every setup follows.
+
+Puts **Continue with Apple** on the Gateway's sign-in page, beside the
+password. At the end the person has an App ID, a Services ID and a Sign in
+with Apple key in their Apple Developer account, the Gateway holds the
+Services ID and a client secret signed with that key, and they have signed
+in with Apple once. `pnpm everyapp signin show apple --json` names this
+file as `setup`, and the CLI prints
+`Guide: .claude/skills/everyapp/setup/signin-apple.md`.
+
+Who gets in doesn't change: Apple only says who someone is. A member signs
+in; someone with a pending invitation for that exact address joins with
+the invited role; everyone else is refused ("You don't have an account on
+this gateway.") and nothing is created. Someone who picks **Hide My
+Email** on Apple's sheet arrives as a `@privaterelay.appleid.com` address
+that no invitation names: ask them to pick **Share My Email**, or invite
+the relay address. The rules: `docs/runbooks/sign-in-providers.md`.
+
+Apple differs from the others twice. The client secret is not copied from
+a page: it is a JWT you sign with the key, valid six months at most, so
+it must be generated again before then or sign-in stops. And Apple returns
+to the Gateway with a POST; behind Cloudflare Access, `everyapp access on`
+leaves `/api/auth/callback/apple` open for it (Verify 4).
+
+## Settings
+
+| Name                         | Required | Flag                             | What it holds                                                                 |
+| ---------------------------- | -------- | -------------------------------- | ----------------------------------------------------------------------------- |
+| `APPLE_SIGNIN_CLIENT_ID`     | required | `--client-id <id>`               | the Services ID's identifier (`com.example.gateway`); not a secret            |
+| `APPLE_SIGNIN_CLIENT_SECRET` | required | `--client-secret-from-env <VAR>` | the ES256 JWT from step 5; expires within six months                          |
+
+Scopes asked for: `email name`. The email is the ID token's `email`,
+counted only when `email_verified` is true.
+
+## Costs and plans
+
+A paid Apple Developer Program membership: US$99 a year (Apple's
+fee-waiver page names the 99 USD fee; local prices vary), as an individual
+or an organization; enrolling an organization needs a D-U-N-S number and
+can take days. Sign in with Apple itself costs nothing more. Only the
+Account Holder or an Admin of the team can set up the identifiers.
+
+## Only a person can
+
+- Enroll in the Apple Developer Program and pay.
+- Create the App ID, the Services ID and the key in Certificates,
+  Identifiers & Profiles, and download the key's `.p8` file (once only).
+- Keep the `.p8` file safe: it is the only way to make the next secret.
+- Sign in with Apple to check it.
+
+## Before you start
+
+1. `pnpm everyapp status --json`: `data.installed` and `data.claimed` true;
+   `data.gatewayUrl` gives `<gateway host>`. Not installed or no owner:
+   [gateway.md](gateway.md) first. `data.access.on` true: see Verify 4.
+2. `pnpm everyapp signin show apple --json` (changes nothing; `Unknown
+   command signin`: `git pull` in the `every-app` folder). `data.status`
+   `off`: this file applies; `on`: it works, and only the secret may need
+   renewing (Rotate). `data.callbackUrl` is the Return URL,
+   `https://<gateway host>/api/auth/callback/apple`.
+3. Ask whether they have a paid Apple Developer membership, and their
+   Team ID (top right of https://developer.apple.com/account, or
+   Membership details: ten characters). The Team ID is not a secret.
+
+## Steps
+
+1. **You:** give the person `<gateway host>` and `data.callbackUrl`.
+2. **Person:** the App ID. https://developer.apple.com/account/resources/identifiers/list
+   → **+** → **App IDs** → **Continue** → **App** → **Continue** →
+   Description (`Every App`), Bundle ID **Explicit** (`com.<their domain
+   reversed>.everyapp`) → tick **Sign in with Apple** (as a primary App
+   ID) → **Continue** → **Register**.
+3. **Person:** the Services ID, which is the client id. Same page → **+** →
+   **Services IDs** → **Continue** → Description (people see it, for
+   example `Every App`), Identifier (`com.<their domain reversed>.gateway`;
+   not the App ID's) → **Continue** → **Register**. Open it from the list
+   (the filter top right switches to **Services IDs**) → tick **Sign in
+   with Apple** → **Configure** → Primary App ID: step 2's → the domain
+   `<gateway host>` and the return URL `data.callbackUrl` (Apple's help
+   calls the field **Website URLs**, a comma-separated list; some screens
+   show **Domains and Subdomains** and **Return URLs** apart) → **Done** →
+   **Continue** → **Save**. No file to upload to the domain.
+4. **Person:** the key. https://developer.apple.com/account/resources/authkeys/list
+   → **+** → Key Name (`Every App sign-in`) → tick **Sign in with Apple**
+   → **Configure** → step 2's App ID → **Save** → **Continue** →
+   **Register** → **Download** (one chance: the file is
+   `AuthKey_<Key ID>.p8`, in Downloads) → **Done**. The Key ID is in the
+   file name and on the key's page. They tell you the Key ID, the Services
+   ID, the Team ID and the file's full path (none of these is a secret;
+   the file's contents are, and nobody opens it). Labels in this step are
+   from Apple's general key steps plus the runbook (unverified on Apple's
+   Sign in with Apple key page, which was missing when checked).
+5. **You:** make the secret and set both at once, from the `every-app`
+   folder, in bash or zsh. The JWT goes straight into an environment
+   variable of the `signin add` process: it never appears on screen, on a
+   command line or in history. Never run the inner command on its own (it
+   prints the JWT) and never open the `.p8`. The key path must be absolute
+   (the command runs inside `packages/sdk`, which is where `jose` resolves).
+   ```sh
+   APPLE_SIGNIN_CLIENT_SECRET="$(APPLE_KEY_FILE=/Users/<them>/Downloads/AuthKey_<Key ID>.p8 APPLE_KEY_ID=<Key ID> APPLE_TEAM_ID=<Team ID> APPLE_SERVICES_ID=<Services ID> pnpm --filter @every-app/sdk exec node --input-type=module -e "import { importPKCS8, SignJWT } from 'jose'; import { readFileSync } from 'node:fs'; const e = process.env; const key = await importPKCS8(readFileSync(e.APPLE_KEY_FILE, 'utf8'), 'ES256'); process.stdout.write(await new SignJWT({}).setProtectedHeader({ alg: 'ES256', kid: e.APPLE_KEY_ID }).setIssuer(e.APPLE_TEAM_ID).setSubject(e.APPLE_SERVICES_ID).setAudience('https://appleid.apple.com').setIssuedAt().setExpirationTime('180d').sign(key))")" pnpm everyapp signin add apple --client-id <Services ID> --client-secret-from-env APPLE_SIGNIN_CLIENT_SECRET --json
+   ```
+   The JWT: header `alg` ES256, `kid` the Key ID; claims `iss` the Team ID,
+   `sub` the Services ID, `aud` `https://appleid.apple.com`, `iat` now,
+   `exp` 180 days out (Apple's limit is 15777000 seconds, about six
+   months). A wrong path or key fails inside `$(…)`, the variable is
+   empty and `signin add` stops with `SECRET_EMPTY`: nothing is written.
+   The done event's `data.status` is `"on"`.
+6. **You:** tell the person to set a reminder for five months from today
+   (Rotate), and to move the `.p8` out of Downloads into a password
+   manager or another safe place outside the repository: Apple never lets
+   it be downloaded again.
+
+## Verify
+
+1. `pnpm everyapp signin list --json`: the `apple` entry has `status:
+   "on"` and `missing` empty.
+2. The person's Apple ID address must be a member's or have a pending
+   invitation: `pnpm everyapp workspace invite <email>` for someone new.
+3. **Person:** private window, `https://<gateway host>/sign-in` →
+   **Continue with Apple** → sign in with the Apple ID → **Share My
+   Email** → **Continue** → the Gateway, signed in.
+4. Behind Cloudflare Access: the Apple address must be the one Access
+   knows the person by, and Access must let Apple's POST through. Run
+   `pnpm everyapp access show --json`: `data.applications.gateway.inSync`
+   false means the ring predates the Apple bypass; `pnpm everyapp access on --json`
+   adds it (also after `pnpm everyapp update`). A ring made by hand without
+   that bypass blocks Apple sign-in.
+5. Logs (README's Verify 4): `signin.config_problem` for a malformed or
+   missing setting.
+
+## If it fails
+
+| error or symptom | meaning | what to do |
+| --- | --- | --- |
+| no **Continue with Apple** button | a setting missing or malformed, or the version isn't live yet | `pnpm everyapp signin list --json`; logs' `signin.config_problem` |
+| Apple's page says the redirect URL or client is invalid (wording unverified) | the Return URL isn't exactly `data.callbackUrl`, or the client id isn't the Services ID | step 3; the client id is the Services ID's identifier, not the App ID |
+| `invalid_client` after Apple's sheet | the JWT is expired, signed with another key, or names another Team ID, Key ID or Services ID | step 5 again with the right values (Rotate) |
+| works for months, then stops | the JWT expired | Rotate |
+| Access's login page, or a 403, right after Apple's sheet | the outer ring blocks Apple's POST to `/api/auth/callback/apple` | `pnpm everyapp access on --json` |
+| "You don't have an account on this gateway." | the address (often a `@privaterelay.appleid.com` one) isn't a member's or invited | **Share My Email**, or invite the address Apple returns |
+| `SECRET_EMPTY` | the JWT command failed (path not absolute, wrong file, a typo in an id) | run step 5 again with corrected values; its stderr says what failed |
+| `SIGNIN_VALUE_REQUIRED` | unattended, and the client id is neither given nor set | `data.rerun`, with `--client-id <Services ID>` |
+
+## Rerun, rotate, remove
+
+- Rerun: step 5 any time; values given replace, settings not given are
+  kept.
+- Rotate, before six months pass: the same command with the same `.p8`,
+  leaving out `--client-id` (it is kept), or pipe the JWT into the one
+  setting (same environment variables and `node … -e "…"` as step 5):
+  `APPLE_KEY_FILE=… pnpm --filter @every-app/sdk exec node --input-type=module -e "…" | pnpm everyapp secret set APPLE_SIGNIN_CLIENT_SECRET --json`.
+  A lost `.p8`: the person makes a new key (step 4), revokes the old one,
+  and step 5 runs with the new Key ID.
+- Remove, only when asked: `pnpm everyapp signin remove apple --json --yes`
+  (`--yes` only when they said so). Accounts made with it stay. Then the
+  person revokes the key and deletes the Services ID in Apple's console.
+
+## Sources
+
+- https://developer.apple.com/documentation/accountorganizationaldatasharing/creating-a-client-secret
+  (the JWT's header and claims; at most 15777000 seconds; the page didn't
+  render when fetched, so the claim list is checked against the runbook
+  and the test below)
+- https://developer.apple.com/help/account/capabilities/configure-sign-in-with-apple-for-the-web
+  (Services ID → Sign in with Apple → Configure → primary App ID → Website
+  URLs → Done → Continue → Save; no domain file)
+- https://developer.apple.com/help/account/capabilities/about-sign-in-with-apple
+  (primary App ID; Account Holder or Admin)
+- https://developer.apple.com/help/account/keys/create-a-private-key
+  (Keys → +; download once, `.p8` in Downloads)
+- https://developer.apple.com/support/fee-waiver (the 99 USD yearly fee)
+- Step 5's command was run on 2026-10-24 against a throwaway P-256 key:
+  the JWT verified with `jose` (ES256, `kid`, `iss`, `sub`, `aud`, `exp -
+  iat` = 15552000), and pnpm prints nothing else on stdout.
+- `docs/runbooks/sign-in-providers.md` ("Apple") and
+  `packages/sdk/src/internal/signInProviders.ts`

package/skills/everyapp/setup/signin-cloudflare.md

@@ -0,0 +1,148 @@
+# Sign in with Cloudflare on the Gateway
+
+Read [README.md](README.md) first: the rules every setup follows.
+
+Puts **Continue with Cloudflare** on the Gateway's sign-in page, beside
+the password, for the members of the person's Cloudflare account. At the
+end the person has a private OAuth client in that account, its two
+settings on the Gateway, and has signed in with Cloudflare once.
+`pnpm everyapp signin show cloudflare --json` names this file as `setup`,
+and the CLI prints `Guide: .claude/skills/everyapp/setup/signin-cloudflare.md`.
+
+Who gets in doesn't change: Cloudflare only says who someone is. A member
+of the Gateway signs in; someone with a pending invitation for that exact
+address joins with the invited role; everyone else is refused ("You don't
+have an account on this gateway.") and nothing is created. An existing
+password account connects Cloudflare once, by signing in with the password
+when the page asks. The rules: `docs/runbooks/sign-in-providers.md`.
+
+**Keep the client private** (the default). Cloudflare's `/user` answer has
+no "verified" flag; the address is trusted only because a private client
+can be authorized by nobody but the Cloudflare account's members, who got
+in by accepting an invitation sent to that address. Making a client public
+is permanent and would let any Cloudflare user present an address nobody
+checked. Everyone outside the Cloudflare account uses another provider, a
+password, or Access's one-time PIN.
+
+Not the same as Access's "Sign in with Cloudflare" ([access.md](access.md)):
+that one is a login *in front of* the Gateway, at Cloudflare's edge, for
+every page and app. This one is a button *on* the Gateway's sign-in page,
+like Google's. Both can be on; with Access on, this button is rarely needed.
+
+## Settings
+
+| Name                              | Required | Flag                             | What it holds                                    |
+| --------------------------------- | -------- | -------------------------------- | ------------------------------------------------ |
+| `CLOUDFLARE_SIGNIN_CLIENT_ID`     | required | `--client-id <id>`               | the OAuth client's Client ID; not a secret       |
+| `CLOUDFLARE_SIGNIN_CLIENT_SECRET` | required | `--client-secret-from-env <VAR>` | the OAuth client's Client Secret, shown once     |
+
+Scope asked for: `user-details.read` (User Details Read), nothing an app
+could act with. The email is the Cloudflare API's `/user` `email`.
+
+## Costs and plans
+
+No price on Cloudflare's OAuth client page, and no plan named (free as far
+as checked; unverified). Creating a client needs the Super Administrator,
+Administrator or OAuth Client Write role on the account.
+
+## Only a person can
+
+- Sign in to the Cloudflare dashboard and create the OAuth client.
+- Copy the Client Secret off the screen (shown once).
+- Type it at the hidden prompt of `pnpm everyapp signin add cloudflare`.
+- Sign in with Cloudflare to check it; decide never to make the client
+  public.
+
+## Before you start
+
+1. `pnpm everyapp status --json`: `data.installed` and `data.claimed` true;
+   `data.gatewayUrl` gives `<gateway host>`. Not installed or no owner:
+   [gateway.md](gateway.md) first. `data.access.on` true: see Verify 4.
+2. `pnpm everyapp signin show cloudflare --json` (changes nothing;
+   `Unknown command signin`: `git pull` in the `every-app` folder).
+   `data.status` `off`: this file applies; `needs setup`: `data.missing`
+   says what is left (step 3); `on`: ask before replacing.
+   `data.callbackUrl` is `https://<gateway host>/api/auth/callback/cloudflare`.
+3. Ask who should use it: only people who are members of their Cloudflare
+   account can. For anyone else, suggest Google, Microsoft or the password.
+
+## Steps
+
+1. **You:** give the person `data.callbackUrl`.
+2. **Person:** in the Cloudflare dashboard, the account the Gateway runs
+   in: https://dash.cloudflare.com/?to=/:account/oauth-clients (or
+   **Manage Account** → **OAuth clients**) → **Create client**. Client name
+   (`Every App`); response type code, grant type **Authorization Code**;
+   token authentication method `client_secret_basic`; redirect URL the
+   exact URL from step 1 → **Continue** → scopes: **User Details Read**,
+   left **Required** (an optional one can be declined, and then sign-in
+   can't finish) → **Create client**. The page shows the **Client ID** and
+   the **Client Secret**, the secret only now. Leave its visibility
+   private: never **Change Visibility**.
+3. **Person:** in a second terminal in the `every-app` folder:
+   ```sh
+   pnpm everyapp signin add cloudflare
+   ```
+   It asks for the Client ID (shown as typed) and the Client Secret
+   (hidden: pasting works, nothing is echoed), and writes both in one new
+   Gateway Worker version, live on the next request. They tell you when
+   it's done.
+   Another way: in that terminal, the hidden read (bash or zsh:
+   `read -rs CLOUDFLARE_SIGNIN_CLIENT_SECRET && export CLOUDFLARE_SIGNIN_CLIENT_SECRET`;
+   fish: `read -s -x CLOUDFLARE_SIGNIN_CLIENT_SECRET`), paste, Enter, then
+   `pnpm everyapp signin add cloudflare --client-id <Client ID> --client-secret-from-env CLOUDFLARE_SIGNIN_CLIENT_SECRET --json`
+   and `unset CLOUDFLARE_SIGNIN_CLIENT_SECRET` (fish: `set -e CLOUDFLARE_SIGNIN_CLIENT_SECRET`).
+
+## Verify
+
+1. `pnpm everyapp signin list --json`: the `cloudflare` entry has `status:
+   "on"` and `missing` empty.
+2. The person's Cloudflare login address must be a Gateway member's or
+   have a pending invitation: `pnpm everyapp workspace invite <email>` for
+   someone new (who must also be a member of the Cloudflare account).
+3. **Person:** private window, `https://<gateway host>/sign-in` →
+   **Continue with Cloudflare** → Cloudflare's login → the consent screen
+   → allow → the Gateway, signed in.
+4. Behind Cloudflare Access: nothing else changes, but the Cloudflare
+   address must be the one Access knows the person by.
+5. Logs (README's Verify 4): `signin.config_problem` for a malformed or
+   missing setting.
+
+## If it fails
+
+| error or symptom | meaning | what to do |
+| --- | --- | --- |
+| no **Continue with Cloudflare** button | a setting missing or malformed, or the version isn't live yet | `pnpm everyapp signin list --json`; logs' `signin.config_problem` |
+| Cloudflare refuses the redirect (wording unverified) | the client's redirect URL isn't exactly `data.callbackUrl` | fix it on the client |
+| Cloudflare refuses someone at its consent screen | they aren't a member of the Cloudflare account (a private client) | invite them to the Cloudflare account, or they use another way in |
+| the Gateway refuses after consent, or the profile can't be read | **User Details Read** missing or made optional and declined | edit the client: the scope, **Required** |
+| "You don't have an account on this gateway." | their Cloudflare address isn't a member's or invited | `pnpm everyapp workspace invite <email>` with the Cloudflare address |
+| `SIGNIN_VALUE_REQUIRED` / `SECRET_EMPTY` | unattended, a required setting neither given nor set / the env variable empty in that shell | `data.rerun` with the flag / the hidden read again in the same terminal |
+| Create client is missing or refused | the person's role on the account lacks OAuth Client Write | an Administrator creates it, or grants the role |
+
+## Rerun, rotate, remove
+
+- Rerun: `pnpm everyapp signin add cloudflare` any time; values given
+  replace, settings not given are kept (Enter at a prompt keeps it).
+- Rotate: rotate the secret on the client's page in the dashboard (a lost
+  secret can only be rotated), then `pnpm everyapp signin add cloudflare`
+  with Enter at the Client ID prompt, or the hidden read and
+  `pnpm everyapp signin add cloudflare --client-secret-from-env CLOUDFLARE_SIGNIN_CLIENT_SECRET --json`.
+- Remove, only when asked: `pnpm everyapp signin remove cloudflare --json --yes`
+  (`--yes` only when they said so). Accounts made with it stay. Then
+  delete the client in **Manage Account** → **OAuth clients**.
+
+## Sources
+
+- https://developers.cloudflare.com/fundamentals/oauth/create-an-oauth-client/
+  (Manage Account → OAuth clients → Create client; the three roles;
+  Authorization Code only; `client_secret_basic`; Required scopes; secret
+  shown once; private by default, public permanent, Change Visibility; no
+  price on the page)
+- https://developers.cloudflare.com/api/resources/user/methods/get/
+  (`GET /user`, User Details Read)
+- https://better-auth.com/docs/authentication/cloudflare (`/user` for the
+  email; keep `user-details.read` required)
+- `docs/runbooks/sign-in-providers.md` ("Cloudflare", "Sign in with
+  Cloudflare: Access's identity provider versus this") and
+  `packages/sdk/src/internal/signInProviders.ts`