@comfyorg/account-core 1.0.0-alpha.0

package/dist/core/credentialCache.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { CredentialResponseSchema } from './exchange.js';
+/** The generated contract for POST /api/auth/token, never a local copy of it. */
+const CachedCredentialSchema = CredentialResponseSchema.omit({
+    expires_at: true
+}).extend({
+    // Storage and broadcast are untrusted boundaries: an empty token can never
+    // authorize and a non-finite expiry can never lapse, so neither is a session.
+    token: z.string().min(1),
+    expiresAt: z.number().finite(),
+    uid: z.string(),
+    /** The workspace target the credential was minted for; absent = personal. */
+    target: z.string().optional()
+});
+function toCredential(data) {
+    return {
+        token: data.token,
+        expiresAt: data.expiresAt,
+        uid: data.uid,
+        workspace: data.workspace,
+        role: data.role,
+        permissions: data.permissions
+    };
+}
+export function encodeCached(session, target) {
+    return JSON.stringify({ ...session, target });
+}
+export function decodeCached(raw, uid) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const result = CachedCredentialSchema.safeParse(parsed);
+    if (!result.success || result.data.uid !== uid)
+        return undefined;
+    return { credential: toCredential(result.data), target: result.data.target };
+}
+export function decodeAdopted(message) {
+    const parsed = CachedCredentialSchema.safeParse(message);
+    return parsed.success ? toCredential(parsed.data) : undefined;
+}
+export const DEFAULT_FRESH_MARGIN_MS = 5 * 60 * 1000;
+export function isCredentialFresh(session, now, freshMarginMs = DEFAULT_FRESH_MARGIN_MS) {
+    return session.expiresAt - now > freshMarginMs;
+}
+/**
+ * The live credential is authoritative; storage is recovery state, not a
+ * competing source. Candidates are consulted in the order given (memory
+ * first, then storage) for this exact uid and target, and the first fresh one
+ * wins — expiry must not override this (a rejected token can outlive its
+ * shorter-lived replacement), and a target-less read must never adopt a team
+ * session.
+ */
+export function selectFreshCredential(candidates, uid, target, now, freshMarginMs) {
+    for (const supply of candidates) {
+        const candidate = supply();
+        if (candidate?.credential?.uid === uid &&
+            candidate.target === target &&
+            isCredentialFresh(candidate.credential, now, freshMarginMs)) {
+            return candidate.credential;
+        }
+    }
+    return undefined;
+}
+export function createCredentialCache(storage) {
+    return {
+        read(uid) {
+            let raw;
+            try {
+                raw = storage.read();
+            }
+            catch {
+                return undefined;
+            }
+            return raw === null ? undefined : decodeCached(raw, uid);
+        },
+        write(session, target) {
+            try {
+                storage.write(encodeCached(session, target));
+            }
+            catch {
+                void 0;
+            }
+        },
+        clear() {
+            try {
+                storage.clear();
+            }
+            catch {
+                void 0;
+            }
+        }
+    };
+}

package/dist/core/customerRecovery.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Self-healing for accounts whose customer record was never provisioned.
+ *
+ * Customer creation runs after the Firebase session is established during
+ * sign-in/sign-up, so an interruption (navigation, closed tab, network
+ * failure) can leave a permanently signed-in user without a customer
+ * record. Sessions restored from persisted credentials never re-run the
+ * sign-in flow, so every /customers/* request fails with 409 and nothing
+ * ever retries the creation. The cloud app's rule, shared so every host
+ * heals the same way.
+ */
+/**
+ * The auth middleware rejects requests for accounts without a customer
+ * record using this exact message. Business-level 409s from /customers/*
+ * endpoints (e.g. conflicting subscription state) must NOT trigger
+ * provisioning or a blind retry of a payment request.
+ */
+export declare const MISSING_CUSTOMER_MESSAGE = "Failed to find customer";
+export declare function isMissingCustomerResponse(response: Response): Promise<boolean>;
+export declare function isCustomerEndpoint(input: string, base?: string): boolean;
+export interface CustomerRecoveryDeps {
+    /** The request itself; run again, once, after a successful recovery. */
+    readonly request: () => Promise<Response>;
+    /** Provisions the customer; the host deduplicates concurrent callers. */
+    readonly recoverMissingCustomer: () => Promise<void>;
+    /**
+     * False once the signed-in identity is no longer the one that started the
+     * request: recovery and retry are then skipped and the 409 returned.
+     */
+    readonly identityUnchanged?: () => boolean;
+}
+/**
+ * The recovery above, applied only to /customers/* endpoints: a 409 from
+ * anywhere else is never a missing customer.
+ */
+export declare function fetchWithCustomerRecovery(input: string, deps: CustomerRecoveryDeps & {
+    /** Resolves a relative `input`; a browser host passes its page href. */
+    readonly base?: string;
+}): Promise<Response>;

package/dist/core/customerRecovery.js

@@ -0,0 +1,79 @@
+/**
+ * Self-healing for accounts whose customer record was never provisioned.
+ *
+ * Customer creation runs after the Firebase session is established during
+ * sign-in/sign-up, so an interruption (navigation, closed tab, network
+ * failure) can leave a permanently signed-in user without a customer
+ * record. Sessions restored from persisted credentials never re-run the
+ * sign-in flow, so every /customers/* request fails with 409 and nothing
+ * ever retries the creation. The cloud app's rule, shared so every host
+ * heals the same way.
+ */
+/**
+ * The auth middleware rejects requests for accounts without a customer
+ * record using this exact message. Business-level 409s from /customers/*
+ * endpoints (e.g. conflicting subscription state) must NOT trigger
+ * provisioning or a blind retry of a payment request.
+ */
+export const MISSING_CUSTOMER_MESSAGE = 'Failed to find customer';
+export async function isMissingCustomerResponse(response) {
+    if (response.status !== 409)
+        return false;
+    try {
+        const body = await response.clone().json();
+        return (typeof body === 'object' &&
+            body !== null &&
+            'message' in body &&
+            body.message === MISSING_CUSTOMER_MESSAGE);
+    }
+    catch {
+        return false;
+    }
+}
+export function isCustomerEndpoint(input, base) {
+    try {
+        const { pathname } = new URL(input, base);
+        return pathname === '/customers' || pathname.startsWith('/customers/');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * On a missing-customer 409 this provisions the customer record and retries
+ * the original request a single time. If recovery fails, the original 409
+ * response is returned so callers surface their normal error handling.
+ */
+async function retryAfterCustomerRecovery(response, deps) {
+    const { request, recoverMissingCustomer, identityUnchanged = () => true } = deps;
+    if (!(await isMissingCustomerResponse(response)) || !identityUnchanged()) {
+        return response;
+    }
+    try {
+        await recoverMissingCustomer();
+    }
+    catch (error) {
+        console.warn('Customer provisioning during 409 recovery failed; returning original response', error);
+        return response;
+    }
+    if (!identityUnchanged()) {
+        return response;
+    }
+    try {
+        return await request();
+    }
+    catch (error) {
+        console.warn('Retry after customer provisioning failed; returning original 409 response', error);
+        return response;
+    }
+}
+/**
+ * The recovery above, applied only to /customers/* endpoints: a 409 from
+ * anywhere else is never a missing customer.
+ */
+export async function fetchWithCustomerRecovery(input, deps) {
+    const response = await deps.request();
+    if (!isCustomerEndpoint(input, deps.base))
+        return response;
+    return retryAfterCustomerRecovery(response, deps);
+}

package/dist/core/exchange.d.ts

@@ -0,0 +1,50 @@
+import type { AccountUser, SessionResult } from './sessionContracts.js';
+export declare const CredentialResponseSchema: import("zod").ZodObject<{
+    expires_at: import("zod").ZodString;
+    permissions: import("zod").ZodArray<import("zod").ZodString, "many">;
+    role: import("zod").ZodEnum<["owner", "member"]>;
+    token: import("zod").ZodString;
+    workspace: import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        name: import("zod").ZodString;
+        type: import("zod").ZodEnum<["personal", "team"]>;
+    }, "strip", import("zod").ZodTypeAny, {
+        type: "personal" | "team";
+        id: string;
+        name: string;
+    }, {
+        type: "personal" | "team";
+        id: string;
+        name: string;
+    }>;
+}, "strip", import("zod").ZodTypeAny, {
+    role: "owner" | "member";
+    expires_at: string;
+    token: string;
+    permissions: string[];
+    workspace: {
+        type: "personal" | "team";
+        id: string;
+        name: string;
+    };
+}, {
+    role: "owner" | "member";
+    expires_at: string;
+    token: string;
+    permissions: string[];
+    workspace: {
+        type: "personal" | "team";
+        id: string;
+        name: string;
+    };
+}>;
+export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
+export interface ExchangeRequest {
+    readonly exchangeUrl: string;
+    readonly body: Record<string, unknown>;
+    readonly fetchImpl: typeof fetch;
+    readonly signal: AbortSignal | undefined;
+    readonly timeoutMs: number;
+    readonly now: () => number;
+}
+export declare function exchangeToken(user: AccountUser, request: ExchangeRequest): Promise<SessionResult>;

package/dist/core/exchange.js

@@ -0,0 +1,137 @@
+/**
+ * The pure token exchange: POST the signed-in identity's Firebase token to
+ * the workspace JWT endpoint, parse the generated contract, and return a
+ * usable credential or a coded failure. No state, no storage, no identity
+ * ownership — the caller owns all of that and passes the request body (an
+ * empty body resolves the personal workspace; `{ workspace_id }` targets
+ * one). Cancelable by the caller's signal and bounded by a timeout, which
+ * the production store's timer-scheduled callers did not need.
+ */
+import { zExchangeTokenResponse } from '@comfyorg/ingest-types/zod';
+export const CredentialResponseSchema = zExchangeTokenResponse;
+/** 401/403/404 carry their own codes; everything else is one failure bucket. */
+function codeForResponse(status) {
+    if (status === 401)
+        return 'INVALID_FIREBASE_TOKEN';
+    if (status === 403)
+        return 'ACCESS_DENIED';
+    if (status === 404)
+        return 'WORKSPACE_NOT_FOUND';
+    return 'TOKEN_EXCHANGE_FAILED';
+}
+export function abortable(promise, signal) {
+    if (signal.aborted) {
+        return Promise.reject(new DOMException('Aborted', 'AbortError'));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new DOMException('Aborted', 'AbortError'));
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
+export async function exchangeToken(user, request) {
+    const { exchangeUrl, body, fetchImpl, signal, timeoutMs, now } = request;
+    if (signal?.aborted) {
+        return { status: 'error', code: 'TOKEN_EXCHANGE_FAILED' };
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal?.addEventListener('abort', abort, { once: true });
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        let idToken;
+        try {
+            idToken = await abortable(user.getIdToken(), controller.signal);
+        }
+        catch (error) {
+            // A missing identity token is NOT_AUTHENTICATED; an identity failure
+            // carrying that code keeps it, anything else (including our own abort)
+            // stays in the transient bucket.
+            const coded = !controller.signal.aborted &&
+                typeof error === 'object' &&
+                error !== null &&
+                'code' in error &&
+                error.code === 'NOT_AUTHENTICATED';
+            return {
+                status: 'error',
+                code: coded ? 'NOT_AUTHENTICATED' : 'TOKEN_EXCHANGE_FAILED'
+            };
+        }
+        let response;
+        try {
+            response = await fetchImpl(exchangeUrl, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${idToken}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal
+            });
+        }
+        catch {
+            return { status: 'error', code: 'TOKEN_EXCHANGE_FAILED' };
+        }
+        if (!response.ok) {
+            return {
+                status: 'error',
+                code: codeForResponse(response.status),
+                httpStatus: response.status
+            };
+        }
+        let rawBody;
+        try {
+            // The timeout stays armed through the body read: headers arriving does
+            // not bound the body, and a stalled body must abort like a stalled connect.
+            rawBody = await abortable(response.json(), controller.signal);
+        }
+        catch {
+            return {
+                status: 'error',
+                code: 'TOKEN_EXCHANGE_FAILED',
+                httpStatus: response.status
+            };
+        }
+        const parsed = CredentialResponseSchema.safeParse(rawBody);
+        if (!parsed.success) {
+            return {
+                status: 'error',
+                code: 'TOKEN_EXCHANGE_FAILED',
+                httpStatus: response.status
+            };
+        }
+        // Date.parse can yield NaN on a schema-valid string, so the expiry is
+        // checked after the schema. A token dead on arrival can never authorize
+        // anything; a short-but-future one is left to the valid-on-read path; an
+        // empty token is never a session.
+        const expiresAt = Date.parse(parsed.data.expires_at);
+        if (Number.isNaN(expiresAt) ||
+            parsed.data.token === '' ||
+            expiresAt <= now()) {
+            return {
+                status: 'error',
+                code: 'TOKEN_EXCHANGE_FAILED',
+                httpStatus: response.status
+            };
+        }
+        const session = {
+            token: parsed.data.token,
+            expiresAt,
+            uid: user.uid,
+            workspace: parsed.data.workspace,
+            role: parsed.data.role,
+            permissions: parsed.data.permissions
+        };
+        return { status: 'ok', session };
+    }
+    finally {
+        clearTimeout(timeout);
+        signal?.removeEventListener('abort', abort);
+    }
+}

package/dist/core/identity.d.ts

@@ -0,0 +1,21 @@
+import type { AccountUser } from './sessionContracts.js';
+/**
+ * The identity boundary. An internal port, not a host adapter: real hosts
+ * get their implementation from `@comfyorg/account-core/firebase`; tests brand a
+ * fake through `@comfyorg/account-core/testing`. `attachIdentity` accepts only
+ * the branded form.
+ */
+export interface IdentityPort<TUser extends AccountUser = AccountUser> {
+    onUserChanged: (callback: (user: TUser | null) => void) => () => void;
+}
+/**
+ * Only the package's own identity entry (and the `./testing` seam) can mint
+ * an identity the session client accepts. A host cannot hand in its own
+ * provider: the symbol lives in a module the exports map never exposes.
+ */
+export declare const identityBrand: unique symbol;
+export interface AccountIdentity<TUser extends AccountUser = AccountUser> extends IdentityPort<TUser> {
+    readonly [identityBrand]: true;
+}
+export declare function brandIdentity<TUser extends AccountUser>(port: IdentityPort<TUser>): AccountIdentity<TUser>;
+export declare function isAccountIdentity(value: unknown): value is AccountIdentity;

package/dist/core/identity.js

@@ -0,0 +1,16 @@
+/**
+ * Only the package's own identity entry (and the `./testing` seam) can mint
+ * an identity the session client accepts. A host cannot hand in its own
+ * provider: the symbol lives in a module the exports map never exposes.
+ */
+export const identityBrand = Symbol('@comfyorg/account-core identity');
+export function brandIdentity(port) {
+    return { ...port, [identityBrand]: true };
+}
+export function isAccountIdentity(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (candidate[identityBrand] === true &&
+        typeof candidate.onUserChanged === 'function');
+}

package/dist/core/mintCoordinator.d.ts

@@ -0,0 +1,18 @@
+import type { MintHandle, SessionResult } from './sessionContracts.js';
+export type MintDispatch = MintHandle & {
+    readonly joined: boolean;
+};
+export interface InFlightMint {
+    readonly promise: Promise<SessionResult>;
+    readonly uid: string;
+    readonly target: string | undefined;
+    readonly forced: boolean;
+    readonly mintId: number;
+}
+export declare function canJoin(inFlight: InFlightMint | undefined, uid: string, target: string | undefined, forced: boolean): inFlight is InFlightMint;
+interface MintCoordinator {
+    dispatch: (uid: string, target: string | undefined, forced: boolean, start: () => MintHandle) => MintDispatch;
+    abandon: () => void;
+}
+export declare function createMintCoordinator(): MintCoordinator;
+export {};

package/dist/core/mintCoordinator.js

@@ -0,0 +1,31 @@
+export function canJoin(inFlight, uid, target, forced) {
+    return (inFlight !== undefined &&
+        inFlight.uid === uid &&
+        inFlight.target === target &&
+        (!forced || inFlight.forced));
+}
+export function createMintCoordinator() {
+    let inFlight;
+    return {
+        dispatch(uid, target, forced, start) {
+            if (canJoin(inFlight, uid, target, forced)) {
+                return {
+                    mintId: inFlight.mintId,
+                    response: inFlight.promise,
+                    joined: true
+                };
+            }
+            const { mintId, response } = start();
+            const running = response.finally(() => {
+                if (inFlight?.promise !== running)
+                    return;
+                inFlight = undefined;
+            });
+            inFlight = { promise: running, uid, target, forced, mintId };
+            return { mintId, response: running, joined: false };
+        },
+        abandon() {
+            inFlight = undefined;
+        }
+    };
+}

package/dist/core/refreshScheduler.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The proactive-refresh owner: an optional piece the session client hands
+ * its lifecycle to when a host asks for scheduled refresh. It owns its own
+ * timers, retry count, the expiry fail-close, and (when a cross-tab port is
+ * given) the lease, leadership and sibling adoption. It never holds session
+ * state: it reads the client's live credential through the host and commits
+ * a refreshed, failed, expired or adopted result back through the host, so
+ * the client stays the single owner of `credential`/`failure`.
+ *
+ * Extracted from createSessionClient so the mint/commit core can be reasoned
+ * about without the scheduling and cross-tab machinery, and so a client with
+ * no `refreshScheduler` option carries none of it.
+ */
+import type { AccountCredential, AccountUser, MintHandle, RefreshSchedulerOptions, SessionFailure } from './sessionContracts.js';
+export declare const DEFAULT_BUFFER_MS: number;
+/** Guards captured before a scheduled mint, re-checked before its commit. */
+interface RefreshGuards {
+    readonly epoch: number;
+    readonly invalidation: number;
+}
+export interface RefreshHost {
+    now: () => number;
+    getCurrentUser: () => AccountUser | null;
+    getCredential: () => AccountCredential | undefined;
+    captureGuards: () => RefreshGuards;
+    /** A scheduled mint's result may commit only if nothing superseded it. */
+    guardsHold: (guards: RefreshGuards, user: AccountUser, mintId: number) => boolean;
+    /** A forced mint for the target that produced the live credential. */
+    mint: (user: AccountUser) => MintHandle;
+    /** Returns a failure when the refreshed session was rejected (wrong scope). */
+    commitRefreshed: (session: AccountCredential, mintId: number) => SessionFailure | undefined;
+    commitPermanentFailure: (failure: SessionFailure) => void;
+    /** Clears iff the live credential is still `expiring`; returns what it committed. */
+    commitExpired: (expiring: AccountCredential) => SessionFailure | undefined;
+    /** Parse a cross-tab message into a credential, or undefined if malformed. */
+    parseAdopted: (message: unknown) => AccountCredential | undefined;
+    /** Commit a sibling's credential: supersede any in-flight mint, persist, publish. */
+    commitAdopted: (session: AccountCredential) => void;
+}
+export interface RefreshScheduler {
+    /** A fresh credential committed: cancel the fail-close, arm the next refresh, tell siblings. */
+    armAfterCommit: (session: AccountCredential, now: number) => void;
+    stop: () => void;
+}
+export declare function createRefreshScheduler(options: RefreshSchedulerOptions, host: RefreshHost): RefreshScheduler;
+export {};