everyapp 0.2.2 → 0.3.0-rc.2

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

@@ -0,0 +1,139 @@
+# Sign in with GitHub on the Gateway
+
+Read [README.md](README.md) first: the rules every setup follows.
+
+Puts **Continue with GitHub** on the Gateway's sign-in page, beside the
+password. At the end the person has a GitHub OAuth App, its two settings
+on the Gateway, and has signed in with GitHub once.
+`pnpm everyapp signin show github --json` names this file as `setup`, and
+the CLI prints `Guide: .claude/skills/everyapp/setup/signin-github.md`.
+
+Who gets in doesn't change: GitHub only says who someone is, by their
+primary address, and only when GitHub marks it verified. 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. An existing password account
+connects GitHub once, by signing in with the password when the page asks.
+The rules: `docs/runbooks/sign-in-providers.md`, "Who gets in".
+
+An **OAuth App**, not a GitHub App: the two live side by side under
+Developer settings, and only an OAuth App fits here.
+
+## Settings
+
+| Name                          | Required | Flag                             | What it holds                                  |
+| ----------------------------- | -------- | -------------------------------- | ---------------------------------------------- |
+| `GITHUB_SIGNIN_CLIENT_ID`     | required | `--client-id <id>`               | the OAuth App's Client ID; not a secret        |
+| `GITHUB_SIGNIN_CLIENT_SECRET` | required | `--client-secret-from-env <VAR>` | a client secret generated on the OAuth App     |
+
+Scopes asked for: `read:user user:email`. The email is the person's
+primary address from GitHub's emails API, counted only when verified.
+
+## Costs and plans
+
+Free, on any GitHub account. An OAuth App can belong to the person's own
+account or to an organization they administer (up to 100 per owner); an
+organization owner keeps it from depending on one person.
+
+## Only a person can
+
+- Sign in to GitHub and register the OAuth App.
+- Generate the client secret and copy it off the screen.
+- Type the secret at the hidden prompt of `pnpm everyapp signin add github`.
+- Sign in with GitHub 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 github --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 4); `on`: ask before replacing. `data.callbackUrl` is
+   `https://<gateway host>/api/auth/callback/github`.
+3. Ask whether the app should belong to their own account or to an
+   organization they administer.
+
+## Steps
+
+1. **You:** give the person `data.callbackUrl`.
+2. **Person:** open https://github.com/settings/developers (for an
+   organization: the organization's **Settings** → **Developer settings**
+   → **OAuth Apps**) → **New OAuth App** (**Register a new application**
+   when there is none yet). Application name (people see it, for example
+   `Every App`), Homepage URL `https://<gateway host>`, **Authorization
+   callback URL** the exact URL from step 1. Leave **Enable Device Flow**
+   off. **Register application**. The app's page shows the **Client ID**.
+3. **Person:** on that page, **Generate a new client secret** (GitHub may
+   ask for their password or 2FA again). The secret is shown once; keep
+   the page open for step 4.
+4. **Person:** in a second terminal in the `every-app` folder:
+   ```sh
+   pnpm everyapp signin add github
+   ```
+   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 GITHUB_SIGNIN_CLIENT_SECRET && export GITHUB_SIGNIN_CLIENT_SECRET`;
+   fish: `read -s -x GITHUB_SIGNIN_CLIENT_SECRET`), paste, Enter, then
+   `pnpm everyapp signin add github --client-id <Client ID> --client-secret-from-env GITHUB_SIGNIN_CLIENT_SECRET --json`
+   and `unset GITHUB_SIGNIN_CLIENT_SECRET` (fish: `set -e GITHUB_SIGNIN_CLIENT_SECRET`).
+
+## Verify
+
+1. `pnpm everyapp signin list --json`: the `github` entry has `status:
+   "on"` and `missing` empty.
+2. The person's GitHub primary address (https://github.com/settings/emails,
+   marked Primary, not Unverified) 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 GitHub** → **Authorize** on GitHub's page → the
+   Gateway, signed in.
+4. Behind Cloudflare Access: nothing else changes, but the GitHub primary
+   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 GitHub** button | a setting missing or malformed, or the version isn't live yet | `pnpm everyapp signin list --json`; logs' `signin.config_problem` |
+| `redirect_uri_mismatch`: "The redirect_uri MUST match the registered callback URL for this application." | the Authorization callback URL isn't exactly `data.callbackUrl` | fix it on the OAuth App's page → **Update application** |
+| "The sign-in provider hasn't verified this email address." | the primary address is unverified at GitHub | the person verifies it in GitHub's Emails settings, or makes a verified one primary |
+| "You don't have an account on this gateway." | the primary address isn't a member's or invited | invite that address (people often sign up to GitHub with a personal one) |
+| `incorrect_client_credentials` | the secret doesn't belong to this Client ID | Rotate |
+| `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 |
+| `SIGNIN_FLAG_NOT_APPLICABLE` | `--tenant`, `--issuer` or `--label` given for GitHub | drop it |
+
+## Rerun, rotate, remove
+
+- Rerun: `pnpm everyapp signin add github` any time; values given replace,
+  settings not given are kept (Enter at a prompt keeps it).
+- Rotate: **Generate a new client secret** on the OAuth App (an app holds
+  several at once), then `pnpm everyapp signin add github` with Enter at
+  the Client ID prompt, or the hidden read and
+  `pnpm everyapp signin add github --client-secret-from-env GITHUB_SIGNIN_CLIENT_SECRET --json`.
+  Then **Delete** the old secret on GitHub.
+- Remove, only when asked: `pnpm everyapp signin remove github --json --yes`
+  (`--yes` only when they said so). Accounts made with it stay. Then delete
+  the OAuth App (its page → **Advanced** → **Delete application**).
+
+## Sources
+
+- https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app
+  (Settings → Developer settings → OAuth apps → New OAuth App; fields;
+  organization owners; 100 apps per owner)
+- https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps
+  (`read:user`, `user:email`)
+- https://docs.github.com/en/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors
+  and https://docs.github.com/en/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors
+  (redirect URI mismatch, `incorrect_client_credentials`)
+- The **Generate a new client secret**, **Advanced** and **Delete
+  application** labels are from GitHub's UI as the runbook records them;
+  GitHub's docs pages above don't show them (unverified).
+- `docs/runbooks/sign-in-providers.md` ("GitHub") and
+  `packages/sdk/src/internal/signInProviders.ts`

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

@@ -0,0 +1,178 @@
+# Sign in with Google on the Gateway
+
+Read [README.md](README.md) first: the rules every setup follows.
+
+Puts **Continue with Google** on the Gateway's sign-in page, beside the
+password. At the end the person has an OAuth client in a Google Cloud
+project, its two settings on the Gateway, and has signed in with Google
+once. `pnpm everyapp signin show google --json` names this file as
+`setup`, and the CLI prints `Guide: .claude/skills/everyapp/setup/signin-google.md`.
+
+Who gets in doesn't change: Google only says who someone is (an email it
+verified). A member signs in; someone with a pending invitation for that
+exact address joins with the invited role, no link or password needed;
+everyone else is refused ("You don't have an account on this gateway.")
+and nothing is created. An existing password account connects Google once:
+the first "Continue with Google" says an account exists, the person signs
+in with the password and the page connects Google (or **Connect Google** in
+the account menu). The full rules: `docs/runbooks/sign-in-providers.md`,
+"Who gets in".
+
+This is not the Google client apps use for Gmail and Calendar
+(`GOOGLE_WORKSPACE_*`, [google.md](google.md)). Make a separate client
+here. When that other client's project is *External* and still in Testing
+(its Gmail scope waits on Google's verification), make this one in a
+separate project too: publishing is per project, and this one must be
+published (step 2).
+
+## Settings
+
+| Name                          | Required | Flag                             | What it holds                                                   |
+| ----------------------------- | -------- | -------------------------------- | --------------------------------------------------------------- |
+| `GOOGLE_SIGNIN_CLIENT_ID`     | required | `--client-id <id>`               | the client's Client ID, ending in `.apps.googleusercontent.com`; not a secret |
+| `GOOGLE_SIGNIN_CLIENT_SECRET` | required | `--client-secret-from-env <VAR>` | the client's Client secret, shown once at creation              |
+
+Scopes asked for: `openid email profile`, identity only. The email is the
+ID token's `email`, and only when `email_verified` is true (every Google
+account's own address is).
+
+## Costs and plans
+
+Free: a Google Cloud project and an OAuth client for sign-in need no
+billing account. The identity scopes are not sensitive, so the consent
+screen can be published without Google's sensitive-scope verification
+(whether Google still asks for brand verification before showing the
+app's name and logo: unverified).
+
+## Only a person can
+
+- Sign in to Google Cloud, create the project and the consent screen.
+- Create the OAuth client and copy its secret off the screen.
+- Publish the consent screen (In production).
+- Type the secret at the hidden prompt of `pnpm everyapp signin add google`.
+- Sign in with Google 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 (nobody signs in with a provider before
+   the Gateway is claimed). `data.access.on` true: see Verify 4.
+2. `pnpm everyapp signin show google --json` (changes nothing). `Unknown
+   command signin` (exit 251): the checkout predates sign-in providers;
+   `git pull` in the `every-app` folder, then again. Read `data.status`:
+   `off`, this file applies; `needs setup`, `data.missing` names what is
+   left (go to step 3); `on`, it works already: ask before replacing (a new
+   secret for the same client is harmless, see Rotate). `data.callbackUrl`
+   is the redirect URL, `https://<gateway host>/api/auth/callback/google`.
+3. Ask whether a Google Cloud project for this exists already, and whether
+   everyone who will sign in is in one Google Workspace organization
+   (then the consent screen can be *Internal*: no publishing needed).
+
+## Steps
+
+1. **You:** give the person `data.callbackUrl` from Before you start 2.
+2. **Person:** the consent screen, once per project. Open
+   https://console.cloud.google.com/auth/overview (pick or create the
+   project in the top bar) → **Get started**: App name (what people see,
+   for example `Every App`), User support email → Next; Audience
+   *Internal* (one Workspace organization) or *External* → Next; Contact
+   Information → Next; agree to the User Data Policy → **Create**.
+   *External* only: https://console.cloud.google.com/auth/audience →
+   **Publish app** → Confirm. While it says Testing, only the test users
+   listed there can sign in. Done when the Audience page says "In
+   production" (or the app is *Internal*).
+3. **Person:** the client. https://console.cloud.google.com/auth/clients →
+   **Create client** → Application type **Web application** → Name (for
+   example `Every App sign-in`) → **Authorized redirect URIs** → **Add
+   URI** → the exact URL from step 1 → **Create**. No JavaScript origins.
+   A dialog shows the Client ID and the Client secret; keep it open (the
+   secret is shown only now; afterwards only its last four characters).
+   Redirect URI changes can take 5 minutes to a few hours to apply.
+4. **Person:** set both on the Gateway, in a second terminal in the
+   `every-app` folder:
+   ```sh
+   pnpm everyapp signin add google
+   ```
+   It prints where the client is made and the redirect URL, then asks for
+   the Client ID (shown as typed) and the Client secret (hidden: pasting
+   works, nothing is echoed). It ends with Google on and the sign-in URL.
+   They tell you when it's done. Both go on in one new version of the
+   Gateway Worker, live on the next request.
+   Another way, when they'd rather not use the prompts: in that terminal
+   they read the secret in hidden (bash or zsh:
+   `read -rs GOOGLE_SIGNIN_CLIENT_SECRET && export GOOGLE_SIGNIN_CLIENT_SECRET`;
+   fish: `read -s -x GOOGLE_SIGNIN_CLIENT_SECRET`), paste, press Enter, then
+   run `pnpm everyapp signin add google --client-id <Client ID> --client-secret-from-env GOOGLE_SIGNIN_CLIENT_SECRET --json`
+   and `unset GOOGLE_SIGNIN_CLIENT_SECRET` (fish: `set -e GOOGLE_SIGNIN_CLIENT_SECRET`).
+   The Client ID isn't a secret, so it may sit on the command line.
+5. **Person:** close the client dialog (Google keeps no copy of the secret
+   to show again; a lost one is replaced in Rotate).
+
+## Verify
+
+1. `pnpm everyapp signin list --json`: the `google` entry has `status:
+   "on"` and `missing` empty.
+2. The person's address must be a member's or have a pending invitation.
+   For someone new: `pnpm everyapp workspace invite <email>` (it prints an
+   invitation link; for Google sign-in they don't need it, the pending
+   invitation for that exact address is enough).
+3. **Person:** in a private window open `https://<gateway host>/sign-in`:
+   **Continue with Google** is there. Select it, choose the Google account,
+   and they land on the Gateway signed in. An existing password account
+   first sees "An account with this email already exists": sign in with
+   the password once, and the page connects Google.
+4. Behind Cloudflare Access (`data.access.on`): nothing else changes, but
+   the Google account's address must be the one Access knows the person
+   by; otherwise the page says Access knows them by another email.
+5. Logs (README's Verify 4): `signin.config_problem` names a malformed or
+   missing setting, the reason the button stays off.
+
+## If it fails
+
+| error or symptom | meaning | what to do |
+| --- | --- | --- |
+| no **Continue with Google** button | the provider isn't on: a setting missing or malformed, or the new version isn't live yet | `pnpm everyapp signin list --json` (`missing`); the logs' `signin.config_problem`; `signin add google` again |
+| Google's "Error 400: redirect_uri_mismatch" | the client's redirect URI isn't exactly `data.callbackUrl` | fix it under Authorized redirect URIs (no trailing slash; `https`); wait a few minutes |
+| Google refuses someone before the Gateway sees them (its wording for people not on Test users: unverified) | the consent screen is *External* and still in Testing: only test users get in, and their grants expire after seven days | **Publish app** (step 2) |
+| Google's `org_internal` error | the consent screen is *Internal* and the person's Google account is outside that organization | they use their Workspace account, or the audience becomes *External* and published |
+| "You don't have an account on this gateway." | the address Google returned isn't a member's and has no pending invitation | `pnpm everyapp workspace invite <email>` with the Google address, exactly as Google spells it |
+| "The sign-in provider hasn't verified this email address." | Google reports the address unverified (a secondary, unverified address on a non-Gmail account) | the person verifies it at Google, or uses another account |
+| "An account with this email already exists." | a password account has that address and isn't verified yet | sign in with the password once; the page connects Google |
+| `SIGNIN_VALUE_REQUIRED` | unattended, and a required setting has no flag and isn't set yet | `data.missing` names it; rerun `data.rerun` with the flag |
+| `SECRET_EMPTY` | the `--client-secret-from-env` variable is empty or unset in that shell | the hidden read again, in the same terminal |
+| `SIGNIN_FLAG_NOT_APPLICABLE` | a flag Google doesn't take (`--tenant`, `--issuer`, `--label`) | drop it |
+| Google's "invalid_client" | the secret doesn't belong to this Client ID (a typo, or another client's) | Rotate |
+
+## Rerun, rotate, remove
+
+- Rerun: `pnpm everyapp signin add google` any time. A value given
+  replaces; a setting not given and already set is kept (at the prompt,
+  Enter keeps it). The done event's `data.set` and `data.kept` say which.
+- Rotate: on the client's page (https://console.cloud.google.com/auth/clients
+  → the client) add a new secret, then the person runs
+  `pnpm everyapp signin add google` and presses Enter at the Client ID
+  prompt, pasting only the new secret; or the hidden read and
+  `pnpm everyapp signin add google --client-secret-from-env GOOGLE_SIGNIN_CLIENT_SECRET --json`
+  (the Client ID is kept). Then disable and delete the old secret there.
+- Remove, only when the person asks:
+  `pnpm everyapp signin remove google --json --yes` (`--yes` only when they
+  said so; at a terminal it asks). Every `GOOGLE_SIGNIN_*` setting goes in
+  one version; people who signed in with Google keep their accounts and
+  use another way in. Then delete the client in the console.
+
+## Sources
+
+- https://support.google.com/cloud/answer/15549257 (Clients page, Create
+  client, Web application, Authorized redirect URIs, the secret shown once,
+  5 minutes to a few hours)
+- https://developers.google.com/identity/openid-connect/openid-connect
+  (`openid email profile`, `email_verified`)
+- https://support.google.com/cloud/answer/13464321 (which scopes need
+  verification; the identity scopes are not sensitive)
+- https://support.google.com/cloud/answer/15549945 (Manage App Audience:
+  Internal, External, Testing and test users, seven-day grants, Publish
+  app, `org_internal`)
+- `docs/runbooks/sign-in-providers.md` ("Who gets in", "Existing accounts",
+  "Google", "Troubleshooting") and the catalog,
+  `packages/sdk/src/internal/signInProviders.ts`

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

@@ -0,0 +1,183 @@
+# Sign in with Microsoft on the Gateway
+
+Read [README.md](README.md) first: the rules every setup follows.
+
+Puts **Continue with Microsoft** on the Gateway's sign-in page, beside the
+password: work or school accounts from the person's Microsoft Entra
+directory (Microsoft 365), or any Microsoft account. At the end the person
+has an app registration in Entra, its settings on the Gateway, and has
+signed in with Microsoft once. `pnpm everyapp signin show microsoft --json`
+names this file as `setup`, and the CLI prints
+`Guide: .claude/skills/everyapp/setup/signin-microsoft.md`.
+
+Who gets in doesn't change: Microsoft 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. An existing password
+account connects Microsoft once, by signing in with the password when the
+page asks. The rules: `docs/runbooks/sign-in-providers.md`, "Who gets in".
+
+Not the Outlook mail and calendar client apps use (`MICROSOFT_365_*`,
+[microsoft-365.md](microsoft-365.md)): make a separate registration here.
+
+**Which tenant decides which addresses count as verified.** Recommended:
+the registration is single tenant and `MICROSOFT_SIGNIN_TENANT` is the
+Directory (tenant) ID, so only the person's own directory signs in, and
+its addresses are trusted. Otherwise (unset, `common`, `organizations`,
+`consumers`) any tenant's admin can put any address on their users
+(Microsoft calls the attack "nOAuth"), so the Gateway trusts an address
+only with the token's own word for it: the optional claims `email` and
+`xms_edov` (step 4). Without them every sign-in is refused as unverified.
+
+## Settings
+
+| Name                             | Required | Flag                             | What it holds                                                    |
+| -------------------------------- | -------- | -------------------------------- | ---------------------------------------------------------------- |
+| `MICROSOFT_SIGNIN_CLIENT_ID`     | required | `--client-id <id>`               | the registration's Application (client) ID; not a secret        |
+| `MICROSOFT_SIGNIN_CLIENT_SECRET` | required | `--client-secret-from-env <VAR>` | a client secret's **Value** (it expires; 24 months at most)      |
+| `MICROSOFT_SIGNIN_TENANT`        | optional | `--tenant <GUID\|common\|organizations\|consumers>` | the Directory (tenant) ID; unset means any Microsoft account (`common`) |
+
+Scopes asked for: `openid profile email`; no Graph scope, no refresh token
+kept. The email is the ID token's `email`, verified when the tenant is
+pinned, or the token carries `xms_edov: true`, `email_verified: true`, a
+matching `verified_primary_email`, or comes from a personal account.
+
+## Costs and plans
+
+No charge for an app registration: any Microsoft Entra tenant has them,
+Entra ID Free included (a Microsoft 365 business subscription comes with a
+tenant). Microsoft's quickstart lists an Azure account as a prerequisite;
+whether a tenant with no Azure subscription can register apps: unverified.
+The client secret expires (24 months at most; Microsoft recommends under
+12), so a reminder is part of the setup.
+
+## Only a person can
+
+- Sign in to the Microsoft Entra admin center (at least the Application
+  Developer role to register; adding optional claims is documented for
+  Cloud Application Administrator, or the app's owner).
+- Create the registration and the client secret, and copy its Value.
+- Type the secret at the hidden prompt of `pnpm everyapp signin add microsoft`.
+- Choose single tenant or any account; sign in with Microsoft to check.
+
+## 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 microsoft --json` (changes nothing; `Unknown
+   command signin`: `git pull` in the `every-app` folder). `data.status`
+   `off`: this file applies; `needs setup`: `data.missing` names what is
+   left (step 5); `on`: ask before replacing. `data.callbackUrl` is the
+   redirect URL, `https://<gateway host>/api/auth/callback/microsoft`;
+   `data.set` says whether `MICROSOFT_SIGNIN_TENANT` is set.
+3. Ask: only people in your own Microsoft 365 directory (recommended:
+   single tenant), or any Microsoft account (guests from other companies,
+   outlook.com addresses)? It decides steps 2 and 4.
+
+## Steps
+
+1. **You:** give the person `data.callbackUrl`.
+2. **Person:** https://entra.microsoft.com → **Entra ID** → **App
+   registrations** → **New registration**. Name (what people see, for
+   example `Every App`). **Supported account types**:
+   **Single tenant only - <your tenant>** (recommended), or **Any Entra ID
+   Tenant + Personal Microsoft accounts** for anyone. **Register**. The **Overview** page
+   shows **Application (client) ID** and **Directory (tenant) ID**: both
+   are plain ids, not secrets.
+3. **Person:** the redirect URL. Under **Manage** → **Authentication** →
+   **Redirect URI configuration** → **Add Redirect URI** → **Web** → the
+   exact URL from step 1 → **Configure**.
+4. **Person,** only when not single tenant: **Token configuration** → **Add
+   optional claim** → token type **ID** → tick `email` and `xms_edov` →
+   **Add** (accept the prompt to turn on the Microsoft Graph email
+   permission if it appears). If `xms_edov` isn't in the list (reported
+   for some apps while the claim was in preview; unverified today):
+   **Manifest** → under `optionalClaims` → `idToken` add
+   `{ "name": "xms_edov", "essential": false }` beside `email` → **Save**.
+5. **Person:** the secret. **Certificates & secrets** → **Client secrets**
+   → **New client secret** → a description, an expiry (the longest is 24
+   months) → **Add**. Copy the **Value** column now (not the Secret ID): it
+   is never shown again after leaving the page. Set a calendar reminder
+   for a week before it expires.
+6. **Person:** in a second terminal in the `every-app` folder:
+   ```sh
+   pnpm everyapp signin add microsoft
+   ```
+   It asks for the Application (client) ID (shown as typed), the client
+   secret Value (hidden: pasting works, nothing is echoed) and the tenant
+   (shown as typed: the Directory (tenant) ID for single tenant; Enter
+   leaves it unset). 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 MICROSOFT_SIGNIN_CLIENT_SECRET && export MICROSOFT_SIGNIN_CLIENT_SECRET`;
+   fish: `read -s -x MICROSOFT_SIGNIN_CLIENT_SECRET`), paste, Enter, then
+   `pnpm everyapp signin add microsoft --client-id <Application (client) ID> --tenant <Directory (tenant) ID> --client-secret-from-env MICROSOFT_SIGNIN_CLIENT_SECRET --json`
+   (leave `--tenant` off for any account), then `unset MICROSOFT_SIGNIN_CLIENT_SECRET`
+   (fish: `set -e MICROSOFT_SIGNIN_CLIENT_SECRET`).
+
+## Verify
+
+1. `pnpm everyapp signin list --json`: the `microsoft` entry has `status:
+   "on"` and `missing` empty; for single tenant, `pnpm everyapp signin show microsoft --json`
+   lists `MICROSOFT_SIGNIN_TENANT` in `data.set`.
+2. The person's address must be a member's or have a pending invitation:
+   `pnpm everyapp workspace invite <email>` for someone new (the pending
+   invitation for that exact address is enough; the printed link isn't
+   needed for this).
+3. **Person:** private window, `https://<gateway host>/sign-in` →
+   **Continue with Microsoft** → their work account → (first time) the
+   consent screen → **Accept** → the Gateway, signed in.
+4. Behind Cloudflare Access: nothing else changes, but the Microsoft
+   address must be the one Access knows the person by.
+5. Logs (README's Verify 4): `signin.config_problem` names a malformed
+   setting (a tenant that isn't a GUID or one of the three words).
+
+## If it fails
+
+| error or symptom | meaning | what to do |
+| --- | --- | --- |
+| no **Continue with Microsoft** button | a setting missing or malformed, or the version isn't live yet | `pnpm everyapp signin list --json`; logs' `signin.config_problem` |
+| `AADSTS50011` (redirect URI mismatch) | the Web redirect URI isn't exactly `data.callbackUrl` | fix it under Authentication (Web, not Single-page application) |
+| "The sign-in provider hasn't verified this email address." | not single tenant, and the token lacks `xms_edov`/`email` | step 4, or pin the tenant (single-tenant registration plus `--tenant`) |
+| `AADSTS50020` or "user account … does not exist in tenant" | single tenant, and the person's account is from another directory | invite them as a guest in Entra, or use any-account mode with step 4 |
+| `AADSTS7000215` (invalid client secret) | the Secret ID was copied instead of the Value, or the secret expired | Rotate |
+| "You don't have an account on this gateway." | no member or invitation for that address | `pnpm everyapp workspace invite <email>` with the address Microsoft returns |
+| `SIGNIN_TENANT_INVALID` | `--tenant` isn't a GUID, `common`, `organizations` or `consumers` | the Directory (tenant) ID from Overview |
+| `SIGNIN_VALUE_REQUIRED` / `SECRET_EMPTY` | unattended with 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 |
+| sign-in stops after months | the client secret expired | Rotate |
+
+## Rerun, rotate, remove
+
+- Rerun: `pnpm everyapp signin add microsoft` any time; values given
+  replace, settings not given are kept (Enter at a prompt keeps it).
+- Rotate, before the expiry: **Certificates & secrets** → **New client
+  secret**, then `pnpm everyapp signin add microsoft` (Enter at the client
+  id and tenant prompts, paste the new Value), or the hidden read and
+  `pnpm everyapp signin add microsoft --client-secret-from-env MICROSOFT_SIGNIN_CLIENT_SECRET --json`.
+  Then delete the old secret in Entra.
+- Drop the tenant pin (any account, after step 4):
+  `pnpm everyapp secret unset MICROSOFT_SIGNIN_TENANT --json` (asks at a
+  terminal; with `--json`, `--yes` only when the person said so).
+- Remove, only when asked: `pnpm everyapp signin remove microsoft --json --yes`
+  (`--yes` only when they said so). Accounts made with it stay. Then delete
+  the registration in Entra.
+
+## Sources
+
+- https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app
+  (Entra ID → App registrations → New registration; Supported account
+  types; Application (client) ID; Application Developer role)
+- https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri
+  (Authentication → Redirect URI configuration → Add Redirect URI → Web)
+- https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials
+  (New client secret; 24 months at most, under 12 recommended; the Value
+  is never shown again)
+- https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims
+  (Token configuration → Add optional claim; the manifest's `optionalClaims`)
+- https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference
+  (`xms_edov`: needs the `email` claim; `verified_primary_email`)
+- https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization
+  (nOAuth: never trust `email` alone)
+- `docs/runbooks/sign-in-providers.md` ("Microsoft", "Troubleshooting") and
+  `packages/sdk/src/internal/signInProviders.ts`