authflow-cli 0.1.1 → 0.3.0

package/README.md

@@ -1,265 +1,374 @@
-# Authflow CLI
-
-License: Apache-2.0. See [LICENSE](LICENSE).
-
-Minimal TypeScript CLI for Authflow Rail onboarding. Wraps the public admin and Origin Protocol surfaces so a tenant can register a resource, connect Stripe, mint a local identity header, run the conformance probe, and scaffold the origin sidecar — without reading rail source.
-
-`authflow mcp` exposes the same operations as an MCP server, so a coding agent can onboard a server against the codebase it already has open. The tenant-facing walkthrough is [Onboard with your agent](../../docs/onboarding/agent.md). Command reference: [`authflow mcp`](#authflow-mcp).
-
-## Install
-
-The command is `authflow`. The npm package is [`authflow-cli`](https://www.npmjs.com/package/authflow-cli) (npm blocked the unscoped name `authflow`). No repo checkout is required:
-
-```bash
-npx -y -p authflow-cli authflow --help
-npx -y -p authflow-cli authflow init --slug video --price 900 --credits 12
-```
-
-Or install globally and drop the `npx` prefix:
-
-```bash
-npm install -g authflow-cli
-authflow --help
-```
-
-## From this repo (development)
-
-```bash
-cd sdk/cli
-npm install
-npm run build
-npx authflow --help
-```
-
-During development (no build step):
-
-```bash
-npx tsx src/cli.ts --help
-npm run authflow -- --help
-```
-
-## Config
-
-| Env | Flag | Used by |
-| --- | --- | --- |
-| `AUTHFLOW_ISSUER` | `--issuer` | all HTTP commands |
-| `AUTHFLOW_ADMIN_API_KEY` | `--admin-key` | `init`, `register`, `connect`, `set-origin` (mint with `authflow signup`) |
-| `AUTHFLOW_ORIGIN_API_KEY` | `--origin-key` | `mint-header`, `probe` |
-| `AUTHFLOW_RESOURCE` / `AUTHFLOW_GATEWAY_URL` | `--gateway-url` / `--receipt` | curl hint on `mint-header` |
-
-Issuer is the Origin Protocol issuer origin, with no trailing slash: staging is `https://app-rail-railstg-4joi6asiofdcm.azurewebsites.net`, local is typically `https://localhost:7175`. For an already-registered resource it is the `issuer` field of the receipt. See [tenant quickstart §1](../../docs/onboarding/tenant-quickstart.md#environments-and-hostnames).
-
-## Commands
-
-### `authflow signup`
-
-Mints a per-tenant admin API key. This is how a creator gets `AUTHFLOW_ADMIN_API_KEY` without the rail operator handing them one.
-
-```bash
-export AUTHFLOW_ISSUER=https://app-rail-railstg-4joi6asiofdcm.azurewebsites.net
-npx -y -p authflow-cli authflow signup --email you@example.com
-```
-
-The key (`afa_test_` on staging, `afa_live_` in production) is shown once and written to `.env.local` by default. It can only register and manage slugs created with that key. The operator bearer still exists as a super-admin.
-
-### `authflow init`
-
-The whole onboarding path in one command: register the resource, put the origin API key in a secret
-store, print the config to paste into your MCP server, and probe the origin if it is already up.
-
-```bash
-export AUTHFLOW_ISSUER=https://app-rail-railstg-4joi6asiofdcm.azurewebsites.net
-export AUTHFLOW_ADMIN_API_KEY=…
-
-authflow init --slug video --price 900 --credits 12
-```
-
-Neither a Stripe account nor a deployed origin is required. Both are deferrable, in any order, and
-omitting either registers a **draft**: priced and registered, with a receipt you can build against,
-but not routable. That is the normal case — you rarely have a connected Stripe account or an origin
-URL before you have built anything.
-
-The receipt's `pending_requirements` lists what is still outstanding:
-
-| Requirement | Clear it with |
-| --- | --- |
-| `origin_base_uri` | `authflow set-origin --slug video --origin-url https://…` |
-| `connected_account_id` | `authflow connect --slug video` |
-| `stripe_onboarding_complete` | finish Stripe's form, then `authflow connect --slug video` again |
-
-The resource goes live once the list is empty. Add `--connect` to `init` to get the Stripe
-onboarding link from the first command instead of running `connect` separately.
-
-Useful flags:
-
-| Flag | Default | Meaning |
-| --- | --- | --- |
-| `--integration <dotnet\|proxy>` | `dotnet` | Which origin config to print |
-| `--write-secrets <target>` | `user-secrets` | `user-secrets`, `env-file`, or `keyvault` |
-| `--secret-destination <value>` | — | Project dir, env-file path, or vault name |
-| `--connected-account <acct>` | — | Attach a Stripe account you already have |
-| `--connect` | — | Start Stripe onboarding and print the hosted link |
-| `--origin-url <url>` | — | Supply the origin now instead of later |
-| `--no-probe` | — | Skip the conformance probe |
-
-### `authflow connect`
-
-Starts or resumes Stripe Connect Standard onboarding and prints the hosted link the creator opens to
-complete KYC.
-
-```bash
-authflow connect --slug video
-authflow connect --slug video --wait   # poll until Stripe reports the account can take charges
-```
-
-Account links are single-use and expire in minutes. Re-running is the expected way to get a fresh
-one: it resumes the same Stripe account rather than creating another, so retrying never leaves
-abandoned accounts behind. Run it again after the form is submitted to confirm `charges_enabled` and
-promote the resource.
-
-### `authflow set-origin`
-
-Points a draft at its origin, promoting it to live if nothing else is pending.
-
-```bash
-authflow set-origin --slug video --origin-url https://video-xyz.azurecontainerapps.io
-```
-
-Pass the base URI without `/mcp`; the gateway appends it.
-
-### `authflow doctor`
-
-Preflights a rail deployment before you spend time debugging your own origin.
-
-```bash
-authflow doctor --issuer https://app-rail-railstg-4joi6asiofdcm.azurewebsites.net --slug video
-```
-
-Checks that the issuer is reachable, that the Origin Protocol keys document is served and
-self-consistent (issuer byte-match, protocol version, a usable Ed25519 key, no private key
-material), and — with `--slug` — that the resource's PRM document resolves and the gateway answers
-an unauthenticated connect with a `401` carrying `resource_metadata`.
-
-Run this first when anything looks broken. It separates the two failures that are indistinguishable
-from the outside: a hostname that is not bound to the rail returns `404` on every path including
-`/healthz`, which reads exactly like a broken endpoint. Exit code is non-zero on any failure.
-
-### `authflow register`
-
-```bash
-export AUTHFLOW_ISSUER=https://app-rail-railstg-4joi6asiofdcm.azurewebsites.net
-export AUTHFLOW_ADMIN_API_KEY=…
-authflow register --file resource.json --out receipt.json
-```
-
-`resource.json` uses the same snake_case fields as `POST /admin/resources` (see [tenant quickstart](../../docs/onboarding/tenant-quickstart.md) §3):
-
-```json
-{
-  "slug": "video",
-  "origin_base_uri": "https://video-xyz.azurecontainerapps.io",
-  "display_name": "Snyder Video",
-  "connected_account_id": "acct_…",
-  "currency": "usd",
-  "price_amount_minor": 900,
-  "credits_per_period": 12,
-  "price_version": 1
-}
-```
-
-`origin_base_uri` may be `null` or omitted, which registers a draft — see `authflow set-origin`.
-
-Writes the registration receipt to `--out` (default `receipt.json`). By default that file contains
-the one-time `origin_api_key` in plaintext, which is a credential you probably do not want on disk:
-
-```bash
-authflow register --file resource.json --write-secrets user-secrets --secret-destination ./src/MyMcpServer
-```
-
-That stores the key and redacts it from the receipt. `env-file` writes `.env.local` (and adds it to
-`.gitignore`); `keyvault` calls `az keyvault secret set` and needs `--secret-destination <vault>`.
-
-Rotate a key later with the admin API: `POST /admin/resources/{slug}/rotate-origin-key`.
-
-### `authflow mint-header`
-
-Dev/staging only (`OriginProtocol:EnableDevEndpoints`). Mints a signed `X-Authflow-Identity` without OAuth.
-
-```bash
-export AUTHFLOW_ORIGIN_API_KEY=afo_test_…
-authflow mint-header --tier standard --ttl 90 --grant-credits 3 --receipt receipt.json
-```
-
-Prints the header and, when a gateway URL is known, a ready-to-paste `curl` against it.
-
-### `authflow probe`
-
-Asks the rail to probe the registered origin with valid and deliberately broken identity headers.
-
-```bash
-authflow probe
-```
-
-Renders a pass/fail table. Exit code is non-zero when any check fails or the origin is unreachable.
-
-### `authflow scaffold`
-
-```bash
-authflow scaffold --receipt receipt.json --upstream http://upstream:3000
-```
-
-Writes:
-
-- `.env` — `AUTHFLOW_ISSUER`, `AUTHFLOW_RESOURCE`, `AUTHFLOW_ORIGIN_API_KEY`, `AUTHFLOW_UPSTREAM_BASE_URI`
-- `docker-compose.authflow.yml` — `authflow-origin-proxy` in front of an upstream placeholder
-
-See [origin-proxy.md](../../docs/onboarding/origin-proxy.md) for the forwarded-header contract and the
-nonce-cache options.
-
-### `authflow mcp`
-
-Runs the onboarding operations as an MCP server on stdio, so a coding agent can do the onboarding
-instead of a human running commands. The agent already has the creator's codebase; what it lacks is
-a way to talk to the rail. This supplies exactly that, and nothing more — the server never reads or
-writes source files. It hands back an integration plan and the agent applies it.
-
-Add it to Cursor or Claude Desktop:
-
-```json
-{
-  "mcpServers": {
-    "authflow": {
-      "command": "npx",
-      "args": ["-y", "-p", "authflow-cli", "authflow", "mcp"],
-      "env": {
-        "AUTHFLOW_ISSUER": "https://app-rail-railstg-4joi6asiofdcm.azurewebsites.net",
-        "AUTHFLOW_ADMIN_API_KEY": "…"
-      }
-    }
-  }
-}
-```
-
-Tools:
-
-| Tool | Does |
-| --- | --- |
-| `authflow_signup` | Mint a per-tenant admin API key (no existing credential) |
-| `authflow_doctor` | Preflight the rail; distinguishes a bad hostname from an outage |
-| `authflow_register_resource` | Register and price a resource; optionally store the key in a secret store |
-| `authflow_get_resource` | Current receipt, `status`, and `pending_requirements` |
-| `authflow_integration_plan` | Config, snippets, verification steps, and invariants for `dotnet`, `typescript`, `python`, or `proxy` |
-| `authflow_start_stripe_connect` | Hosted Stripe onboarding link; resumable |
-| `authflow_set_connected_account` | Attach an existing `acct_…` |
-| `authflow_set_origin` | Supply the origin and promote to live |
-| `authflow_probe` | Conformance probe against the origin |
-| `authflow_mint_test_header` | Signed identity header for local verifier testing |
-| `authflow_rotate_origin_key` | Rotate the origin API key (invalidates the old one immediately) |
-
-Every tool takes `issuer` and `admin_key` optionally, falling back to the environment, so credentials
-stay in the MCP client config rather than in the conversation. `write_secrets` is available on both
-tools that issue a key; prefer it, because a key returned in a tool result is a credential in a chat
-transcript.
-
-Authentication is a per-tenant `afa_` admin API key from `authflow signup` (or `authflow_signup`).
-The operator bearer still works as a super-admin. Per-creator OAuth is not required for onboarding.
+# Authflow CLI
+
+License: Apache-2.0. See [LICENSE](LICENSE).
+
+Minimal TypeScript CLI for Authflow Rail onboarding. Wraps the public admin and Origin Protocol surfaces so a tenant can register a resource, connect Stripe, mint a local identity header, run the conformance probe, and scaffold the origin sidecar — without reading rail source.
+
+`authflow mcp` exposes the same operations as an MCP server, so a coding agent can onboard a server against the codebase it already has open. The tenant-facing walkthrough is [Onboard with your agent](../../docs/onboarding/agent.md). Command reference: [`authflow mcp`](#authflow-mcp).
+
+## Install
+
+The command is `authflow`. The npm package is [`authflow-cli`](https://www.npmjs.com/package/authflow-cli) (npm blocked the unscoped name `authflow`). No repo checkout is required:
+
+```bash
+npx -y -p authflow-cli authflow --help
+npx -y -p authflow-cli authflow init --slug video --price 900 --credits 12
+```
+
+Or install globally and drop the `npx` prefix:
+
+```bash
+npm install -g authflow-cli
+authflow --help
+```
+
+## From this repo (development)
+
+```bash
+cd sdk/cli
+npm install
+npm run build
+npx authflow --help
+```
+
+During development (no build step):
+
+```bash
+npx tsx src/cli.ts --help
+npm run authflow -- --help
+```
+
+## Config
+
+| Env | Flag | Used by |
+| --- | --- | --- |
+| `AUTHFLOW_ISSUER` | `--issuer` | all HTTP commands |
+| `AUTHFLOW_ADMIN_API_KEY` | `--admin-key` | `init`, `register`, `connect`, `set-connected-account`, `set-origin`, `status`, `get`, `list`, `plan`, `rotate-origin-key` (mint with `authflow signup`) |
+| `AUTHFLOW_ORIGIN_API_KEY` | `--origin-key` | `mint-header`, `probe`, `set-origin` (for its probe) |
+| `AUTHFLOW_RESOURCE` / `AUTHFLOW_GATEWAY_URL` | `--gateway-url` / `--receipt` | curl hint on `mint-header` |
+
+Issuer is the Origin Protocol issuer origin, with no trailing slash: staging is `https://staging.rails.authflow.ai`, local is typically `https://localhost:7175`. For an already-registered resource it is the `issuer` field of the receipt. See [tenant quickstart §1](../../docs/onboarding/tenant-quickstart.md#environments-and-hostnames).
+
+## Commands
+
+### `authflow signup`
+
+Mints a per-tenant admin API key. This is how a creator gets `AUTHFLOW_ADMIN_API_KEY` without the rail operator handing them one.
+
+```bash
+export AUTHFLOW_ISSUER=https://staging.rails.authflow.ai
+npx -y -p authflow-cli authflow signup --email you@example.com
+```
+
+The key (`afa_test_` on staging, `afa_live_` in production) is shown once and written to `.env.local` by default. It can only register and manage slugs created with that key. The operator bearer still exists as a super-admin.
+
+### `authflow init`
+
+The whole onboarding path in one command: register the resource, put the origin API key in a secret
+store, print the config to paste into your MCP server, and probe the origin if it is already up.
+
+```bash
+export AUTHFLOW_ISSUER=https://staging.rails.authflow.ai
+export AUTHFLOW_ADMIN_API_KEY=…
+
+authflow init --slug video --price 900 --credits 12
+```
+
+Neither a Stripe account nor a deployed origin is required. Both are deferrable, in any order, and
+omitting either registers a **draft**: priced and registered, with a receipt you can build against,
+but not routable. That is the normal case — you rarely have a connected Stripe account or an origin
+URL before you have built anything.
+
+The receipt's `pending_requirements` lists what is still outstanding:
+
+| Requirement | Clear it with |
+| --- | --- |
+| `origin_base_uri` | `authflow set-origin --slug video --origin-url https://…` |
+| `connected_account_id` | `authflow connect --slug video` (hosted KYC) or `authflow set-connected-account --slug video --account acct_…` (you already have the id) |
+| `stripe_onboarding_complete` | finish Stripe's form, then `authflow connect --slug video` again |
+
+Re-running `init` against a slug this admin key already owns resumes it: `409 slug_owned_by_caller`
+is not a dead end. `--connected-account` and `--origin-url` then attach instead of failing. A slug
+owned by someone else still returns `slug_taken`.
+
+The resource goes live once the list is empty. Add `--connect` to `init` to get the Stripe
+onboarding link from the first command instead of running `connect` separately.
+
+Useful flags:
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--integration <dotnet\|proxy>` | `dotnet` | Which origin config to print |
+| `--write-secrets <target>` | `user-secrets` | `user-secrets`, `env-file`, or `keyvault` |
+| `--secret-destination <value>` | — | Project dir, env-file path, or vault name |
+| `--connected-account <acct>` | — | Attach a Stripe account you already have |
+| `--connect` | — | Start Stripe onboarding and print the hosted link |
+| `--origin-url <url>` | — | Supply the origin now instead of later |
+| `--no-probe` | — | Skip the conformance probe |
+
+### `authflow connect`
+
+Starts or resumes Stripe Connect Standard onboarding and prints the hosted link the creator opens to
+complete KYC.
+
+```bash
+authflow connect --slug video
+authflow connect --slug video --wait   # poll until Stripe reports the account can take charges
+authflow connect --slug video --connected-account acct_…   # attach an account you already have
+```
+
+Account links are single-use and expire in minutes. Re-running is the expected way to get a fresh
+one: it resumes the same Stripe account rather than creating another, so retrying never leaves
+abandoned accounts behind. Run it again after the form is submitted to confirm `charges_enabled` and
+promote the resource.
+
+`--connected-account` skips hosted KYC and is the same PUT as `authflow set-connected-account`.
+
+### `authflow set-connected-account`
+
+Attach a Stripe Standard account id the platform already has. This is the CLI twin of
+`authflow_set_connected_account` and of `PUT /admin/resources/{slug}/connected-account`. Use it when
+`connect` would otherwise start a new hosted onboarding you do not need.
+
+```bash
+authflow set-connected-account --slug video --account acct_…
+```
+
+### `authflow set-origin`
+
+Points a draft at its origin, promoting it to live if nothing else is pending, then runs the
+conformance probe.
+
+```bash
+authflow set-origin --slug video --origin-url https://video-xyz.azurecontainerapps.io
+```
+
+Pass the base URI without `/mcp`; the gateway appends it.
+
+The probe runs automatically because this is the moment the resource starts accepting traffic, and a
+closing "remember to verify" is a step that gets skipped. It needs `AUTHFLOW_ORIGIN_API_KEY` (or
+`--origin-key`) — the admin key cannot stand in, because the probe authenticates as the origin. If
+the key is not available the command says so and completes; `--no-probe` skips it deliberately.
+
+The command also prints the client MCP config for the gateway URL. Use it verbatim: an MCP client
+pointed at the origin's own hostname gets `403 invalid_origin_identity`, which is the origin
+correctly refusing an unsigned request, not an auth bug.
+
+### `authflow status`
+
+Where onboarding actually got to, and the command that clears each remaining step.
+
+```bash
+authflow status --slug video
+```
+
+```
+resource: video
+status:   draft
+gateway:  https://staging.rails.authflow.ai/video/mcp
+
+  [x] resource registered
+  [ ] origin URI set
+      no origin — the gateway has nowhere to forward to
+      next: authflow set-origin --slug video --origin-url https://your-origin.example
+  [ ] Stripe connected
+      no connected account — nothing can be charged
+      next: authflow connect --slug video  (or authflow set-connected-account --slug video --account acct_…)
+  [ ] Stripe onboarding complete
+      no connected account — attach one before Stripe can confirm charges
+      next: authflow connect --slug video  (or authflow set-connected-account --slug video --account acct_…)
+```
+
+"Stripe onboarding complete" is ticked only when this resource has an account attached **and** Stripe
+has not listed `stripe_onboarding_complete` as pending. No account is not "charges enabled."
+
+Use it to resume an onboarding whose earlier steps may or may not have finished — a deploy that got
+backgrounded, a terminal that was closed. `doctor` answers "is the rail up", which is a different
+question: the rail can be perfectly healthy while a resource sits half-configured and rejects every
+request. Exit code is non-zero until the resource can take paid traffic, so it works as a deploy
+gate. `--json` emits the report for scripting.
+
+### `authflow plan`
+
+Prints the same framework-specific origin integration plan as `authflow_integration_plan`.
+
+```bash
+authflow plan --slug video --framework dotnet
+```
+
+`--framework` is one of `dotnet`, `typescript`, `python`, or `proxy`.
+
+### `authflow get` / `authflow list`
+
+```bash
+authflow get --slug video          # one receipt, plus the client MCP config
+authflow list                      # every resource this admin key owns
+```
+
+`list` is the recovery path for a forgotten slug, which `get` cannot be — it needs the slug you are
+trying to remember. If a registration reported the slug was taken and it is not in `list`, another
+tenant owns it and you need a different name; slugs are global because they are the gateway path
+segment.
+
+### `authflow rotate-origin-key`
+
+```bash
+authflow rotate-origin-key --slug video --write-secrets user-secrets
+```
+
+The recovery path for a lost origin API key, which is shown only once. The previous key stops working
+the moment the command returns, so update the origin's secret store immediately or its usage reports
+and probes will start failing.
+
+### `authflow doctor`
+
+Preflights a rail deployment before you spend time debugging your own origin.
+
+```bash
+authflow doctor --issuer https://staging.rails.authflow.ai --slug video
+```
+
+Checks that the issuer is reachable, that the Origin Protocol keys document is served and
+self-consistent (issuer byte-match, protocol version, a usable Ed25519 key, no private key
+material), and — with `--slug` — that the resource's PRM document resolves and the gateway answers
+an unauthenticated connect with a `401` carrying `resource_metadata`.
+
+Run this first when anything looks broken. It separates the two failures that are indistinguishable
+from the outside: a hostname that is not bound to the rail returns `404` on every path including
+`/healthz`, which reads exactly like a broken endpoint. Exit code is non-zero on any failure.
+
+### `authflow register`
+
+```bash
+export AUTHFLOW_ISSUER=https://staging.rails.authflow.ai
+export AUTHFLOW_ADMIN_API_KEY=…
+authflow register --file resource.json --out receipt.json
+```
+
+`resource.json` uses the same snake_case fields as `POST /admin/resources` (see [tenant quickstart](../../docs/onboarding/tenant-quickstart.md) §3):
+
+```json
+{
+  "slug": "video",
+  "origin_base_uri": "https://video-xyz.azurecontainerapps.io",
+  "display_name": "Snyder Video",
+  "connected_account_id": "acct_…",
+  "currency": "usd",
+  "price_amount_minor": 900,
+  "credits_per_period": 12,
+  "price_version": 1
+}
+```
+
+`origin_base_uri` may be `null` or omitted, which registers a draft — see `authflow set-origin`.
+
+Writes the registration receipt to `--out` (default `receipt.json`). The one-time `origin_api_key` is
+**not** written to that file: receipts get committed, pasted into issues, and handed to agents, and
+the key is a live bearer credential for the usage endpoint. It is printed to the terminal instead, so
+nothing is lost. `--keep-secret-in-receipt` restores the old behaviour if you really need it.
+
+Better still, have the CLI store it for you:
+
+```bash
+authflow register --file resource.json --write-secrets user-secrets --secret-destination ./src/MyMcpServer
+```
+
+`env-file` writes `.env.local` (and adds it to `.gitignore`); `keyvault` calls
+`az keyvault secret set` and needs `--secret-destination <vault>`.
+
+Lost the key? `authflow rotate-origin-key --slug <slug>`.
+
+Registration also prints the client MCP config and, for a draft, the remaining steps — a registered
+resource is not yet a reachable one, and from the outside the two are indistinguishable.
+
+### `authflow mint-header`
+
+Dev/staging only (`OriginProtocol:EnableDevEndpoints`). Mints a signed `X-Authflow-Identity` without OAuth.
+
+```bash
+export AUTHFLOW_ORIGIN_API_KEY=afo_test_…
+authflow mint-header --tier standard --ttl 90 --grant-credits 3 --receipt receipt.json
+```
+
+Prints the header and, when a gateway URL is known, a ready-to-paste `curl` against it.
+
+### `authflow probe`
+
+Asks the rail to probe the registered origin with valid and deliberately broken identity headers.
+
+```bash
+authflow probe
+authflow probe --slug video
+```
+
+The origin API key is bound to one resource, so `--slug` is optional and ignored. It exists so a
+documented `authflow probe --slug …` does not fail. Renders a pass/fail table. Exit code is
+non-zero when any check fails or the origin is unreachable.
+
+### `authflow scaffold`
+
+```bash
+authflow scaffold --receipt receipt.json --upstream http://upstream:3000
+```
+
+Writes:
+
+- `.env` — `AUTHFLOW_ISSUER`, `AUTHFLOW_RESOURCE`, `AUTHFLOW_ORIGIN_API_KEY`, `AUTHFLOW_UPSTREAM_BASE_URI`
+- `docker-compose.authflow.yml` — `authflow-origin-proxy` in front of an upstream placeholder
+
+See [origin-proxy.md](../../docs/onboarding/origin-proxy.md) for the forwarded-header contract and the
+nonce-cache options.
+
+### `authflow mcp`
+
+Runs the onboarding operations as an MCP server on stdio, so a coding agent can do the onboarding
+instead of a human running commands. The agent already has the creator's codebase; what it lacks is
+a way to talk to the rail. This supplies exactly that, and nothing more — the server never reads or
+writes source files. It hands back an integration plan and the agent applies it.
+
+Add it to Cursor or Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "authflow": {
+      "command": "npx",
+      "args": ["-y", "-p", "authflow-cli", "authflow", "mcp"],
+      "env": {
+        "AUTHFLOW_ISSUER": "https://staging.rails.authflow.ai",
+        "AUTHFLOW_ADMIN_API_KEY": "…"
+      }
+    }
+  }
+}
+```
+
+Tools:
+
+| Tool | Does |
+| --- | --- |
+| `authflow_signup` | Mint a per-tenant admin API key (no existing credential) |
+| `authflow_doctor` | Preflight the rail; distinguishes a bad hostname from an outage |
+| `authflow_register_resource` | Register and price a resource; optionally store the key in a secret store |
+| `authflow_get_resource` | Current receipt, `status`, and `pending_requirements` |
+| `authflow_list_resources` | Every resource this key owns — how an agent recovers an unknown slug |
+| `authflow_status` | Per-step readiness with the command that clears each one; use it to resume |
+| `authflow_integration_plan` | Config, snippets, verification steps, and invariants for `dotnet`, `typescript`, `python`, or `proxy` |
+| `authflow_start_stripe_connect` | Hosted Stripe onboarding link; resumable |
+| `authflow_set_connected_account` | Attach an existing `acct_…` |
+| `authflow_set_origin` | Supply the origin and promote to live |
+| `authflow_probe` | Conformance probe against the origin |
+| `authflow_mint_test_header` | Signed identity header for local verifier testing |
+| `authflow_rotate_origin_key` | Rotate the origin API key (invalidates the old one immediately) |
+
+Every tool takes `issuer` and `admin_key` optionally, falling back to the environment, so credentials
+stay in the MCP client config rather than in the conversation. `write_secrets` is available on both
+tools that issue a key; prefer it, because a key returned in a tool result is a credential in a chat
+transcript.
+
+Every receipt a tool returns carries `client_mcp_config` — the config for reaching the resource
+through the gateway. Hand the user that, never the origin's hostname, which rejects unsigned requests
+by design.
+
+Authentication is a per-tenant `afa_` admin API key from `authflow signup` (or `authflow_signup`).
+The operator bearer still works as a super-admin. Per-creator OAuth is not required for onboarding.