unfazed 0.5.0 → 0.6.1

package/README.md

@@ -18,6 +18,13 @@ SDK:  one script. Three requests. You read the four lines you cared about.
 ```
 
 - Zero runtime dependencies. Installing `unfazed` installs exactly one package.
+  (The optional [`unfazed/workflow`](#durable-workflows-unfazedworkflow) subpath
+  uses Workflow SDK packages your app installs; the root entry never loads them.)
+- `npx unfazed login` signs you in from a terminal in the browser; the SDK then
+  acts as you, with no token to copy ([details](#sign-in-from-a-terminal-npx-unfazed)).
+- `npx unfazed workflow inspect runs --app <alias>`: Workflow SDK's CLI and web
+  UI read your app's runs through the platform, from any directory
+  ([details](#inspect-runs-from-your-terminal)).
 - Strict TypeScript, generated from the platform's own GraphQL schema.
 - Bun-first, runs unchanged on Node >= 20 and Deno.
 
@@ -29,27 +36,79 @@ bun add unfazed     # or: npm i unfazed
 
 ## Auth
 
-Get a token from <https://unfazed.dev/auth.md> (or `POST
-https://unfazed.dev/agents/register`). The SDK reads `UNFZ_API_TOKEN`:
+**A person** signs in once from a terminal, in the browser
+([`npx unfazed login`](#sign-in-from-a-terminal-npx-unfazed)); the SDK then acts
+as them, with their apps, teams and claimed agents:
+
+```sh
+npx unfazed login
+```
+
+**An agent or a CI job** uses a bearer token instead: an agent registers itself
+at <https://unfazed.dev/auth.md> (`POST https://unfazed.dev/agents/register`).
+The SDK reads `UNFZ_API_TOKEN`, which wins over a stored login:
 
 ```sh
 export UNFZ_API_TOKEN="..."
 ```
 
 ```ts
-const unfazed = new Unfazed();                       // reads UNFZ_API_TOKEN
-const unfazed = new Unfazed({ token });              // or pass it explicitly
+const unfazed = new Unfazed();          // UNFZ_API_TOKEN, else your `npx unfazed login`
+const unfazed = new Unfazed({ token }); // or pass a token explicitly
 ```
 
 Both endpoint and token are configurable. `UNFZ_API_URL` overrides the endpoint
-(default `https://unfazed.dev/query`); `baseUrl` is a convenience for
-self-hosted control planes where only the host differs.
+(default `https://unfazed.dev/query`, or the stored login's); `baseUrl` is a
+convenience for self-hosted control planes where only the host differs.
 
 ```ts
 new Unfazed({ token, baseUrl: "https://staging.example.com" });   // → /query
 new Unfazed({ token, endpoint: "https://example.com/graphql" });  // exact
 ```
 
+## Sign in from a terminal: `npx unfazed`
+
+The package's `unfazed` bin signs a person in, the way `vercel login` does. It
+runs from any directory (`npx` fetches the package when the directory has no
+`unfazed`), on Node >= 20.16 or Bun, with no dependencies.
+
+```sh
+npx unfazed login      # opens the browser; you sign in and allow access
+npx unfazed whoami     # who the SDK acts as here
+npx unfazed logout     # revokes the login where the server offers it, and deletes it
+```
+
+```
+$ npx unfazed login
+Opening your browser to sign in to https://unfazed.dev.
+…
+Signed in to https://unfazed.dev as ada (user).
+The login is stored in /home/ada/.config/unfazed/credentials.json.
+```
+
+- **How:** OAuth 2.1 with PKCE against the platform's own authorization server,
+  the one MCP clients sign in through. The CLI registers itself once as a
+  public client (cached in `oauth-clients.json` beside the login), listens on
+  `http://127.0.0.1:<random port>/callback` for the answer, and asks for
+  `unfz:read unfz:deploy` (`--scope` narrows it).
+- **The login** is `${XDG_CONFIG_HOME:-~/.config}/unfazed/credentials.json`,
+  mode 0600: the access token (an hour long), the refresh token (30 days, rotated
+  on every refresh), the expiry, the endpoint and who signed in. The SDK uses it
+  whenever no token is passed and `UNFZ_API_TOKEN` is unset, refreshes the access
+  token before it expires (and once when the platform refuses it), and writes
+  the rotated pair back for the next process. It is only ever sent to the
+  endpoint it was issued by; another `UNFZ_API_URL` needs its own
+  `UNFZ_API_URL=… npx unfazed login`. `new UnfazedClient({ login: false })`
+  ignores it.
+- **A browser on another machine** (an SSH session, a box): the URL is printed
+  instead of opened. Sign in there, then paste the address the browser ends up
+  on (`http://127.0.0.1:…/callback?code=…`, which does not load there) into the
+  terminal. `--no-browser` prints the URL on your own machine too.
+- **Another control plane:** `--endpoint https://staging.example.com` (or
+  `UNFZ_API_URL`).
+- `whoami --json` prints the same as JSON; nothing the CLI prints ever carries
+  a token.
+
 ## Code mode: deploy, wait, tail logs, in one script
 
 ```ts
@@ -413,6 +472,336 @@ So an agent working inside a run can create workspaces, deploy, and read logs
 through this same SDK with zero configuration and no credential ever written
 into the prompt.
 
+## Durable workflows: `unfazed/workflow`
+
+[Workflow SDK](https://workflow-sdk.dev) runs durable functions: a
+`"use workflow"` function orchestrates `"use step"` functions, survives
+crashes and redeploys, sleeps for minutes or months and waits for webhooks.
+`unfazed/workflow` is the **World** that runs it on unfazed:
+
+- run storage, streams and `await run.returnValue` are the upstream
+  `@workflow/world-postgres` code over **the app's own Postgres** (its
+  migrations are applied for you; the upstream graphile-worker queue is never
+  started);
+- the **queue is the platform's**: every wake-up (`sleep()`, a retry, the next
+  step, a resumed hook) is a delivery the unfazed worker makes to the app's flow
+  route, cold-starting an `on_demand` VM when it is asleep. Nothing needs a warm
+  process, so the default `on_demand` lifecycle is the right one.
+
+```sh
+bun add unfazed workflow @workflow/world-postgres nitro hono
+```
+
+`workflow`, `@workflow/core`, `@workflow/world`, `@workflow/world-postgres`,
+`pg`, `drizzle-orm` and `nitro` are **optional peer dependencies**: code-mode
+users of `unfazed` install none of them. `@workflow/core` arrives with
+`workflow`, and `@workflow/world`, `pg` and `drizzle-orm` with
+`@workflow/world-postgres`, under npm and Bun; with pnpm or Yarn PnP add them
+to the app as well.
+
+### With Nitro (the recipe)
+
+```ts
+// nitro.config.ts
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  modules: ["workflow/nitro", "unfazed/workflow/nitro"],
+  routes: { "/**": "./src/app.ts" },   // a Hono app; not named server.ts (Nitro claims that name)
+});
+```
+
+```json
+// unfazed.json — package.json has "build": "nitro build"
+{ "kind": "SERVICE", "runtime": "BUN", "install": "bun install", "build": "bun run build", "entry": "unfazed-entry.ts" }
+```
+
+```ts
+// unfazed-entry.ts
+export { default } from "./.output/server/index.mjs";
+```
+
+Then bind a Postgres or Neon integration to the app and deploy. In a
+production build the module:
+
+- installs the World with `setWorld(createWorld())` from a server plugin, which
+  Nitro runs before the first request (a bundle without `node_modules` cannot
+  load a World through `WORKFLOW_TARGET_WORLD`);
+- embeds the SQL migrations of **the app's own** `@workflow/world-postgres`, so
+  the schema always matches the storage code in the bundle;
+- answers anything that reaches `/.well-known/workflow/v1/flow` without the
+  platform's queue token with **401** (including the SDK's `?__health` probe).
+  Public ingress strips that header, so only the platform can deliver. The
+  webhook route stays public: its unguessable token is its authorization;
+- mounts the **inspection route** the unfazed dashboard and MCP read runs
+  through (below), with the build's workflow list and Workflow SDK version;
+- sets `noExternals: true` and builds Nitro's `standard` output (`export
+  default { fetch }`), which is what unfazed serves, whenever no preset was
+  chosen, whatever Nitro detected on the build machine: `bun` under Bun (as on
+  the unfazed build VM), `node-server` under Node, `deno-server` under Deno.
+  Their own outputs start a server of their own (under Bun with a 10 s idle
+  timeout that cuts every quiet workflow stream). A preset chosen explicitly
+  (`preset` in nitro.config.ts or .nitrorc, `NITRO_PRESET`, `SERVER_PRESET`)
+  other than `standard` **fails the build** with a message saying so; leave it
+  out, or set `preset: "standard"`.
+- serves public assets only when `serveStatic: "inline"` embeds them in the
+  bundle (a service VM has nothing next to it to read from disk). That is how
+  one service ships an API and its UI (`publicAssets: [{ dir: "dist" }]`
+  after a `vite build`).
+
+`nitro dev` is left alone and keeps the SDK's Local World.
+
+A complete app — steps, a retried step, `sleep`, a webhook (plain
+`createWebhook()` and `webhook.url`), a progress stream — is in
+[`examples/workflow-nitro`](./examples/workflow-nitro). Once it is deployed,
+`npx unfazed workflow inspect runs --app <alias>` lists its runs
+([Inspect runs from your terminal](#inspect-runs-from-your-terminal)).
+[`examples/birthday-card-generator`](./examples/birthday-card-generator) is
+Vercel's Workflow launch demo on unfazed: a React UI built by Vite and served
+from the same bundle, AI steps, webhooks resumed from emails, `sleep` until a
+date, and a stream the UI reconnects to; it runs without any provider keys.
+
+### Without Nitro
+
+Install the World in your framework's start-up hook, before it serves:
+
+```ts
+import { setWorld } from "workflow/runtime";
+import { createWorld } from "unfazed/workflow";
+
+setWorld(createWorld());   // Next.js: instrumentation.ts register(); SvelteKit: hooks.server.ts init
+```
+
+`createWorld()` is synchronous and opens nothing. Without the Nitro module the
+World applies the migrations embedded in this package (built from the
+`@workflow/world-postgres` version in its devDependencies), so keep the app's
+`@workflow/world-postgres` on that version.
+
+Mount the inspection route yourself, as a catch-all under its base path:
+
+```ts
+// e.g. Next.js: app/.well-known/workflow/v1/unfazed/inspect/v1/[op]/route.ts
+import { createInspectHandler } from "unfazed/workflow";
+
+const inspect = createInspectHandler({ workflowVersion: "5.2.2" });   // optional: workflows: [...names]
+export const GET = inspect;
+export const POST = inspect;
+```
+
+### Inspecting runs from the dashboard and MCP
+
+The app answers the platform's questions about its runs itself, on
+`/.well-known/workflow/v1/unfazed/inspect/v1/<op>` (unfazed
+`docs/workflow-inspect.md`, guest contract v1): `info`, `runs`, `run`, `steps`,
+`step`, `events`, `event` and `stream` read through the app's own World
+(`getWorld()`), so an `on_demand` app cold-starts for the request and holds no
+database connection afterwards; `wake` and `cancel` are Workflow SDK's own
+`getRun(id).wakeUp()` and `.cancel()`.
+
+- Only the platform can call it: anything without `X-Unfz-Queue-Token` equal to
+  `UNFZ_STATE_TOKEN` (compared in constant time) gets 401, and public ingress
+  strips that header. A World that failed to start answers 503
+  `world_unavailable` with its start error, which the owner sees.
+- Payloads (inputs, outputs, errors, event data, stream chunks) are hydrated
+  with `workflow/observability` on top of the SDK's common revivers and sent as
+  display text, cut at the contract's caps (16 KiB per input or output, 64 KiB
+  per event payload, 8 KiB per chunk); every answer stays under 1 MiB, a page
+  coming back shorter (with the World's cursor for the rest) when it must.
+- Hook tokens and webhook URLs never leave: hooks are shown by ID, kind and
+  state; every `token` key is dropped from event info and event data; every
+  occurrence of the run's hook tokens in an event's data reads `[redacted]`;
+  and every Workflow SDK webhook URL in any text the route returns (run and
+  step inputs and outputs, errors, event info and data, stream chunks,
+  attributes) has its token segment replaced, as
+  `https://app.example/.well-known/workflow/v1/webhook/[redacted]?answer=yes`,
+  also when percent-encoded inside another URL or written with JSON-escaped
+  slashes. That happens before any cap, so a cut never leaves part of a token.
+  Everything else the app writes is shown as written, as in its logs.
+- A step's input shows as its arguments: Workflow SDK stores it as
+  `{ args, closureVars, thisVal }`, and the route answers `args`, or
+  `{ args, closureVars?, thisVal? }` with only the parts that hold something
+  (any other stored shape is shown as it is).
+- A run page carries at most the latest 500 sleeps and 500 hooks
+  (`waits_truncated` / `hooks_truncated` say when there were more); a list
+  page may hold fewer items than `limit`, so callers page on `has_more`.
+
+### Inspect runs from your terminal
+
+Workflow SDK's own CLI reads an app's runs through the platform, the way
+`--backend vercel` reads a Vercel project. From any directory:
+
+```sh
+npx unfazed login                                       # once
+npx unfazed workflow inspect runs --app birthday-card
+```
+
+```
+runId                            workflowName          status     startedAt                completedAt
+-------------------------------  --------------------  ---------  -----------------------  -----------------------
+wrun_01KPBDAY00000000000000RN01  generateBirthdayCard  running    2026-10-15 09:30:01.000
+wrun_01KPBDAY00000000000000RN02  generateBirthdayCard  completed  2026-10-15 09:10:01.000  2026-10-15 09:12:00.000
+wrun_01KPBDAY00000000000000RN03  generateBirthdayCard  failed     2026-10-15 09:05:01.000  2026-10-15 09:06:00.000
+```
+
+```sh
+npx unfazed workflow inspect run <run-id> --app birthday-card            # input, output, error
+npx unfazed workflow inspect steps --runId <run-id> --app birthday-card  # also: events, hooks, sleeps, streams
+npx unfazed workflow inspect step <step-id> --runId <run-id> --app birthday-card
+npx unfazed workflow inspect stream <stream-id> --runId <run-id> --app birthday-card   # follows it while the run writes
+npx unfazed workflow cancel <run-id> --app birthday-card
+npx unfazed workflow web --app birthday-card     # the local web UI: trace, events, streams,
+                                                 # Wake Up Sleep and Cancel
+```
+
+`npx unfazed workflow …` is Workflow SDK's CLI with this package as its
+backend: everything after `workflow` but `--app` is passed to it, and its
+output and exit code come back unchanged. It runs the project's own
+`workflow` (major 5) when the directory has one, else `npx -y workflow@5`.
+
+**Inside a project** that has `unfazed` installed, the CLI's native form works
+too, since the CLI resolves `--backend unfazed` from the project:
+
+```sh
+UNFZ_APP=birthday-card npx workflow inspect runs --backend unfazed
+```
+
+`export WORKFLOW_TARGET_WORLD=unfazed` saves typing `--backend` there. The
+usual options work (`--json`, `--limit`, `--cursor`, `--all`, `--status`,
+`--workflowName`, `--interactive`); the exceptions are below.
+
+- **Which app:** `--app` (`npx unfazed workflow` only), else `UNFZ_APP` (its
+  alias, the `<alias>` of `https://<alias>.unfz.to`), else the `alias` in
+  `./unfazed.json`, or its only `apps[]` entry. `UNFZ_API_URL` points at
+  another control plane.
+- **The token** is your `npx unfazed login`, or `UNFZ_API_TOKEN` when set. It
+  needs `unfz:read`; cancel and Wake Up Sleep need `unfz:deploy` too, and the
+  caller must be allowed to restart the app (owner, team member, operator).
+- **Every command is one platform call relayed to the app**, through the same
+  inspection route the dashboard reads; an `on_demand` app cold-starts for it,
+  as for a visitor.
+
+What differs from `--backend vercel`:
+
+- **Payloads are the inspection route's display data**: hydrated inside the
+  app and cut at its caps (16 KiB per run or step input and output, 64 KiB
+  per event payload, 8 KiB per stream chunk). A cut value is a string ending
+  in `… [truncated by unfazed inspection: N bytes in full]`. Values are JSON:
+  a `Date` reads as its ISO string, a `Map`, `Set`, bytes or `Error` as
+  `{"$map": …}`, `{"$set": …}`, `{"$bytes": n}`, `{"$error": …}`. A payload the
+  app could not read is `[unreadable payload: <why>]`. Run data on unfazed is
+  not encrypted, so `--decrypt` has nothing to do.
+- **Hook tokens never leave the app**: hooks show `token: "[redacted]"`, and
+  the web UI cannot resume a hook.
+- **List views carry no payloads**, so `--withData` (deprecated by the CLI for
+  lists) shows none; `inspect run <id>` and `inspect step <id>` do. Listed
+  events carry their metadata, `inspect event <id>` its payload.
+- **No analytics read path**: `--attribute`, `--since`/`--until` and `inspect
+  attributes` need one, and the CLI says it is ignored or unavailable.
+- **Runs list newest first only** (`--sort asc` is refused). A run's steps
+  newest first (the CLI's default) are read whole, up to 2 000, and paged
+  locally.
+- **Hooks are found through their run**: `inspect hooks` without `--runId`,
+  and `inspect hook <id>`, look through the app's running and pending runs.
+- **A run page reads at most 10 000 events**, the latest 500 sleeps and 500
+  hooks, and 50 streams (the route's limits).
+- **Writes**: cancel (`workflow cancel`, bulk cancel, the web UI) and wake-up
+  (the web UI) go through the platform. Everything else (replay, re-enqueue,
+  resuming a hook, starting a run) is refused: this backend is read-only, and
+  an app's own World is `unfazed/workflow`. Setting
+  `WORKFLOW_TARGET_WORLD=unfazed` inside an app fails loudly for the same
+  reason.
+
+### How it behaves
+
+- **Start-up is lazy and cheap.** The first World call of a process applies the
+  migrations (one query when the database is current) and probes the platform
+  queue; every call waits for that, so a request arriving during a cold start
+  waits instead of failing. Active runs are then re-enqueued in the background
+  with the key `reenqueue:<runId>:<deploymentId>`, which the platform drops as
+  a duplicate while that message is stored and for an hour after it settles,
+  so a run asleep for days is not re-enqueued on every cold start.
+  `world.start()` does the same and lets you await it.
+- **No warm process, no lingering connections.** Postgres connections,
+  including the `LISTEN` ones behind stream readers and
+  `waitForTerminalStatus`, are held only while a World call or a stream reader
+  is open (plus 2 s); idle pool connections close after 5 s. A reaped VM leaves
+  nothing behind on the database.
+- **Deliveries** carry `X-Unfz-Queue-*` headers; the handler checks the token
+  in constant time against `UNFZ_STATE_TOKEN`, maps the rest to the SDK's
+  message metadata, and reports the delivery deadline (15 minutes from the
+  moment the VM was ready, so a cold start does not shorten it) through
+  `getRuntimeDeadline()`, so the SDK sizes its inline work to fit. Every answer
+  is a complete JSON body and never a redirect (the platform follows none, and
+  retries a 3xx or a broken 2xx body).
+- **Concurrency:** at most 32 deliveries per app are open at once. Set it per
+  app in `unfazed.json` with `"workflow": {"concurrency": N}` (1 to 256;
+  `workflow_concurrency` on `create_service_deployment` for an app deployed
+  from a workspace). A step that awaits a child run holds one delivery for the
+  child's whole run, so keep the concurrency above the number of such waits.
+  When the VM stops on its own under deliveries (out of memory, a crash), the
+  platform halves the app's concurrency for 5 minutes and records a
+  `service.workflow_throttled` event.
+- **Routes for other queue consumers:** `world.registerRoute(prefix, path)` is
+  stored on the platform. `registerHandler()` is not offered: the platform
+  delivers over HTTP, never inside a process.
+- **Webhook URLs need no code.** `createWebhook().url` (and
+  `getWorkflowMetadata().url`) are built on the app's public address. Workflow
+  SDK 5.x reads only `VERCEL_URL` for that (`https://${VERCEL_URL}`, else
+  `http://localhost:<port>`), so when `VERCEL_URL` is unset and
+  `UNFZ_PUBLIC_URL` is a bare https host — a custom domain or
+  `https://<alias>.unfz.to` — `createWorld()` sets `VERCEL_URL` to that host in
+  the app's own process. Inside the SDK that variable decides nothing else
+  (it also skips probing for the local port, which is then unneeded). Your own
+  code and libraries see it too, as the public host. Opt out with
+  `createWorld({ publicUrl: false })`; an explicit `VERCEL_URL` is never
+  changed.
+
+  A **path-form** public URL (`https://app.unfazed.dev/<alias>`) cannot be
+  passed that way: the SDK's base path is fixed at build time and Workflow
+  SDK's Nitro integration sets none. Those apps build the URL in a step:
+
+  ```ts
+  async function publicWebhookUrl(token: string) {
+    "use step";
+    return `${process.env.UNFZ_PUBLIC_URL}/.well-known/workflow/v1/webhook/${token}`;
+  }
+  ```
+- **Errors** are `UnfazedWorkflowError` with a `code`: `no_database` (bind a
+  Postgres or Neon integration), `no_platform` (not inside an unfazed service),
+  `queue_not_supported` (the worker has no queue yet), `queue_unavailable`,
+  `quota_exceeded` (its message names the limit: 100 000 pending messages,
+  64 MiB of live messages or 200 000 idempotency keys), `payload_too_large`
+  (over 1 MiB), `unavailable` (503 or network, after 30 s of retries with the
+  same idempotency keys), …
+
+| Read from | Meaning |
+| --- | --- |
+| `WORKFLOW_POSTGRES_URL`, `DATABASE_URL_UNPOOLED`, `DATABASE_URL` | run storage, first one set; `sslmode=require` gets `uselibpqcompat=true` |
+| `WORKFLOW_POSTGRES_MAX_POOL_SIZE` | pool size (default 10) |
+| `UNFZ_STATE_URL`, `UNFZ_STATE_TOKEN` | the platform queue and the delivery token (injected by unfazed) |
+| `UNFZ_DEPLOYMENT_ID` | `getDeploymentId()` |
+| `UNFZ_PUBLIC_URL` | the public address webhook URLs are built on (see above) |
+
+`createWorld({ ... })` takes the same settings as options (`connectionString`,
+`stateUrl`, `stateToken`, `deploymentId`, `maxPoolSize`, `migrations`,
+`publicUrl`, `retryBudgetMs`, `idleReleaseMs`, `env`, `fetch`).
+
+### Testing it
+
+```sh
+bun test                                           # unit tests, incl. a fake platform implementing the wire contract
+export UNFAZED_TEST_DATABASE_URL=postgres://...    # a database whose user may CREATE DATABASE
+bun test test/workflow                             # + the World against Postgres
+WORKFLOW_POSTGRES_URL=$UNFAZED_TEST_DATABASE_URL bun run test:conformance
+                                                   # the SDK's World conformance suite, and every
+                                                   # delivery cold-started in a fresh process
+bun run test:example                               # the example, bundled as unfazed builds it,
+                                                   # one fresh process per delivery and request
+bun run test:birthday                              # the same for examples/birthday-card-generator
+bun run test:cli                                   # Workflow SDK's CLI with --backend unfazed (and --web)
+                                                   # against a fake of the platform's inspection API
+```
+
 ## Development
 
 ```sh
@@ -424,6 +813,10 @@ bun run build
 bun run check        # all of the above, plus a dist smoke test on Bun AND Node
 ```
 
+After bumping the `@workflow/world-postgres` devDependency, run
+`bun run embed-migrations`: `bun run check` fails while
+`src/workflow/migrations.generated.ts` is stale.
+
 ### Regenerating from the schema
 
 `schema/schema.graphqls` is a **vendored copy** of `graph/schema.graphqls` from

package/dist/cli/login.d.ts

@@ -0,0 +1,129 @@
+import { type StoredCredentials } from "../credentials.js";
+import { UnfazedError } from "../errors.js";
+export declare const USER_AGENT = "unfazed-cli/0.6.1 (+https://unfazed.dev/auth.md)";
+/** What a login asks for: reading and deploying, like an MCP client. */
+export declare const DEFAULT_SCOPE = "unfz:read unfz:deploy";
+export declare const CLIENT_NAME = "unfazed CLI";
+export declare const CALLBACK_PATH = "/callback";
+/** The redirect registered once; each login uses it with its own port. */
+export declare const REGISTERED_REDIRECT_URI = "http://127.0.0.1/callback";
+/** Registered clients, per issuer, beside the login. */
+export declare const CLIENTS_FILE = "oauth-clients.json";
+/** How long a login waits for the browser. */
+export declare const LOGIN_TIMEOUT_MS: number;
+export type Env = Record<string, string | undefined>;
+/** The `fetch` the CLI needs; the global one fits. */
+export type Fetch = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    redirect?: "manual" | "follow";
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** A login that could not be completed; the message says why and what to do. */
+export declare class UnfazedLoginError extends UnfazedError {
+}
+/** The GraphQL endpoint: given, else `UNFZ_API_URL`, else unfazed.dev's; a bare origin gets `/query`. */
+export declare function resolveEndpoint(raw: string | undefined, env: Env): string;
+/** Whether a URL may carry tokens: https, or plain http to this machine only. */
+export declare function safeURL(raw: unknown): raw is string;
+/** RFC 8414 authorization server metadata: the fields the CLI uses. */
+export interface AuthServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    revocation_endpoint?: string;
+    code_challenge_methods_supported?: string[];
+    response_types_supported?: string[];
+    authorization_response_iss_parameter_supported?: boolean;
+}
+/** Reads and checks the metadata of the server at `origin` (e.g. https://unfazed.dev). */
+export declare function discover(origin: string, fetch: Fetch): Promise<AuthServerMetadata>;
+/** A PKCE verifier and its S256 challenge. */
+export declare function pkcePair(): {
+    verifier: string;
+    challenge: string;
+};
+/** A client the CLI registered at one issuer. */
+export interface ClientRecord {
+    client_id: string;
+    redirect_uri: string;
+    scope: string;
+    registered_at: string;
+}
+/** The cached client for `issuer` that may ask for `scope`, if any. */
+export declare function cachedClient(env: Env, issuer: string, scope: string): ClientRecord | undefined;
+export interface LoginOptions {
+    /** GraphQL endpoint or platform origin. Default: `UNFZ_API_URL`, else https://unfazed.dev. */
+    endpoint?: string;
+    /** Space-separated scopes. Default: `unfz:read unfz:deploy`. */
+    scope?: string;
+    /** Default `process.env`: where `UNFZ_API_URL` and the login's location come from. */
+    env?: Env;
+    fetch?: Fetch;
+    /** Opens the sign-in URL; resolves to whether a browser started. Default: print only. */
+    openBrowser?: (url: string) => boolean | Promise<boolean>;
+    /** Where progress goes (never a token). Default: stderr. */
+    log?: (line: string) => void;
+    /** Where a pasted answer is read from (a browser on another machine). Default: none. */
+    input?: NodeJS.ReadableStream;
+    /** How long to wait for the browser. Default {@link LOGIN_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/** Signs in through the browser and stores the login. Resolves to it and where it was stored. */
+export declare function login(options?: LoginOptions): Promise<{
+    credentials: StoredCredentials;
+    path: string;
+}>;
+/** The fields `whoami` shows. */
+export interface Actor {
+    kind: string;
+    userID: string;
+    name: string;
+    scopes: string[];
+}
+export interface WhoamiResult {
+    actor: Actor;
+    endpoint: string;
+    /** `token`: UNFZ_API_TOKEN; `login`: the stored login at `path`. */
+    source: "token" | "login";
+    path?: string;
+}
+/** Who the SDK acts as here: `UNFZ_API_TOKEN` when set, else the stored login (refreshed as needed). */
+export declare function whoami(options?: {
+    env?: Env;
+    fetch?: Fetch;
+}): Promise<WhoamiResult>;
+export interface LogoutResult {
+    /** Whether there was a login to remove. */
+    signedOut: boolean;
+    issuer?: string;
+    /** Whether the server revoked the tokens. */
+    revoked: boolean;
+    /** Whether the server offers revocation (RFC 7009). */
+    revocationSupported: boolean;
+}
+/**
+ * Revokes the stored tokens when the server advertises revocation, then
+ * deletes the login. The endpoint is read from the server's metadata again,
+ * so one the server gained since the login is used.
+ */
+export declare function logout(options?: {
+    env?: Env;
+    fetch?: Fetch;
+}): Promise<LogoutResult>;
+export declare function accountName(credentials: StoredCredentials): string;
+/**
+ * Whether a browser can be expected here. Over SSH, or on Linux without a
+ * display, the login prints the URL instead (and takes the pasted answer).
+ */
+export declare function canOpenBrowser(env: Env, platform?: NodeJS.Platform): boolean;
+/** The command that opens `url` — `$BROWSER`, `open`, `xdg-open` or the Windows URL handler — as argv, never a shell line. */
+export declare function browserCommand(url: string, env: Env, platform?: NodeJS.Platform): string[];
+/** Starts the browser on `url`. Resolves to whether it could be started. */
+export declare function openBrowser(url: string, env?: Env, platform?: NodeJS.Platform): Promise<boolean>;