@relayfile/sdk 0.10.60 → 0.10.62

package/dist/cli/setup.js

@@ -1,7 +1,6 @@
-import { createRelayfileCloudAccessTokenProvider } from "../cloud-token-provider.js";
 import { runRelayfileCloudLogin } from "../cloud-login.js";
 import { defaultMountLauncher, readMountedWorkspaceStatus } from "../mount-launcher.js";
-import { RelayfileSetup as BaseRelayfileSetup } from "../setup.js";
+import { RelayfileSetup as BaseRelayfileSetup, resolveCloudTokensAccessToken } from "../setup.js";
 const DEFAULT_CLOUD_API_URL = "https://agentrelay.com/cloud";
 export class RelayfileSetup extends BaseRelayfileSetup {
     static async login(options = {}) {
@@ -21,13 +20,8 @@ export class RelayfileSetup extends BaseRelayfileSetup {
         return new RelayfileSetup({
             ...options,
             cloudApiUrl,
-            accessToken: createRelayfileCloudAccessTokenProvider({
-                ...tokens,
-                apiUrl: tokens.apiUrl ?? cloudApiUrl
-            }, {
-                ...options,
-                cloudApiUrl
-            })
+            // Shared routing: relay_pa pairs rotate at RelayAuth, cloud pairs at Cloud.
+            accessToken: resolveCloudTokensAccessToken(tokens, options, cloudApiUrl)
         });
     }
     getDefaultMountLauncher() {

package/dist/client.d.ts

@@ -7,6 +7,41 @@ import type { ForkHandle } from "@relayfile/core";
  * `{ workspace_id: "ws_123", agent_name: "review-bot", aud: ["relayfile"] }`
  */
 export type AccessTokenProvider = string | (() => string | Promise<string>);
+/**
+ * An access+refresh token pair (e.g. `RELAYFILE_ACCESS_TOKEN` +
+ * `RELAYFILE_REFRESH_TOKEN`). Pass this as `token` and the client auto-wraps it
+ * in the correct rotating provider — a RelayAuth `relay_pa` pair refreshes at
+ * RelayAuth, a Cloud device-auth pair at Cloud — so the short access token is
+ * rotated automatically.
+ *
+ * Rotation is in-memory: on refresh the refresh token rotates too and the old
+ * one is revoked, so the pair you passed here (e.g. the one in your `.env`) is
+ * spent after the first refresh. In a long-lived process this is invisible, but
+ * a process that restarts (a redeploy, a new worker) will reload the original,
+ * now-revoked pair and fail with `invalid_grant` / "refresh token revoked".
+ * Supply {@link RelayFileClientOptions.onTokens} to persist each rotated pair so
+ * the next process boots from a live credential.
+ */
+export interface RelayFileTokenPair {
+    accessToken: string;
+    refreshToken: string;
+    /** ISO expiry of the access token; derived from its `exp` claim when omitted. */
+    accessTokenExpiresAt?: string;
+    refreshTokenExpiresAt?: string;
+    /** RelayAuth base URL; derived from the refresh token's `iss` when omitted. */
+    relayauthUrl?: string;
+    /** Cloud API URL for a Cloud device-auth pair. */
+    apiUrl?: string;
+}
+/**
+ * Called after the client rotates the access+refresh {@link RelayFileTokenPair}.
+ * Persist the new pair (e.g. write it back to your secret store / `.env`) so a
+ * later process starts from a live credential instead of the revoked original.
+ * The callback is best-effort and retried on the next request until it succeeds;
+ * a throw is swallowed (the in-memory access token stays usable) but leaves the
+ * pair unpersisted, so make it durable.
+ */
+export type RelayFileTokenPersister = (tokens: RelayFileTokenPair) => void | Promise<void>;
 export interface RelayFileRetryOptions {
     maxRetries?: number;
     baseDelayMs?: number;
@@ -31,12 +66,24 @@ export interface RelayFileClientOptions {
     /** API base URL. Defaults to https://api.relayfile.dev */
     baseUrl?: string;
     /**
-     * Bearer token or token factory for SDK requests.
+     * Bearer token, token factory, or an access+refresh {@link RelayFileTokenPair}
+     * for SDK requests. A pair is auto-wrapped in a rotating provider (RelayAuth
+     * `relay_pa` pairs refresh at RelayAuth, Cloud pairs at Cloud), so the short
+     * access token is renewed automatically.
      *
      * Relayfile-authenticated JWTs should include `workspace_id`, `agent_name`,
      * and `aud` containing `relayfile`.
      */
-    token: AccessTokenProvider;
+    token: AccessTokenProvider | RelayFileTokenPair;
+    /**
+     * Persistence hook for a rotating {@link RelayFileTokenPair}. Called with the
+     * new pair each time the access token is refreshed (the refresh token rotates
+     * too). Write it back to your secret store so a process that restarts reloads a
+     * live credential instead of the spent original — without this, a `token` pair
+     * survives only within one process lifetime. Ignored when `token` is a string
+     * or token factory (that provider owns its own rotation).
+     */
+    onTokens?: RelayFileTokenPersister;
     fetchImpl?: typeof fetch;
     userAgent?: string;
     retry?: RelayFileRetryOptions;

package/dist/client.js

@@ -1,5 +1,53 @@
 import { RelayFileSync, normalizeFilesystemEvent } from "./sync.js";
+import { createRelayfileCloudAccessTokenProvider } from "./cloud-token-provider.js";
+import { createRelayauthPathTokenAccessTokenProvider, isRelayauthRefreshToken } from "./relayauth-token-provider.js";
 import { InvalidStateError, MergeConflictError, ParentMovedError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
+// Resolve the `token` option into a concrete AccessTokenProvider. A string or
+// function is used as-is; a token PAIR is auto-wrapped in the rotating provider
+// that matches the refresh token's issuer. When `onTokens` is supplied, each
+// rotated pair is handed back so the caller can persist it across restarts.
+function resolveTokenOption(token, onTokens) {
+    if (typeof token === "string" || typeof token === "function") {
+        return token;
+    }
+    if (isRelayauthRefreshToken(token.refreshToken)) {
+        return createRelayauthPathTokenAccessTokenProvider({
+            accessToken: token.accessToken,
+            refreshToken: token.refreshToken,
+            accessTokenExpiresAt: token.accessTokenExpiresAt,
+            refreshTokenExpiresAt: token.refreshTokenExpiresAt,
+            relayauthUrl: token.relayauthUrl
+        }, onTokens
+            ? {
+                onTokens: (rotated) => onTokens({
+                    accessToken: rotated.accessToken,
+                    refreshToken: rotated.refreshToken,
+                    accessTokenExpiresAt: rotated.accessTokenExpiresAt,
+                    refreshTokenExpiresAt: rotated.refreshTokenExpiresAt,
+                    relayauthUrl: rotated.relayauthUrl
+                })
+            }
+            : undefined);
+    }
+    return createRelayfileCloudAccessTokenProvider({
+        apiUrl: token.apiUrl,
+        accessToken: token.accessToken,
+        refreshToken: token.refreshToken,
+        // The cloud provider treats an unparseable expiry as "refresh now".
+        accessTokenExpiresAt: token.accessTokenExpiresAt ?? "",
+        refreshTokenExpiresAt: token.refreshTokenExpiresAt
+    }, onTokens
+        ? {
+            onTokens: (rotated) => onTokens({
+                accessToken: rotated.accessToken,
+                refreshToken: rotated.refreshToken,
+                accessTokenExpiresAt: rotated.accessTokenExpiresAt,
+                refreshTokenExpiresAt: rotated.refreshTokenExpiresAt,
+                apiUrl: rotated.apiUrl
+            })
+        }
+        : undefined);
+}
 /** Default base URL for the hosted Relayfile API */
 export const DEFAULT_RELAYFILE_BASE_URL = "https://api.relayfile.dev";
 const DEFAULT_RETRY_OPTIONS = {
@@ -1222,7 +1270,7 @@ export class RelayFileClient {
     retryOptions;
     constructor(options) {
         this.baseUrl = (options.baseUrl ?? DEFAULT_RELAYFILE_BASE_URL).replace(/\/+$/, "");
-        this.tokenProvider = options.token;
+        this.tokenProvider = resolveTokenOption(options.token, options.onTokens);
         this.fetchImpl = options.fetchImpl ?? fetch.bind(globalThis);
         this.userAgent = options.userAgent;
         this.retryOptions = normalizeRetryOptions(options.retry);

package/dist/cloud-token-provider.js

@@ -14,6 +14,11 @@ export function createRelayfileCloudAccessTokenProvider(initialTokens, options =
         apiUrl: normalizeNonEmptyString(initialTokens.apiUrl) ?? cloudApiUrl
     };
     let refreshPromise;
+    // A rotated token set whose `onTokens` persistence callback has not yet
+    // succeeded. Until it does, a consumed refresh token may still live in the
+    // caller's persisted copy (→ `invalid_grant` after restart), so we retry the
+    // callback on every subsequent use rather than treating rotation as complete.
+    let pendingPersist;
     return async () => {
         if (shouldRefresh(tokens, refreshWindowMs)) {
             if (!refreshPromise) {
@@ -26,6 +31,10 @@ export function createRelayfileCloudAccessTokenProvider(initialTokens, options =
                 refreshPromise = undefined;
             }
         }
+        else if (pendingPersist) {
+            // No refresh needed, but a prior rotation still owes a successful persist.
+            await persistPendingTokens();
+        }
         return tokens.accessToken;
     };
     async function refresh() {
@@ -42,7 +51,32 @@ export function createRelayfileCloudAccessTokenProvider(initialTokens, options =
             throw new CloudApiError(response.status, payload);
         }
         tokens = readTokenSetFromPayload(payload, cloudApiUrl);
-        await options.onTokens?.({ ...tokens });
+        pendingPersist = { ...tokens };
+        await persistPendingTokens();
+    }
+    // Best-effort, retried persistence. A callback failure never rejects the
+    // provider — the in-memory access token is valid and usable — but the set
+    // stays pending so the next provider() call re-attempts, so a durable copy
+    // eventually catches up with the rotated refresh token.
+    async function persistPendingTokens() {
+        if (!pendingPersist) {
+            return;
+        }
+        if (!options.onTokens) {
+            pendingPersist = undefined;
+            return;
+        }
+        const toPersist = pendingPersist;
+        try {
+            await options.onTokens({ ...toPersist });
+            // Only clear if nothing rotated again while the callback was in flight.
+            if (pendingPersist === toPersist) {
+                pendingPersist = undefined;
+            }
+        }
+        catch {
+            // Keep pending; retried on the next use.
+        }
     }
 }
 function shouldRefresh(tokens, refreshWindowMs) {

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type RelayFileChangeLogOptions, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type RelayFileTokenPair, type RelayFileTokenPersister, type RelayFileChangeLogOptions, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
 export type { RelayFileReadCacheOptions } from "./types.js";
 export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.js";
 export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";
+export { createRelayauthPathTokenAccessTokenProvider, isRelayauthRefreshToken, type RelayauthPathTokenSet, type RelayauthPathTokenSetupOptions } from "./relayauth-token-provider.js";
 export { CloudAbortError, CloudApiError, CloudTimeoutError, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountModeUnavailableError, MountMultiPathUnsupportedError, MountReadyTimeoutError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
 export { type EnsureMountedWorkspaceInput, WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CheckpointAndSealInput, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type MountLauncher, type MountLauncherEvent, type MountLauncherInstance, type MountLauncherStart, type MountLocalLayout, type MountMode, type MountSessionRequest, type MountSessionResponse, type MountSessionResult, type MountSyncMode, type MountSupervisorEvent, type MountedWorkspaceHandle, type MountedWorkspaceStatus, type MountWorkspaceInput, type ReadMountedWorkspaceStatusInput, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspacePermissions } from "./setup-types.js";
 export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncStart, type RelayFileSyncState, type RelayFileSyncTokenProvider } from "./sync.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL } from "./client.js";
 export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.js";
+export { createRelayauthPathTokenAccessTokenProvider, isRelayauthRefreshToken } from "./relayauth-token-provider.js";
 export { CloudAbortError, CloudApiError, CloudTimeoutError, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountModeUnavailableError, MountMultiPathUnsupportedError, MountReadyTimeoutError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
 export { WORKSPACE_INTEGRATION_PROVIDERS } from "./setup-types.js";
 export { RelayFileSync } from "./sync.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const RELAYFILE_VERSION = "0.10.60";
+export declare const RELAYFILE_VERSION = "0.10.62";

package/dist/package-version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/sync-package-version.mjs during every SDK build.
-export const RELAYFILE_VERSION = "0.10.60";
+export const RELAYFILE_VERSION = "0.10.62";

package/dist/relayauth-token-provider.d.ts

@@ -0,0 +1,22 @@
+import type { AccessTokenProvider } from "./client.js";
+export interface RelayauthPathTokenSet {
+    accessToken: string;
+    refreshToken: string;
+    /** Optional; when omitted it is derived from the access token's `exp` claim. */
+    accessTokenExpiresAt?: string;
+    refreshTokenExpiresAt?: string;
+    /**
+     * RelayAuth base URL (e.g. `https://api.relayauth.dev`). When omitted it is
+     * derived from the refresh token's `iss` claim, mapping the issuer host to its
+     * API host (`relayauth.dev` -> `api.relayauth.dev`).
+     */
+    relayauthUrl?: string;
+}
+export interface RelayauthPathTokenSetupOptions {
+    requestTimeoutMs?: number;
+    refreshWindowMs?: number;
+    onTokens?: (tokens: RelayauthPathTokenSet) => void | Promise<void>;
+}
+/** True when `refreshToken` is a RelayAuth-issued refresh token (relay_pa pair). */
+export declare function isRelayauthRefreshToken(refreshToken: string): boolean;
+export declare function createRelayauthPathTokenAccessTokenProvider(initialTokens: RelayauthPathTokenSet, options?: RelayauthPathTokenSetupOptions): AccessTokenProvider;

package/dist/relayauth-token-provider.js

@@ -0,0 +1,250 @@
+import { CloudApiError, CloudTimeoutError, MalformedCloudResponseError, RelayfileSetupError } from "./setup-errors.js";
+import { RELAYFILE_SDK_VERSION } from "./version.js";
+// A `relay_pa` (RelayAuth path-token) access+refresh pair is issued and rotated
+// by RelayAuth, NOT by the Cloud device-auth flow. Its refresh token carries
+// `aud: ["relayauth"]` and scope `relayauth:token:refresh`, and it is exchanged
+// at `<relayauth>/v1/tokens/refresh` — a DIFFERENT endpoint from Cloud's
+// `api/v1/auth/token/refresh`. Sending such a refresh token to the Cloud endpoint
+// returns `invalid_grant`, which is the failure mode this provider fixes:
+// `createRelayfileCloudAccessTokenProvider` unconditionally targets Cloud, so a
+// relay_pa credential (e.g. `RELAYFILE_ACCESS_TOKEN` + `RELAYFILE_REFRESH_TOKEN`
+// in an agent .env) never rotates through it. Conveniently, RelayAuth's refresh
+// response has the SAME shape Cloud returns
+// (`accessToken`/`refreshToken`/`accessTokenExpiresAt`/`refreshTokenExpiresAt`),
+// so only the endpoint differs.
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const DEFAULT_REFRESH_WINDOW_MS = 60_000;
+/** True when `refreshToken` is a RelayAuth-issued refresh token (relay_pa pair). */
+export function isRelayauthRefreshToken(refreshToken) {
+    const claims = decodeJwtClaims(refreshToken);
+    if (!claims)
+        return false;
+    const aud = claims.aud;
+    const audiences = Array.isArray(aud) ? aud : typeof aud === "string" ? [aud] : [];
+    if (audiences.includes("relayauth"))
+        return true;
+    const scopes = Array.isArray(claims.scopes) ? claims.scopes : [];
+    return scopes.includes("relayauth:token:refresh");
+}
+export function createRelayauthPathTokenAccessTokenProvider(initialTokens, options = {}) {
+    const requestTimeoutMs = Math.max(1, Math.floor(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS));
+    const refreshWindowMs = Math.max(0, Math.floor(options.refreshWindowMs ?? DEFAULT_REFRESH_WINDOW_MS));
+    const refreshUrl = buildRefreshUrl(initialTokens);
+    let tokens = withDerivedAccessExpiry(initialTokens);
+    let refreshPromise;
+    // A rotated token set whose `onTokens` persistence callback has not yet
+    // succeeded. Until it does, a consumed refresh token may still live in the
+    // caller's persisted copy (→ `invalid_grant` after restart), so we retry the
+    // callback on every subsequent use rather than treating rotation as complete.
+    let pendingPersist;
+    return async () => {
+        if (shouldRefresh(tokens, refreshWindowMs)) {
+            if (!refreshPromise) {
+                refreshPromise = refresh();
+            }
+            try {
+                await refreshPromise;
+            }
+            finally {
+                refreshPromise = undefined;
+            }
+        }
+        else if (pendingPersist) {
+            // No refresh needed, but a prior rotation still owes a successful persist.
+            await persistPendingTokens();
+        }
+        return tokens.accessToken;
+    };
+    async function refresh() {
+        const { response, payload } = await fetchJsonWithTimeout(refreshUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Relayfile-SDK-Version": RELAYFILE_SDK_VERSION
+            },
+            body: JSON.stringify({ refreshToken: tokens.refreshToken })
+        }, requestTimeoutMs);
+        if (!response.ok) {
+            throw new CloudApiError(response.status, payload);
+        }
+        tokens = withDerivedAccessExpiry({
+            relayauthUrl: tokens.relayauthUrl,
+            accessToken: requireStringField(payload, "accessToken"),
+            refreshToken: requireStringField(payload, "refreshToken"),
+            accessTokenExpiresAt: readOptionalStringField(payload, "accessTokenExpiresAt"),
+            refreshTokenExpiresAt: readOptionalStringField(payload, "refreshTokenExpiresAt")
+        });
+        pendingPersist = { ...tokens };
+        await persistPendingTokens();
+    }
+    // Best-effort, retried persistence. A callback failure never rejects the
+    // provider — the in-memory access token is valid and usable — but the set
+    // stays pending so the next provider() call re-attempts, so a durable copy
+    // eventually catches up with the rotated refresh token.
+    async function persistPendingTokens() {
+        if (!pendingPersist) {
+            return;
+        }
+        if (!options.onTokens) {
+            pendingPersist = undefined;
+            return;
+        }
+        const toPersist = pendingPersist;
+        try {
+            await options.onTokens({ ...toPersist });
+            // Only clear if nothing rotated again while the callback was in flight.
+            if (pendingPersist === toPersist) {
+                pendingPersist = undefined;
+            }
+        }
+        catch {
+            // Keep pending; retried on the next use.
+        }
+    }
+}
+function buildRefreshUrl(tokens) {
+    const explicit = normalizeNonEmptyString(tokens.relayauthUrl);
+    const base = explicit ?? deriveRelayauthApiBase(tokens.refreshToken);
+    if (!base) {
+        // NEVER put the refresh token in the error — it is a live bearer credential.
+        throw new RelayfileSetupError("Cannot determine the RelayAuth refresh endpoint: pass `relayauthUrl`, or use a refresh token that carries an `iss` claim.", "relayauth_url_unresolved");
+    }
+    let url;
+    try {
+        url = new URL(base);
+    }
+    catch {
+        throw new RelayfileSetupError(`Invalid RelayAuth URL: ${base}`, "relayauth_url_invalid");
+    }
+    // The refresh token is transmitted in the request body, so the endpoint must
+    // be HTTPS. A loopback host is allowed for local self-host development.
+    if (url.protocol !== "https:" && !isLoopbackHost(url.hostname)) {
+        throw new RelayfileSetupError(`RelayAuth refresh endpoint must use HTTPS (got ${url.protocol}//${url.host}).`, "relayauth_url_insecure");
+    }
+    if (!url.pathname.endsWith("/")) {
+        url.pathname = `${url.pathname}/`;
+    }
+    return new URL("v1/tokens/refresh", url).toString();
+}
+function isLoopbackHost(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "::1" ||
+        hostname === "[::1]");
+}
+// Derive the RelayAuth API base from the refresh token's `iss`. The issuer is the
+// public host (`https://relayauth.dev`); token exchange lives on the API host
+// (`https://api.relayauth.dev`). A host that already begins with `api.` is left
+// as-is so self-hosted issuers work unchanged.
+function deriveRelayauthApiBase(refreshToken) {
+    const claims = decodeJwtClaims(refreshToken);
+    const iss = typeof claims?.iss === "string" ? claims.iss : undefined;
+    if (!iss)
+        return undefined;
+    try {
+        const url = new URL(iss);
+        if (!url.hostname.startsWith("api.")) {
+            url.hostname = `api.${url.hostname}`;
+        }
+        // `url.host` preserves a non-default port; `url.hostname` would drop it.
+        return `${url.protocol}//${url.host}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function withDerivedAccessExpiry(tokens) {
+    const explicit = normalizeNonEmptyString(tokens.accessTokenExpiresAt);
+    if (explicit && !Number.isNaN(Date.parse(explicit))) {
+        return { ...tokens, accessTokenExpiresAt: explicit };
+    }
+    const exp = decodeJwtClaims(tokens.accessToken)?.exp;
+    const iso = typeof exp === "number" && Number.isFinite(exp)
+        ? new Date(exp * 1000).toISOString()
+        : new Date(0).toISOString(); // unknown -> force refresh on first use
+    return { ...tokens, accessTokenExpiresAt: iso };
+}
+function shouldRefresh(tokens, refreshWindowMs) {
+    const expiresAt = Date.parse(tokens.accessTokenExpiresAt);
+    if (Number.isNaN(expiresAt)) {
+        return true;
+    }
+    return expiresAt - Date.now() <= refreshWindowMs;
+}
+function decodeJwtClaims(token) {
+    try {
+        const compact = token.replace(/^relay_[a-z]+_/, "");
+        const payload = compact.split(".")[1];
+        if (!payload)
+            return undefined;
+        const json = Buffer.from(payload, "base64url").toString("utf8");
+        return JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+}
+// Runs the fetch AND the response-body read under one timeout, so a server that
+// sends headers then stalls the body still trips `requestTimeoutMs` instead of
+// hanging the shared refresh (and every caller awaiting it) indefinitely.
+async function fetchJsonWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        const payload = await readResponseBody(response);
+        return { response, payload };
+    }
+    catch (error) {
+        if (controller.signal.aborted) {
+            throw new CloudTimeoutError("refreshRelayauthAccessToken", timeoutMs);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (text === "") {
+        return null;
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+function requireStringField(payload, field) {
+    const value = readField(payload, field);
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new MalformedCloudResponseError(field, payload);
+    }
+    return value;
+}
+function readOptionalStringField(payload, field) {
+    const value = readField(payload, field);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new MalformedCloudResponseError(field, payload);
+    }
+    return value;
+}
+function readField(payload, field) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return undefined;
+    }
+    return payload[field];
+}
+function normalizeNonEmptyString(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+}

package/dist/setup.d.ts

@@ -37,6 +37,16 @@ interface WorkspaceHandleOptions {
     token: string;
     joinOptions: NormalizedJoinWorkspaceOptions;
 }
+/**
+ * Build the rotating access-token provider for a cloud token set, auto-routing
+ * by the refresh token's issuer: a RelayAuth `relay_pa` pair (e.g.
+ * RELAYFILE_ACCESS_TOKEN + RELAYFILE_REFRESH_TOKEN) rotates at RelayAuth, while a
+ * Cloud device-auth pair rotates at Cloud. Routing a relay_pa token through the
+ * Cloud endpoint returns `invalid_grant`, so this picks the right provider once
+ * and is shared by every `fromCloudTokens` (base and CLI subclass) so no entry
+ * point can silently skip the routing.
+ */
+export declare function resolveCloudTokensAccessToken(tokens: RelayfileCloudTokenSet, options: RelayfileCloudTokenSetupOptions, cloudApiUrl: string): AccessTokenProvider;
 export declare class RelayfileSetup {
     private readonly cloudApiUrl;
     private readonly accessToken?;

package/dist/setup.js

@@ -1,5 +1,6 @@
 import { RelayFileClient } from "./client.js";
 import { createRelayfileCloudAccessTokenProvider } from "./cloud-token-provider.js";
+import { createRelayauthPathTokenAccessTokenProvider, isRelayauthRefreshToken } from "./relayauth-token-provider.js";
 import { CloudAbortError, CloudApiError, CloudTimeoutError, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
 import { WORKSPACE_INTEGRATION_PROVIDERS } from "./setup-types.js";
 import { RELAYFILE_SDK_VERSION } from "./version.js";
@@ -32,6 +33,38 @@ const nodeOnlyMountLauncher = {
         throw new RelayfileSetupError("The default relayfile-mount launcher is only available from @relayfile/sdk/cli. Import RelayfileSetup from @relayfile/sdk/cli or pass a custom launcher to mountWorkspace().", "node_only_sdk_feature");
     }
 };
+/**
+ * Build the rotating access-token provider for a cloud token set, auto-routing
+ * by the refresh token's issuer: a RelayAuth `relay_pa` pair (e.g.
+ * RELAYFILE_ACCESS_TOKEN + RELAYFILE_REFRESH_TOKEN) rotates at RelayAuth, while a
+ * Cloud device-auth pair rotates at Cloud. Routing a relay_pa token through the
+ * Cloud endpoint returns `invalid_grant`, so this picks the right provider once
+ * and is shared by every `fromCloudTokens` (base and CLI subclass) so no entry
+ * point can silently skip the routing.
+ */
+export function resolveCloudTokensAccessToken(tokens, options, cloudApiUrl) {
+    if (!isRelayauthRefreshToken(tokens.refreshToken)) {
+        return createRelayfileCloudAccessTokenProvider({ ...tokens, apiUrl: tokens.apiUrl ?? cloudApiUrl }, { ...options, cloudApiUrl });
+    }
+    return createRelayauthPathTokenAccessTokenProvider({
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+        accessTokenExpiresAt: tokens.accessTokenExpiresAt,
+        refreshTokenExpiresAt: tokens.refreshTokenExpiresAt
+    }, {
+        requestTimeoutMs: options.requestTimeoutMs,
+        refreshWindowMs: options.refreshWindowMs,
+        onTokens: options.onTokens
+            ? (rotated) => options.onTokens({
+                apiUrl: tokens.apiUrl ?? cloudApiUrl,
+                accessToken: rotated.accessToken,
+                refreshToken: rotated.refreshToken,
+                accessTokenExpiresAt: rotated.accessTokenExpiresAt ?? "",
+                refreshTokenExpiresAt: rotated.refreshTokenExpiresAt
+            })
+            : undefined
+    });
+}
 export class RelayfileSetup {
     cloudApiUrl;
     accessToken;
@@ -47,13 +80,7 @@ export class RelayfileSetup {
         return new RelayfileSetup({
             ...options,
             cloudApiUrl,
-            accessToken: createRelayfileCloudAccessTokenProvider({
-                ...tokens,
-                apiUrl: tokens.apiUrl ?? cloudApiUrl
-            }, {
-                ...options,
-                cloudApiUrl
-            })
+            accessToken: resolveCloudTokensAccessToken(tokens, options, cloudApiUrl)
         });
     }
     constructor(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.10.60",
+  "version": "0.10.62",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -60,15 +60,15 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.10.60",
+    "@relayfile/core": "0.10.62",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },
   "optionalDependencies": {
-    "@relayfile/mount-darwin-arm64": "0.10.60",
-    "@relayfile/mount-darwin-x64": "0.10.60",
-    "@relayfile/mount-linux-arm64": "0.10.60",
-    "@relayfile/mount-linux-x64": "0.10.60"
+    "@relayfile/mount-darwin-arm64": "0.10.62",
+    "@relayfile/mount-darwin-x64": "0.10.62",
+    "@relayfile/mount-linux-arm64": "0.10.62",
+    "@relayfile/mount-linux-x64": "0.10.62"
   },
   "devDependencies": {
     "typescript": "^5.7.3",