@kurtbruns/kestrel 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -10,6 +10,39 @@ To move a running instance from one version to another, follow [Upgrade to a new
 
 <!-- Add entries under Added / Changed / Fixed / Breaking. One operator-facing line each; see .claude/rules/changelog.md. Upgrade steps (a migration, a new setting) go once, in the Upgrading paragraph, never on an entry. -->
 
+## [1.14.0] - 2026-10-22
+
+**Upgrading from 1.13.0.** Two database migrations, which `npm run sync-migrations` brings in: apply them before you deploy with `npx wrangler d1 migrations apply DB --remote --env production` (and `--local` for local development). `0013_who_acted_client` records the client each revision and import came through. No client was recorded before it, and nothing tells a person's change in the editor from one through another program, so every revision and import a person made is read as made in the editor, and those rows are rewritten once, which counts against the day's database writes on Workers Free like any other write; a service token's read as naming no client. `0014_send_acts` adds a record of every act on a send: who scheduled it, moved it, canceled it, or resolved it, and when. It rewrites nothing: a send made before it reads as acted on by no one recorded.
+
+**Before you deploy, check your Access policies.** Your Access application must let people in only through an Allow policy on emails, and programs only through a Service Auth policy on a service token: a login through any other kind of policy is now refused, and a search of your Worker's logs for `auth.unidentified` shows any that would be.
+
+Run `npm run check-context` in your instance's repository: this release changes the operator's Claude context, and a copy you've edited is merged by hand. To let Claude connect as a person, turn on Managed OAuth for the Access application, with its localhost and loopback clients allowed and `https://claude.ai/api/mcp/auth_callback` among its Allowed redirect URIs, as the new Allow Claude to connect guide describes; the `api` path already covers the new MCP server. Then, in your instance's repository, run `npx -p @kurtbruns/kestrel kestrel login <your instance's address>`, take out the service token's two values from `.claude/settings.local.json`, and revoke the token, or keep it for a script.
+
+### Added
+
+- Kestrel records the client each change came through, beside the person or service token who made it (SPEC §11, Who acted). A client names itself on each request in a `Kestrel-Client` header, one short lowercase word (the editor sends `editor`, Claude Code `claude-code`); a malformed name is a 400 naming the header, and a request that names none reads as made through the API. `GET /api/whoami` answers `client`, a revision and a post `author_client`, and an import's record `client` in its `principal`; a service token's is always null. Where the editor names who made a change, a person through another client reads with it, such as "you@example.com via Claude Code" or "you@example.com via the API", and a person in the editor by their address alone.
+- A send records every act on it, a schedule or Send now, a reschedule, a cancel, and a Resolve, with who took it (a person with the client they came through, or a service token by its name) and when (SPEC §6, §11). The send view answers them as `scheduled_by`, `rescheduled_by`, `canceled_by`, and `resolved_by`. The send's page shows them, and the scheduled banner names the latest when it wasn't you in the editor, such as "Scheduled by you@example.com via Claude Code", so a send Claude or automation scheduled never reads as one you scheduled yourself.
+- `kestrel login <url>` signs Claude Code in to a deployed instance as you, through Cloudflare Access's Managed OAuth, which you approve in your browser, and `kestrel api <method> <path>` calls the API as you, naming Claude Code as the client, so what Claude changes shows as yours, via Claude Code (SPEC §11). The sign-in is kept in your user config, never in the instance's repository, and renews itself until the Access application's grant session ends; a token request gives up after 10 seconds instead of hanging, and `kestrel logout` forgets it. Outside the instance's repository, run it as `npx -p @kurtbruns/kestrel kestrel …`, since an unrelated npm package is called `kestrel`. `kestrel api --local` calls this folder's dev server as its stand-in person, the same way. `--client` names a script of your own instead, and never the editor, which `kestrel api` refuses. A refusal that signing in again can't fix, an Access login that named no one (`access_unidentified`), says what to change in Access instead. It needs Managed OAuth on for the instance's Access application, as the new Allow Claude to connect guide describes.
+- `kestrel api` describes the API it calls, read from the instance's own OpenAPI document so it matches the release that instance runs: `kestrel api --list [resource]` lists the routes, and `kestrel api help <method> <path>` describes one, its parameters, body fields, answer, and refusals with their next moves. `-f name=value` (a string) and `-F name=value` (typed by the route, or `@file` for a file's text) build a JSON body, or the query string on a GET and for a name the route takes only as a query parameter, and a field the route doesn't take is refused before the request; a body field can't be combined with `--data` or `--form`. A refusal prints its code, message, field, and next move on stderr, and the raw body on stdout. The OpenAPI document names the next move on each refusal any route can give.
+- Claude Desktop and claude.ai can work with an instance as a custom connector, signed in as you through Cloudflare Access's Managed OAuth, at `https://<your instance>/api/mcp` (SPEC §11). It's an MCP server in the Worker with a short set of tools for publishing in a chat: search and read posts, sends, and subscribers; preview a post's email; save a draft; send a test; schedule, reschedule, or cancel a send; import a list; unsubscribe someone; and `kestrel_api_read` for most other reads, never a write or a bulk export. Each tool acts through the API's own routes, so it's refused as the route is, a refusal coming back to Claude with its next move, and none confirms anything for you: an import's attestation waits for you to accept it in the chat, and an import that would grow a scheduled send is yours to finish in the dashboard. Its calls always name their client `claude`, so what Claude changes shows as yours, "via Claude". The publisher's docs come with it, for Claude to read. Erasure, uploads, and the logo stay in the dashboard. On connecting, Claude is told to offer a test once a post is scheduled and to send tests only to your test recipients or an address you give as yours. The publishing docs' Connect Claude page covers adding it in Claude Desktop or claude.ai.
+- The connector's tools also change a post's archive listing or address, delete a draft, add a subscriber by double opt-in, block an address or lift a block or a bounce, resolve a stuck send with the answer you pick, change your settings and email template, and test your notifications (SPEC §11). Claude confirms with you before it deletes a draft, changes a sent post's listing, clears a bounce, saves a new test recipient or notifications address, or re-makes a scheduled send's email.
+- `GET /api/posts/:id/preview.json` answers `text`, the email's plain-text part from the same render as the preview, so a client that can't show the page can read what goes out.
+
+### Changed
+
+- The Configuration reference opens with the whole `production` block, then lists each setting once, by name, with whether it's required, its default, and what the app refuses, in place of summary tables and a separate list of refusals.
+- The Docs tab's code blocks are quieter cards with a Copy icon beside the code, which turns to a check when the copy lands, and shell commands and JSON are highlighted. Inline code in the docs is maroon on a darker chip. The copy icon is redrawn everywhere with its two pages evenly offset.
+- The browser tab now names the screen you're on, such as "Subscribers - Kestrel", a post or send by its subject, and a doc by its title, instead of "Kestrel" on every screen, so tabs, bookmarks, and history entries say where they lead. The web version's tab adds "(web version)" after the subject, so it reads apart from the editor's.
+- Every admin `401` now carries a `message`, as every other refusal does, and the API reference and OpenAPI document describe its `reason`, which says when signing in again can't help (SPEC §11).
+- The scheduled banner is quieter: "No test of this email has been sent yet" is now a muted "Not tested yet" beside Send test email, the button that settles it (SPEC §8).
+- A service token now means automation, never Claude: the editor shows its changes as "a service token" (and an import's as "a service token", not "Claude, for you"), the publisher's email about an import a service token commits says a service token made it rather than Claude, and the dashboard says Claude is connected once a post's current revision came through Claude Code or the connector. Service tokens keep working as before. The setup guide's Connect Claude page is now two guides: Allow Claude to connect, which turns on Managed OAuth so a publisher can connect Claude as themselves, and Automate with a service token, the service-token steps. A new Connect Claude page in the publishing docs walks a publisher through adding the connector in Claude Desktop or claude.ai, or signing Claude Code in with the Kestrel CLI, and ends with what to ask Claude and the lines the app holds whatever it's asked, in place of the Working with Claude page. `/llms.txt` and the API reference point an agent to `kestrel login` first (SPEC §11).
+- The operator's Claude context (`template/claude/CLAUDE.md`) has Claude call the API through `kestrel api` instead of curl with a service token's headers, deployed and locally, and run `kestrel login` with the person when they aren't signed in, so Claude's work is recorded as the person's, via Claude Code, rather than a service token's. It also tells Claude never to use a service token in its environment for the person's work, and shows it `kestrel api --list`, `kestrel api help`, and `-f`/`-F`, so it learns a route's body from the instance instead of building JSON by hand. For safety, it also tells Claude never to pass `kestrel api --client`, so a change it makes can't read as made in the editor, where some steps only you may take, and to send a test only to your test recipients or an address you give as yours, asking before any other. It has Claude offer a test once a post is scheduled, since only a test of the scheduled email settles "Not tested yet", and cancel, fix, and schedule again if the test shows a problem. When the instance offers no sign-in for programs, it walks the person through the new Allow Claude to connect guide. Run `npm run check-context` to bring it in.
+
+### Breaking
+
+- A Cloudflare Access login that is neither a person (with an email) nor a service token (with its Client ID) is refused with a `401` whose `reason` is `access_unidentified`, where it was admitted as an anonymous service token with full access. The app accepts only the two kinds of Access policy the setup guide describes, an Allow policy on emails and a Service Auth policy on a service token, so another kind added to the application, such as a certificate or device rule, can no longer grant the admin surface to a caller nobody can name. The editor explains the refusal in place of a sign-in, naming those two kinds and offering Sign out, and each refusal logs `auth.unidentified` with the names of the claims it carried (SPEC §11).
+- A commit through the API that would grow a scheduled send's audience is refused `sends_acknowledgement_required` unless it comes through the editor, whoever signed in: a script of yours that commits such an import with your own sign-in now has you finish it in the dashboard, as Claude does (SPEC §7, §11).
+
 ## [1.13.0] - 2026-10-19
 
 **Upgrading from 1.12.0.** One database migration, which `npm run sync-migrations` brings in: apply it before you deploy with `npx wrangler d1 migrations apply DB --remote --env production` (and `--local` for local development). `0012_unsubscribe_cause` records why each subscriber left and leaves the suppressions only bounces and blocks. Every unsubscribe before it reads as the reader's own, since the record never said otherwise. Each complaint becomes an unsubscribe by a complaint, and an address it held with no subscriber is recorded as one, unsubscribed and holding only the address. Each erasure's marker becomes a subscriber unsubscribed by an erasure, holding only the address and when, except that someone who signed up again after it stays pending, read as having left by the erasure until they confirm. An erasure that found a bounce or a block already on an address left no trace of itself, so that address keeps its suppression alone. It rebuilds the subscribers and suppressions tables, copying every row once, which counts against the day's database writes on Workers Free like any other write. Deploy straight after applying it: until this release is serving, the previous one fails to record a reader's unsubscribe, a confirmation from someone who once left, an erasure, and a complaint report, which the new tables refuse. SES retries a refused report, so complaints arrive once the deploy lands; a reader whose unsubscribe failed meanwhile has to unsubscribe again. Run `npm run check-context` in your instance's repository: this release changes the operator's Claude context, and a copy you've edited is merged by hand. Several API changes can break a script of yours, each listed under Breaking; the table gives every renamed route, field, value, and sort key, old to new. A request that still sends an old name is refused with a 400 naming it, never answered as if it had been read: every API route now refuses a body field, a query parameter, or a filter value it doesn't take, so check a script's requests against the API reference before you deploy.
@@ -584,7 +617,8 @@ The first tagged release: a self-contained newsletter app on a Cloudflare Worker
 - A build-version stamp: every instance reports its version, commit, and build time, read-only in the editor and at `GET /api/version`.
 - This changelog and a semantic-versioning release process.
 
-[Unreleased]: https://github.com/kurtbruns/kestrel/compare/v1.13.0...HEAD
+[Unreleased]: https://github.com/kurtbruns/kestrel/compare/v1.14.0...HEAD
+[1.14.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.14.0
 [1.13.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.13.0
 [1.12.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.12.0
 [1.11.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.11.0

package/README.md

@@ -2,7 +2,7 @@
 
 Kestrel is an open-source newsletter app you run yourself, on Cloudflare and Amazon SES. You own the list, the proof each reader opted in, the record of every send, and a permanent archive of every post.
 
-You write in Markdown, preview the exact email, and schedule it with a window to cancel. Bring your list from another service, and take it out whenever you like. Work in the editor, or ask Claude to do it through the same API.
+You write in Markdown, preview the exact email, and schedule it with a window to cancel. Bring your list from another service, and take it out whenever you like. Work in the editor, or ask Claude to do it through the same API, from Claude Code, Claude Desktop, or claude.ai.
 
 See [getkestrel.dev](https://getkestrel.dev) to learn more about Kestrel.
 

package/bin/kestrel.mjs

@@ -6,8 +6,9 @@
  * bringing a release's migrations and Claude context in, and the demo. This repository's npm scripts run the same commands, so both
  * use one implementation.
  *
- * Every command acts on the directory it runs in. Seed and reset work only against a local
- * dev server, whose dev routes exist nowhere else.
+ * Every command acts on the directory it runs in, except the sign-in: login, logout, and api
+ * act as the person at this computer, whose sign-ins are theirs rather than a folder's.
+ * Seed and reset work only against a local dev server, whose dev routes exist nowhere else.
  */
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -29,6 +30,11 @@ Usage: kestrel <command> [options]
   seed [--size <n>] [port|url]  load the demo publication into the local dev server
   reset [port|url]              return the local dev server to a fresh install
 
+  login <url> [--no-browser]    sign in to a deployed instance as you, in your browser
+  logout [url]                  sign out of it on this computer
+  api <method> <path> [opts]    call the API as you, via Claude Code (kestrel api for options)
+  api --list | help <m> <path>  list the instance's routes, or describe one
+
   help, --help                  show this
   version, --version            print the installed version`;
 
@@ -53,6 +59,15 @@ switch (command) {
   case "reset":
     await (await import("../cli/reset.mjs")).resetCommand(argv);
     break;
+  case "login":
+    await (await import("../cli/login.mjs")).loginCommand(argv);
+    break;
+  case "logout":
+    await (await import("../cli/login.mjs")).logoutCommand(argv);
+    break;
+  case "api":
+    await (await import("../cli/api.mjs")).apiCommand(argv);
+    break;
   case "version":
   case "--version":
   case "-v":

package/cli/api.mjs

@@ -0,0 +1,462 @@
+/*
+ * `kestrel api`: call an instance's API as the person signed in, naming the program the
+ * request came through, the way Claude Code reaches Kestrel (SPEC §11, Who acted).
+ *
+ * Deployed, it sends the access token `kestrel login` stored, refreshing it from the
+ * refresh token when it is about to expire or Access has turned it away, and storing what
+ * comes back. Locally there is no Access: the target is this directory's dev server, and
+ * the credential is the dev server's human token, so a local run is a person via Claude
+ * Code just as a deployed one is. Every request carries `Kestrel-Client: claude-code`
+ * unless `--client` names another program, so a person's own script can name itself. It
+ * never names the editor: the server trusts the name it is sent (SPEC, Trusted, not guarded),
+ * and the editor's name lifts a step only a person in the editor may take (SPEC §7).
+ *
+ * It prints the answer's body as it came, so a script or Claude reads a refusal whole; a
+ * non-2xx answer also prints its status, and a refusal's code, message, field, and next move,
+ * on stderr and exits 1, as curl --fail-with-body.
+ *
+ * What the API is comes from the instance itself: `--list` and `help` read its OpenAPI
+ * document through the same sign-in, as `-f` and `-F` do to build a body and refuse a field
+ * the route doesn't take (cli/openapi.mjs). It is read fresh each time it is needed, not
+ * cached, so it can never describe a release the instance no longer runs.
+ */
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { readSignIn, readSignIns, withCredentialsLock, writeSignInHeld } from "./credentials.mjs";
+import { devTarget } from "./dev-api.mjs";
+import {
+  DEFAULT_CLIENT,
+  instanceOrigin,
+  isLoopback,
+  needsRefresh,
+  refreshTokens,
+  SignInError,
+  tokenFields,
+} from "./oauth.mjs";
+import {
+  buildFields,
+  describeRefusal,
+  describeRoute,
+  findOperation,
+  listRoutes,
+} from "./openapi.mjs";
+
+const USAGE = `Usage: kestrel api <method> <path> [options]
+       kestrel api --list [resource]       the instance's routes, or one resource's
+       kestrel api help <method> <path>    one route: its fields, refusals, and answer
+
+  -f, --raw-field <name=value>  a body field, as a string; repeatable. On a GET, or for a name
+                                the route takes only as one, a query parameter
+  -F, --field <name=value>      a body field typed by the route's schema (true, 3, null, JSON),
+                                or name=@file for a file's text. name.sub nests; name[] lists
+  --data <json|@file|->         the request body: inline, from a file, or from stdin
+  --type <media type>           the body's type (default application/json)
+  --form <name=value>           a multipart field, repeatable; name=@file attaches a file
+  --url <url>                   the instance (default: KESTREL_URL, else your one sign-in)
+  --local                       this directory's dev server, started by kestrel dev
+  --client <name>               your own script's Kestrel-Client name (default ${DEFAULT_CLIENT});
+                                never editor, which only the editor names itself
+
+The routes, fields, and refusals come from the instance's own /api/openapi.json, so they
+match the release it runs. A field the route doesn't take is refused before the request.`;
+
+// The name only the editor sends; `kestrel api` refuses to claim it (SPEC §7, §11).
+const EDITOR_CLIENT = "editor";
+
+// The server's rule for a client name (shared/who_acted.ts), mirrored since the CLI is plain
+// Node; a spec holds the two equal. Checking it here, after the trim fetch applies to a header
+// value, means the name refused is the one the server would have read.
+export const CLIENT_NAME_MAX = 32;
+export const CLIENT_NAME_PATTERN = "^[a-z0-9]+(?:-[a-z0-9]+)*$";
+
+const ONE_WAY = "Send the body one way: --data, --form, or -f and -F fields, not two.";
+
+// Options that take a value, by the name they are stored under.
+const VALUED = {
+  data: "data",
+  type: "type",
+  url: "url",
+  client: "client",
+  form: "forms",
+  "raw-field": "fields",
+  f: "fields",
+  field: "fields",
+  F: "fields",
+};
+
+/**
+ * Read `kestrel api`'s argv. A call is a method and a path, `--form`, `-f`, and `-F`
+ * repeatable; `--list [resource]`, `help`, and `help <resource>` list the routes, and
+ * `help <method> <path>` describes one. The body is sent one way: `--data`, `--form`, or
+ * fields, never two at once, since merging them would leave a reader guessing which won; a
+ * field that is a query parameter may go beside `--data` or `--form`.
+ */
+export function parseApiArgs(argv) {
+  const opts = { forms: [], fields: [], local: false, list: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const eq = /^--([^=]+)=(.*)$/s.exec(arg);
+    const short = /^-([A-Za-z])$/.exec(arg);
+    const name = eq ? eq[1] : short ? short[1] : arg.startsWith("--") ? arg.slice(2) : undefined;
+    if (name === undefined) {
+      positional.push(arg);
+      continue;
+    }
+    if (name === "local" || name === "list") {
+      // `--list=sends` names its resource as `--list sends` does; --local names nothing.
+      if (eq && name === "local") {
+        throw new SignInError(`--local takes no value; to name a server, use --url <url>.`);
+      }
+      if (eq) {
+        positional.push(eq[2]);
+      }
+      opts[name] = true;
+      continue;
+    }
+    const key = VALUED[name];
+    const flag = short ? `-${name}` : `--${name}`;
+    if (!key) {
+      throw new SignInError(`unknown option ${flag}\n\n${USAGE}`);
+    }
+    const value = eq ? eq[2] : argv[++i];
+    if (value === undefined) {
+      throw new SignInError(`${flag} needs a value\n\n${USAGE}`);
+    }
+    if (key === "fields") {
+      opts.fields.push({ typed: name === "F" || name === "field", text: value });
+    } else if (key === "forms") {
+      opts.forms.push(value);
+    } else {
+      opts[key] = value;
+    }
+  }
+  if (opts.client !== undefined) {
+    opts.client = opts.client.trim();
+    if (
+      opts.client.length > CLIENT_NAME_MAX ||
+      !new RegExp(CLIENT_NAME_PATTERN).test(opts.client)
+    ) {
+      throw new SignInError(
+        `--client takes one short lowercase word, its parts joined by hyphens (my-script), up to ${CLIENT_NAME_MAX} characters.`,
+      );
+    }
+    if (opts.client === EDITOR_CLIENT) {
+      throw new SignInError(
+        "--client editor is refused: only the editor names itself the editor, since some acts only a person in the editor may confirm. Name your own program, or leave --client out.",
+      );
+    }
+  }
+  const { list, ...rest } = opts;
+  const bodies = [opts.data !== undefined, opts.forms.length > 0, opts.fields.length > 0];
+  const help = positional[0] === "help";
+  if (list || help) {
+    const args = help ? positional.slice(1) : positional;
+    if (bodies.some(Boolean)) {
+      throw new SignInError("--list and help send nothing, so they take no body or fields.");
+    }
+    if (args.length === 2 && help) {
+      const [method, path] = args;
+      return { mode: "help", method: method.toUpperCase(), path, ...rest };
+    }
+    if (args.length > 1) {
+      throw new SignInError(USAGE);
+    }
+    return { mode: "list", resource: args[0], ...rest };
+  }
+  const [method, path, ...extra] = positional;
+  if (!method || !path || extra.length) {
+    throw new SignInError(USAGE);
+  }
+  if (!path.startsWith("/")) {
+    throw new SignInError(`The path starts with a slash, as in /api/posts.\n\n${USAGE}`);
+  }
+  // Fields may go with --data or --form only as query parameters, which apiCommand checks
+  // once it knows where each field goes.
+  if (bodies[0] && bodies[1]) {
+    throw new SignInError(ONE_WAY);
+  }
+  return { mode: "call", method: method.toUpperCase(), path, ...rest };
+}
+
+/**
+ * Which instance a call goes to: `--url`, then `KESTREL_URL`, then the one instance this
+ * person is signed in to. Several sign-ins and nothing naming one is a refusal, not a guess.
+ */
+export function chooseInstance({ url, env = process.env, signIns }) {
+  if (url) {
+    return instanceOrigin(url);
+  }
+  if (env.KESTREL_URL) {
+    return instanceOrigin(env.KESTREL_URL);
+  }
+  const origins = Object.keys(signIns);
+  if (origins.length === 1) {
+    return origins[0];
+  }
+  if (origins.length === 0) {
+    throw new SignInError(
+      "You aren't signed in to an instance. Run `npx kestrel login <url>` first, or --local for this directory's dev server.",
+    );
+  }
+  throw new SignInError(
+    `You're signed in to ${origins.length} instances (${origins.join(", ")}). Name one with --url or KESTREL_URL.`,
+  );
+}
+
+/** The request body and its headers, from --data, --type, and --form. */
+async function requestBody({ data, type, forms }) {
+  if (forms.length) {
+    const form = new FormData();
+    for (const field of forms) {
+      const at = field.indexOf("=");
+      if (at < 1) {
+        throw new SignInError(`--form takes name=value or name=@file, not "${field}".`);
+      }
+      const name = field.slice(0, at);
+      const value = field.slice(at + 1);
+      if (value.startsWith("@")) {
+        const file = value.slice(1);
+        form.append(name, new Blob([readFileSync(file)]), basename(file));
+      } else {
+        form.append(name, value);
+      }
+    }
+    return { body: form, headers: {} };
+  }
+  if (data === undefined) {
+    return { body: undefined, headers: {} };
+  }
+  let body;
+  if (data === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    body = Buffer.concat(chunks);
+  } else if (data.startsWith("@")) {
+    body = readFileSync(data.slice(1));
+  } else {
+    body = data;
+  }
+  return { body, headers: { "content-type": type ?? "application/json" } };
+}
+
+/**
+ * A usable access token for `origin`'s stored sign-in, refreshed first when it is about to
+ * expire, or when `force` says Access just turned it away. The refresh runs under the
+ * credentials lock, and a call that waited there uses the token the other stored, so one
+ * refresh token is never spent twice. A grant that has ended leaves the person to sign in
+ * again.
+ */
+export async function accessToken(origin, { force = false, env = process.env } = {}) {
+  const ended = `Your sign-in to ${origin} has ended. Run \`npx kestrel login ${origin}\` again.`;
+  const entry = readSignIn(origin, env);
+  if (!entry) {
+    throw new SignInError(
+      `You aren't signed in to ${origin}. Run \`npx kestrel login ${origin}\`.`,
+    );
+  }
+  if (!force && !needsRefresh(entry)) {
+    return entry.access_token;
+  }
+  // The token Access just refused, when it did: a stored token equal to it is no use.
+  const refused = force ? entry.access_token : undefined;
+  return withCredentialsLock(async () => {
+    const now = readSignIn(origin, env);
+    if (!now) {
+      throw new SignInError(
+        `You aren't signed in to ${origin}. Run \`npx kestrel login ${origin}\`.`,
+      );
+    }
+    if (!needsRefresh(now) && now.access_token !== refused) {
+      return now.access_token;
+    }
+    if (!now.refresh_token) {
+      throw new SignInError(ended);
+    }
+    try {
+      const fields = tokenFields(await refreshTokens(now), now);
+      writeSignInHeld(origin, { ...now, ...fields }, env);
+      return fields.access_token;
+    } catch (err) {
+      if (err instanceof SignInError && err.oauthError === "invalid_grant") {
+        throw new SignInError(ended);
+      }
+      throw err;
+    }
+  }, env);
+}
+
+/**
+ * Call `origin`'s API as the signed-in person: one retry after a refresh when Access answers
+ * 401, since a token can be revoked or shortened before its stated expiry. Answers the
+ * Response.
+ */
+export async function signedInFetch(origin, path, { method = "GET", body, headers = {}, client }) {
+  const send = async (token) =>
+    fetch(`${origin}${path}`, {
+      method,
+      body,
+      redirect: "manual",
+      headers: {
+        accept: "application/json",
+        ...headers,
+        "kestrel-client": client,
+        authorization: `Bearer ${token}`,
+      },
+    });
+  let res = await send(await accessToken(origin));
+  // Access's own refusal names its OAuth metadata; the app's 401 doesn't, and a fresh token
+  // wouldn't change it. A streamed body (stdin) can't be sent twice, but it is read whole.
+  if (res.status === 401 && /resource_metadata=/.test(res.headers.get("www-authenticate") ?? "")) {
+    res = await send(await accessToken(origin, { force: true }));
+  }
+  return res;
+}
+
+/**
+ * How a run reaches its instance: a function that sends one request there and answers the
+ * Response. A loopback address, given or in KESTREL_URL, is a dev server, which has no sign-in:
+ * its own human token is minted as the editor's is (SPEC §10). Anything else is the stored
+ * sign-in, refreshed as it needs.
+ */
+async function openTarget(args, client) {
+  const named = args.url || process.env.KESTREL_URL || undefined;
+  if (args.local || (named && isLoopback(instanceOrigin(named)))) {
+    const { base, token } = await devTarget(
+      args.local ? undefined : instanceOrigin(named),
+      "api",
+      "human",
+    );
+    return (path, { method = "GET", body, headers = {} } = {}) =>
+      fetch(`${base}${path}`, {
+        method,
+        body,
+        headers: {
+          accept: "application/json",
+          ...headers,
+          "kestrel-client": client,
+          authorization: `Bearer ${token}`,
+        },
+      });
+  }
+  const origin = chooseInstance({ url: args.url, signIns: readSignIns() });
+  return (path, { method = "GET", body, headers = {} } = {}) =>
+    signedInFetch(origin, path, { method, body, headers, client });
+}
+
+/** The instance's OpenAPI document, read through `call`, or a refusal saying why there is none. */
+export async function readOpenApi(call) {
+  const res = await call("/api/openapi.json");
+  const text = await res.text();
+  if (res.status === 404) {
+    throw new SignInError(
+      "This instance serves no /api/openapi.json, so its routes can't be listed or checked: it runs a release older than this CLI's. Send a body with --data instead.",
+    );
+  }
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    doc = undefined;
+  }
+  if (!res.ok || !doc?.paths) {
+    const said = typeof doc?.message === "string" ? `: ${doc.message}` : "";
+    throw new SignInError(
+      `Couldn't read the instance's /api/openapi.json (HTTP ${res.status})${said}`,
+    );
+  }
+  return doc;
+}
+
+/** A call's path with `query`'s pairs appended to whatever query string it already has. */
+function withQuery(path, query) {
+  if (!query.length) {
+    return path;
+  }
+  const params = new URLSearchParams(query);
+  return `${path}${path.includes("?") ? "&" : "?"}${params}`;
+}
+
+/**
+ * `kestrel api`: list the routes, describe one, or call one. A call prints the answer's body
+ * on stdout as it came; on a non-2xx answer it also prints the status and, for a refusal, its
+ * code, message, field, and next move on stderr, and exits 1.
+ */
+export async function apiCommand(argv) {
+  let res;
+  let doc;
+  let found;
+  let call;
+  try {
+    const args = parseApiArgs(argv);
+    const client = args.client ?? DEFAULT_CLIENT;
+    call = await openTarget(args, client);
+    if (args.mode === "list") {
+      console.log(listRoutes(await readOpenApi(call), args.resource));
+      return;
+    }
+    if (args.mode === "help") {
+      console.log(describeRoute(await readOpenApi(call), args.method, args.path));
+      return;
+    }
+    let path = args.path;
+    let { body, headers } = await requestBody(args);
+    if (args.fields.length) {
+      doc = await readOpenApi(call);
+      found = findOperation(doc, args.method, path);
+      if (!found) {
+        throw new SignInError(
+          `This instance has no route ${args.method} ${path.split("?")[0]}, so its fields can't be checked. \`kestrel api --list\` lists them.`,
+        );
+      }
+      const built = buildFields(doc, found, args.fields);
+      path = withQuery(path, built.query);
+      if (built.body && body !== undefined) {
+        throw new SignInError(ONE_WAY);
+      }
+      if (built.body) {
+        body = JSON.stringify(built.body);
+        headers = { "content-type": "application/json" };
+      }
+    }
+    res = await call(path, { method: args.method, body, headers });
+  } catch (err) {
+    console.error(`kestrel api: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  const text = await res.text();
+  if (text) {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+  }
+  if (!res.ok) {
+    console.error(`kestrel api: HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ""}`);
+    for (const line of (await refusalLines(text, { doc, found, call })) ?? []) {
+      console.error(`  ${line}`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * A refusal's readable lines, its next move from the instance's document (read now if the
+ * call didn't already), or undefined when the body isn't a refusal. A document that can't be
+ * read only leaves the move out: the refusal itself is already printed.
+ */
+async function refusalLines(text, { doc, found, call }) {
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (typeof body?.error !== "string") {
+    return undefined;
+  }
+  let known = doc;
+  if (!known) {
+    known = await readOpenApi(call).catch(() => undefined);
+  }
+  return describeRefusal(body, { doc: known, op: found?.op });
+}