@loomcycle/client 1.125.0 → 1.127.0

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";
+    }
+}

package/dist/fetch-helpers.d.ts

@@ -9,6 +9,7 @@
  * Method-level code in client.ts stays focused on URL + body shape;
  * the boring fetch + error-translation machinery lives here.
  */
+import type { TokenProvider } from "./types.js";
 /**
  * @internal — not part of @loomcycle/client's public API surface.
  *
@@ -28,6 +29,13 @@ export interface _FetchContext {
     authToken: string | undefined;
     fetchImpl: typeof fetch;
 }
+/** 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. */
+export declare function authorizedFetch(inner: typeof fetch, provider: TokenProvider): typeof fetch;
 /** 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/fetch-helpers.js

@@ -10,6 +10,36 @@
  * the boring fetch + error-translation machinery lives here.
  */
 import { AclDeniedError, AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, ChannelCursorRegressionError, InsufficientScopeError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./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. */
+export 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/index.d.ts

@@ -27,6 +27,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)
  *
@@ -115,6 +129,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>
@@ -187,5 +214,7 @@ export { verifyLoomcycleSignature, verifyLoomcycleDelivery } from "./signature.j
 export type { VerifySignatureOptions, VerifiedDelivery } from "./signature.js";
 export { ClientToolHost, clientToolsURL, CLIENT_TOOL_SUBPROTOCOL } from "./client-tools.js";
 export type { ClientToolSchema, ClientToolInvocation, ConnectClientToolsOptions, WebSocketLike, WebSocketCtor, } from "./client-tools.js";
-export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ImageMediaType, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, RunOverrideOptions, SamplingOptions, CompactionOptions, ContextOptions, ToolUse, Usage, CallTiming, Agent, AgentStatus, AwaitedState, AgentUsage, RunResult, RunSpec, RunSpecTeam, ConfiguredRun, ConfiguredRunPatch, ToolChoiceOptions, OutputFormatOptions, CancelAgentResult, ListAgentsResponse, ListUserAgentsOptions, AgentList, WalkRunsPage, RunBatchOptions, RunBatchResult, SpawnRunResult, CompactRunResult, RunTreeDeletion, RunTreeNotReached, DirectoryBudget, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureAccess, ErasureReport, ErasureResidue, ErasureResult, ErasureTier, ErasureTokenRef, CancelTurnResult, ReviewRunResult, ReplaySessionResult, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, TokenRestrictions, UserTokenMeta, ListUserTokensResponse, RunnableAgent, RunnableAgentsResponse, WhoamiResponse, WhoamiEffective, WhoamiAuth, PauseResult, RetentionOverride, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, ResolverMatrix, ResolverModelStatus, ResolverProviderAvailability, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, MemorySearchDocumentFilter, MemorySearchInput, MemorySource, MemoryWhen, MemoryTimeFilter, MemorySearchEntry, MemorySearchResponse, MemoryEmbedModelStats, MemoryEmbedStatsResponse, MemoryReembedConfigured, MemoryReembedResponse, MemoryBackfillResponse, MemoryPurgeResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, ChannelHookCall, ChannelHookResult, HookFailMode, HookPhase, HookToolCall, HookToolResult, PostHookCall, PostHookResult, PreHookCall, PreHookResult, SubstrateToolInput, SubstrateToolResponse, TeamNameSummary, ListTeamsResponse, TeamDiagram, CreatedTeam, PromotedTeam, RetiredTeam, TeamDefDetail, TeamVerification, TeamDraft, TeamDraftVerification, TeamIssue, TeamIssueKind, TeamVersion, TeamVersionList, TeamBreakpoints, TeamRunDetached, TeamRunResult, TeamRunTarget, CreateTeamOptions, ForkTeamOptions, DefNameSummary, DefNamesResponse, OperatorTokenDefNameSummary, OperatorTokenDefNamesResponse, ScheduleListEntry, ScheduleListResponse, ScheduleActiveRun, ScheduleStateView, ScheduleRunNowResult, SchedulePauseResult, ModelAlias, ModelAliasesResponse, RoutingResponse, RoutingUserTier, RoutingTier, RoutingCandidate, RoutingThroughput, RoutingProvider, SearchRoutingProvider, RoutingEmbedder, RoutingDecision, RoutingDecisionModel, ProviderModelsResponse, TeamRunStep, TeamDecisionHandler, TeamDecisionQuestion, TeamDecisionAnswer, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, DocumentSearchFilter, DocumentSearchHit, DocumentSearchResult, DocumentRelatedResult, HistoryToolInput, HistoryToolResponse, EvaluationEmitterRole, EvaluationSubmitInput, EvaluationGetInput, EvaluationListForRunInput, EvaluationListForDefInput, EvaluationAggregateInput, EvaluationInput, EvaluationSubmitResult, EvaluationRecord, EvaluationListForRunResult, EvaluationListForDefResult, EvaluationScoreStats, EvaluationAggregate, VolumeMode, PersistentVolumeEntry, PersistentVolumesResponse, EphemeralVolumeEntry, EphemeralVolumesResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, ChangeFeedError, ChangeFeedFrame, ChangeFeedStatus, EmbedderHealth, MemoryChange, MemoryChangeScope, MemoryChangeType, StreamChangesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ListTeamChannelsOptions, PeekTeamChannelOptions, ReleaseTeamChannelOptions, TeamChannelReleaseResult, TeamChannelDeclaredIn, TeamChannelDescriptor, TeamChannelPeekResult, TeamChannelsResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAwaitEntry, ChannelAwaitMode, ChannelAwaitResult, ChannelBroadcastEntry, ChannelBroadcastResult, CreateChannelOptions, ReleaseChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, EnsureMcpServerOptions, EnsureMcpServerResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, AgentDefOverlay, AgentRouting, AgentChannelACL, AgentInterruptionACL, AgentDecision, MemoryRerank, AgentSampling, AgentCompaction, AgentTranscription, AgentContext, TierCandidate, CoreBlock, HookEvent, InlineWebhook, HookEntry, EventHooks, ToolEntry, ToolHooksByTool, EnsureCodeAgentOptions, EnsureCodeAgentResult, CreateDefOptions, ForkDefOptions, EnsureHookDefOptions, EnsureHookDefResult, HookDefBody, HookDefForkOverlay, HookDefInput, HookDefMatch, HookDefOverlay, HookDefRowResponse, HookDefVerifyResult, ScheduleDefInput, ScheduleDefOverlay, ScheduleDefRowResponse, ScheduledRunHook, ScheduledRunPromptContent, ScheduledRunPromptSegment, WebhookDefAuth, WebhookDefFilter, WebhookDefInput, WebhookDefOverlay, WebhookDefRateLimit, WebhookDefRowResponse, WebhookDefDeliveries, WebhookDefSyncResponse, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, UsageDimension, UsageAggregate, UsageReportResponse, CapabilityInertInfo, LimitInfo, FileCapturedInfo, TranscriptionInfo, AdmissionInfo, ErrorInfo, CallFormat, CallRef, HookDecisionInfo, TeamDecisionInfo, OverrideInfo, FallbackInfo, InterruptionEventInfo, SpawnChildInfo, TurnCancelledInfo, ChannelEventInfo, ContextCompactionInfo, ContextRecapInfo, ContextStateInfo, ContextExhaustedInfo, ContextTierVerdict, ContextDistillDeclinedInfo, EffectiveConfigResponse, RunFileInput, RunInboxDownload, EffectiveConfigSource, EffectiveValue, InertContextSetting, AgentOverridableResponse, OverridableField, OverrideLockReason, RetuneRunResponse, RunConfigRecord, SubagentHoldInfo, RunConfigResponse, RunPromptResponse, RunPromptSnapshot, PromptBlock, TokenLimit, TokenLimitsResponse, ConfigResponse, ConfigProvider, ConfigModel, ConfigSearch, ConfigInstance, SetTokenLimitRequest, CredentialScope, CredentialMeta, CredentialListResponse, CryptoKeyVersion, CryptoKeyExport, CryptoKeyType, CryptoKeyEncoding, CryptoKeyBackend, CryptoKeyExternal, CryptoOp, CryptoRequestBase, CryptoKeyRef, CryptoEncryptRequest, CryptoDecryptRequest, CryptoRewrapRequest, CryptoMacRequest, CryptoVerifyMacRequest, CryptoSignRequest, CryptoVerifyRequest, CryptoPublicKeyRequest, CryptoTotpRequest, CryptoHashRequest, CryptoRandomRequest, CryptoHashPasswordRequest, CryptoVerifyPasswordRequest, CryptoRequest, CryptoEncryptResult, CryptoDecryptResult, CryptoRewrapResult, CryptoMacResult, CryptoVerifyResult, CryptoSignResult, CryptoPublicJWK, CryptoPublicKeyResult, CryptoTotpResult, CryptoHashResult, CryptoRandomResult, CryptoHashPasswordResult, CryptoVerifyPasswordResult, CryptoResultByOp, CryptoResult, DecideRequest, DecideResponse, DecisionQuestion, DecisionChoiceQuestion, DecisionNoulQuestion, DecisionScoreQuestion, DecisionAnswer, DecisionChoiceAnswer, DecisionNoulAnswer, DecisionScoreAnswer, DecisionModel, DecisionModelsResponse, AclMode, AclSource, AclEffect, AclSubjectKind, AclCondition, AclRule, AclList, AclDefRow, AclDefListResponse, AclDefNamesResponse, AclValidateResult, AclCatalogType, AclCatalog, AclDefOp, AclDefInput, GroupRow, GroupMemberKind, GroupMember, GroupListResponse, GroupDetail, GroupEffective, CreateGroupBody, GroupMemberChange, AclBinding, AclBindingListResponse, CreateAclBindingBody, AuthzReason, AuthzDecision, AuthzRequestContext, AuthzEvaluationRequest, AuthzEvaluationsSemantic, AuthzEvaluationsRequest, AuthzEvaluationsResponse, AuthzTrace, AuthzAppliedBinding, AuthzExplainResponse, AuthzDraftBinding, AuthzSimulateRequest, AuthzSimulateResult, AuthzSimulateResponse, } from "./types.js";
-export { AclDeniedError, AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, NotFoundError, InsufficientScopeError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";
+export { LoomcycleOAuth, OAuthTokenProvider, parseAuthorizeResponse, pkceChallenge } from "./oauth.js";
+export type { LoomcycleOAuthOptions, OAuthTokenProviderOptions } from "./oauth.js";
+export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ImageMediaType, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, RunOverrideOptions, SamplingOptions, CompactionOptions, ContextOptions, ToolUse, Usage, CallTiming, Agent, AgentStatus, AwaitedState, AgentUsage, RunResult, RunSpec, RunSpecTeam, ConfiguredRun, ConfiguredRunPatch, ToolChoiceOptions, OutputFormatOptions, CancelAgentResult, ListAgentsResponse, ListUserAgentsOptions, AgentList, WalkRunsPage, RunBatchOptions, RunBatchResult, SpawnRunResult, CompactRunResult, RunTreeDeletion, RunTreeNotReached, DirectoryBudget, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureAccess, ErasureReport, ErasureResidue, ErasureResult, ErasureTier, ErasureTokenRef, CancelTurnResult, ReviewRunResult, ReplaySessionResult, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, UserStatus, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, TokenRestrictions, UserTokenMeta, ListUserTokensResponse, UserIdentity, UserIdentitiesResponse, AuthGateKind, AuthGate, AuthGateKey, AuthGateRemoval, AuthGateProbe, AuthGateListResponse, CreateInviteBody, CreatedInvite, AuthInviteState, AuthInvite, AuthInviteListResponse, CreatedPasswordReset, GateIdentity, GateIdentitiesResponse, GateTenantStatus, RunnableAgent, RunnableAgentsResponse, WhoamiResponse, WhoamiEffective, WhoamiAuth, PauseResult, RetentionOverride, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, ResolverMatrix, ResolverModelStatus, ResolverProviderAvailability, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, MemorySearchDocumentFilter, MemorySearchInput, MemorySource, MemoryWhen, MemoryTimeFilter, MemorySearchEntry, MemorySearchResponse, MemoryEmbedModelStats, MemoryEmbedStatsResponse, MemoryReembedConfigured, MemoryReembedResponse, MemoryBackfillResponse, MemoryPurgeResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, ChannelHookCall, ChannelHookResult, HookFailMode, HookPhase, HookToolCall, HookToolResult, PostHookCall, PostHookResult, PreHookCall, PreHookResult, SubstrateToolInput, SubstrateToolResponse, TeamNameSummary, ListTeamsResponse, TeamDiagram, CreatedTeam, PromotedTeam, RetiredTeam, TeamDefDetail, TeamVerification, TeamDraft, TeamDraftVerification, TeamIssue, TeamIssueKind, TeamVersion, TeamVersionList, TeamBreakpoints, TeamRunDetached, TeamRunResult, TeamRunTarget, CreateTeamOptions, ForkTeamOptions, DefNameSummary, DefNamesResponse, OperatorTokenDefNameSummary, OperatorTokenDefNamesResponse, ScheduleListEntry, ScheduleListResponse, ScheduleActiveRun, ScheduleStateView, ScheduleRunNowResult, SchedulePauseResult, ModelAlias, ModelAliasesResponse, RoutingResponse, RoutingUserTier, RoutingTier, RoutingCandidate, RoutingThroughput, RoutingProvider, SearchRoutingProvider, RoutingEmbedder, RoutingDecision, RoutingDecisionModel, ProviderModelsResponse, TeamRunStep, TeamDecisionHandler, TeamDecisionQuestion, TeamDecisionAnswer, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, DocumentSearchFilter, DocumentSearchHit, DocumentSearchResult, DocumentRelatedResult, HistoryToolInput, HistoryToolResponse, EvaluationEmitterRole, EvaluationSubmitInput, EvaluationGetInput, EvaluationListForRunInput, EvaluationListForDefInput, EvaluationAggregateInput, EvaluationInput, EvaluationSubmitResult, EvaluationRecord, EvaluationListForRunResult, EvaluationListForDefResult, EvaluationScoreStats, EvaluationAggregate, VolumeMode, PersistentVolumeEntry, PersistentVolumesResponse, EphemeralVolumeEntry, EphemeralVolumesResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, ChangeFeedError, ChangeFeedFrame, ChangeFeedStatus, EmbedderHealth, MemoryChange, MemoryChangeScope, MemoryChangeType, StreamChangesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ListTeamChannelsOptions, PeekTeamChannelOptions, ReleaseTeamChannelOptions, TeamChannelReleaseResult, TeamChannelDeclaredIn, TeamChannelDescriptor, TeamChannelPeekResult, TeamChannelsResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAwaitEntry, ChannelAwaitMode, ChannelAwaitResult, ChannelBroadcastEntry, ChannelBroadcastResult, CreateChannelOptions, ReleaseChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, EnsureMcpServerOptions, EnsureMcpServerResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, AgentDefOverlay, AgentRouting, AgentChannelACL, AgentInterruptionACL, AgentDecision, MemoryRerank, AgentSampling, AgentCompaction, AgentTranscription, AgentSpeech, AgentContext, TierCandidate, CoreBlock, HookEvent, InlineWebhook, HookEntry, EventHooks, ToolEntry, ToolHooksByTool, EnsureCodeAgentOptions, EnsureCodeAgentResult, CreateDefOptions, ForkDefOptions, EnsureHookDefOptions, EnsureHookDefResult, HookDefBody, HookDefForkOverlay, HookDefInput, HookDefMatch, HookDefOverlay, HookDefRowResponse, HookDefVerifyResult, ScheduleDefInput, ScheduleDefOverlay, ScheduleDefRowResponse, ScheduledRunHook, ScheduledRunPromptContent, ScheduledRunPromptSegment, WebhookDefAuth, WebhookDefFilter, WebhookDefInput, WebhookDefOverlay, WebhookDefRateLimit, WebhookDefRowResponse, WebhookDefDeliveries, WebhookDefSyncResponse, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, UsageDimension, UsageBucket, UsageAggregate, UsageReportResponse, CapabilityInertInfo, LimitInfo, FileCapturedInfo, TranscriptionInfo, AdmissionInfo, ErrorInfo, CallFormat, CallRef, HookDecisionInfo, TeamDecisionInfo, OverrideInfo, FallbackInfo, InterruptionEventInfo, SpawnChildInfo, TurnCancelledInfo, ChannelEventInfo, ContextCompactionInfo, ContextRecapInfo, ContextStateInfo, ContextExhaustedInfo, ContextTierVerdict, ContextDistillDeclinedInfo, EffectiveConfigResponse, RunFileInput, RunFileImportSource, RunFileImportHeading, RunInboxDownload, EffectiveConfigSource, EffectiveValue, InertContextSetting, AgentOverridableResponse, OverridableField, OverrideLockReason, RetuneRunResponse, RunConfigRecord, SubagentHoldInfo, RunConfigResponse, RunPromptResponse, RunPromptSnapshot, PromptBlock, TokenLimit, TokenLimitsResponse, ConfigResponse, ConfigProvider, ConfigModel, ConfigSearch, ConfigInstance, SetTokenLimitRequest, CredentialScope, CredentialMeta, CredentialListResponse, CryptoKeyVersion, CryptoKeyExport, CryptoKeyType, CryptoKeyEncoding, CryptoKeyBackend, CryptoKeyExternal, CryptoOp, CryptoRequestBase, CryptoKeyRef, CryptoEncryptRequest, CryptoDecryptRequest, CryptoRewrapRequest, CryptoMacRequest, CryptoVerifyMacRequest, CryptoSignRequest, CryptoVerifyRequest, CryptoPublicKeyRequest, CryptoTotpRequest, CryptoHashRequest, CryptoRandomRequest, CryptoHashPasswordRequest, CryptoVerifyPasswordRequest, CryptoRequest, CryptoEncryptResult, CryptoDecryptResult, CryptoRewrapResult, CryptoMacResult, CryptoVerifyResult, CryptoSignResult, CryptoPublicJWK, CryptoPublicKeyResult, CryptoTotpResult, CryptoHashResult, CryptoRandomResult, CryptoHashPasswordResult, CryptoVerifyPasswordResult, CryptoResultByOp, CryptoResult, DecideRequest, DecideResponse, DecisionQuestion, DecisionChoiceQuestion, DecisionNoulQuestion, DecisionScoreQuestion, DecisionAnswer, DecisionChoiceAnswer, DecisionNoulAnswer, DecisionScoreAnswer, DecisionModel, DecisionModelsResponse, AclMode, AclSource, AclEffect, AclSubjectKind, AclCondition, AclRule, AclList, AclDefRow, AclDefListResponse, AclDefNamesResponse, AclValidateResult, AclCatalogType, AclCatalog, AclDefOp, AclDefInput, GroupRow, GroupMemberKind, GroupMember, GroupListResponse, GroupDetail, GroupEffective, CreateGroupBody, GroupMemberChange, AclBinding, AclBindingListResponse, CreateAclBindingBody, AuthzReason, AuthzDecision, AuthzRequestContext, AuthzEvaluationRequest, AuthzEvaluationsSemantic, AuthzEvaluationsRequest, AuthzEvaluationsResponse, AuthzTrace, AuthzAppliedBinding, AuthzExplainResponse, AuthzDraftBinding, AuthzSimulateRequest, AuthzSimulateResult, AuthzSimulateResponse, OAuthServerMetadata, OAuthTokenResponse, OAuthTokenSet, BeginAuthorizeOptions, AuthorizeRequest, AuthorizeResponseParams, CompleteAuthorizeOptions, RefreshTokenOptions, RevokeTokenOptions, TokenProvider, AppClientRefresh, AppClientConfig, ClientDefInput, ClientDefRecord, ConfigAppClient, AppClientEntry, ClientDefListResponse, ClientDefVerifyResult, ClientDefRetireResult, ClientDefNameSummary, ClientDefNamesResponse, DeviceLoginPrompt, DeviceLoginOptions, DeviceLoginResult, } from "./types.js";
+export { AclDeniedError, AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, DeviceLoginError, NotFoundError, InsufficientScopeError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, OAuthError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";

package/dist/index.js

@@ -27,6 +27,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)
  *
@@ -115,6 +129,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>
@@ -184,4 +211,5 @@ export { LoomcycleClient } from "./client.js";
 export { InteractiveSession } from "./interactive.js";
 export { verifyLoomcycleSignature, verifyLoomcycleDelivery } from "./signature.js";
 export { ClientToolHost, clientToolsURL, CLIENT_TOOL_SUBPROTOCOL } from "./client-tools.js";
-export { AclDeniedError, AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, NotFoundError, InsufficientScopeError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";
+export { LoomcycleOAuth, OAuthTokenProvider, parseAuthorizeResponse, pkceChallenge } from "./oauth.js";
+export { AclDeniedError, AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, DeviceLoginError, NotFoundError, InsufficientScopeError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, OAuthError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";

package/dist/oauth.d.ts

@@ -0,0 +1,131 @@
+import { OAuthError } from "./errors.js";
+import type { AuthorizeRequest, AuthorizeResponseParams, BeginAuthorizeOptions, CompleteAuthorizeOptions, OAuthServerMetadata, OAuthTokenSet, RefreshTokenOptions, RevokeTokenOptions, TokenProvider } from "./types.js";
+/** Options for {@link LoomcycleOAuth}. */
+export interface LoomcycleOAuthOptions {
+    /** loomcycle's address as the person's browser reaches it, e.g.
+     *  `https://loom.example.com`. Defaults to http://127.0.0.1:8787. */
+    baseUrl?: string;
+    /** Custom fetch (tests, Tauri's HTTP plugin); defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Web Crypto; defaults to `globalThis.crypto` (browsers, Node 19+). On
+     *  Node 18 pass `require("node:crypto").webcrypto`. */
+    crypto?: Crypto;
+    /** The server's issuer identifier, when the app knows it. A redirect's
+     *  `iss` is compared with it; without it, the issuer is discovered from
+     *  the server's metadata the first time a redirect carries `iss`. */
+    issuer?: string;
+}
+/**
+ * The app sign-in helper. Construct one per loomcycle server.
+ *
+ * ```ts
+ * const oauth = new LoomcycleOAuth({ baseUrl: "https://loom.example.com" });
+ * // 1. Start: keep verifier + state in session storage, then navigate.
+ * const req = await oauth.beginAuthorize({ clientId: "loomboard", redirectUri });
+ * sessionStorage.setItem("lc_pkce", JSON.stringify({ verifier: req.verifier, state: req.state }));
+ * location.assign(req.url);
+ * // 2. Back on redirectUri:
+ * const saved = JSON.parse(sessionStorage.getItem("lc_pkce")!);
+ * const tokens = await oauth.completeAuthorize({
+ *   ...parseAuthorizeResponse(location.href),
+ *   expectedState: saved.state, verifier: saved.verifier, clientId: "loomboard", redirectUri,
+ * });
+ * ```
+ */
+export declare class LoomcycleOAuth {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly cryptoImpl?;
+    private readonly issuer?;
+    private metadata?;
+    constructor(opts?: LoomcycleOAuthOptions);
+    /** Start a sign-in: a fresh PKCE verifier, its S256 challenge, a state,
+     *  and the authorize URL to send the person to. Nothing is sent to the
+     *  server. */
+    beginAuthorize(opts: BeginAuthorizeOptions): Promise<AuthorizeRequest>;
+    /** Finish a sign-in from the redirect's parameters (see
+     *  {@link parseAuthorizeResponse}). In order: the `state` must be the one
+     *  this sign-in sent, an `iss` must name this server (RFC 9207), an
+     *  `error` is thrown as an {@link OAuthError}, and only then is the code
+     *  exchanged. */
+    completeAuthorize(opts: CompleteAuthorizeOptions): Promise<OAuthTokenSet>;
+    /** Trade a refresh token for a new token set. The refresh token is spent:
+     *  persist the returned one before anything else uses the old. A spent
+     *  token presented again ends the whole sign-in. */
+    refresh(opts: RefreshTokenOptions): Promise<OAuthTokenSet>;
+    /** Sign out (RFC 7009): a refresh token ends the whole sign-in, an access
+     *  token ends that token. The server answers the same for a token it does
+     *  not know, so this resolves unless the request itself failed. */
+    revoke(opts: RevokeTokenOptions): Promise<void>;
+    /** The server's authorization server metadata (RFC 8414). Cached after the
+     *  first success. Fails with a 404 when the server does not know its public
+     *  address (`LOOMCYCLE_PUBLIC_URL` unset). */
+    discover(opts?: {
+        signal?: AbortSignal;
+    }): Promise<OAuthServerMetadata>;
+    private fetchMetadata;
+    private tokenRequest;
+    /** POST a form: parameters in the body, never the URL; no bearer and no
+     *  cookie (the code or the refresh token is the credential); only
+     *  CORS-safelisted headers, so a browser sends it without a preflight. */
+    private postForm;
+    private webCrypto;
+}
+/** Read the authorization response parameters from the redirect URL (its
+ *  query). Pass the result to {@link LoomcycleOAuth.completeAuthorize}. */
+export declare function parseAuthorizeResponse(url: string | URL): AuthorizeResponseParams;
+/** The PKCE S256 code challenge of a verifier (RFC 7636 §4.2):
+ *  BASE64URL(SHA-256(ASCII(verifier))). */
+export declare function pkceChallenge(verifier: string, cryptoImpl?: Crypto): Promise<string>;
+/** Options for {@link OAuthTokenProvider}. */
+export interface OAuthTokenProviderOptions {
+    /** The helper for the server that issued the tokens. */
+    oauth: LoomcycleOAuth;
+    clientId: string;
+    /** The current token set (from completeAuthorize, or persisted). */
+    tokens: OAuthTokenSet;
+    /** Called with every new token set, before the token is used. Persist it:
+     *  the refresh token it replaced is spent. A throw fails the request that
+     *  caused the refresh; the new set is kept in memory regardless. */
+    onTokens?: (tokens: OAuthTokenSet) => void | Promise<void>;
+    /** Called once when the sign-in ends: the server refused the refresh token
+     *  (revoked, expired, reused) or {@link OAuthTokenProvider.signOut} ran.
+     *  Clear what you persisted and send the person to sign in again. */
+    onSignedOut?: (reason: OAuthError) => void;
+    /** Refresh this long before the access token expires (default 60 s). */
+    refreshSkewMs?: number;
+}
+/**
+ * A {@link TokenProvider} over an app sign-in: hands out the access token,
+ * refreshes it before it expires and once after a 401, and shares one
+ * refresh between concurrent requests (two refreshes of the same refresh
+ * token would end the sign-in, since the server takes the second as a
+ * replay).
+ *
+ * One provider per sign-in: two providers — or two browser tabs — refreshing
+ * the same refresh token end it the same way.
+ */
+export declare class OAuthTokenProvider implements TokenProvider {
+    private readonly opts;
+    private current?;
+    private inflight?;
+    private ended?;
+    private readonly skew;
+    constructor(opts: OAuthTokenProviderOptions);
+    /** The current token set; undefined once signed out. */
+    get tokens(): OAuthTokenSet | undefined;
+    getToken(): Promise<string | undefined>;
+    onUnauthorized(rejected: string | undefined): Promise<string | undefined>;
+    /** Refresh now, sharing a refresh already under way. */
+    refresh(): Promise<OAuthTokenSet>;
+    /** End the sign-in: revoke the refresh token on the server (which also
+     *  ends the access tokens it issued) and forget the tokens. Resolves even
+     *  if the server could not be reached; the tokens are forgotten either
+     *  way. */
+    signOut(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    private refreshOnce;
+    private doRefresh;
+    private end;
+}