@comfyorg/account-core 1.0.0-alpha.0

package/dist/core/refreshScheduler.js

@@ -0,0 +1,262 @@
+import { isPermanentSessionError } from './sessionContracts.js';
+export const DEFAULT_BUFFER_MS = 5 * 60 * 1000;
+function disposeQuietly(dispose, label) {
+    try {
+        dispose?.();
+    }
+    catch (error) {
+        console.warn(`Cross-tab refresh ${label} teardown failed:`, error);
+    }
+}
+export function createRefreshScheduler(options, host) {
+    const bufferMs = options.bufferMs ?? DEFAULT_BUFFER_MS;
+    const retryBaseMs = options.retryBaseMs ?? 5000;
+    const maxRetries = options.maxRetries ?? 3;
+    const reportOutcome = options.onScheduledOutcome;
+    const crossTab = options.crossTab;
+    const followerJitterMs = crossTab?.followerJitterMs ?? 15_000;
+    let scheduledTimer;
+    /**
+     * The hard fail-close for a credential whose refresh chain died. Its own
+     * timer on purpose: re-arming the refresh (a retry, a promotion) must not
+     * cancel it; only a committed credential or a teardown does.
+     */
+    let expiryTimer;
+    let scheduledRetryCount = 0;
+    /** Without coordination every tab is its own leader. */
+    let isRefreshLeader = crossTab === undefined;
+    let coordinationKey;
+    /**
+     * Bumped on every coordination teardown. A leadership grant landing on an
+     * abandoned request carries the generation it was issued under — the key
+     * string alone cannot distinguish an abandoned request from its same-key
+     * successor after a sign-out/sign-in round trip.
+     */
+    let coordinationGeneration = 0;
+    let armingScheduledRefresh = false;
+    let releaseLeadership;
+    let stopCredentialFeed;
+    function stopScheduledRefresh() {
+        if (scheduledTimer !== undefined) {
+            clearTimeout(scheduledTimer);
+            scheduledTimer = undefined;
+        }
+    }
+    function clearExpiry() {
+        if (expiryTimer !== undefined) {
+            clearTimeout(expiryTimer);
+            expiryTimer = undefined;
+        }
+    }
+    function teardownCoordination() {
+        coordinationGeneration += 1;
+        disposeQuietly(releaseLeadership, 'leadership release');
+        releaseLeadership = undefined;
+        disposeQuietly(stopCredentialFeed, 'credential feed');
+        stopCredentialFeed = undefined;
+        coordinationKey = undefined;
+        isRefreshLeader = crossTab === undefined;
+    }
+    function ensureCoordination() {
+        const credential = host.getCredential();
+        if (crossTab === undefined || credential === undefined)
+            return;
+        // Keyed by the SERVER-RESOLVED workspace, never the requested target: a
+        // personal {} mint resolves to a concrete workspace the target string
+        // cannot name, and tabs on one workspace must share one lease however
+        // they reached it.
+        const key = `comfy-account-refresh:${credential.uid}:${credential.workspace.id}`;
+        if (key === coordinationKey)
+            return;
+        teardownCoordination();
+        coordinationKey = key;
+        const generationAtRequest = coordinationGeneration;
+        // Cross-tab coordination is optional: a port that throws during setup
+        // must never propagate past a committed credential. Tear down whatever
+        // partial wiring landed and lead this tab on its own schedule.
+        try {
+            stopCredentialFeed = crossTab.port.onCredential(key, adoptPublishedCredential);
+            releaseLeadership = crossTab.port.requestLeadership(key, () => {
+                // A grant is honored only for the coordination generation that issued
+                // the request: abandoned requests can still win the grant race in the
+                // lock manager, and after a same-user round trip their key is
+                // byte-identical to the live request's.
+                if (generationAtRequest !== coordinationGeneration)
+                    return;
+                isRefreshLeader = true;
+                // Promotion retakes the schedule unconditionally — the follower timer
+                // may be jittered, mid-retry, or already dead from exhausted retries.
+                // The latch skips the redundant re-arm when the grant fires
+                // synchronously inside armScheduledRefresh itself.
+                const live = host.getCredential();
+                if (live !== undefined && !armingScheduledRefresh) {
+                    armScheduledRefresh(live.expiresAt, host.now());
+                }
+            });
+        }
+        catch (error) {
+            console.warn('Cross-tab refresh coordination setup failed:', error);
+            teardownCoordination();
+            isRefreshLeader = true;
+        }
+    }
+    /**
+     * Every committed mint is published once a coordination key exists —
+     * leadership gates adoption, never publication — so the reactive 401
+     * re-mint and a leaderless follower's fallback reach siblings too: those
+     * are exactly the rotations they must not miss. Adoption itself never
+     * republishes, and the monotonic-expiry guard makes redelivery a no-op,
+     * so the channel cannot loop.
+     */
+    function publishToSiblings(session) {
+        if (coordinationKey === undefined)
+            return;
+        // Publication is optional: a throwing port must not unwind a mint that
+        // already committed and persisted its credential.
+        try {
+            crossTab?.port.publishCredential(coordinationKey, session);
+        }
+        catch (error) {
+            console.warn('Cross-tab refresh credential publish failed:', error);
+        }
+    }
+    function adoptPublishedCredential(message) {
+        // Any tab adopts a strictly newer credential, the leader included: a
+        // leader whose own chain died recovers from a sibling's fallback mint,
+        // and the monotonic-expiry check keeps the channel from looping.
+        const next = host.parseAdopted(message);
+        if (next === undefined)
+            return;
+        if (host.getCurrentUser()?.uid !== next.uid)
+            return;
+        // Scope check: the channel key cannot fully encode the workspace (the
+        // personal target is server-resolved), so a same-user credential minted
+        // for a DIFFERENT workspace must never switch this tab.
+        const credential = host.getCredential();
+        if (credential === undefined)
+            return;
+        if (next.workspace.id !== credential.workspace.id)
+            return;
+        if (next.expiresAt <= credential.expiresAt)
+            return;
+        clearExpiry();
+        host.commitAdopted(next);
+        armScheduledRefresh(next.expiresAt, host.now());
+        crossTab?.onCredentialAdopted?.(next);
+    }
+    function armScheduledRefresh(expiresAt, now) {
+        stopScheduledRefresh();
+        scheduledRetryCount = 0;
+        armingScheduledRefresh = true;
+        try {
+            ensureCoordination();
+        }
+        finally {
+            armingScheduledRefresh = false;
+        }
+        // A follower holds past the leader's refresh point by bounded random
+        // jitter; when no published credential has arrived by then, the leader
+        // is gone and this tab refreshes for itself. Never tighter than one
+        // retry interval: a token already inside the buffer (a host buffer at
+        // or above the TTL, a skewed clock) would otherwise re-mint in a loop.
+        const jitter = isRefreshLeader ? 0 : Math.random() * followerJitterMs;
+        scheduledTimer = setTimeout(() => {
+            scheduledTimer = undefined;
+            void runScheduledRefresh();
+        }, Math.max(retryBaseMs, expiresAt - bufferMs - now) + jitter);
+    }
+    /**
+     * Retries are spent and the credential still has time on it: keep serving
+     * it until its expiry instant, then fail closed and tell the host, as the
+     * cloud store's clear-at-expiry does. A dead scheduler must never leave an
+     * expired token in circulation.
+     */
+    function armClearAtExpiry(expiring) {
+        const now = host.now();
+        clearExpiry();
+        expiryTimer = setTimeout(() => {
+            expiryTimer = undefined;
+            const committed = host.commitExpired(expiring);
+            if (!committed)
+                return;
+            stopScheduledRefresh();
+            reportOutcome?.({ outcome: 'expired', failure: committed });
+        }, Math.max(0, expiring.expiresAt - now));
+    }
+    /**
+     * The scheduled re-mint mirrors the cloud store's refresh semantics: a
+     * transient failure keeps the still-valid credential and retries with
+     * doubling backoff; a permanent failure commits the error; exhausted
+     * retries keep the credential until it expires, then fail closed. Every
+     * commit runs publish() before reporting its outcome — host outcome
+     * handlers read state the publish just wrote.
+     */
+    async function runScheduledRefresh() {
+        const user = host.getCurrentUser();
+        if (!user)
+            return;
+        const guards = host.captureGuards();
+        // Refresh with the target that produced the live credential, so a
+        // scheduled refresh reproduces the same session AND coalesces with any
+        // concurrent reactive re-mint for it.
+        const { mintId, response } = host.mint(user);
+        let result;
+        try {
+            result = await response;
+        }
+        catch {
+            result = { status: 'error', code: 'TOKEN_EXCHANGE_FAILED' };
+        }
+        if (!host.guardsHold(guards, user, mintId))
+            return;
+        if (result.status === 'ok') {
+            const rejected = host.commitRefreshed(result.session, mintId);
+            if (rejected) {
+                reportOutcome?.({ outcome: 'permanent_failure', failure: rejected });
+                return;
+            }
+            clearExpiry();
+            armScheduledRefresh(result.session.expiresAt, host.now());
+            publishToSiblings(result.session);
+            reportOutcome?.({ outcome: 'succeeded' });
+            return;
+        }
+        if (isPermanentSessionError(result.code)) {
+            host.commitPermanentFailure(result);
+            reportOutcome?.({ outcome: 'permanent_failure', failure: result });
+            return;
+        }
+        if (scheduledRetryCount >= maxRetries) {
+            const live = host.getCredential();
+            if (live !== undefined)
+                armClearAtExpiry(live);
+            // A leader with a dead chain must not sit on the lease: release it so
+            // a sibling can lead, and queue again as a follower so this tab can
+            // adopt what that sibling mints or be promoted back if nobody does.
+            teardownCoordination();
+            ensureCoordination();
+            reportOutcome?.({ outcome: 'retries_exhausted' });
+            return;
+        }
+        const delay = retryBaseMs * 2 ** scheduledRetryCount;
+        scheduledRetryCount += 1;
+        stopScheduledRefresh();
+        scheduledTimer = setTimeout(() => {
+            scheduledTimer = undefined;
+            void runScheduledRefresh();
+        }, delay);
+        reportOutcome?.({ outcome: 'retry_scheduled' });
+    }
+    return {
+        armAfterCommit(session, now) {
+            clearExpiry();
+            armScheduledRefresh(session.expiresAt, now);
+            publishToSiblings(session);
+        },
+        stop() {
+            stopScheduledRefresh();
+            clearExpiry();
+            teardownCoordination();
+        }
+    };
+}

package/dist/core/session.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The workspace session: a short-lived JWT minted from the signed-in
+ * identity, which is what actually authorizes runs and balance reads.
+ *
+ * The exchange contract, response schema, and error taxonomy are extracted
+ * from the cloud app's production implementation of this same POST
+ * /auth/token call (`requestToken` in
+ * src/platform/workspace/stores/workspaceAuthStore.ts) — keep the two in
+ * step. Only the freshness strategy differs: valid-on-read (callers await
+ * `ensureFresh` at the moment they need a token; it never resolves with
+ * less than `freshMarginMs` of validity) rather than a proactive refresh
+ * timer, because background tabs throttle timers and this package's callers
+ * can await. A host that needs proactive refresh wraps this client with its
+ * own scheduler.
+ *
+ * The credential cache sits behind the host's storage adapter keyed to the
+ * signed-in uid, so a token survives a reload but can never be served to a
+ * different signed-in user.
+ */
+import type { CredentialStorage } from './credentialCache.js';
+import type { AccountIdentity } from './identity.js';
+import type { AccountCredential, AccountUser, RefreshSchedulerOptions, SessionErrorCode, SessionFailure, SessionResult } from './sessionContracts.js';
+export type { AccountIdentity } from './identity.js';
+export type { AccountCredential, AccountUser, CrossTabRefreshPort, MintHandle, RefreshSchedulerOptions, ScheduledRefreshReport, SessionErrorCode, SessionFailure, SessionRefreshOutcome, SessionResult } from './sessionContracts.js';
+export { isPermanentSessionError } from './sessionContracts.js';
+export type { CredentialStorage } from './credentialCache.js';
+export { isCredentialFresh } from './credentialCache.js';
+/**
+ * The session error codes, keys only. Hosts own the copy (the cloud app's
+ * workspaceAuth.errors.*); the package ships the vocabulary so a host can
+ * narrow an arbitrary error code to one it has a line for. Exhaustive by
+ * type: a new SessionErrorCode is a compile error until it is listed here.
+ */
+export declare const SESSION_ERROR_CODES: Readonly<Record<SessionErrorCode, true>>;
+export { SESSION_TELEMETRY_EVENT } from '../telemetry.js';
+export interface SessionRequestOptions {
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: () => number;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    /** Mint for this workspace instead of the server-resolved personal one. */
+    readonly workspaceId?: string;
+    /**
+     * On a transient remint failure, keep the currently published credential
+     * instead of committing the error — for hosts whose still-valid token
+     * must survive a failed proactive or reactive refresh. Permanent
+     * failures always commit.
+     */
+    readonly preserveCredentialOnTransientFailure?: boolean;
+}
+export interface SessionClientOptions extends SessionRequestOptions {
+    readonly exchangeUrl: string;
+    readonly storage: CredentialStorage;
+    readonly freshMarginMs?: number;
+    readonly refreshScheduler?: RefreshSchedulerOptions;
+    /** Applies to the identity passed at construction; see `AttachIdentityOptions.autoMint`. */
+    readonly autoMint?: boolean;
+}
+/**
+ * `pending` is the initial phase, before the attached identity has delivered
+ * even once, so a host can tell "Firebase has not answered yet" (pending)
+ * from "nobody is signed in" (a delivered null) without wrapping the port.
+ */
+export type SessionSnapshot<TUser extends AccountUser = AccountUser> = {
+    readonly phase: 'pending';
+    readonly user: null;
+    readonly session: undefined;
+} | {
+    readonly phase: 'signed-out';
+    readonly user: null;
+    readonly session: undefined;
+} | {
+    readonly phase: 'minting';
+    readonly user: TUser;
+    readonly session: undefined;
+} | {
+    readonly phase: 'authenticated';
+    readonly user: TUser;
+    readonly session: AccountCredential;
+} | {
+    readonly phase: 'error';
+    readonly user: TUser;
+    readonly session: undefined;
+    readonly failure: SessionFailure;
+};
+export interface AttachIdentityOptions {
+    /**
+     * When false, an identity event sets the user and publishes without
+     * starting a warm-up mint — for hosts that drive every mint explicitly.
+     */
+    readonly autoMint?: boolean;
+}
+export interface SessionClient<TUser extends AccountUser = AccountUser> {
+    /** @deprecated Transitional Pinia-adapter seam; pass the identity as `createSessionClient`'s second argument instead (FE-2171, PoC #16639). */
+    attachIdentity: (identity: AccountIdentity<TUser>, options?: AttachIdentityOptions) => () => void;
+    /**
+     * Detaches the current identity; the persisted credential stays until
+     * `clearStoredCredential`. Not terminal, like a detach: an explicit-user
+     * mint issued after `dispose()` still commits and can re-arm the scheduler
+     * and cross-tab lease, so dispose and then stop calling the client.
+     */
+    dispose: () => void;
+    getSnapshot: () => SessionSnapshot<TUser>;
+    subscribe: (listener: (snapshot: SessionSnapshot<TUser>) => void) => () => void;
+    /** The current credential's token, uid-guarded and withheld once expired (zero margin); no `freshMarginMs` or proactive-refresh promise. */
+    getToken: () => string | undefined;
+    /**
+     * The valid-on-read entry point: resolves with a session that has more
+     * than `freshMarginMs` of validity, minting inside the call when the
+     * cache cannot promise that. Resolves undefined when nobody is signed in,
+     * when the identity changed while the mint was in flight, or when a
+     * concurrent mint for a different target superseded this call.
+     *
+     * Concurrent callers for one user share one in-flight mint, which runs
+     * with the first caller's `timeoutMs`; a later caller's own `signal`
+     * still releases that caller (with a transient failure) without
+     * cancelling the shared mint.
+     *
+     * An explicit-user call made before the identity port has ever fired
+     * (the popup path) resolves with the result, and the credential is
+     * cached — but the snapshot and getToken() stay signed-out until the
+     * port delivers that user, since the snapshot's user is the port's.
+     */
+    ensureFresh: (requestedUser?: AccountUser, options?: SessionRequestOptions) => Promise<SessionResult | undefined>;
+    /** A mint that ignores the cache — for the one 401-retry a read allows. */
+    remint: (requestedUser?: AccountUser, options?: SessionRequestOptions) => Promise<SessionResult | undefined>;
+    /**
+     * Fail closed on a host scope change: drop the published credential,
+     * cancel scheduled work, and invalidate in-flight mints. The identity
+     * stays, because it belongs to the port, so a targeted re-mint can
+     * follow at once. Identity changes fail closed through the port itself.
+     */
+    invalidate: () => void;
+    /**
+     * Drops only the persisted copy of the credential. The published session
+     * stays live; a host that must end it detaches or invalidates as well.
+     */
+    clearStoredCredential: () => void;
+}
+/**
+ * The status→code mapping from `requestToken`: 401/403/404 are permanent
+ * failures with their own codes; everything else — 5xx, network failure,
+ * abort, unparseable body — collapses to TOKEN_EXCHANGE_FAILED, matching
+ * production's default branch.
+ */
+export declare function createSessionClient<TUser extends AccountUser = AccountUser>(clientOptions: SessionClientOptions, identity?: AccountIdentity<TUser>): SessionClient<TUser>;