unfazed 0.6.0 → 0.6.1

package/README.md

@@ -20,8 +20,11 @@ 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 workflow inspect runs --backend unfazed`: Workflow SDK's CLI and web UI
-  read your app's runs through the platform ([details](#inspect-runs-from-your-terminal)).
+- `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.
 
@@ -33,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
@@ -499,8 +554,12 @@ production build the module:
 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,
-`UNFZ_APP=<alias> npx workflow inspect runs --backend unfazed` lists its runs
+`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
 
@@ -569,12 +628,11 @@ database connection afterwards; `wake` and `cancel` are Workflow SDK's own
 ### 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 the app's project (where
-`unfazed` is installed; the CLI loads `createWorld()` from it):
+`--backend vercel` reads a Vercel project. From any directory:
 
 ```sh
-export UNFZ_API_TOKEN=...          # a token from https://unfazed.dev/auth.md
-UNFZ_APP=birthday-card npx workflow inspect runs --backend unfazed
+npx unfazed login                                       # once
+npx unfazed workflow inspect runs --app birthday-card
 ```
 
 ```
@@ -586,25 +644,38 @@ wrun_01KPBDAY00000000000000RN03  generateBirthdayCard  failed     2026-10-15 09:
 ```
 
 ```sh
-npx workflow inspect run <run-id> --backend unfazed               # input, output, error
-npx workflow inspect steps --runId <run-id> --backend unfazed     # also: events, hooks, sleeps, streams
-npx workflow inspect step <step-id> --runId <run-id> --backend unfazed
-npx workflow inspect stream <stream-id> --runId <run-id> --backend unfazed   # follows it while the run writes
-npx workflow cancel <run-id> --backend unfazed
-npx workflow web --backend unfazed                                # the local web UI: trace, events, streams,
-                                                                  # Wake Up Sleep and Cancel
+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
 ```
 
-The usual options work (`--json`, `--limit`, `--cursor`, `--all`, `--status`,
+`export WORKFLOW_TARGET_WORLD=unfazed` saves typing `--backend` there. The
+usual options work (`--json`, `--limit`, `--cursor`, `--all`, `--status`,
 `--workflowName`, `--interactive`); the exceptions are below.
-`export WORKFLOW_TARGET_WORLD=unfazed` saves typing `--backend`.
-
-- **Which app:** `UNFZ_APP` (its alias, the `<alias>` of
-  `https://<alias>.unfz.to`); without it, the `alias` in `./unfazed.json`, or
-  its only `apps[]` entry. `UNFZ_API_URL` points at another control plane.
-- **The token** 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).
+
+- **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.
@@ -726,6 +797,7 @@ WORKFLOW_POSTGRES_URL=$UNFAZED_TEST_DATABASE_URL bun run test:conformance
                                                    # 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
 ```

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>;