@nominalso/vibe-auth 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,338 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { ReactNode } from 'react';
+
+/**
+ * Timeout knobs for the silent-SSO flow. All optional — sane defaults (below)
+ * are the same values the silent-supabase-oidc-login skill shipped after its
+ * production incidents, so only override these if you've measured a reason to.
+ */
+interface VibeAuthTimeouts {
+    /**
+     * Bounds the hidden-iframe wait for a `prompt=none` result. Does NOT bound
+     * the whole silent attempt — see `silentFlowCapMs`.
+     * @default 10_000
+     */
+    silentIframeMs?: number;
+    /**
+     * Hard cap on ONE WHOLE silent attempt (the `signInWithOAuth` fetch, the
+     * hidden-iframe wait, and the code exchange). Without this, a slow attempt
+     * could hold the cross-document lock past every waiter's patience.
+     * @default 15_000
+     */
+    silentFlowCapMs?: number;
+    /**
+     * How long a document queues for the cross-document Web Lock before giving
+     * up. Sized off `silentFlowCapMs` by default (two full holder turns plus
+     * margin) — pass this explicitly only if you also override `silentFlowCapMs`
+     * and want the derived relationship preserved.
+     * @default 2 * silentFlowCapMs + 5_000
+     */
+    lockWaitMs?: number;
+    /**
+     * Bounds the wait for `detectSessionInUrl` to finish a top-level OAuth
+     * return before the gate falls through to the sign-in screen.
+     * @default 15_000
+     */
+    oauthCompletionMs?: number;
+    /** Bounds the interactive popup flow (user-facing — generous on purpose). @default 120_000 */
+    popupMs?: number;
+    /** Bounds the Lovable-preview "prime the popup" navigation. @default 8_000 */
+    previewPrimingMs?: number;
+    /** Poll interval while waiting for the preview-priming navigation to settle. @default 250 */
+    previewPrimingPollMs?: number;
+}
+interface ResolvedVibeAuthTimeouts {
+    silentIframeMs: number;
+    silentFlowCapMs: number;
+    lockWaitMs: number;
+    oauthCompletionMs: number;
+    popupMs: number;
+    previewPrimingMs: number;
+    previewPrimingPollMs: number;
+}
+/** Config passed to `createVibeAuth`. */
+interface VibeAuthConfig {
+    /**
+     * The app's own Supabase client — injected, never created by this package.
+     * MUST have `auth.flowType: 'pkce'` (checked at init; see `assertPkce`). Own
+     * this client for the same reason a generated app owns its `client.ts`: it
+     * carries app-specific types, storage adapters, and Lovable Cloud wiring.
+     */
+    supabase: SupabaseClient;
+    /**
+     * The IdP-federation provider name for `signInWithOAuth`, e.g.
+     * `'custom:supabase-fedapp'`. Never guess this — it comes from the app's own
+     * Supabase Auth → Providers configuration.
+     */
+    provider: string;
+    /**
+     * Path of the same-origin OAuth callback route. Must match the app's actual
+     * route AND the `redirect_to` the app's Supabase project allowlists.
+     * @default '/silent-callback'
+     */
+    callbackPath?: string;
+    timeouts?: VibeAuthTimeouts;
+    /**
+     * Prefix for the cross-document Web Lock name and the identity-switch
+     * bound-user localStorage key. Only change this if multiple vibe apps with
+     * DIFFERENT Supabase projects share one origin (rare) and you need their
+     * locks/markers to not collide — same-project apps on different origins
+     * never collide regardless, since Web Locks and localStorage are
+     * origin-scoped.
+     * @default 'nominal'
+     */
+    storageKeyPrefix?: string;
+}
+interface ResolvedVibeAuthConfig {
+    supabase: SupabaseClient;
+    provider: string;
+    callbackPath: string;
+    timeouts: ResolvedVibeAuthTimeouts;
+    lockName: string;
+    boundUserKey: string;
+}
+
+/**
+ * Snapshot the callback URL and return a `SilentCallback` component closed
+ * over that snapshot.
+ *
+ * MUST be called synchronously, at the top of the app's own auth-setup
+ * module (i.e. as part of `createVibeAuth`, itself called at module scope —
+ * never lazily or inside a hook). Module bodies run synchronously at import;
+ * supabase-js's `detectSessionInUrl` strips the `#access_token` hash
+ * asynchronously shortly after a client boots ANYWHERE in the page. Reading
+ * `window.location` later (inside a React effect, or after some other
+ * module's async work) races that strip — it wins on a fast machine with a
+ * warm module cache and loses on a cold one, which presents as "works on my
+ * laptop, fails on my colleague's".
+ *
+ * The `posted` once-latch is scoped to THIS call, not a bare module `let` —
+ * unlike the skill's single-instance-per-app assumption, a factory-based
+ * package must not leak state across multiple `createVibeAuth` calls (e.g.
+ * in tests).
+ */
+declare function createCallbackHandler(): {
+    SilentCallback: () => null;
+};
+
+/**
+ * Who the Nominal host says this document is acting as. Tenant is part of
+ * identity, not metadata: the same user in another tenant is a different
+ * principal and must re-bind before the gate opens.
+ *
+ * Its own module because `silentAuth`, `hostAuth`, and `AuthGate` all speak it
+ * — putting it in any one of them would make the other two import a peer.
+ */
+type HostPrincipal = {
+    userId: string;
+    tenant: string;
+};
+
+declare enum AuthResultKind {
+    Code = "code"
+}
+type AuthResult = {
+    kind: AuthResultKind.Code;
+    code: string;
+};
+interface SilentAuth {
+    hasValidSession(): Promise<boolean>;
+    trySilentSignIn(): Promise<boolean>;
+    ensureSession(): Promise<boolean>;
+    rebindSession(principal: HostPrincipal): Promise<boolean>;
+    /**
+     * True when the bound-user marker is this host principal. No TTL — used by
+     * `AuthGate` on load so a same-principal refresh can open without running
+     * silent SSO. Live switch waiters still use a young-marker check inside
+     * `rebindSession`.
+     */
+    isBoundTo(principal: HostPrincipal): boolean;
+    clearBoundUser(): void;
+    /** @internal exposed for interactive.ts, which shares completeWithResult/parseCallbackMessage's private helpers */
+    completeWithResult(result: AuthResult): Promise<boolean>;
+}
+
+declare enum SignInKind {
+    Authenticated = "authenticated",
+    Redirecting = "redirecting",
+    Failed = "failed"
+}
+declare enum SignInFailureReason {
+    /** window.open returned null → the "allow popups" hint */
+    PopupBlocked = "popup-blocked",
+    /** signInWithOAuth errored (or returned no URL) */
+    OauthError = "oauth-error",
+    /** popup closed / timed out before a result arrived */
+    PopupClosed = "popup-closed",
+    /** a code arrived but redeeming it produced no session */
+    ExchangeFailed = "exchange-failed",
+    /** no window: SSR or a non-browser context */
+    Unsupported = "unsupported",
+    /** signInInteractive threw; the error is logged to the console */
+    Unexpected = "unexpected"
+}
+/** A session exists; the gate can open. */
+interface SignInAuthenticated {
+    kind: SignInKind.Authenticated;
+}
+/**
+ * Top-level (non-iframe) flow: this page is navigating to the IdP. Not a
+ * failure — keep any "opening sign-in…" state; the document is about to unload.
+ */
+interface SignInRedirecting {
+    kind: SignInKind.Redirecting;
+}
+/** The attempt is over; `reason` picks the user-facing message. */
+interface SignInFailed {
+    kind: SignInKind.Failed;
+    reason: SignInFailureReason;
+}
+type SignInResult = SignInAuthenticated | SignInRedirecting | SignInFailed;
+
+interface InteractiveAuth {
+    signInInteractive(): Promise<SignInResult>;
+}
+
+/** The subset of `VibeAppBridge` this module needs — structural, not a hard dependency. */
+interface AuthBridgeLike {
+    onAuthChange(cb: (auth: {
+        authenticated: boolean;
+        userId?: string;
+        tenant?: string;
+    }) => void): () => void;
+}
+interface HostAuth {
+    isHostWired(): boolean;
+    waitForSeededPrincipal(timeoutMs: number): Promise<HostPrincipal | null>;
+    onSeededPrincipal(cb: (principal: HostPrincipal) => void): () => void;
+    /**
+     * Wire BEFORE `bridge.connect()`, at module scope so `AuthGate` sees
+     * `isHostWired()` on first resolve.
+     */
+    wireHostAuth(bridge: AuthBridgeLike): () => void;
+    /**
+     * Seed `{userId, tenant}` from `connect()`, from a **parent** of `AuthGate`.
+     */
+    seedLastUserId(userId: string, tenant: string): void;
+    /** Current seeded host `{userId, tenant}`, if any. */
+    getPrincipal(): HostPrincipal | undefined;
+}
+
+interface AuthGateProps {
+    children: ReactNode;
+    /** Override the default sign-in screen (branding). Defaults to `DefaultSignInScreen`. */
+    signInScreen?: ReactNode;
+    /** Override the default full-screen loader. Defaults to a bare "Signing you in…" spinner-less div. */
+    loader?: ReactNode;
+}
+interface AuthGateBundle {
+    AuthGate: (props: AuthGateProps) => ReactNode;
+    DefaultSignInScreen: () => ReactNode;
+}
+/**
+ * MUST be called synchronously, at the top of the app's own auth-setup
+ * module (as part of `createVibeAuth`) — same timing constraint as
+ * `createCallbackHandler`: `RETURNING_FROM_OAUTH`/`IS_CALLBACK_PATH` must be
+ * captured before any effect runs, and before supabase-js's
+ * `detectSessionInUrl` can strip the URL.
+ */
+declare function createAuthGate(config: ResolvedVibeAuthConfig, silentAuth: SilentAuth, interactiveAuth: InteractiveAuth, hostAuth?: HostAuth): AuthGateBundle;
+
+interface VibeAuth {
+    /** True when a Supabase session already exists locally. */
+    hasValidSession(): Promise<boolean>;
+    /**
+     * Fresh sign-in as a NEW host identity, coordinated across documents. Call
+     * this from your host-auth handler on an identity switch — NOT `ensureSession`.
+     * Prefer `wireHostAuth`, which already calls this correctly.
+     */
+    rebindSession(principal: HostPrincipal): Promise<boolean>;
+    /**
+     * Runs the `prompt=none` silent flow once, deduped within this document.
+     * Most apps want `ensureSession` (the gate calls it); this is exposed for
+     * advanced cases like a post-handshake retry.
+     */
+    trySilentSignIn(): Promise<boolean>;
+    /** Gets a session, coordinated across every document and tab on this origin. */
+    ensureSession(): Promise<boolean>;
+    /**
+     * The interactive (popup / top-level redirect) fallback. `AuthGate`'s
+     * default sign-in screen calls this. Note `redirecting` is not a failure:
+     * the page is navigating to the IdP and is about to unload.
+     */
+    signInInteractive(): Promise<SignInResult>;
+    /** Remove the identity-switch bound-user marker. Call on host logout, next to signOut(). */
+    clearBoundUser(): void;
+    /** Wrap the ENTIRE app: `<AuthGate><App /></AuthGate>`. The app never mounts until authenticated. */
+    AuthGate: ReturnType<typeof createAuthGate>['AuthGate'];
+    /** The default sign-in screen `AuthGate` renders unless you pass `signInScreen`. */
+    DefaultSignInScreen: ReturnType<typeof createAuthGate>['DefaultSignInScreen'];
+    /** Mount this, and ONLY this, at `callbackPath` — ungated, outside `AuthGate`. */
+    SilentCallback: ReturnType<typeof createCallbackHandler>['SilentCallback'];
+    /**
+     * Wire the host's auth signal to this Supabase client. Call at module
+     * scope, BEFORE `bridge.connect()`, so `AuthGate` will not open on a
+     * leftover Supabase session before it knows the current Nominal user.
+     * Returns the unsubscribe function.
+     */
+    wireHostAuth(bridge: AuthBridgeLike): () => void;
+    /**
+     * Seed `{userId, tenant}` from `connect()`. Call from a **parent** of
+     * `AuthGate` after `connect()` resolves. The gate waits for this, then
+     * opens without rebind when the bound-user marker already matches.
+     */
+    seedLastUserId(userId: string, tenant: string): void;
+    /** The postMessage type relayed by `SilentCallback` — do not change if migrating an existing app. */
+    RESULT_MESSAGE_TYPE: string;
+    /** The resolved callback path (default `/silent-callback`). */
+    callbackPath: string;
+}
+/**
+ * Creates a configured, self-contained silent-SSO auth instance for a Nominal
+ * Vibe App — the packaged, fixed replacement for a hand-copied
+ * `silentAuth.ts`/`AuthGate.tsx` generated from the silent-supabase-oidc-login
+ * skill.
+ *
+ * MUST be called synchronously, at the top of the app's own auth-setup
+ * module (e.g. `src/lib/auth.ts`), and that module must be imported eagerly
+ * (never lazily) — `AuthGate`/`SilentCallback` capture the callback URL at
+ * this call, before any React effect or async work can let supabase-js's
+ * `detectSessionInUrl` strip it first.
+ *
+ * @example
+ * ```ts
+ * // src/lib/auth.ts
+ * import { createVibeAuth } from '@nominalso/vibe-auth'
+ * import { supabase } from './supabaseClient'
+ *
+ * export const auth = createVibeAuth({
+ *   supabase,
+ *   provider: 'custom:supabase-fedapp', // from your Supabase Auth → Providers config
+ * })
+ * ```
+ *
+ * ```tsx
+ * // src/routes/silent-callback.tsx (TanStack Start; ssr: false on this route)
+ * import { auth } from '@/lib/auth'
+ * export default auth.SilentCallback
+ * ```
+ *
+ * ```tsx
+ * // wrap the app root — see AGENTS.md for the SSR-safe recipe
+ * <auth.AuthGate>
+ *   <App />
+ * </auth.AuthGate>
+ * ```
+ *
+ * ```ts
+ * // wire the host bridge before connect()
+ * const unsub = auth.wireHostAuth(bridge)
+ * const ctx = await bridge.connect()
+ * auth.seedLastUserId(ctx.user.id, ctx.tenant)
+ * ```
+ */
+declare function createVibeAuth(userConfig: VibeAuthConfig): VibeAuth;
+
+declare const RESULT_MESSAGE_TYPE = "silent-auth-result";
+
+export { type AuthBridgeLike, type AuthGateProps, type AuthResult, AuthResultKind, type HostPrincipal, RESULT_MESSAGE_TYPE, type ResolvedVibeAuthConfig, type ResolvedVibeAuthTimeouts, type SignInAuthenticated, type SignInFailed, SignInFailureReason, SignInKind, type SignInRedirecting, type SignInResult, type VibeAuth, type VibeAuthConfig, type VibeAuthTimeouts, createVibeAuth };