@loomcycle/client 1.125.0 → 1.127.0

package/dist/cjs/device-login.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * @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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceLogin = deviceLogin;
+const errors_js_1 = require("./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;
+}
+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 errors_js_1.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 errors_js_1.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 errors_js_1.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 errors_js_1.DeviceLoginError(why, {
+            status: res.status,
+            bodyText: res.status === 200 ? undefined : res.text.slice(0, 1024),
+            code,
+        });
+    }
+}

package/dist/cjs/errors.js

@@ -19,7 +19,7 @@
  * to raise typed errors via `raiseFromResponse`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SubstrateToolRefusedError = exports.ChannelCursorRegressionError = exports.SnapshotVersionError = exports.PromptTooLargeError = exports.RequestTooLargeError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.NotPausedError = exports.AlreadyPausingError = exports.PauseNotConfiguredError = exports.InvalidArgumentError = exports.UnavailableError = exports.AclDeniedError = exports.InsufficientScopeError = exports.AuthError = exports.PerUserQuotaExhaustedError = exports.TokenLimitExceededError = exports.RateLimitedError = exports.BackpressureError = exports.AgentIDInUseError = exports.SessionBusyError = exports.SessionNotFoundError = exports.AgentNotFoundError = exports.NotFoundError = exports.LoomcycleError = void 0;
+exports.DeviceLoginError = exports.OAuthError = exports.SubstrateToolRefusedError = exports.ChannelCursorRegressionError = exports.SnapshotVersionError = exports.PromptTooLargeError = exports.RequestTooLargeError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.NotPausedError = exports.AlreadyPausingError = exports.PauseNotConfiguredError = exports.InvalidArgumentError = exports.UnavailableError = exports.AclDeniedError = exports.InsufficientScopeError = exports.AuthError = exports.PerUserQuotaExhaustedError = exports.TokenLimitExceededError = exports.RateLimitedError = exports.BackpressureError = exports.AgentIDInUseError = exports.SessionBusyError = exports.SessionNotFoundError = exports.AgentNotFoundError = exports.NotFoundError = exports.LoomcycleError = void 0;
 class LoomcycleError extends Error {
     status;
     bodyText;
@@ -455,3 +455,42 @@ class SubstrateToolRefusedError extends LoomcycleError {
     }
 }
 exports.SubstrateToolRefusedError = SubstrateToolRefusedError;
+/** 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. */
+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";
+    }
+}
+exports.OAuthError = OAuthError;
+/** 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. */
+class DeviceLoginError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "DeviceLoginError";
+    }
+}
+exports.DeviceLoginError = DeviceLoginError;

package/dist/cjs/fetch-helpers.js

@@ -11,6 +11,7 @@
  * the boring fetch + error-translation machinery lives here.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorizedFetch = authorizedFetch;
 exports.authHeaders = authHeaders;
 exports.jsonFetch = jsonFetch;
 exports.postJSON = postJSON;
@@ -20,6 +21,36 @@ exports.deleteRequest = deleteRequest;
 exports.deleteJSON = deleteJSON;
 exports.raiseFromResponse = raiseFromResponse;
 const errors_js_1 = require("./errors.js");
+/** authorizedFetch wraps a fetch so every request carries the provider's
+ *  current bearer (replacing whatever Authorization the caller set), and a
+ *  401 is retried once with the token `onUnauthorized` hands back — never
+ *  twice, so a token the server keeps refusing cannot loop. A request whose
+ *  body is a stream is not retried: the stream was consumed by the first
+ *  send. */
+function authorizedFetch(inner, provider) {
+    return async (input, init) => {
+        const token = await provider.getToken();
+        const first = await inner(input, withBearer(init, token));
+        if (first.status !== 401 || !provider.onUnauthorized || !replayableBody(init?.body))
+            return first;
+        const fresh = await provider.onUnauthorized(token);
+        if (!fresh || fresh === token)
+            return first;
+        await first.body?.cancel().catch(() => undefined);
+        return inner(input, withBearer(init, fresh));
+    };
+}
+function withBearer(init, token) {
+    const headers = new Headers(init?.headers);
+    if (token)
+        headers.set("Authorization", `Bearer ${token}`);
+    else
+        headers.delete("Authorization");
+    return { ...init, headers };
+}
+function replayableBody(body) {
+    return !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream);
+}
 /** authHeaders builds the standard request header set: JSON Accept
  *  + Bearer token when the client was constructed with one. The
  *  caller adds Content-Type when posting a body. */

package/dist/cjs/index.js

@@ -28,6 +28,20 @@
  *     mintUserToken(subject, opts?): Promise<MintedUserToken>   // delegated token
  *     listUserTokens(subject, opts?): Promise<ListUserTokensResponse>
  *     revokeUserToken(subject, defId, opts?): Promise<{def_id, retired_at}>
+ *     approveUser(subject, opts?): Promise<UserRecord>           // pending → active (RFC FA)
+ *     listUserIdentities(subject, opts?): Promise<UserIdentitiesResponse>
+ *     unlinkUserIdentity(subject, gate, opts?): Promise<void>
+ *
+ *     // Sign-in gates + the password gate's management API (RFC FA)
+ *     listAuthGates(opts?): Promise<AuthGateListResponse>        // admin token only
+ *     createInvite(gate, body, opts?): Promise<CreatedInvite>    // one-time link, shown once
+ *     listInvites(gate, opts?): Promise<AuthInviteListResponse>
+ *     revokeInvite(gate, inviteId, opts?): Promise<void>
+ *     createPasswordReset(gate, subject, opts?): Promise<CreatedPasswordReset>
+ *     removeGateCredentials(gate, subject, opts?): Promise<void>
+ *     renameGateLogin(gate, subject, login, opts?): Promise<{subject, login}>
+ *     listGateIdentities(gate, subject, opts?): Promise<GateIdentitiesResponse>
+ *     getGateTenantStatus(gate, opts?): Promise<GateTenantStatus>
  *     runnableAgents(opts?): Promise<RunnableAgentsResponse>    // RFC BY (v1.51.0) — agents I can run
  *     whoami(): Promise<WhoamiResponse>               // RFC L principal (v0.17.0)
  *
@@ -116,6 +130,19 @@
  *     listVolumes(): Promise<PersistentVolumesResponse>
  *     listEphemeralVolumes(): Promise<EphemeralVolumesResponse>
  *
+ *     // App clients (RFC FL ClientDef; tenant operator or admin)
+ *     clientDef(input): Promise<unknown>                          // POST /v1/_clientdef
+ *     createClientDef / updateClientDef(name, client, opts?): Promise<ClientDefRecord>
+ *     getClientDef({name | def_id}): Promise<AppClientEntry>
+ *     listClientDefs(opts?): Promise<ClientDefListResponse>
+ *     retireClientDef(name): Promise<ClientDefRetireResult>
+ *     verifyClientDef(name, {contentSha256}?): Promise<ClientDefVerifyResult>
+ *     listClientDefNames(opts?): Promise<ClientDefNamesResponse> // GET /v1/_clientdef/names
+ *
+ *     // App sign-in (RFC FL) — also standalone as `new LoomcycleOAuth(...)`
+ *     oauth: LoomcycleOAuth   // beginAuthorize / completeAuthorize / refresh / revoke / discover
+ *     new LoomcycleClient({ tokenProvider: new OAuthTokenProvider(...) })  // refreshes on its own
+ *
  *     // Agent Teams (RFC AP — TeamDef substrate; tenant-confined)
  *     listTeams(): Promise<ListTeamsResponse>
  *     renderTeamDiagram(name, opts?): Promise<TeamDiagram>
@@ -182,7 +209,7 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnavailableError = exports.TokenLimitExceededError = exports.SubstrateToolRefusedError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.SessionNotFoundError = exports.SessionBusyError = exports.RequestTooLargeError = exports.RateLimitedError = exports.PromptTooLargeError = exports.PerUserQuotaExhaustedError = exports.PauseNotConfiguredError = exports.NotPausedError = exports.LoomcycleError = exports.ChannelCursorRegressionError = exports.InvalidArgumentError = exports.InsufficientScopeError = exports.NotFoundError = exports.BackpressureError = exports.AuthError = exports.AlreadyPausingError = exports.AgentNotFoundError = exports.AgentIDInUseError = exports.AclDeniedError = exports.CLIENT_TOOL_SUBPROTOCOL = exports.clientToolsURL = exports.ClientToolHost = exports.verifyLoomcycleDelivery = exports.verifyLoomcycleSignature = exports.InteractiveSession = exports.LoomcycleClient = void 0;
+exports.UnavailableError = exports.TokenLimitExceededError = exports.SubstrateToolRefusedError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.SessionNotFoundError = exports.SessionBusyError = exports.RequestTooLargeError = exports.RateLimitedError = exports.PromptTooLargeError = exports.PerUserQuotaExhaustedError = exports.PauseNotConfiguredError = exports.OAuthError = exports.NotPausedError = exports.LoomcycleError = exports.ChannelCursorRegressionError = exports.InvalidArgumentError = exports.InsufficientScopeError = exports.NotFoundError = exports.DeviceLoginError = exports.BackpressureError = exports.AuthError = exports.AlreadyPausingError = exports.AgentNotFoundError = exports.AgentIDInUseError = exports.AclDeniedError = exports.pkceChallenge = exports.parseAuthorizeResponse = exports.OAuthTokenProvider = exports.LoomcycleOAuth = exports.CLIENT_TOOL_SUBPROTOCOL = exports.clientToolsURL = exports.ClientToolHost = exports.verifyLoomcycleDelivery = exports.verifyLoomcycleSignature = exports.InteractiveSession = exports.LoomcycleClient = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "LoomcycleClient", { enumerable: true, get: function () { return client_js_1.LoomcycleClient; } });
 var interactive_js_1 = require("./interactive.js");
@@ -194,6 +221,11 @@ var client_tools_js_1 = require("./client-tools.js");
 Object.defineProperty(exports, "ClientToolHost", { enumerable: true, get: function () { return client_tools_js_1.ClientToolHost; } });
 Object.defineProperty(exports, "clientToolsURL", { enumerable: true, get: function () { return client_tools_js_1.clientToolsURL; } });
 Object.defineProperty(exports, "CLIENT_TOOL_SUBPROTOCOL", { enumerable: true, get: function () { return client_tools_js_1.CLIENT_TOOL_SUBPROTOCOL; } });
+var oauth_js_1 = require("./oauth.js");
+Object.defineProperty(exports, "LoomcycleOAuth", { enumerable: true, get: function () { return oauth_js_1.LoomcycleOAuth; } });
+Object.defineProperty(exports, "OAuthTokenProvider", { enumerable: true, get: function () { return oauth_js_1.OAuthTokenProvider; } });
+Object.defineProperty(exports, "parseAuthorizeResponse", { enumerable: true, get: function () { return oauth_js_1.parseAuthorizeResponse; } });
+Object.defineProperty(exports, "pkceChallenge", { enumerable: true, get: function () { return oauth_js_1.pkceChallenge; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "AclDeniedError", { enumerable: true, get: function () { return errors_js_1.AclDeniedError; } });
 Object.defineProperty(exports, "AgentIDInUseError", { enumerable: true, get: function () { return errors_js_1.AgentIDInUseError; } });
@@ -201,12 +233,14 @@ Object.defineProperty(exports, "AgentNotFoundError", { enumerable: true, get: fu
 Object.defineProperty(exports, "AlreadyPausingError", { enumerable: true, get: function () { return errors_js_1.AlreadyPausingError; } });
 Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_js_1.AuthError; } });
 Object.defineProperty(exports, "BackpressureError", { enumerable: true, get: function () { return errors_js_1.BackpressureError; } });
+Object.defineProperty(exports, "DeviceLoginError", { enumerable: true, get: function () { return errors_js_1.DeviceLoginError; } });
 Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
 Object.defineProperty(exports, "InsufficientScopeError", { enumerable: true, get: function () { return errors_js_1.InsufficientScopeError; } });
 Object.defineProperty(exports, "InvalidArgumentError", { enumerable: true, get: function () { return errors_js_1.InvalidArgumentError; } });
 Object.defineProperty(exports, "ChannelCursorRegressionError", { enumerable: true, get: function () { return errors_js_1.ChannelCursorRegressionError; } });
 Object.defineProperty(exports, "LoomcycleError", { enumerable: true, get: function () { return errors_js_1.LoomcycleError; } });
 Object.defineProperty(exports, "NotPausedError", { enumerable: true, get: function () { return errors_js_1.NotPausedError; } });
+Object.defineProperty(exports, "OAuthError", { enumerable: true, get: function () { return errors_js_1.OAuthError; } });
 Object.defineProperty(exports, "PauseNotConfiguredError", { enumerable: true, get: function () { return errors_js_1.PauseNotConfiguredError; } });
 Object.defineProperty(exports, "PerUserQuotaExhaustedError", { enumerable: true, get: function () { return errors_js_1.PerUserQuotaExhaustedError; } });
 Object.defineProperty(exports, "PromptTooLargeError", { enumerable: true, get: function () { return errors_js_1.PromptTooLargeError; } });