@comfyorg/account-core 1.0.0-alpha.0 → 1.0.0-alpha.2

package/dist/core/webSessionIdentity.d.ts

@@ -0,0 +1,297 @@
+/**
+ * The session-backed identity source: boots a site from `GET /auth/session`
+ * and follows the server's answer. It keeps no record of past sessions, and
+ * the remembered provider login is an opaque port, so no provider leaks in.
+ */
+import { z } from 'zod';
+import type { CrossTabRefreshPort, WebSession, WebSessionCommandResult, WebSessionResult } from './sessionContracts.js';
+import type { WebSessionOptions } from './webSession.js';
+export interface RememberedLogin {
+    /** The Comfy user id of the login this browser remembers, or null. */
+    currentUserId: () => Promise<string | null>;
+    /** Null when the provider has no usable login; a throw is transient. */
+    getProof: () => Promise<string | null>;
+    signOutLocally: () => Promise<void>;
+}
+export type WebSessionPrincipal = {
+    readonly kind: 'account';
+    readonly rememberedLogin: RememberedLogin;
+} | {
+    readonly kind: 'api_key';
+};
+export type WebSessionBootOutcome = 'signed_in' | 'restored' | 'signed_out' | 'revoked' | 'restore_failed';
+export interface WebSessionBootstrapEvent {
+    readonly outcome: WebSessionBootOutcome;
+    readonly origin: string;
+}
+type SignedOutOutcome = Exclude<WebSessionBootOutcome, 'signed_in' | 'restored'>;
+/** The account this tab holds changed under it, or went away. */
+export type WebSessionAccountChange = {
+    readonly reason: 'user_changed';
+    readonly session: WebSession;
+} | {
+    readonly reason: 'signed_out';
+    readonly outcome: SignedOutOutcome;
+};
+export type WebSessionIdentityState = {
+    readonly phase: 'idle';
+} | {
+    readonly phase: 'api_key';
+} | {
+    readonly phase: 'reading' | 'retry_wait' | 'restoring';
+    readonly failures: number;
+} | {
+    readonly phase: 'signed_in';
+    readonly session: WebSession;
+} | {
+    readonly phase: 'signed_out';
+    readonly outcome: SignedOutOutcome;
+};
+/** Only a sibling's sign-in is news to a tab that has signed out. */
+export type SessionObservedFrom = 'this_tab' | 'sibling_heartbeat' | 'sibling_sign_in' | 'sibling_sign_out';
+export type WebSessionIdentityEvent = {
+    readonly type: 'boot';
+} | {
+    readonly type: 'read_answered' | 'restore_answered';
+    readonly result: WebSessionResult;
+    readonly rememberedUserId: string | null;
+} | {
+    readonly type: 'proof_missing' | 'proof_errored' | 'login_errored';
+} | {
+    readonly type: 'retry_due';
+}
+/** A heartbeat answer, this tab's or one a sibling tab published. */
+ | {
+    readonly type: 'session_observed';
+    readonly from: SessionObservedFrom;
+    readonly result: WebSessionResult;
+    readonly rememberedUserId: string | null;
+} | {
+    readonly type: 'session_created';
+    readonly session: WebSession;
+} | {
+    readonly type: 'sign_out_requested';
+};
+export type WebSessionIdentityEffect = {
+    readonly type: 'read';
+} | {
+    readonly type: 'restore';
+    readonly expectedUserId: string;
+} | {
+    readonly type: 'schedule_retry';
+    readonly failures: number;
+} | {
+    readonly type: 'sign_out_locally';
+} | {
+    readonly type: 'report';
+    readonly outcome: WebSessionBootOutcome;
+} | {
+    readonly type: 'account_changed';
+    readonly change: WebSessionAccountChange;
+} | {
+    readonly type: 'report_signed_out_remotely';
+};
+export interface WebSessionIdentityTransition {
+    readonly state: WebSessionIdentityState;
+    readonly effects: readonly WebSessionIdentityEffect[];
+}
+/** Pure: an event that means nothing in the current phase changes nothing. */
+export declare function transitionWebSessionIdentity(state: WebSessionIdentityState, event: WebSessionIdentityEvent): WebSessionIdentityTransition;
+export type ScheduleRetry = (run: () => void, delayMs: number) => () => void;
+export interface VisibilityPort {
+    isVisible: () => boolean;
+    onChange: (listener: (visible: boolean) => void) => () => void;
+}
+export interface WebSessionHeartbeatOptions {
+    readonly visibility: VisibilityPort;
+    /** Without it every tab reads for itself. */
+    readonly crossTab?: CrossTabRefreshPort<WebSessionSharedMessage>;
+    readonly intervalMs?: number;
+}
+export interface WebSessionIdentityOptions {
+    readonly session: WebSessionOptions;
+    readonly principal: WebSessionPrincipal;
+    /** The site reporting the boot, e.g. `https://www.comfy.org`. */
+    readonly origin: string;
+    readonly onBootstrap?: (event: WebSessionBootstrapEvent) => void;
+    /** Telemetry for `session_signed_out_remotely`. */
+    readonly onSignedOutRemotely?: (event: {
+        readonly origin: string;
+    }) => void;
+    /** The host drops pending actions and user-scoped state here. */
+    readonly onAccountChanged?: (change: WebSessionAccountChange & {
+        readonly epoch: number;
+    }) => void;
+    readonly heartbeat?: WebSessionHeartbeatOptions;
+    readonly schedule?: ScheduleRetry;
+    readonly retryBaseMs?: number;
+    readonly retryMaxMs?: number;
+}
+export interface WebSessionIdentity {
+    getState: () => WebSessionIdentityState;
+    /** Delivers the current state at once, then every change. */
+    subscribe: (listener: (state: WebSessionIdentityState) => void) => () => void;
+    /** Starts the boot and the heartbeat; a no-op unless idle. */
+    boot: () => void;
+    /** Only after an interactive sign-in; a token refresh must never call it. */
+    signedIn: (getProof: () => Promise<string>) => Promise<WebSessionResult>;
+    signOut: () => Promise<WebSessionCommandResult>;
+    /**
+     * Reads the session now, as a heartbeat would, and resolves once the answer
+     * and any restore it starts have settled. Reads nothing unless signed in as
+     * `expectedUserId` (any user when omitted).
+     */
+    refresh: (expectedUserId?: string) => Promise<WebSessionIdentityState>;
+    /** Changes with the account; an answer started under an older epoch is stale. */
+    getEpoch: () => number;
+    /** Cancels timers, ignores answers in flight, and returns to idle. */
+    dispose: () => void;
+}
+/**
+ * Every tab of a site reads the same host-only cookie, so a sibling's answer
+ * is this tab's own session observed elsewhere; that is what makes adopting
+ * it safe. A per-tab session scope would break this assumption.
+ */
+declare const zSharedMessage: z.ZodObject<{
+    from: z.ZodEnum<["heartbeat", "sign_in", "sign_out"]>;
+    result: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
+        status: z.ZodLiteral<"ok">;
+        session: z.ZodObject<{
+            user: z.ZodObject<{
+                id: z.ZodString;
+                email: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+                emailVerified: z.ZodBoolean;
+                signInProvider: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                email: string;
+                id: string;
+                emailVerified: boolean;
+                name?: string | undefined;
+                signInProvider?: string | undefined;
+            }, {
+                email: string;
+                id: string;
+                emailVerified: boolean;
+                name?: string | undefined;
+                signInProvider?: string | undefined;
+            }>;
+            csrfToken: z.ZodString;
+            expiresAt: z.ZodNumber;
+            absoluteExpiresAt: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            user: {
+                email: string;
+                id: string;
+                emailVerified: boolean;
+                name?: string | undefined;
+                signInProvider?: string | undefined;
+            };
+            expiresAt: number;
+            csrfToken: string;
+            absoluteExpiresAt: number;
+        }, {
+            user: {
+                email: string;
+                id: string;
+                emailVerified: boolean;
+                name?: string | undefined;
+                signInProvider?: string | undefined;
+            };
+            expiresAt: number;
+            csrfToken: string;
+            absoluteExpiresAt: number;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        status: "ok";
+        session: {
+            user: {
+                email: string;
+                id: string;
+                emailVerified: boolean;
+                name?: string | undefined;
+                signInProvider?: string | undefined;
+            };
+            expiresAt: number;
+            csrfToken: string;
+            absoluteExpiresAt: number;
+        };
+    }, {
+        status: "ok";
+        session: {
+            user: {
+                email: string;
+                id: string;
+                emailVerified: boolean;
+                name?: string | undefined;
+                signInProvider?: string | undefined;
+            };
+            expiresAt: number;
+            csrfToken: string;
+            absoluteExpiresAt: number;
+        };
+    }>, z.ZodObject<{
+        status: z.ZodLiteral<"error">;
+        code: z.ZodLiteral<"SESSION_REVOKED">;
+        retryable: z.ZodLiteral<false>;
+    }, "strip", z.ZodTypeAny, {
+        code: "SESSION_REVOKED";
+        status: "error";
+        retryable: false;
+    }, {
+        code: "SESSION_REVOKED";
+        status: "error";
+        retryable: false;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    result: {
+        status: "ok";
+        session: {
+            user: {
+                email: string;
+                id: string;
+                emailVerified: boolean;
+                name?: string | undefined;
+                signInProvider?: string | undefined;
+            };
+            expiresAt: number;
+            csrfToken: string;
+            absoluteExpiresAt: number;
+        };
+    } | {
+        code: "SESSION_REVOKED";
+        status: "error";
+        retryable: false;
+    };
+    from: "heartbeat" | "sign_in" | "sign_out";
+}, {
+    result: {
+        status: "ok";
+        session: {
+            user: {
+                email: string;
+                id: string;
+                emailVerified: boolean;
+                name?: string | undefined;
+                signInProvider?: string | undefined;
+            };
+            expiresAt: number;
+            csrfToken: string;
+            absoluteExpiresAt: number;
+        };
+    } | {
+        code: "SESSION_REVOKED";
+        status: "error";
+        retryable: false;
+    };
+    from: "heartbeat" | "sign_in" | "sign_out";
+}>;
+type SharedFrom = z.infer<typeof zSharedMessage>['from'];
+/** What one tab of a site tells its siblings, and why. */
+export interface WebSessionSharedMessage {
+    readonly from: SharedFrom;
+    readonly result: WebSessionResult;
+}
+/** Inert until `boot()`: constructing it sends no request and arms no timer. */
+export declare function createWebSessionIdentity(options: WebSessionIdentityOptions): WebSessionIdentity;
+export {};