@comfyorg/account-core 1.0.0-alpha.0

package/dist/core/session.js

@@ -0,0 +1,312 @@
+import { DEFAULT_FRESH_MARGIN_MS, createCredentialCache, decodeAdopted, isCredentialFresh, selectFreshCredential } from './credentialCache.js';
+import { isAccountIdentity } from './identity.js';
+import { abortable, exchangeToken } from './exchange.js';
+import { createMintCoordinator } from './mintCoordinator.js';
+import { createRefreshScheduler } from './refreshScheduler.js';
+import { arbitrateMint, initialSessionState, scheduledMintHolds, transition } from './sessionState.js';
+export { isPermanentSessionError } from './sessionContracts.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 const SESSION_ERROR_CODES = {
+    NOT_AUTHENTICATED: true,
+    INVALID_FIREBASE_TOKEN: true,
+    ACCESS_DENIED: true,
+    WORKSPACE_NOT_FOUND: true,
+    TOKEN_EXCHANGE_FAILED: true
+};
+export { SESSION_TELEMETRY_EVENT } from '../telemetry.js';
+const DEFAULT_MINT_TIMEOUT_MS = 15_000;
+/**
+ * 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 function createSessionClient(clientOptions, identity) {
+    const { exchangeUrl, storage, freshMarginMs = DEFAULT_FRESH_MARGIN_MS } = clientOptions;
+    let state = initialSessionState();
+    let detachCurrent;
+    const listeners = new Set();
+    const cache = createCredentialCache(storage);
+    const mints = createMintCoordinator();
+    function getSnapshot() {
+        const { user, identitySettled, credential, failure } = state;
+        if (!user) {
+            return identitySettled
+                ? { phase: 'signed-out', user: null, session: undefined }
+                : { phase: 'pending', user: null, session: undefined };
+        }
+        if (credential) {
+            return { phase: 'authenticated', user, session: credential };
+        }
+        if (failure) {
+            return { phase: 'error', user, session: undefined, failure };
+        }
+        return { phase: 'minting', user, session: undefined };
+    }
+    function publish() {
+        const snapshot = getSnapshot();
+        listeners.forEach((listener) => listener(snapshot));
+    }
+    // The exchange echoes the requested workspace on success (a non-member 404s),
+    // so a scope mismatch is a backend regression to fail closed on — shared by
+    // the direct commit and the scheduled-refresh commit.
+    function targetMismatch(session, target) {
+        return target !== undefined && session.workspace.id !== target
+            ? { status: 'error', code: 'ACCESS_DENIED' }
+            : undefined;
+    }
+    /**
+     * The package's thin wrapper over the pure exchange: resolves the host's
+     * transport/timeout/clock defaults and sends the personal-workspace body.
+     */
+    function mint(user, options) {
+        const workspaceId = options.workspaceId ?? clientOptions.workspaceId;
+        if (workspaceId === '') {
+            // An explicit empty id is an invalid selection, not personal; fail
+            // closed instead of silently minting a personal-scoped session.
+            return Promise.resolve({ status: 'error', code: 'WORKSPACE_NOT_FOUND' });
+        }
+        return exchangeToken(user, {
+            exchangeUrl,
+            body: workspaceId ? { workspace_id: workspaceId } : {},
+            fetchImpl: options.fetchImpl ?? clientOptions.fetchImpl ?? globalThis.fetch,
+            signal: options.signal ?? clientOptions.signal,
+            timeoutMs: options.timeoutMs ?? clientOptions.timeoutMs ?? DEFAULT_MINT_TIMEOUT_MS,
+            now: () => options.now?.() ?? clientOptions.now?.() ?? Date.now()
+        });
+    }
+    function hostNow() {
+        return clientOptions.now?.() ?? Date.now();
+    }
+    function runEffect(effect, now) {
+        switch (effect.type) {
+            case 'persist':
+                cache.write(effect.session, effect.target);
+                return;
+            case 'clearStorage':
+                cache.clear();
+                return;
+            case 'stopScheduler':
+                scheduler?.stop();
+                return;
+            case 'armScheduler':
+                scheduler?.armAfterCommit(effect.session, now());
+                return;
+            case 'abandonInFlight':
+                mints.abandon();
+                return;
+            case 'publish':
+                publish();
+                return;
+        }
+    }
+    function commit(event, now = hostNow) {
+        const next = transition(state, event);
+        state = next.state;
+        for (const effect of next.effects)
+            runEffect(effect, now);
+        return next;
+    }
+    function sharedMint(user, options, forced) {
+        const target = options.workspaceId ?? clientOptions.workspaceId;
+        return mints.dispatch(user.uid, target, forced, () => {
+            const { mintSequence } = commit({ type: 'mint-started' }).state;
+            return { mintId: mintSequence, response: mint(user, options) };
+        });
+    }
+    function ensureCore(user, options) {
+        const now = options.now?.() ?? clientOptions.now?.() ?? Date.now();
+        const target = options.workspaceId ?? clientOptions.workspaceId;
+        const fresh = selectFreshCredential([
+            () => ({
+                credential: state.credential,
+                target: state.credentialTarget
+            }),
+            () => cache.read(user.uid)
+        ], user.uid, target, now, freshMarginMs);
+        if (fresh) {
+            return {
+                mintId: state.mintSequence,
+                response: Promise.resolve({ status: 'ok', session: fresh }),
+                joined: false
+            };
+        }
+        return sharedMint(user, options, false);
+    }
+    function remintCore(user, options) {
+        cache.clear();
+        return sharedMint(user, options, true);
+    }
+    const scheduler = clientOptions.refreshScheduler
+        ? createRefreshScheduler(clientOptions.refreshScheduler, {
+            now: hostNow,
+            getCurrentUser: () => state.user,
+            getCredential: () => state.credential,
+            captureGuards: () => ({
+                epoch: state.identityEpoch,
+                invalidation: state.invalidationEpoch
+            }),
+            guardsHold: (guards, user, mintId) => scheduledMintHolds(state, guards, user.uid, mintId),
+            mint: (user) => sharedMint(user, { workspaceId: state.credentialTarget }, true),
+            commitRefreshed: (session, mintId) => {
+                const mismatch = targetMismatch(session, state.credentialTarget);
+                if (mismatch) {
+                    commit({
+                        type: 'mint-rejected',
+                        origin: 'scheduler',
+                        failure: mismatch
+                    });
+                    return mismatch;
+                }
+                commit({
+                    type: 'mint-committed',
+                    origin: 'scheduler',
+                    session,
+                    mintId
+                });
+                return undefined;
+            },
+            commitPermanentFailure: (failure) => {
+                commit({ type: 'mint-rejected', origin: 'scheduler', failure });
+            },
+            commitExpired: (expiring) => state.credential === expiring
+                ? commit({ type: 'credential-expired', expiring }).state.failure
+                : undefined,
+            parseAdopted: decodeAdopted,
+            commitAdopted: (session) => {
+                commit({ type: 'credential-adopted', session });
+            }
+        })
+        : undefined;
+    async function refreshWith(core, requestedUser, options = {}) {
+        const user = requestedUser ?? state.user;
+        if (!user)
+            return undefined;
+        const startEpoch = state.identityEpoch;
+        const startInvalidation = state.invalidationEpoch;
+        const startedSignedOut = state.user === null;
+        const requestedTarget = options.workspaceId ?? clientOptions.workspaceId;
+        const { mintId, response, joined } = core(user, options);
+        // A caller that joined an in-flight mint still gets its own signal
+        // honored: the shared mint runs on, this caller stops waiting for it.
+        let result;
+        try {
+            result = options.signal
+                ? await abortable(response, options.signal)
+                : await response;
+        }
+        catch {
+            return { status: 'error', code: 'TOKEN_EXCHANGE_FAILED' };
+        }
+        const arbitration = arbitrateMint(state, {
+            mintId,
+            joined,
+            explicitUser: requestedUser !== undefined,
+            userUid: user.uid,
+            requestedTarget,
+            startEpoch,
+            startInvalidation,
+            startedSignedOut
+        });
+        if (arbitration.verdict === 'superseded')
+            return undefined;
+        if (arbitration.verdict === 'reuse') {
+            return { status: 'ok', session: arbitration.session };
+        }
+        return commitCallerMint(result, mintId, requestedTarget, options);
+    }
+    function commitCallerMint(result, mintId, requestedTarget, options) {
+        const rejectMint = (failure) => {
+            commit({
+                type: 'mint-rejected',
+                origin: 'caller',
+                failure,
+                preserveCredentialOnTransientFailure: options.preserveCredentialOnTransientFailure === true
+            });
+            return failure;
+        };
+        if (result.status !== 'ok')
+            return rejectMint(result);
+        const mismatch = targetMismatch(result.session, requestedTarget);
+        if (mismatch)
+            return rejectMint(mismatch);
+        commit({
+            type: 'mint-committed',
+            origin: 'caller',
+            session: result.session,
+            target: requestedTarget,
+            mintId
+        }, () => options.now?.() ?? hostNow());
+        return result;
+    }
+    function subscribeIdentity(port, autoMint) {
+        if (!isAccountIdentity(port)) {
+            throw new Error('the session client needs the identity from @comfyorg/account-core/firebase (or /testing)');
+        }
+        detachCurrent?.();
+        let unsubscribe = () => undefined;
+        const detach = () => {
+            if (detachCurrent !== detach)
+                return;
+            detachCurrent = undefined;
+            unsubscribe();
+            commit({ type: 'identity-detached' });
+        };
+        detachCurrent = detach;
+        unsubscribe = port.onUserChanged((next) => {
+            if (detachCurrent !== detach)
+                return;
+            commit({ type: 'identity-changed', user: next });
+            if (detachCurrent === detach && next && autoMint) {
+                void refreshWith(ensureCore, next);
+            }
+        });
+        if (detachCurrent !== detach)
+            unsubscribe();
+        return detach;
+    }
+    if (identity)
+        subscribeIdentity(identity, clientOptions.autoMint !== false);
+    return {
+        attachIdentity: (port, attachOptions) => subscribeIdentity(port, attachOptions?.autoMint !== false),
+        dispose() {
+            detachCurrent?.();
+        },
+        getSnapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            // The immediate replay runs host code; if it throws, drop the listener
+            // so a failed subscribe leaves nothing behind to publish to.
+            try {
+                listener(getSnapshot());
+            }
+            catch (error) {
+                listeners.delete(listener);
+                throw error;
+            }
+            return () => listeners.delete(listener);
+        },
+        getToken() {
+            const { user, credential } = state;
+            return credential !== undefined &&
+                user?.uid === credential.uid &&
+                isCredentialFresh(credential, hostNow(), 0)
+                ? credential.token
+                : undefined;
+        },
+        ensureFresh: (requestedUser, options) => refreshWith(ensureCore, requestedUser, options),
+        remint: (requestedUser, options) => refreshWith(remintCore, requestedUser, options),
+        invalidate() {
+            commit({ type: 'invalidated' });
+        },
+        clearStoredCredential() {
+            cache.clear();
+        }
+    };
+}

package/dist/core/sessionContracts.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The contracts the session client shares with the pieces it composes
+ * (`exchange`, `refreshScheduler`). Dependency-neutral by design: `session.ts`
+ * depends on those pieces, and they depend only on this module, never back on
+ * the client — so no top-level binding is ever read before it initializes.
+ */
+import type { zExchangeTokenResponse } from '@comfyorg/ingest-types/zod';
+import type { z } from 'zod';
+export interface AccountUser {
+    readonly uid: string;
+    getIdToken: () => Promise<string>;
+}
+/** Field types come from the generated POST /api/auth/token contract. */
+type ExchangeTokenResponse = z.infer<typeof zExchangeTokenResponse>;
+export interface AccountCredential {
+    readonly token: string;
+    /** ms since epoch */
+    readonly expiresAt: number;
+    readonly uid: string;
+    readonly workspace: ExchangeTokenResponse['workspace'];
+    readonly role: ExchangeTokenResponse['role'];
+    readonly permissions: readonly string[];
+}
+/**
+ * The production store's error taxonomy (`WorkspaceAuthError` codes),
+ * emitted as codes only — the host localizes. TOKEN_EXCHANGE_FAILED also
+ * covers unparseable bodies, network failures, aborts, and timeouts: a
+ * request that produced no usable credential is one failure bucket in
+ * production, not three.
+ */
+export type SessionErrorCode = 'NOT_AUTHENTICATED' | 'INVALID_FIREBASE_TOKEN' | 'ACCESS_DENIED' | 'WORKSPACE_NOT_FOUND' | 'TOKEN_EXCHANGE_FAILED';
+export declare function isPermanentSessionError(code: SessionErrorCode): boolean;
+export type SessionResult = {
+    readonly status: 'ok';
+    readonly session: AccountCredential;
+} | {
+    readonly status: 'error';
+    readonly code: SessionErrorCode;
+    /** Set only when the failure came from an HTTP response, not aborted/network. */
+    readonly httpStatus?: number;
+};
+export type SessionFailure = Extract<SessionResult, {
+    status: 'error';
+}>;
+/**
+ * The result of one SCHEDULED refresh attempt as a single tagged value: the
+ * outcomes that committed a failure carry it and the rest structurally cannot,
+ * so a permanent failure without its error — or a success with one — cannot be
+ * represented.
+ *
+ * `failure?: never` is what makes "structurally cannot" true rather than
+ * aspirational. Without it, excess-property checking still rejects a bad
+ * object literal, but a report built in a variable or returned from a helper
+ * assigns cleanly.
+ */
+export type ScheduledRefreshReport = {
+    readonly outcome: 'succeeded';
+    readonly failure?: never;
+} | {
+    readonly outcome: 'retry_scheduled';
+    readonly failure?: never;
+} | {
+    readonly outcome: 'retries_exhausted';
+    readonly failure?: never;
+} | {
+    readonly outcome: 'permanent_failure';
+    readonly failure: SessionFailure;
+}
+/** Retries ran out and the credential reached expiry; the client failed closed. */
+ | {
+    readonly outcome: 'expired';
+    readonly failure: SessionFailure;
+};
+/** The outcome discriminants a scheduled refresh can report. */
+export type SessionRefreshOutcome = ScheduledRefreshReport['outcome'];
+export interface MintHandle {
+    readonly mintId: number;
+    readonly response: Promise<SessionResult>;
+}
+/**
+ * Cross-tab refresh coordination. One tab per (uid, workspace) key holds the
+ * lease and performs the proactive refresh; the others adopt its published
+ * credential and mint for themselves only when the leader goes quiet past
+ * their jittered fallback. Real hosts wrap Web Locks + BroadcastChannel
+ * (`createWebCrossTabRefreshPort` from `@comfyorg/account-core/web`); tests pass
+ * fakes.
+ */
+export interface CrossTabRefreshPort {
+    /**
+     * Queue for the key's lease. `onAcquired` fires if and when this tab
+     * becomes leader; the returned function abandons the request or releases
+     * held leadership.
+     */
+    requestLeadership: (key: string, onAcquired: () => void) => () => void;
+    publishCredential: (key: string, credential: AccountCredential) => void;
+    /** Messages cross a serialization boundary; the client validates them. */
+    onCredential: (key: string, callback: (message: unknown) => void) => () => void;
+}
+/**
+ * Opt-in proactive refresh, mirroring the cloud store's scheduled-refresh
+ * semantics (its buffer, retry base, and retry cap are the defaults): arm at
+ * expiry minus the buffer, retry transient failures with doubling backoff,
+ * stop on sign-out, detach, or a permanent failure. Hosts whose consumers
+ * read the token synchronously need this; valid-on-read hosts do not.
+ */
+export interface RefreshSchedulerOptions {
+    readonly bufferMs?: number;
+    readonly retryBaseMs?: number;
+    readonly maxRetries?: number;
+    /**
+     * Cross-tab coordination (opt-in): the leader tab refreshes and publishes;
+     * followers adopt the published credential and fall back to their own mint
+     * only after a bounded random hold past the refresh point.
+     */
+    readonly crossTab?: {
+        readonly port: CrossTabRefreshPort;
+        /** Upper bound for the follower's random hold. Default 15s. */
+        readonly followerJitterMs?: number;
+        /**
+         * Fires when this tab commits a sibling's credential. Adoption is a
+         * rotation the tab did not perform itself, so a host that reacts to
+         * rotations (cookie refresh, extension hooks) needs this signal.
+         */
+        readonly onCredentialAdopted?: (credential: AccountCredential) => void;
+    };
+    /**
+     * Called with the result of every SCHEDULED refresh attempt (never a
+     * login or caller-initiated mint), so a host can feed its refresh
+     * telemetry without owning the scheduler. A permanent failure and an
+     * expiry carry the failure the client committed, so the host never has
+     * to read it back out of the snapshot.
+     */
+    readonly onScheduledOutcome?: (report: ScheduledRefreshReport) => void;
+}
+export {};

package/dist/core/sessionContracts.js

@@ -0,0 +1,9 @@
+const PERMANENT_ERROR_CODES = new Set([
+    'ACCESS_DENIED',
+    'WORKSPACE_NOT_FOUND',
+    'INVALID_FIREBASE_TOKEN',
+    'NOT_AUTHENTICATED'
+]);
+export function isPermanentSessionError(code) {
+    return PERMANENT_ERROR_CODES.has(code);
+}

package/dist/core/sessionState.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The session's authoritative state and its only commit boundary. Effects
+ * come back in the order the client must run them: persist before arming
+ * the scheduler, publish last, so a host reacting to a snapshot never reads
+ * state a later step would still change.
+ */
+import type { AccountCredential, AccountUser, SessionFailure } from './sessionContracts.js';
+export interface SessionState<TUser extends AccountUser = AccountUser> {
+    readonly user: TUser | null;
+    readonly identitySettled: boolean;
+    readonly credential: AccountCredential | undefined;
+    readonly credentialTarget: string | undefined;
+    readonly failure: SessionFailure | undefined;
+    /**
+     * The result the winning mint published, so a caller joining that same mint
+     * returns it instead of running the commit/publication path a second time.
+     */
+    readonly committedMint: {
+        readonly mintId: number;
+        readonly session: AccountCredential;
+    } | undefined;
+    /**
+     * Bumped on every identity event so a mint can tell "the listener has not
+     * settled yet" (the legitimate popup path) from "an identity event
+     * happened while I was in flight" (must invalidate).
+     */
+    readonly identityEpoch: number;
+    readonly invalidationEpoch: number;
+    /**
+     * Monotonic id taken by every started mint; a commit is allowed only for
+     * the newest one. Target-agnostic on purpose — a slower mint for the old
+     * workspace resolving after a switch must never revert it. Ports the
+     * cloud store's unifiedRefreshRequestId guard.
+     */
+    readonly mintSequence: number;
+}
+export declare function initialSessionState<TUser extends AccountUser = AccountUser>(): SessionState<TUser>;
+export type SessionEvent<TUser extends AccountUser = AccountUser> = {
+    readonly type: 'identity-changed';
+    readonly user: TUser | null;
+} | {
+    readonly type: 'identity-detached';
+} | {
+    readonly type: 'invalidated';
+} | {
+    readonly type: 'mint-started';
+} | {
+    readonly type: 'mint-committed';
+    readonly origin: 'caller';
+    readonly session: AccountCredential;
+    readonly target: string | undefined;
+    readonly mintId: number;
+} | {
+    readonly type: 'mint-committed';
+    readonly origin: 'scheduler';
+    readonly session: AccountCredential;
+    readonly mintId: number;
+} | {
+    readonly type: 'mint-rejected';
+    readonly origin: 'caller';
+    readonly failure: SessionFailure;
+    readonly preserveCredentialOnTransientFailure: boolean;
+} | {
+    readonly type: 'mint-rejected';
+    readonly origin: 'scheduler';
+    readonly failure: SessionFailure;
+} | {
+    readonly type: 'credential-adopted';
+    readonly session: AccountCredential;
+} | {
+    readonly type: 'credential-expired';
+    readonly expiring: AccountCredential;
+};
+export type SessionEffect = {
+    readonly type: 'persist';
+    readonly session: AccountCredential;
+    readonly target: string | undefined;
+} | {
+    readonly type: 'armScheduler';
+    readonly session: AccountCredential;
+} | {
+    readonly type: 'clearStorage';
+} | {
+    readonly type: 'stopScheduler';
+} | {
+    readonly type: 'abandonInFlight';
+} | {
+    readonly type: 'publish';
+};
+export interface SessionTransition<TUser extends AccountUser = AccountUser> {
+    readonly state: SessionState<TUser>;
+    readonly effects: readonly SessionEffect[];
+}
+export declare function transition<TUser extends AccountUser>(state: SessionState<TUser>, event: SessionEvent<TUser>): SessionTransition<TUser>;
+export interface MintAttempt {
+    readonly mintId: number;
+    /** Awaited another owner's in-flight mint instead of starting its own. */
+    readonly joined: boolean;
+    readonly explicitUser: boolean;
+    readonly userUid: string;
+    readonly requestedTarget: string | undefined;
+    readonly startEpoch: number;
+    readonly startInvalidation: number;
+    readonly startedSignedOut: boolean;
+}
+export type MintVerdict = {
+    readonly verdict: 'commit';
+} | {
+    readonly verdict: 'reuse';
+    readonly session: AccountCredential;
+} | {
+    readonly verdict: 'superseded';
+};
+export declare function arbitrateMint<TUser extends AccountUser>(state: SessionState<TUser>, attempt: MintAttempt): MintVerdict;
+export declare function scheduledMintHolds<TUser extends AccountUser>(state: SessionState<TUser>, guards: {
+    readonly epoch: number;
+    readonly invalidation: number;
+}, userUid: string, mintId: number): boolean;