@nominalso/vibe-auth 0.2.1 → 0.2.3

package/dist/index.d.cts

@@ -147,6 +147,15 @@ interface SilentAuth {
      * `rebindSession`.
      */
     isBoundTo(principal: HostPrincipal): boolean;
+    /**
+     * Record that the live session belongs to this principal.
+     *
+     * Normally `completeWithResult` does this after redeeming a code. The
+     * top-level redirect flow never routes through that function — the session
+     * arrives via supabase-js's `detectSessionInUrl` — so `AuthGate` stamps it
+     * there instead, and only for a `SIGNED_IN` it observed in that document.
+     */
+    stampBoundMarker(principal: HostPrincipal): void;
     clearBoundUser(): void;
     /** @internal exposed for interactive.ts, which shares completeWithResult/parseCallbackMessage's private helpers */
     completeWithResult(result: AuthResult): Promise<boolean>;
@@ -238,6 +247,97 @@ interface AuthGateBundle {
  */
 declare function createAuthGate(config: ResolvedVibeAuthConfig, silentAuth: SilentAuth, interactiveAuth: InteractiveAuth, hostAuth?: HostAuth): AuthGateBundle;
 
+/**
+ * The contract between this package and `@nominalso/vibe-bridge`, plus the
+ * shape `wireVibeApp` hands back.
+ *
+ * Its own module for the same reason as `principal.ts`: `wireVibeApp` and
+ * `createVibeAuth` both speak these types, and consumers re-export them, so
+ * putting them in the implementation would make every reader import the
+ * implementation to name a type.
+ *
+ * Everything here is **structural**. `@nominalso/vibe-auth` must keep zero
+ * dependency on `@nominalso/vibe-bridge` — they publish separately and version
+ * independently, and a hard dependency would couple their release cycles.
+ */
+/**
+ * The subset of `ContextPayload` this package reads. Apps get their own full
+ * `ContextPayload` back via the `Ctx` type parameter; structural assignability
+ * already allows the extra properties.
+ *
+ * Deliberately NO index signature. One here looks harmless but makes the
+ * constraint unsatisfiable by the very type it exists for: TypeScript does not
+ * give an `interface` an implicit index signature, so `ContextPayload` — an
+ * interface — failed `Ctx extends HostContextLike`.
+ */
+interface HostContextLike {
+    tenant: string;
+    user: {
+        id: string;
+    };
+    /** Set by the host only when it lets a user clear the app's data. */
+    enableDataReset?: boolean;
+}
+/**
+ * The subset of `VibeAppBridge` `wireVibeApp` needs.
+ *
+ * Deliberately does NOT extend `AuthBridgeLike`, i.e. does not require
+ * `onAuthChange`. That method is `@internal` in `@nominalso/vibe-bridge` and
+ * stripped from its published `.d.ts`, so a real `VibeAppBridge` does not
+ * satisfy a constraint that demands it — requiring it here would make
+ * `wireVibeApp(bridge)` reject the only argument it is ever passed.
+ *
+ * It still exists at runtime, and `wireVibeApp` is the sanctioned caller, so
+ * that one call casts to `AuthBridgeLike` locally.
+ *
+ * `onDataReset` / `onSubrouteRequest` are optional so an app on an older bridge
+ * still type-checks; `wireVibeApp` feature-detects both before calling them.
+ */
+interface VibeBridgeLike {
+    onContextChange(cb: (ctx: HostContextLike) => void): () => void;
+    connect(): Promise<HostContextLike>;
+    onDataReset?(cb: (payload: ResetPayloadLike) => void): () => void;
+    onSubrouteRequest?(cb: (subroute: string) => void): () => void;
+}
+/** Informational payload of a host `RESET_DATA` push. */
+interface ResetPayloadLike {
+    reason?: string;
+}
+interface WireVibeAppOptions<Ctx extends HostContextLike> {
+    /**
+     * Extra work on each post-connect context push (subsidiary / period switch)
+     * — refetch scoped data here. The built-in store updates first, so
+     * `getHostContext()` already returns `next` by the time this runs.
+     */
+    onContextChange?: (next: Ctx) => void;
+    /**
+     * Reset the app to its initial state. Wired only when the host actually
+     * enabled it (`ctx.enableDataReset`), so passing it is always safe.
+     */
+    onDataReset?: (payload: ResetPayloadLike) => void;
+    /**
+     * Host-originated subroute pushes. Registering anything — even a no-op —
+     * suppresses the bridge's `history.pushState` fallback, which otherwise
+     * navigates a single-route iframe away and unmounts in-flight dialogs.
+     */
+    onSubrouteRequest?: (subroute: string) => void;
+}
+interface VibeAppWiring<Ctx extends HostContextLike> {
+    /** The bridge you passed in, returned so one import covers the whole module. */
+    bridge: VibeBridgeLike;
+    /**
+     * Resolves the host context, or `null` when there is no host to reach — a
+     * standalone preview, the OAuth callback document, or SSR. **Never rejects:**
+     * a failed handshake is expected outside Nominal, and `AuthGate` falls back
+     * to interactive sign-in on its own.
+     */
+    hostContext: Promise<Ctx | null>;
+    /** Current host context; `null` before connect resolves and when standalone. */
+    getHostContext(): Ctx | null;
+    /** Subscribe to context changes. Returns an unsubscribe function. */
+    subscribeHostContext(listener: (ctx: Ctx | null) => void): () => void;
+}
+
 interface VibeAuth {
     /** True when a Supabase session already exists locally. */
     hasValidSession(): Promise<boolean>;
@@ -269,11 +369,24 @@ interface VibeAuth {
     DefaultSignInScreen: ReturnType<typeof createAuthGate>['DefaultSignInScreen'];
     /** Mount this, and ONLY this, at `callbackPath` — ungated, outside `AuthGate`. */
     SilentCallback: ReturnType<typeof createCallbackHandler>['SilentCallback'];
+    /**
+     * **The one call an embedded app needs.** Wires the bridge to this auth
+     * instance and starts the host handshake — `onContextChange`, `wireHostAuth`,
+     * the callback-document guard, `connect()`, and `seedLastUserId` — in the
+     * one correct order. Returns a context store plus the connect promise.
+     *
+     * Call it once, synchronously, at module scope of an eagerly imported module.
+     * Prefer this over calling `wireHostAuth` / `seedLastUserId` by hand.
+     */
+    wireVibeApp<Ctx extends HostContextLike>(bridge: VibeBridgeLike, options?: WireVibeAppOptions<Ctx>): VibeAppWiring<Ctx>;
     /**
      * 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.
+     *
+     * Low-level: `wireVibeApp` already does this in the right order. Reach for
+     * this only when an app genuinely cannot hand its bridge over.
      */
     wireHostAuth(bridge: AuthBridgeLike): () => void;
     /**
@@ -339,4 +452,4 @@ 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 };
+export { type AuthBridgeLike, type AuthGateProps, type AuthResult, AuthResultKind, type HostContextLike, type HostPrincipal, RESULT_MESSAGE_TYPE, type ResetPayloadLike, type ResolvedVibeAuthConfig, type ResolvedVibeAuthTimeouts, type SignInAuthenticated, type SignInFailed, SignInFailureReason, SignInKind, type SignInRedirecting, type SignInResult, type VibeAppWiring, type VibeAuth, type VibeAuthConfig, type VibeAuthTimeouts, type VibeBridgeLike, type WireVibeAppOptions, createVibeAuth };

package/dist/index.d.ts

@@ -147,6 +147,15 @@ interface SilentAuth {
      * `rebindSession`.
      */
     isBoundTo(principal: HostPrincipal): boolean;
+    /**
+     * Record that the live session belongs to this principal.
+     *
+     * Normally `completeWithResult` does this after redeeming a code. The
+     * top-level redirect flow never routes through that function — the session
+     * arrives via supabase-js's `detectSessionInUrl` — so `AuthGate` stamps it
+     * there instead, and only for a `SIGNED_IN` it observed in that document.
+     */
+    stampBoundMarker(principal: HostPrincipal): void;
     clearBoundUser(): void;
     /** @internal exposed for interactive.ts, which shares completeWithResult/parseCallbackMessage's private helpers */
     completeWithResult(result: AuthResult): Promise<boolean>;
@@ -238,6 +247,97 @@ interface AuthGateBundle {
  */
 declare function createAuthGate(config: ResolvedVibeAuthConfig, silentAuth: SilentAuth, interactiveAuth: InteractiveAuth, hostAuth?: HostAuth): AuthGateBundle;
 
+/**
+ * The contract between this package and `@nominalso/vibe-bridge`, plus the
+ * shape `wireVibeApp` hands back.
+ *
+ * Its own module for the same reason as `principal.ts`: `wireVibeApp` and
+ * `createVibeAuth` both speak these types, and consumers re-export them, so
+ * putting them in the implementation would make every reader import the
+ * implementation to name a type.
+ *
+ * Everything here is **structural**. `@nominalso/vibe-auth` must keep zero
+ * dependency on `@nominalso/vibe-bridge` — they publish separately and version
+ * independently, and a hard dependency would couple their release cycles.
+ */
+/**
+ * The subset of `ContextPayload` this package reads. Apps get their own full
+ * `ContextPayload` back via the `Ctx` type parameter; structural assignability
+ * already allows the extra properties.
+ *
+ * Deliberately NO index signature. One here looks harmless but makes the
+ * constraint unsatisfiable by the very type it exists for: TypeScript does not
+ * give an `interface` an implicit index signature, so `ContextPayload` — an
+ * interface — failed `Ctx extends HostContextLike`.
+ */
+interface HostContextLike {
+    tenant: string;
+    user: {
+        id: string;
+    };
+    /** Set by the host only when it lets a user clear the app's data. */
+    enableDataReset?: boolean;
+}
+/**
+ * The subset of `VibeAppBridge` `wireVibeApp` needs.
+ *
+ * Deliberately does NOT extend `AuthBridgeLike`, i.e. does not require
+ * `onAuthChange`. That method is `@internal` in `@nominalso/vibe-bridge` and
+ * stripped from its published `.d.ts`, so a real `VibeAppBridge` does not
+ * satisfy a constraint that demands it — requiring it here would make
+ * `wireVibeApp(bridge)` reject the only argument it is ever passed.
+ *
+ * It still exists at runtime, and `wireVibeApp` is the sanctioned caller, so
+ * that one call casts to `AuthBridgeLike` locally.
+ *
+ * `onDataReset` / `onSubrouteRequest` are optional so an app on an older bridge
+ * still type-checks; `wireVibeApp` feature-detects both before calling them.
+ */
+interface VibeBridgeLike {
+    onContextChange(cb: (ctx: HostContextLike) => void): () => void;
+    connect(): Promise<HostContextLike>;
+    onDataReset?(cb: (payload: ResetPayloadLike) => void): () => void;
+    onSubrouteRequest?(cb: (subroute: string) => void): () => void;
+}
+/** Informational payload of a host `RESET_DATA` push. */
+interface ResetPayloadLike {
+    reason?: string;
+}
+interface WireVibeAppOptions<Ctx extends HostContextLike> {
+    /**
+     * Extra work on each post-connect context push (subsidiary / period switch)
+     * — refetch scoped data here. The built-in store updates first, so
+     * `getHostContext()` already returns `next` by the time this runs.
+     */
+    onContextChange?: (next: Ctx) => void;
+    /**
+     * Reset the app to its initial state. Wired only when the host actually
+     * enabled it (`ctx.enableDataReset`), so passing it is always safe.
+     */
+    onDataReset?: (payload: ResetPayloadLike) => void;
+    /**
+     * Host-originated subroute pushes. Registering anything — even a no-op —
+     * suppresses the bridge's `history.pushState` fallback, which otherwise
+     * navigates a single-route iframe away and unmounts in-flight dialogs.
+     */
+    onSubrouteRequest?: (subroute: string) => void;
+}
+interface VibeAppWiring<Ctx extends HostContextLike> {
+    /** The bridge you passed in, returned so one import covers the whole module. */
+    bridge: VibeBridgeLike;
+    /**
+     * Resolves the host context, or `null` when there is no host to reach — a
+     * standalone preview, the OAuth callback document, or SSR. **Never rejects:**
+     * a failed handshake is expected outside Nominal, and `AuthGate` falls back
+     * to interactive sign-in on its own.
+     */
+    hostContext: Promise<Ctx | null>;
+    /** Current host context; `null` before connect resolves and when standalone. */
+    getHostContext(): Ctx | null;
+    /** Subscribe to context changes. Returns an unsubscribe function. */
+    subscribeHostContext(listener: (ctx: Ctx | null) => void): () => void;
+}
+
 interface VibeAuth {
     /** True when a Supabase session already exists locally. */
     hasValidSession(): Promise<boolean>;
@@ -269,11 +369,24 @@ interface VibeAuth {
     DefaultSignInScreen: ReturnType<typeof createAuthGate>['DefaultSignInScreen'];
     /** Mount this, and ONLY this, at `callbackPath` — ungated, outside `AuthGate`. */
     SilentCallback: ReturnType<typeof createCallbackHandler>['SilentCallback'];
+    /**
+     * **The one call an embedded app needs.** Wires the bridge to this auth
+     * instance and starts the host handshake — `onContextChange`, `wireHostAuth`,
+     * the callback-document guard, `connect()`, and `seedLastUserId` — in the
+     * one correct order. Returns a context store plus the connect promise.
+     *
+     * Call it once, synchronously, at module scope of an eagerly imported module.
+     * Prefer this over calling `wireHostAuth` / `seedLastUserId` by hand.
+     */
+    wireVibeApp<Ctx extends HostContextLike>(bridge: VibeBridgeLike, options?: WireVibeAppOptions<Ctx>): VibeAppWiring<Ctx>;
     /**
      * 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.
+     *
+     * Low-level: `wireVibeApp` already does this in the right order. Reach for
+     * this only when an app genuinely cannot hand its bridge over.
      */
     wireHostAuth(bridge: AuthBridgeLike): () => void;
     /**
@@ -339,4 +452,4 @@ 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 };
+export { type AuthBridgeLike, type AuthGateProps, type AuthResult, AuthResultKind, type HostContextLike, type HostPrincipal, RESULT_MESSAGE_TYPE, type ResetPayloadLike, type ResolvedVibeAuthConfig, type ResolvedVibeAuthTimeouts, type SignInAuthenticated, type SignInFailed, SignInFailureReason, SignInKind, type SignInRedirecting, type SignInResult, type VibeAppWiring, type VibeAuth, type VibeAuthConfig, type VibeAuthTimeouts, type VibeBridgeLike, type WireVibeAppOptions, createVibeAuth };

package/dist/index.js

@@ -60,7 +60,7 @@ function parseCallbackMessage(data) {
   }
   return null;
 }
-function createSilentAuth(config, getHostPrincipal) {
+function createSilentAuth(config, getHostPrincipal, onBound) {
   const { supabase, provider, callbackPath, timeouts, lockName, boundUserKey } = config;
   async function getSessionUserId() {
     const { data } = await supabase.auth.getSession();
@@ -98,7 +98,10 @@ function createSilentAuth(config, getHostPrincipal) {
       if (priorUserId !== null && sessionUserId === priorUserId) return false;
     }
     const host = getHostPrincipal?.();
-    if (host) writeBoundMarker(host);
+    if (host) {
+      writeBoundMarker(host);
+      onBound?.(host);
+    }
     return true;
   }
   function runHiddenAuthFrame(url) {
@@ -246,6 +249,7 @@ function createSilentAuth(config, getHostPrincipal) {
     ensureSession,
     rebindSession,
     isBoundTo,
+    stampBoundMarker: writeBoundMarker,
     clearBoundUser,
     completeWithResult
   };
@@ -520,6 +524,14 @@ function createAuthGate(config, silentAuth, interactiveAuth, hostAuth) {
       let applyGen = 0;
       let pendingSessionRead;
       let acceptPrincipalUpdates = !hostAuth?.isHostWired();
+      let redeemedHere = false;
+      const sessionBelongsTo = (principal, sessionOk) => {
+        if (!sessionOk) return false;
+        if (silentAuth.isBoundTo(principal)) return true;
+        if (!redeemedHere) return false;
+        silentAuth.stampBoundMarker(principal);
+        return true;
+      };
       const applyPrincipal = async (principal) => {
         hostPrincipal = principal;
         const gen = ++applyGen;
@@ -532,10 +544,11 @@ function createAuthGate(config, silentAuth, interactiveAuth, hostAuth) {
           sessionOk = await silentAuth.hasValidSession().catch(() => false);
         }
         if (cancelled || gen !== applyGen) return;
-        if (sessionOk && silentAuth.isBoundTo(principal)) {
+        if (sessionBelongsTo(principal, sessionOk)) {
           setStatus("authenticated" /* Authenticated */);
           return;
         }
+        if (RETURNING_FROM_OAUTH) return;
         const ok = await silentAuth.rebindSession(principal).catch(() => false);
         if (cancelled || gen !== applyGen) return;
         if (!ok) void supabase.auth.signOut().catch(() => {
@@ -550,12 +563,13 @@ function createAuthGate(config, silentAuth, interactiveAuth, hostAuth) {
         if (principal) {
           const sessionOk = await silentAuth.hasValidSession().catch(() => false);
           if (cancelled || gen !== applyGen) return;
-          if (!(sessionOk && silentAuth.isBoundTo(principal))) return;
+          if (!sessionBelongsTo(principal, sessionOk)) return;
         }
         setStatus("authenticated" /* Authenticated */);
       };
       async function resolve() {
         if (RETURNING_FROM_OAUTH) {
+          acceptPrincipalUpdates = true;
           oauthTimer = window.setTimeout(() => {
             if (!cancelled)
               setStatus((s) => s === "checking" /* Checking */ ? "unauthenticated" /* Unauthenticated */ : s);
@@ -600,8 +614,10 @@ function createAuthGate(config, silentAuth, interactiveAuth, hostAuth) {
       window.addEventListener("storage", onStorage);
       const { data: sub } = supabase.auth.onAuthStateChange((event, session) => {
         if (cancelled || event === "INITIAL_SESSION") return;
-        if (session) void openIfBound();
-        else {
+        if (session) {
+          if (RETURNING_FROM_OAUTH && event === "SIGNED_IN") redeemedHere = true;
+          void openIfBound();
+        } else {
           pendingSessionRead = void 0;
           setStatus((s) => s === "authenticated" /* Authenticated */ ? "unauthenticated" /* Unauthenticated */ : s);
         }
@@ -687,12 +703,58 @@ function createHostAuth(config, silentAuth) {
   };
 }
 
+// src/wireVibeApp.ts
+function createWireVibeApp(config, hostAuth) {
+  return function wireVibeApp(bridge, options = {}) {
+    const listeners = /* @__PURE__ */ new Set();
+    let current = null;
+    function publish(next) {
+      current = next;
+      for (const listener of [...listeners]) listener(next);
+    }
+    bridge.onContextChange((next) => {
+      publish(next);
+      options.onContextChange?.(next);
+    });
+    if (options.onSubrouteRequest) bridge.onSubrouteRequest?.(options.onSubrouteRequest);
+    hostAuth.wireHostAuth(bridge);
+    const noHost = typeof window === "undefined" || window.location.pathname === config.callbackPath;
+    const hostContext = noHost ? Promise.resolve(null) : bridge.connect().then((ctx) => {
+      const next = ctx;
+      hostAuth.seedLastUserId(next.user.id, next.tenant);
+      if (next.enableDataReset && options.onDataReset) {
+        bridge.onDataReset?.(options.onDataReset);
+      }
+      publish(next);
+      return next;
+    }).catch((error) => {
+      console.warn("[vibe-auth] host connect failed", error);
+      return null;
+    });
+    return {
+      bridge,
+      hostContext,
+      getHostContext: () => current,
+      subscribeHostContext: (listener) => {
+        listeners.add(listener);
+        return () => {
+          listeners.delete(listener);
+        };
+      }
+    };
+  };
+}
+
 // src/createVibeAuth.ts
 function createVibeAuth(userConfig) {
   const config = resolveConfig(userConfig);
   assertPkce(config.supabase);
   let hostAuth;
-  const silentAuth = createSilentAuth(config, () => hostAuth.getPrincipal());
+  const silentAuth = createSilentAuth(
+    config,
+    () => hostAuth.getPrincipal(),
+    (principal) => hostAuth.seedLastUserId(principal.userId, principal.tenant)
+  );
   const interactiveAuth = createInteractiveAuth(config, silentAuth);
   const { SilentCallback } = createCallbackHandler();
   hostAuth = createHostAuth(config, silentAuth);
@@ -713,6 +775,7 @@ function createVibeAuth(userConfig) {
     AuthGate,
     DefaultSignInScreen,
     SilentCallback,
+    wireVibeApp: createWireVibeApp(config, hostAuth),
     wireHostAuth,
     seedLastUserId,
     RESULT_MESSAGE_TYPE,