@nominalso/vibe-auth 0.2.2 → 0.2.4

package/AGENTS.md

@@ -39,11 +39,28 @@ export const auth = createVibeAuth({
    render the app's provider tree there (see **Root wiring** below).
 2. **The app root.** Wrap everything in `<auth.AuthGate>`. The app renders nothing of itself
    until authenticated.
-3. **The host bridge**, if embedded via `@nominalso/vibe-bridge`. Call
-   `auth.wireHostAuth(bridge)` at module scope, then start `bridge.connect()`
-   immediately in that same module — do not defer it to a React effect. Seed
-   `auth.seedLastUserId(ctx.user.id, ctx.tenant)` once `connect()` resolves,
-   from a **parent** of `AuthGate`, not inside gated children.
+3. **The host bridge**, if embedded via `@nominalso/vibe-bridge`. One call, at
+   module scope, from a **parent** of `AuthGate` — never a React effect, and
+   never a module reachable only through a `lazy()` chunk:
+
+   ```ts
+   export const bridge = new VibeAppBridge()
+   export const { hostContext, getHostContext, subscribeHostContext } =
+     auth.wireVibeApp<ContextPayload>(bridge)
+   ```
+
+   `wireVibeApp` registers the context subscriber and host auth **before**
+   `connect()`, seeds the host principal `AuthGate` waits on **before**
+   publishing context, skips the handshake entirely in the callback document,
+   and resolves `null` rather than rejecting when there is no host. Pass
+   `onContextChange` / `onDataReset` / `onSubrouteRequest` as options in the
+   same call; each is a single subscriber, and routing them through here is what
+   guarantees exactly one of each.
+
+   `wireHostAuth` / `seedLastUserId` are the pre-0.2.3 hand-wiring. They are
+   still exported for compatibility, but new code should not call them — four of
+   seven migrated apps got that sequence wrong, each differently, which is why
+   `wireVibeApp` exists.
 
 ## Root wiring (SSR — React #418)
 

package/README.md

@@ -62,17 +62,22 @@ function Root() {
 
 ```ts
 // Start the Nominal host handshake at module scope, before React mounts.
+import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 import { auth } from '@/lib/auth'
-import { bridge } from './bridge'
 
-const unsub = auth.wireHostAuth(bridge)
-export const hostContext = bridge.connect().then((ctx) => {
-  auth.seedLastUserId(ctx.user.id, ctx.tenant)
-  return ctx
-})
+export const bridge = new VibeAppBridge()
+
+export const { hostContext, getHostContext, subscribeHostContext } =
+  auth.wireVibeApp<ContextPayload>(bridge)
 ```
 
-See [`AGENTS.md`](./AGENTS.md) for SSR root wiring and host `seedLastUserId` rules.
+One call does the whole handshake, in the one correct order: context subscriber
+and host auth registered before `connect()`, the host principal seeded before
+context is published, the handshake skipped in the callback document, and `null`
+rather than a rejection when there is no host. Pass `onContextChange`,
+`onDataReset` and `onSubrouteRequest` as options in the same call.
+
+See [`AGENTS.md`](./AGENTS.md) for SSR root wiring and the full ordering rules.
 Timeouts live on `VibeAuthTimeouts` in the package `.d.ts`.
 
 ## Why a client you own, not one this package creates
@@ -87,11 +92,13 @@ control**, not a preference (the `.d.ts` on `VibeAuthConfig` explains why).
 
 - `ensureSession()` / `rebindSession({ userId, tenant })` — the cross-document-safe core (Web Lock
   serialised, terminal-capped, sibling-adopting). Most apps never call these directly; the
-  gate and `wireHostAuth` do.
+  gate and `wireVibeApp` do.
 - `AuthGate` / `DefaultSignInScreen` / `SilentCallback` — the three React pieces. Override
   `signInScreen`/`loader` props on `AuthGate` for branding.
-- `wireHostAuth(bridge)` / `seedLastUserId(userId, tenant)` — the Nominal-host integration (logout,
-  identity/tenant switch). Seed from a parent of `AuthGate` after `connect()`.
+- `wireVibeApp(bridge, options?)` — the Nominal-host integration in one call (handshake,
+  host context store, logout and identity/tenant switch). Call it at module scope from a
+  parent of `AuthGate`. (`wireHostAuth` / `seedLastUserId` are the pre-0.2.3 hand-wiring,
+  still exported for compatibility; new code should not use them.)
 - Fully configurable timeouts (`VibeAuthTimeouts` in the `.d.ts`) — every value defaults to
   what shipped after this flow's production incidents.
 

package/dist/index.cjs

@@ -278,6 +278,7 @@ function createSilentAuth(config, getHostPrincipal, onBound) {
     ensureSession,
     rebindSession,
     isBoundTo,
+    stampBoundMarker: writeBoundMarker,
     clearBoundUser,
     completeWithResult
   };
@@ -552,6 +553,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;
@@ -564,10 +573,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(() => {
@@ -582,12 +592,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);
@@ -632,8 +643,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);
         }
@@ -719,6 +732,48 @@ 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);
@@ -749,6 +804,7 @@ function createVibeAuth(userConfig) {
     AuthGate,
     DefaultSignInScreen,
     SilentCallback,
+    wireVibeApp: createWireVibeApp(config, hostAuth),
     wireHostAuth,
     seedLastUserId,
     RESULT_MESSAGE_TYPE,