@loomcycle/client 1.124.0 → 1.126.0

package/dist/client.js

@@ -23,9 +23,11 @@
  * via fetch-helpers.ts:raiseFromResponse — see README.md for the
  * full mapping table.
  */
-import { authHeaders, deleteRequest, deleteJSON, jsonFetch, patchJSON, postJSON, putJSON, raiseFromResponse, } from "./fetch-helpers.js";
+import { authHeaders, authorizedFetch, deleteRequest, deleteJSON, jsonFetch, patchJSON, postJSON, putJSON, raiseFromResponse, } from "./fetch-helpers.js";
 import { parseSSE } from "./stream.js";
 import { InteractiveSession } from "./interactive.js";
+import { LoomcycleOAuth } from "./oauth.js";
+import { deviceLogin } from "./device-login.js";
 import { ClientToolHost, clientToolsURL, } from "./client-tools.js";
 /** samplingToWire maps the camelCase SamplingOptions to the snake_case wire
  *  object, omitting unset fields so they inherit the agent's value. */
@@ -217,13 +219,30 @@ function applyOverridesToWire(body, opts) {
 }
 export 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 ? 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 LoomcycleOAuth({ baseUrl: this.ctx.baseUrl, fetch: this.rawFetch });
+        return this.oauthHelper;
+    }
     // ---- Run lifecycle ----
     /**
      * Run an agent and stream events. Returns AsyncIterable<AgentEvent>;
@@ -443,6 +462,51 @@ export class LoomcycleClient {
     async getEffectiveConfig(runId, opts) {
         return jsonFetch(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/effective-config`, opts);
     }
+    /** Run one File-tool op on a run's inbox from outside the run — the files the
+     *  run's tools returned. Mirrors `POST /v1/runs/{run_id}/file`, the HTTP twin
+     *  of the MCP `file` tool. Ops: stat, ls, extract, import, keep, rm, clear.
+     *  The response is the op's own JSON (narrow as needed).
+     *
+     *  Needs `runs:read`, and works on any run you can read; another tenant's run
+     *  is an opaque {@link NotFoundError}. extract, keep, rm and clear write, so
+     *  they need the run's owner or an admin — a tenant operator counts as one
+     *  for its own tenant's runs; anyone else gets a
+     *  {@link SubstrateToolRefusedError}, as does a refused op. */
+    async runFile(runId, input, opts) {
+        return postJSON(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/file`, input, opts);
+    }
+    /** Download one file of a run's inbox. Mirrors
+     *  `GET /v1/runs/{run_id}/inbox/{path}` (HEAD with `head: true`). `path` is
+     *  relative to the inbox root (`documents/a.pdf`) or a reference
+     *  (`volume:inbox:documents/a.pdf`).
+     *
+     *  Any reader of the run may download (`runs:read`). `range` is sent as the
+     *  Range header (`bytes=0-1023`). The inbox is deleted when its run ends, so
+     *  a finished run's file — like a missing file, run, or another tenant's run —
+     *  is a {@link NotFoundError}. */
+    async downloadRunInboxFile(runId, path, opts) {
+        const rel = path.replace(/^volume:inbox:/, "");
+        const encoded = rel.split("/").map(encodeURIComponent).join("/");
+        const headers = {};
+        if (this.ctx.authToken)
+            headers.Authorization = `Bearer ${this.ctx.authToken}`;
+        if (opts?.range)
+            headers.Range = opts.range;
+        const resp = await this.ctx.fetchImpl(`${this.ctx.baseUrl}/v1/runs/${encodeURIComponent(runId)}/inbox/${encoded}`, { method: opts?.head ? "HEAD" : "GET", headers, signal: opts?.signal });
+        if (!resp.ok) {
+            await raiseFromResponse(resp);
+        }
+        const bytes = opts?.head ? new Uint8Array() : new Uint8Array(await resp.arrayBuffer());
+        return {
+            bytes,
+            status: resp.status,
+            contentType: resp.headers.get("Content-Type") ?? "",
+            filename: dispositionFilename(resp.headers.get("Content-Disposition")) ?? rel.split("/").pop() ?? "",
+            sha256: resp.headers.get("X-Loomcycle-SHA256") ?? "",
+            origin: resp.headers.get("X-Loomcycle-Origin") ?? "",
+            headers: resp.headers,
+        };
+    }
     /** Which per-run overrides a run of `name` may set, for this caller — what a
      *  run form needs before it sends anything. Mirrors
      *  `GET /v1/_agentdef/{name}/overridable`.
@@ -796,8 +860,11 @@ export 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 over an optional time window; group by
-     *  `source` for the operator-vs-tenant split. Tenant-scoped server-side: a
+     *  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
      *  tenant principal sees only its own tenant (the `tenant` focus is
      *  admin-only). Mirrors `GET /v1/_usage`. */
     async usageReport(opts) {
@@ -810,6 +877,16 @@ export 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 jsonFetch(this.ctx, `/v1/_usage${q}`, opts);
     }
@@ -934,28 +1011,151 @@ export 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 postJSON(this.ctx, "/v1/_users", body, opts);
+        return 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 patchJSON(this.ctx, `/v1/_users/${encodeURIComponent(subject)}`, body, opts);
+        return 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 deleteRequest(this.ctx, `/v1/_users/${encodeURIComponent(subject)}`, opts);
+        return 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 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 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 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 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 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 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 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 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 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 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 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 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 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),
@@ -1149,7 +1349,11 @@ export 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 ClientToolHost(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 ClientToolHost(clientToolsURL(this.ctx.baseUrl), auth, opts);
         host.start();
         return host;
     }
@@ -1272,6 +1476,12 @@ export class LoomcycleClient {
             body.document_ids = input.documentIds;
         if (input.excludeDocumentIds !== undefined)
             body.exclude_document_ids = input.excludeDocumentIds;
+        // The second scope's documents: sent only when set, so a one-scope search's
+        // response stays byte-identical (no per-entry `scope`).
+        if (input.documentsScope !== undefined)
+            body.documents_scope = input.documentsScope;
+        if (input.documentsScopeId !== undefined)
+            body.documents_scope_id = input.documentsScopeId;
         return postJSON(this.ctx, "/v1/_memory/search", body, {
             signal: opts?.signal,
         });
@@ -1780,6 +1990,73 @@ export class LoomcycleClient {
     async volumeDef(input, opts) {
         return 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 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 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
@@ -3215,6 +3492,23 @@ export class LoomcycleClient {
         return postJSON(this.ctx, "/v1/_crypto", input, opts);
     }
 }
+/** The file name of an RFC 8187 `filename*=UTF-8''…` Content-Disposition, or
+ *  a plain quoted `filename="…"`; undefined when there is neither. */
+function dispositionFilename(header) {
+    if (!header)
+        return undefined;
+    const star = /filename\*=UTF-8''([^;]+)/i.exec(header);
+    if (star) {
+        try {
+            return decodeURIComponent(star[1].trim());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const plain = /filename="([^"]*)"/i.exec(header);
+    return plain ? plain[1] : undefined;
+}
 /** Lightweight SSE parser tailored to the run-state stream. Each
  *  frame's event name distinguishes the two kinds; data is JSON.
  *  Comment lines (": keepalive") are ignored. */
@@ -3277,6 +3571,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;
 }

package/dist/device-login.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @internal — reached through LoomcycleClient.deviceLogin().
+ *
+ * The client side of loomcycle's device login (RFC 8628, a `kind: device`
+ * sign-in gate): ask the server for a code pair, show the person the short
+ * code, poll until they approve it in a signed-in Web UI session, and return
+ * the token issued to them. Both requests are unauthenticated — the device
+ * code is the credential — so no bearer the client holds is sent with them.
+ */
+import type { _FetchContext } from "./fetch-helpers.js";
+import type { DeviceLoginOptions, DeviceLoginResult } from "./types.js";
+export declare function deviceLogin(ctx: _FetchContext, opts: DeviceLoginOptions): Promise<DeviceLoginResult>;

package/dist/device-login.js

@@ -0,0 +1,143 @@
+/**
+ * @internal — reached through LoomcycleClient.deviceLogin().
+ *
+ * The client side of loomcycle's device login (RFC 8628, a `kind: device`
+ * sign-in gate): ask the server for a code pair, show the person the short
+ * code, poll until they approve it in a signed-in Web UI session, and return
+ * the token issued to them. Both requests are unauthenticated — the device
+ * code is the credential — so no bearer the client holds is sent with them.
+ */
+import { DeviceLoginError } from "./errors.js";
+const GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** RFC 8628 §3.5: a slow_down lengthens this and every later poll by 5 s. */
+const SLOW_DOWN_STEP_MS = 5_000;
+const DEFAULT_INTERVAL_S = 5;
+/** The server issues codes for ten minutes; a longer claim is not trusted. */
+const DEFAULT_EXPIRES_S = 600;
+const MAX_EXPIRES_S = 3_600;
+async function postForm(ctx, path, form, signal) {
+    const res = await ctx.fetchImpl(`${ctx.baseUrl}${path}`, {
+        method: "POST",
+        headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(form).toString(),
+        signal,
+    });
+    const text = await res.text();
+    let body = {};
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object")
+            body = parsed;
+    }
+    catch {
+        // A non-JSON answer is reported by status below.
+    }
+    return { status: res.status, body, text };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error("aborted"));
+            return;
+        }
+        const t = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(signal?.reason ?? new Error("aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** A string shown to a person must not carry control characters a hostile
+ *  server could use to rewrite what they see. */
+function printable(s, max) {
+    return typeof s === "string" && s.length > 0 && s.length <= max && /^[\x20-\x7e]+$/.test(s);
+}
+function httpURL(s) {
+    if (!printable(s, 2048))
+        return false;
+    try {
+        const u = new URL(s);
+        return u.protocol === "https:" || u.protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}
+function positiveInt(v) {
+    return typeof v === "number" && Number.isInteger(v) && v > 0 ? v : undefined;
+}
+export async function deviceLogin(ctx, opts) {
+    const clientId = opts.clientId ?? "loomcycle-ts";
+    const start = await postForm(ctx, "/v1/_auth/device", { client_id: clientId }, opts.signal);
+    if (start.status !== 200) {
+        const code = typeof start.body.code === "string" ? start.body.code : undefined;
+        throw new DeviceLoginError(`the server refused to start a device login (HTTP ${start.status})`, {
+            status: start.status,
+            bodyText: start.text.slice(0, 1024),
+            code,
+        });
+    }
+    const da = start.body;
+    if (typeof da.device_code !== "string" || da.device_code === "" ||
+        !printable(da.user_code, 32) || !httpURL(da.verification_uri)) {
+        throw new DeviceLoginError("the server's device-login answer is malformed", { status: start.status });
+    }
+    const deviceCode = da.device_code;
+    let expiresIn = positiveInt(da.expires_in) ?? DEFAULT_EXPIRES_S;
+    if (expiresIn > MAX_EXPIRES_S)
+        expiresIn = DEFAULT_EXPIRES_S;
+    await opts.onPrompt({
+        userCode: da.user_code,
+        verificationUri: da.verification_uri,
+        verificationUriComplete: httpURL(da.verification_uri_complete) ? da.verification_uri_complete : undefined,
+        expiresIn,
+    });
+    let intervalMs = (positiveInt(da.interval) ?? DEFAULT_INTERVAL_S) * 1000;
+    // A little past the code's own expiry, so the server's expired_token is
+    // what ends a login nobody approved.
+    const deadline = Date.now() + expiresIn * 1000 + 30_000;
+    for (;;) {
+        await sleep(intervalMs, opts.signal);
+        if (Date.now() > deadline) {
+            throw new DeviceLoginError("the code expired before it was approved", { code: "expired_token" });
+        }
+        const res = await postForm(ctx, "/v1/_auth/device/token", { grant_type: GRANT_TYPE, device_code: deviceCode, client_id: clientId }, opts.signal);
+        const tok = res.body;
+        if (res.status === 200 && typeof tok.access_token === "string" && tok.access_token !== "") {
+            return {
+                accessToken: tok.access_token,
+                tokenType: typeof tok.token_type === "string" ? tok.token_type : "Bearer",
+                expiresIn: positiveInt(tok.expires_in),
+                scope: typeof tok.scope === "string" && tok.scope !== "" ? tok.scope.split(" ") : undefined,
+            };
+        }
+        switch (tok.error) {
+            case "authorization_pending":
+                continue;
+            case "slow_down":
+                intervalMs += SLOW_DOWN_STEP_MS;
+                continue;
+        }
+        // RFC 8628 refusals carry the code in `error`; loomcycle's own refusals
+        // (device_login_disabled, …) carry it in `code` and a message in `error`.
+        const code = typeof res.body.code === "string" ? res.body.code : typeof tok.error === "string" ? tok.error : undefined;
+        const why = code === "access_denied"
+            ? "the login was denied, or its approval no longer holds"
+            : code === "expired_token"
+                ? "the code expired before it was approved"
+                : typeof tok.error_description === "string"
+                    ? tok.error_description
+                    : `the server refused the login (HTTP ${res.status})`;
+        // A refusal's body carries no token. A 200 without a usable one is
+        // malformed, and its body is not echoed, in case it holds one anyway.
+        throw new DeviceLoginError(why, {
+            status: res.status,
+            bodyText: res.status === 200 ? undefined : res.text.slice(0, 1024),
+            code,
+        });
+    }
+}

package/dist/errors.d.ts

@@ -423,3 +423,39 @@ export declare class SubstrateToolRefusedError extends LoomcycleError {
         tool?: string;
     });
 }
+/** An app sign-in (RFC FL) failed. `code` is the OAuth error code: one the
+ *  server sent (`invalid_grant`, `invalid_client`, `access_denied`,
+ *  `temporarily_unavailable`, …, RFC 6749 §4.1.2.1 / §5.2), or one the client
+ *  decided on before trusting a response:
+ *  - `state_mismatch`: the redirect's `state` is not the one this sign-in
+ *    sent — a forged or crossed response; nothing was exchanged.
+ *  - `issuer_mismatch`: the redirect's `iss` names another server (RFC 9207).
+ *  - `invalid_response`: the server's answer is not a token response.
+ *  - `signed_out`: the sign-in ended (its refresh token was refused); sign in
+ *    again.
+ *  `invalid_grant` on a refresh means the same: the sign-in is over. */
+export declare class OAuthError extends LoomcycleError {
+    /** The server's `error_description`, when it sent one. */
+    readonly errorDescription?: string;
+    constructor(code: string, opts?: {
+        status?: number;
+        bodyText?: string;
+        errorDescription?: string;
+    });
+    /** `temporarily_unavailable` (and a 429 throttle) clear on their own; every
+     *  other sign-in failure needs the person or the app to act. */
+    get retryable(): boolean;
+}
+/** A device login ({@link LoomcycleClient.deviceLogin}) that ended without a
+ *  token. `code` is the server's RFC 8628 error: `access_denied` (the person
+ *  denied it, or the approval no longer holds — the approving session ended
+ *  or its credential was retired), `expired_token` (nobody approved it in
+ *  time), or another refusal. Start a new login; the same one never
+ *  succeeds. */
+export declare class DeviceLoginError extends LoomcycleError {
+    constructor(message: string, opts?: {
+        status?: number;
+        bodyText?: string;
+        code?: string;
+    });
+}

package/dist/errors.js

@@ -427,3 +427,40 @@ export class SubstrateToolRefusedError extends LoomcycleError {
         this.tool = opts?.tool ?? "";
     }
 }
+/** An app sign-in (RFC FL) failed. `code` is the OAuth error code: one the
+ *  server sent (`invalid_grant`, `invalid_client`, `access_denied`,
+ *  `temporarily_unavailable`, …, RFC 6749 §4.1.2.1 / §5.2), or one the client
+ *  decided on before trusting a response:
+ *  - `state_mismatch`: the redirect's `state` is not the one this sign-in
+ *    sent — a forged or crossed response; nothing was exchanged.
+ *  - `issuer_mismatch`: the redirect's `iss` names another server (RFC 9207).
+ *  - `invalid_response`: the server's answer is not a token response.
+ *  - `signed_out`: the sign-in ended (its refresh token was refused); sign in
+ *    again.
+ *  `invalid_grant` on a refresh means the same: the sign-in is over. */
+export class OAuthError extends LoomcycleError {
+    /** The server's `error_description`, when it sent one. */
+    errorDescription;
+    constructor(code, opts) {
+        super(opts?.errorDescription ? `loomcycle sign-in: ${code}: ${opts.errorDescription}` : `loomcycle sign-in: ${code}`, { status: opts?.status, bodyText: opts?.bodyText, code });
+        this.name = "OAuthError";
+        this.errorDescription = opts?.errorDescription;
+    }
+    /** `temporarily_unavailable` (and a 429 throttle) clear on their own; every
+     *  other sign-in failure needs the person or the app to act. */
+    get retryable() {
+        return this.code === "temporarily_unavailable";
+    }
+}
+/** A device login ({@link LoomcycleClient.deviceLogin}) that ended without a
+ *  token. `code` is the server's RFC 8628 error: `access_denied` (the person
+ *  denied it, or the approval no longer holds — the approving session ended
+ *  or its credential was retired), `expired_token` (nobody approved it in
+ *  time), or another refusal. Start a new login; the same one never
+ *  succeeds. */
+export class DeviceLoginError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "DeviceLoginError";
+    }
+}