@loomcycle/client 1.125.0 → 1.127.0

package/README.md

@@ -12,6 +12,7 @@ TypeScript client for the [loomcycle](https://github.com/denn-gubsky/loomcycle)
 
 ### What's new since v0.8.18
 
+- **Sign in with loomcycle (apps)** (RFC FL) — `LoomcycleOAuth` (also `client.oauth`) drives loomcycle's own OAuth sign-in for an app: `beginAuthorize` / `completeAuthorize` (PKCE S256, state and RFC 9207 `iss` checked), `refresh`, `revoke`, `discover`. A new `tokenProvider` client option (instead of `authToken`) takes short-lived bearers; `OAuthTokenProvider` refreshes before expiry and once after a 401. ClientDef methods register the apps: `createClientDef` / `updateClientDef` / `getClientDef` / `listClientDefs` / `retireClientDef` / `verifyClientDef` / `listClientDefNames`. See [Sign in with loomcycle (apps)](#sign-in-with-loomcycle-apps). Additive — an `authToken` client is unchanged.
 - **Breaking — `tools` replaces `allowedTools`** — the per-run tool allowlist is now a single canonical key. The `runStreaming` / `continueSession` option is renamed from `allowedTools` to **`tools`**, and the `AgentDefOverlay` + library wire field is likewise **`tools`**, matching the loomcycle YAML rename and aligning with Claude Code agent frontmatter. No dual-key fallback — update call sites to `runStreaming({ …, tools: [...] })`. Requires a loomcycle server carrying the same rename.
 - **Path/Document browse-by-subject + the full Document op set** (v1.12.1, RFC AS/AK) — `path(input, opts)` and `document(input, opts)` accept optional `scopeId` / `tenant` browse overrides, sent as `?scope_id=` / `?tenant=` query params (the server reads them from the URL and re-checks authorization — a tenant principal's `tenant` is ignored, `scopeId` picks any subject it may see); omit both to browse your own subject (byte-identical to the pre-RFC-AS request). `DocumentToolInput.op` now covers all 16 backend ops — adds **`set_path`** (attach/re-home a Path-tree name for an existing document), **`export_md`** (render to Markdown; `include_metadata: false` for clean human-facing output), and **`import_md`** (build a document from export_md-shaped `markdown`). Additive — existing `path()` / `document()` callers are unchanged.
 - **`interactiveSession` / `sendRunInput` / `streamRunByID` + the `interactive` flag** (v1.1.1, RFC AI) — the interactive agentic session, the adapter port of the Web UI's run terminal. Pass `interactive: true` to `runStreaming` / `continueSession` to start a **persistent** run that parks at end_turn (an `awaiting_input` frame) instead of ending; **`sendRunInput(runId, text)`** steers it (the response arrives on the same stream); **`streamRunByID(runId, {fromSeq})`** re-attaches by run_id (the operator's prior turns replay as `steer` events, `user_input.source === "replay"`, so a cold client — e.g. another device — reconstructs the whole conversation). The high-level **`client.interactiveSession({agent, segments})`** returns an `InteractiveSession` with `events()` / `send()` / `cancel()`; **`attachInteractiveSession(runId)`** resumes one. The `AgentEvent` union gains `awaiting_input` / `steer` / `context_compaction`.
@@ -553,6 +554,163 @@ const why = await client.authzExplain({
 console.log(why.decision.outcome, why.traces);
 ```
 
+### Users and sign-in gates (RFC FA)
+
+First-class users and how people sign in. A user's `status` (`UserStatus`) is `active`, `disabled` or `pending`: a sign-in gate configured with `new_user.status: pending` provisions people who can sign in but are refused everything until an operator approves them. `createUser` / `updateUser` accept only `active` and `disabled`; a pending user is activated by `approveUser` (a PATCH to `active` is a 409 `use_approve`). `whoami().auth.status` is `"pending"` for such a session.
+
+The tenant is your own. `opts.tenant` names another for an admin token, and for an `auth:manage` credential (a website's), which must name one (400 `tenant_required`) and is held to the gate's new-user floor; a tenant operator always acts in its own tenant. Every call needs a persistent store.
+
+| Method | Route | Returns |
+|---|---|---|
+| `createUser(body, opts?)` / `updateUser(subject, body, opts?)` / `deleteUser(subject, opts?)` | `POST /v1/_users` / `PATCH` / `DELETE /v1/_users/{subject}` | `UserRecord` / `UserRecord` / void |
+| `approveUser(subject, opts?)` | `POST /v1/_users/{subject}/approve` | `UserRecord`, now `active`; 409 `not_pending` otherwise |
+| `listUserIdentities(subject, opts?)` | `GET /v1/_users/{subject}/identities` | `UserIdentitiesResponse` — the identity-provider accounts a user signs in with; a user reads its own |
+| `unlinkUserIdentity(subject, gate, opts?)` | `DELETE /v1/_users/{subject}/identities/{gate}` | void; for an operator — a user unlinks its own only from its browser session |
+| `listAuthGates({probe?}?)` | `GET /v1/_authgate` | `AuthGateListResponse` — every configured gate, never key material. **Admin token only** |
+| `createInvite(gate, body, opts?)` | `POST /v1/_authgate/{gate}/invites` | `CreatedInvite` — `{invite_id, url, expires_at}`; the URL is shown once |
+| `listInvites(gate, opts?)` | `GET /v1/_authgate/{gate}/invites` | `AuthInviteListResponse` — `state` is `live` / `redeemed` / `revoked` / `expired`; never a code |
+| `revokeInvite(gate, inviteId, opts?)` | `DELETE /v1/_authgate/{gate}/invites/{id}` | void; 409 `invite_not_live` |
+| `createPasswordReset(gate, subject, opts?)` | `POST /v1/_authgate/{gate}/resets` | `CreatedPasswordReset` — a one-time link that sets a new password |
+| `removeGateCredentials(gate, subject, opts?)` | `DELETE /v1/_authgate/{gate}/credentials/{subject}` | void — password, authenticator and recovery codes go; the login stays |
+| `renameGateLogin(gate, subject, login, opts?)` | `PATCH /v1/_authgate/{gate}/logins/{subject}` | `{subject, login}`; 409 `login_taken` |
+| `listGateIdentities(gate, subject, opts?)` | `GET /v1/_authgate/{gate}/identities?subject=` | `GateIdentitiesResponse` — logins, `has_password`, `has_totp` |
+| `getGateTenantStatus(gate, opts?)` | `GET /v1/_authgate/{gate}/tenant-status` | `GateTenantStatus` — whether the tenant has, or ever had, a user, and whether an owner invite is live |
+| `deviceLogin({onPrompt, clientId?, signal?})` | `POST /v1/_auth/device`, then `POST /v1/_auth/device/token` | `DeviceLoginResult` — signs a person in through the server's device gate (RFC 8628): `onPrompt` gets the code to show, the person approves it at `/ui/device`, and the token is theirs, never outliving the session they approved from. Sends no bearer. `DeviceLoginError` (`code` `access_denied` / `expired_token`) otherwise |
+
+None of these takes a password: the person sets their own through the invite or reset link. Hand the link's `url` to the person and do not log it — its fragment is the one-time code.
+
+Signing in, signing out and a person's own password or authenticator are not here. Those routes (`POST /ui/session`, `POST /v1/_auth/logout`, the password login, redeeming an invite or a reset, `/v1/_auth/account`, `/v1/_auth/password`, `/v1/_auth/totp`) establish or act on a browser's cookie session and accept only same-origin requests from loomcycle's own Web UI. A bearer has no session to end: retire a delegated user token with `revokeUserToken`, an operator token with `operatorTokenDef`.
+
+```ts
+const pending = (await client.listUsers({ tenant: "acme" })).users.filter((u) => u.status === "pending");
+for (const u of pending) await client.approveUser(u.user_id, { tenant: "acme" });
+
+const { url } = await client.createInvite("password", { email: "carol@example.com", ttl: "72h" }, { tenant: "acme" });
+```
+
+### Sign in with loomcycle (apps)
+
+An app built on this client does not need a pasted token: it can send the person to loomcycle's own login page, where they sign in through whatever gates the operator configured, and get back a short-lived access token for that same user (RFC FL). It is the OAuth 2.0 authorization code flow with PKCE S256: the app holds no secret, never sees a password, and is authorized exactly as the user is anywhere else. The server side needs `LOOMCYCLE_PUBLIC_URL` and the app registered as a client — in the config's `auth.clients` or at runtime with `createClientDef` (below); see `docs/CONFIGURATION.md`, "App sign-in".
+
+`LoomcycleOAuth` (also `client.oauth`) runs on Web Crypto and `fetch`, so the same code serves a browser SPA, a Chrome extension and a Tauri or Node app. On Node 18, which has no global `crypto`, pass `crypto: require("node:crypto").webcrypto`.
+
+| Method | Route | Returns |
+|---|---|---|
+| `beginAuthorize({clientId, redirectUri, state?})` | — (builds `GET /v1/_oauth/authorize?…`) | `{url, verifier, state}` — persist `verifier` and `state`, then send the person to `url` |
+| `completeAuthorize({...parseAuthorizeResponse(href), expectedState, verifier, clientId, redirectUri})` | `POST /v1/_oauth/token` | `OAuthTokenSet` — `{access_token, refresh_token, token_type, expires_in, expires_at}` (`expires_at` in ms since the epoch) |
+| `refresh({refreshToken, clientId})` | `POST /v1/_oauth/token` | a new `OAuthTokenSet`; the old refresh token is spent |
+| `revoke({token, clientId})` | `POST /v1/_oauth/revoke` | void — a refresh token ends the whole sign-in |
+| `discover()` | `GET /.well-known/oauth-authorization-server` | `OAuthServerMetadata` (RFC 8414), cached |
+
+`completeAuthorize` refuses, before the code is used, a redirect whose `state` is not the one this sign-in sent (`state_mismatch`) or whose `iss` names another server (`issuer_mismatch`, RFC 9207; the issuer comes from the `issuer` option or from `discover()`), and throws a redirect's `error` (`access_denied` with `pending` for a user awaiting approval). Every failure is an `OAuthError` whose `code` is the OAuth error code.
+
+A browser SPA:
+
+```ts
+import { LoomcycleClient, LoomcycleOAuth, OAuthTokenProvider, parseAuthorizeResponse } from "@loomcycle/client";
+
+const baseUrl = "https://loom.example.com";
+const clientId = "loomboard";
+const redirectUri = `${location.origin}/auth/callback`; // registered exactly
+const oauth = new LoomcycleOAuth({ baseUrl });
+
+// "Sign in" button:
+const req = await oauth.beginAuthorize({ clientId, redirectUri });
+sessionStorage.setItem("lc_sign_in", JSON.stringify({ verifier: req.verifier, state: req.state }));
+location.assign(req.url);
+
+// On /auth/callback:
+const saved = JSON.parse(sessionStorage.getItem("lc_sign_in") ?? "{}");
+sessionStorage.removeItem("lc_sign_in");
+const tokens = await oauth.completeAuthorize({
+  ...parseAuthorizeResponse(location.href),
+  expectedState: saved.state,
+  verifier: saved.verifier,
+  clientId,
+  redirectUri,
+});
+history.replaceState(null, "", "/"); // the code is spent; drop it from the address bar
+
+const provider = new OAuthTokenProvider({
+  oauth,
+  clientId,
+  tokens,
+  onTokens: (t) => saveTokens(t), // persist every rotated set
+  onSignedOut: () => showSignIn(),
+});
+const client = new LoomcycleClient({ baseUrl, tokenProvider: provider });
+console.log((await client.whoami()).subject);
+
+// "Sign out":
+await provider.signOut();
+```
+
+A Chrome extension does the same with `chrome.identity.launchWebAuthFlow({url: req.url, interactive: true})`, which resolves with the redirect URL to hand to `parseAuthorizeResponse`; register `https://<extension-id>.chromiumapp.org/` as the redirect URI and `chrome-extension://<extension-id>` as an allowed origin.
+
+A desktop app (Tauri, Electron, a CLI) uses a loopback redirect: register `http://127.0.0.1/callback` and the server accepts it on any port (RFC 8252). In Node:
+
+```ts
+import { createServer } from "node:http";
+
+const server = createServer();
+await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+const port = (server.address() as { port: number }).port;
+const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+const req = await oauth.beginAuthorize({ clientId: "loomboard-desktop", redirectUri });
+openInSystemBrowser(req.url); // e.g. Tauri's shell.open, Electron's shell.openExternal
+
+const href = await new Promise<string>((resolve) =>
+  server.on("request", (r, res) => {
+    res.end("Signed in. You can close this window.");
+    resolve(`http://127.0.0.1:${port}${r.url}`);
+  }),
+);
+server.close();
+const tokens = await oauth.completeAuthorize({
+  ...parseAuthorizeResponse(href),
+  expectedState: req.state,
+  verifier: req.verifier,
+  clientId: "loomboard-desktop",
+  redirectUri,
+});
+```
+
+A Tauri app may register a private-use scheme instead (`loomboard://auth/callback`) and pass the deep link it receives to `parseAuthorizeResponse`. Token calls made from its webview send the origin `tauri://localhost`, which the client must list in `allowed_origins`; calls from the Rust or Node side send none.
+
+**The token provider.** `new LoomcycleClient({ tokenProvider })` (instead of `authToken`; passing both throws) asks the provider for the bearer on every request, `connectClientTools` included. `OAuthTokenProvider` refreshes 60 s before the access token expires (`refreshSkewMs`), and once after a 401: the request is retried a single time with the new token, never more. Concurrent requests share one refresh. Any other source of short-lived tokens can implement `TokenProvider` (`getToken`, optional `onUnauthorized`).
+
+Things to know:
+
+- **Persist every rotated set.** A refresh spends the old refresh token, and presenting a spent one again ends the whole sign-in (reuse detection). `onTokens` is called before the new token is used.
+- **One provider per sign-in.** Two providers, or two browser tabs, refreshing the same refresh token end it the same way. Share one, or sign each tab in separately.
+- **Never log a token or put one in a URL.** The helper sends codes, verifiers and tokens only in POST bodies, with no cookie and no `Authorization` header; keep the `verifier` in session storage, not the URL, and clear it after the exchange.
+- **An ended sign-in** (revoked, expired, its client retired) reaches `onSignedOut` once, when its refresh token is refused; requests then fail with an `OAuthError` (or the server's 401 as `AuthError`). Send the person to sign in again.
+
+**Registering apps (ClientDef).** A tenant operator (`substrate:tenant`) registers its own tenant's apps; an admin any tenant's, or one for every tenant (`tenant: ""`, the default). Config clients are listed read only, and another tenant's client reads as not found. A refusal raises `SubstrateToolRefusedError`.
+
+| Method | Route | Returns |
+|---|---|---|
+| `createClientDef(name, client, {description?, tenant?}?)` | `POST /v1/_clientdef` `op: create` | `ClientDefRecord` |
+| `updateClientDef(name, client, {description?}?)` | `op: update` | `ClientDefRecord`, a new version; unexchanged codes stop working |
+| `getClientDef({name} \| {def_id})` | `op: get` | `AppClientEntry` (`source: "def"` or `"config"`) |
+| `listClientDefs({tenant?}?)` | `op: list` | `{clients: AppClientEntry[]}` |
+| `retireClientDef(name)` | `op: retire` | `{name, retired}` — its sign-ins are revoked and their tokens retired |
+| `verifyClientDef(name, {contentSha256?}?)` | `op: verify` | `ClientDefVerifyResult` |
+| `listClientDefNames({tenant?}?)` | `GET /v1/_clientdef/names` | `{names: ClientDefNameSummary[]}` |
+| `clientDef(input)` | `POST /v1/_clientdef` | the op dispatch, as sent |
+
+```ts
+await admin.createClientDef("loomboard", {
+  kind: "public",
+  label: "Loomboard",
+  redirect_uris: ["https://board.example.com/auth/callback", "http://127.0.0.1/callback"],
+  allowed_origins: ["https://board.example.com"],
+  access_token_ttl: "1h",
+  refresh: { idle: "7d", absolute: "30d" },
+}, { tenant: "acme" });
+```
+
 ### Decision models
 
 Ask a **decision model** typed questions about a piece of text and get each answer with its probabilities. A decision model does not write: it reads the `state` you give it and answers a choice, a yes/no or a score, so there is no reply to parse and a call costs a few output tokens. Use it to route, gate, rank or grade text you already have. No run is involved; the tokens are charged to the caller and count against its token budget.

package/dist/cjs/client-tools.js

@@ -14,6 +14,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientToolHost = exports.CLIENT_TOOL_SUBPROTOCOL = void 0;
 exports.clientToolsURL = clientToolsURL;
+const errors_js_1 = require("./errors.js");
 /** The app-level subprotocol the server negotiates for /v1/client-tools. */
 exports.CLIENT_TOOL_SUBPROTOCOL = "loomcycle.client-tools.v1";
 /**
@@ -24,13 +25,16 @@ exports.CLIENT_TOOL_SUBPROTOCOL = "loomcycle.client-tools.v1";
  */
 class ClientToolHost {
     url;
-    authToken;
+    auth;
     opts;
     ws;
     closed = false;
-    constructor(url, authToken, opts) {
+    /** `auth` is the bearer, or a function that supplies one on each
+     *  (re)connect — a client built with a token provider passes one, so a
+     *  reconnect after the access token expired carries the refreshed one. */
+    constructor(url, auth, opts) {
         this.url = url;
-        this.authToken = authToken;
+        this.auth = auth;
         this.opts = opts;
     }
     /** Open the connection (called for you by connectClientTools). */
@@ -49,9 +53,28 @@ class ClientToolHost {
         if (!WS) {
             throw new Error("connectClientTools: no WebSocket implementation available — pass WebSocketImpl (e.g. the `ws` package) on Node < 22");
         }
+        if (typeof this.auth === "function") {
+            this.auth().then((token) => this.open(WS, token), (err) => {
+                this.opts.onError?.(err);
+                // A sign-in that ended does not come back by retrying: stop
+                // rather than ask again every few seconds.
+                if (err instanceof errors_js_1.OAuthError && !err.retryable) {
+                    this.closed = true;
+                    this.opts.onStatus?.("closed");
+                    return;
+                }
+                this.scheduleReconnect();
+            });
+            return;
+        }
+        this.open(WS, this.auth);
+    }
+    open(WS, token) {
+        if (this.closed)
+            return;
         const protocols = [exports.CLIENT_TOOL_SUBPROTOCOL];
-        if (this.authToken)
-            protocols.push("bearer." + this.authToken);
+        if (token)
+            protocols.push("bearer." + token);
         this.opts.onStatus?.("connecting");
         const ws = new WS(this.url, protocols);
         this.ws = ws;

package/dist/cjs/client.js

@@ -29,6 +29,8 @@ exports.LoomcycleClient = void 0;
 const fetch_helpers_js_1 = require("./fetch-helpers.js");
 const stream_js_1 = require("./stream.js");
 const interactive_js_1 = require("./interactive.js");
+const oauth_js_1 = require("./oauth.js");
+const device_login_js_1 = require("./device-login.js");
 const client_tools_js_1 = require("./client-tools.js");
 /** samplingToWire maps the camelCase SamplingOptions to the snake_case wire
  *  object, omitting unset fields so they inherit the agent's value. */
@@ -220,13 +222,30 @@ function applyOverridesToWire(body, opts) {
 }
 class LoomcycleClient {
     ctx;
+    tokenProvider;
+    oauthHelper;
+    rawFetch;
     constructor(opts = {}) {
+        if (opts.authToken && opts.tokenProvider) {
+            throw new TypeError("LoomcycleClient: pass authToken or tokenProvider, not both");
+        }
+        const fetchImpl = opts.fetch ?? fetch;
+        this.rawFetch = opts.fetch;
+        this.tokenProvider = opts.tokenProvider;
         this.ctx = {
             baseUrl: (opts.baseUrl ?? "http://127.0.0.1:8787").replace(/\/$/, ""),
             authToken: opts.authToken,
-            fetchImpl: opts.fetch ?? fetch,
+            // With a provider, ctx.authToken stays unset and the wrapper sets the
+            // header on every request, so no method needs to know.
+            fetchImpl: opts.tokenProvider ? (0, fetch_helpers_js_1.authorizedFetch)(fetchImpl, opts.tokenProvider) : fetchImpl,
         };
     }
+    /** The app sign-in helper (RFC FL) for this server: same base URL and
+     *  fetch, never this client's bearer. See {@link LoomcycleOAuth}. */
+    get oauth() {
+        this.oauthHelper ??= new oauth_js_1.LoomcycleOAuth({ baseUrl: this.ctx.baseUrl, fetch: this.rawFetch });
+        return this.oauthHelper;
+    }
     // ---- Run lifecycle ----
     /**
      * Run an agent and stream events. Returns AsyncIterable<AgentEvent>;
@@ -844,7 +863,8 @@ class LoomcycleClient {
         return { agents: resp.agents ?? [], next_cursor: resp.next_cursor ?? "" };
     }
     /** Aggregated token-usage + cost report (RFC AV). Group by any of
-     *  tenant/user/provider/model/source/purpose over an optional time window;
+     *  tenant/user/provider/model/source/purpose/tier/user_tier/agent/class over
+     *  an optional time window, split into periods with `bucket`;
      *  group by `source` for the operator-vs-tenant split, by `purpose` to see
      *  what OCR and speech-to-text cost (a row's `audio_seconds` is the audio its
      *  speech-to-text calls transcribed). Tenant-scoped server-side: a
@@ -860,6 +880,16 @@ class LoomcycleClient {
             params.set("to", opts.to);
         if (opts?.tenant)
             params.set("tenant", opts.tenant);
+        if (opts?.bucket)
+            params.set("bucket", opts.bucket);
+        if (opts?.top)
+            params.set("top", String(opts.top));
+        if (opts?.topBy)
+            params.set("top_by", opts.topBy);
+        for (const [dim, values] of Object.entries(opts?.filters ?? {})) {
+            if (values && values.length > 0)
+                params.set(dim, values.join(","));
+        }
         const q = params.toString() ? `?${params.toString()}` : "";
         return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/_usage${q}`, opts);
     }
@@ -984,28 +1014,151 @@ class LoomcycleClient {
     //
     // A tenant operator (substrate:tenant) manages the first-class users in its
     // OWN tenant and mints/lists/revokes bearer tokens for them. The tenant is
-    // always server-derived from the authenticated principal — never sent — so
-    // there is no tenant field on any of these calls. Requires a persistent store
+    // server-derived from the authenticated principal. `opts.tenant` (sent as
+    // ?tenant=) names another only for an admin token, and for an `auth:manage`
+    // credential, which must name one (400 `tenant_required` otherwise); a
+    // tenant operator always acts in its own tenant. Requires a persistent store
     // (503 otherwise).
     /** Register a first-class user in the caller's own tenant. `access_mode`
      *  defaults to "tenant" (collaborates on tenant-shared primitives);
      *  "isolated" confines the member to its own user scope. 409 on a duplicate
      *  (tenant, subject). */
     async createUser(body, opts) {
-        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_users", body, opts);
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, this.aclPath("/v1/_users", opts?.tenant), body, {
+            signal: opts?.signal,
+        });
     }
     /** Patch mutable fields on a user in the caller's own tenant. An omitted key
      *  leaves the column unchanged. Disabling a user (status:"disabled") also
-     *  revokes its delegated tokens server-side. Cross-tenant target → 404. */
+     *  revokes its delegated tokens server-side. A pending user is activated by
+     *  {@link approveUser}, not here (409 `use_approve`). Cross-tenant target →
+     *  404. */
     async updateUser(subject, body, opts) {
-        return (0, fetch_helpers_js_1.patchJSON)(this.ctx, `/v1/_users/${encodeURIComponent(subject)}`, body, opts);
+        return (0, fetch_helpers_js_1.patchJSON)(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}`, opts?.tenant), body, { signal: opts?.signal });
     }
     /** Delete the user identity row in the caller's own tenant (204). Its
      *  delegated tokens are retired first so the bearer cannot outlive the row.
      *  Owned data (runs / sessions / memory) is left intact — this is not
      *  erasure ({@link erasureExecute}). Cross-tenant target → 404. */
     async deleteUser(subject, opts) {
-        return (0, fetch_helpers_js_1.deleteRequest)(this.ctx, `/v1/_users/${encodeURIComponent(subject)}`, opts);
+        return (0, fetch_helpers_js_1.deleteRequest)(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}`, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Approve a user awaiting approval: `pending` → `active`
+     *  (`POST /v1/_users/{subject}/approve`). A sign-in gate configured with
+     *  `new_user.status: pending` provisions people who can sign in but are
+     *  refused everything until this call. Returns the updated record. 409
+     *  `not_pending` for a user that is not pending; 404 for an unknown or
+     *  cross-tenant subject. An `auth:manage` credential may approve only a user
+     *  at its floor (403 `target_beyond_floor`). */
+    async approveUser(subject, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}/approve`, opts?.tenant), undefined, { signal: opts?.signal });
+    }
+    /** The identity-provider accounts a user signs in with
+     *  (`GET /v1/_users/{subject}/identities`): one row per linked gate, never a
+     *  secret. A user reads its own; a tenant operator or an admin reads any in
+     *  the tenant. Password-gate logins, with whether a password and an
+     *  authenticator are set, are {@link listGateIdentities}. */
+    async listUserIdentities(subject, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}/identities`, opts?.tenant), opts);
+    }
+    /** Unlink one identity-provider account from a user
+     *  (`DELETE /v1/_users/{subject}/identities/{gate}`, 204). Sessions made
+     *  through it end on their next request. For a tenant operator or an admin;
+     *  a user unlinking its own account must do it from a recently
+     *  signed-in Web UI session, so a bearer is refused (403
+     *  `link_needs_own_session`). A password gate's login is removed with
+     *  {@link removeGateCredentials} instead (409 `password_gate`). 404
+     *  `identity_not_found` when no account of that gate is linked. */
+    async unlinkUserIdentity(subject, gate, opts) {
+        return (0, fetch_helpers_js_1.deleteRequest)(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}/identities/${encodeURIComponent(gate)}`, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Sign in through the server's device gate (RFC 8628): shows the person a
+     *  code through `onPrompt`, polls until they approve it in a signed-in Web
+     *  UI session (`/ui/device`), and returns the token issued to them. The
+     *  token is the approver's own member token, at most the device gate's
+     *  `token_ttl` and never past the approving session or the credential it
+     *  was made from. Sends no bearer: a client constructed without one can
+     *  call it. Throws {@link DeviceLoginError} when the login is denied,
+     *  expires, or the server refuses it; 404 `device_login_disabled` when no
+     *  device gate is configured. */
+    async deviceLogin(opts) {
+        return (0, device_login_js_1.deviceLogin)(this.ctx, opts);
+    }
+    // ---- RFC FA: sign-in gates + the password gate's management API ----
+    //
+    // Invitations, reset links, credential removal, login renames and a user's
+    // logins at a password gate, addressed by the gate's configured name. None
+    // takes a password: the person sets their own through the link. A tenant
+    // operator manages its own tenant, an admin any (`opts.tenant`, defaulting
+    // to its own), and an `auth:manage` credential any tenant it names — it
+    // must name one (400 `tenant_required`) and is held to the gate's new-user
+    // floor. A gate that is not a password gate is a 404 `gate_not_found`.
+    // Requires a persistent store (503 otherwise).
+    /** Every configured sign-in gate (`GET /v1/_authgate`): kind, label,
+     *  whether a browser can sign in through it, its identity map and an
+     *  external gate's key fingerprint and removal timing — never key
+     *  material. **Admin token only.** `probe: true` also fetches each
+     *  external gate's discovery document (bounded) and compares it with the
+     *  registration. */
+    async listAuthGates(opts) {
+        const q = opts?.probe ? "?probe=1" : "";
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/_authgate${q}`, opts);
+    }
+    /** Invite a person to sign in through a password gate
+     *  (`POST /v1/_authgate/{gate}/invites`). Without `subject` the invite
+     *  makes a new user, at the gate's new-user floor unless the gate is
+     *  trusted; with one it gives that existing user a login (409
+     *  `credential_exists` if it has one — issue a reset instead). Returns the
+     *  one-time link, shown once. */
+    async createInvite(gate, body, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, `/v1/_authgate/${encodeURIComponent(gate)}/invites`, withTenant(body, opts?.tenant), { signal: opts?.signal });
+    }
+    /** A password gate's invites in the tenant, live and past
+     *  (`GET /v1/_authgate/{gate}/invites`), never their codes. An admin naming
+     *  no tenant lists every tenant's. */
+    async listInvites(gate, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/invites`, opts?.tenant), opts);
+    }
+    /** Revoke a live invite (`DELETE /v1/_authgate/{gate}/invites/{id}`, 204).
+     *  409 `invite_not_live` when it was already redeemed, revoked or expired;
+     *  another tenant's invite is a 404. */
+    async revokeInvite(gate, inviteId, opts) {
+        return (0, fetch_helpers_js_1.deleteRequest)(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/invites/${encodeURIComponent(inviteId)}`, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Issue a one-time link that sets a new password for a user with a login
+     *  at the gate (`POST /v1/_authgate/{gate}/resets`). A user with an
+     *  authenticator still needs a code from it. Completing the reset ends the
+     *  user's sessions from the old password and retires its delegated tokens.
+     *  404 `login_not_found` when the user has no login at the gate. */
+    async createPasswordReset(gate, subject, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, `/v1/_authgate/${encodeURIComponent(gate)}/resets`, withTenant({ subject }, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Remove a user's password, authenticator and recovery codes at a gate
+     *  (`DELETE /v1/_authgate/{gate}/credentials/{subject}`, 204). The login
+     *  stays reserved, so a later {@link createPasswordReset} restores access. */
+    async removeGateCredentials(gate, subject, opts) {
+        return (0, fetch_helpers_js_1.deleteRequest)(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/credentials/${encodeURIComponent(subject)}`, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Change the login a user signs in with at a gate
+     *  (`PATCH /v1/_authgate/{gate}/logins/{subject}`). The subject does not
+     *  change, so nothing the user owns moves. Returns the normalised login;
+     *  409 `login_taken` when another user has it. */
+    async renameGateLogin(gate, subject, login, opts) {
+        return (0, fetch_helpers_js_1.patchJSON)(this.ctx, `/v1/_authgate/${encodeURIComponent(gate)}/logins/${encodeURIComponent(subject)}`, withTenant({ login }, opts?.tenant), { signal: opts?.signal });
+    }
+    /** A user's logins at every gate, and whether it has a password and a
+     *  confirmed authenticator (`GET /v1/_authgate/{gate}/identities`) — never
+     *  a secret. `gate` must name a password gate. */
+    async listGateIdentities(gate, subject, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/identities`, opts?.tenant, {
+            subject,
+        }), opts);
+    }
+    /** Whether the tenant has, or ever had, a user and whether an owner invite
+     *  is live (`GET /v1/_authgate/{gate}/tenant-status`) — what deciding on an
+     *  owner invite needs, and nothing about who the users are. */
+    async getGateTenantStatus(gate, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/tenant-status`, opts?.tenant), opts);
     }
     /** Mint a bearer token for one of the caller's own ACTIVE users. The granted
      *  scopes are DERIVED server-side from the member's access_mode (never sent),
@@ -1199,7 +1352,11 @@ class LoomcycleClient {
      *  `.close()` to stop. Uses the global WebSocket (browsers, Node 22+); pass
      *  `WebSocketImpl` (e.g. the `ws` package) on older Node. */
     connectClientTools(opts) {
-        const host = new client_tools_js_1.ClientToolHost((0, client_tools_js_1.clientToolsURL)(this.ctx.baseUrl), this.ctx.authToken, opts);
+        // A provider is asked on every (re)connect, so a host outliving one
+        // access token reconnects with the next.
+        const provider = this.tokenProvider;
+        const auth = provider ? () => provider.getToken() : this.ctx.authToken;
+        const host = new client_tools_js_1.ClientToolHost((0, client_tools_js_1.clientToolsURL)(this.ctx.baseUrl), auth, opts);
         host.start();
         return host;
     }
@@ -1836,6 +1993,73 @@ class LoomcycleClient {
     async volumeDef(input, opts) {
         return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_volumedef", input, opts);
     }
+    // ---- App clients (RFC FL ClientDef) ----
+    //
+    // The apps that sign people in through this server's gates, registered at
+    // runtime beside the config's `auth.clients`. A tenant operator
+    // (substrate:tenant) registers its own tenant's; an admin any tenant's, or
+    // one for every tenant. Config clients are read only here, and another
+    // tenant's client answers as not found. A refusal raises
+    // SubstrateToolRefusedError. Each method posts to `POST /v1/_clientdef`.
+    /** The ClientDef op dispatch, as sent: `{op, name?, def_id?, client?,
+     *  description?, tenant?, content_sha256?}`. The typed methods below are
+     *  the usual way in. */
+    async clientDef(input, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_clientdef", input, opts);
+    }
+    /** Register an app (`op: "create"`). Its redirect URIs and origins are
+     *  checked as strictly as a config client's. `tenant` is for an admin: the
+     *  tenant whose people it signs in, "" (the default) for every tenant. */
+    async createClientDef(name, client, opts) {
+        const input = { op: "create", name, client };
+        if (opts?.description !== undefined)
+            input.description = opts.description;
+        if (opts?.tenant !== undefined)
+            input.tenant = opts.tenant;
+        return (await this.clientDef(input, signalOpts(opts)));
+    }
+    /** Change an app (`op: "update"`): a new version, whole. Codes issued
+     *  under the old version that were not exchanged yet stop working. */
+    async updateClientDef(name, client, opts) {
+        const input = { op: "update", name, client };
+        if (opts?.description !== undefined)
+            input.description = opts.description;
+        return (await this.clientDef(input, signalOpts(opts)));
+    }
+    /** One app by name (a config client too) or one version by `def_id`
+     *  (`op: "get"`). */
+    async getClientDef(ref, opts) {
+        return (await this.clientDef({ op: "get", ...ref }, opts));
+    }
+    /** The apps the caller may see, config ones included (`op: "list"`). An
+     *  admin may focus one tenant with `tenant` ("" = the every-tenant ones). */
+    async listClientDefs(opts) {
+        const input = { op: "list" };
+        if (opts?.tenant !== undefined)
+            input.tenant = opts.tenant;
+        return (await this.clientDef(input, signalOpts(opts)));
+    }
+    /** Take an app out of service (`op: "retire"`): its unused codes are
+     *  voided, its sign-ins revoked and their access tokens retired. The name
+     *  is not reusable. */
+    async retireClientDef(name, opts) {
+        return (await this.clientDef({ op: "retire", name }, opts));
+    }
+    /** Whether an app is deployed and, with `contentSha256`, whether it matches
+     *  (`op: "verify"`). An absent app answers `deployed: false`. */
+    async verifyClientDef(name, opts) {
+        const input = { op: "verify", name };
+        if (opts?.contentSha256)
+            input.content_sha256 = opts.contentSha256;
+        return (await this.clientDef(input, signalOpts(opts)));
+    }
+    /** The apps the caller may see, by name (`GET /v1/_clientdef/names`). An
+     *  admin may focus one tenant with `tenant`; unlike the other families'
+     *  name lists, `""` is a focus too (the every-tenant apps). */
+    async listClientDefNames(opts) {
+        const q = opts?.tenant !== undefined ? `?tenant=${encodeURIComponent(opts.tenant)}` : "";
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/_clientdef/names${q}`, opts);
+    }
     // ---- Def name enumeration (GET /v1/_<family>def/names) ----
     //
     // Every name declared in one substrate family, each with its version
@@ -3351,6 +3575,12 @@ function defWriteInput(op, name, overlay, opts) {
         input.promote = opts.promote;
     return input;
 }
+/** A password-gate management body with the tenant the caller named. The
+ *  POST/PATCH routes read the tenant from the body where the others read
+ *  ?tenant=; like aclPath, an empty tenant is left out. */
+function withTenant(body, tenant) {
+    return tenant ? { ...body, tenant } : body;
+}
 function signalOpts(opts) {
     return opts?.signal ? { signal: opts.signal } : undefined;
 }