@nominalso/vibe-auth 0.2.0

package/AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md — @nominalso/vibe-auth
+
+Instructions for AI coding agents (Claude Code, Cursor, Copilot, Lovable, etc.) integrating
+this package. This is a **consumer usage guide**, not repo build config.
+
+## What this package is
+
+`@nominalso/vibe-auth` is the silent-SSO login flow for a Nominal Vibe App that authenticates
+through Supabase federated with the Nominal host's IdP (Descope). It replaces a hand-written
+`silentAuth.ts` + `AuthGate.tsx` pair generated from the `silent-supabase-oidc-login` skill.
+**If the app has such files, migrate them to this package — do not hand-write this flow.**
+Follow the skill's Step 1b (delete the hand-written files; keep `provider`, callback path, and
+the existing Supabase client).
+
+## The one rule
+
+Call `createVibeAuth(...)` **once**, **synchronously**, at the top of its own module
+(conventionally `src/lib/auth.ts`), and import that module **eagerly** — never lazily, never
+inside a component or a conditional. `AuthGate`/`SilentCallback` capture the callback URL at
+that call, before any React effect or async work lets supabase-js's `detectSessionInUrl`
+strip it first.
+
+```ts
+// src/lib/auth.ts
+import { createVibeAuth } from '@nominalso/vibe-auth'
+import { supabase } from './supabaseClient'
+
+export const auth = createVibeAuth({
+  supabase,
+  provider: 'custom:supabase-fedapp', // ask the user for this — never guess it
+})
+```
+
+## The three wiring points
+
+1. **The callback route.** Mount `auth.SilentCallback` at `auth.callbackPath` (default
+   `/silent-callback`), and ONLY that — it must render ungated, outside `AuthGate`. SSR
+   frameworks: `ssr: false` (or equivalent) on this route, and the root layout must not
+   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 BEFORE `bridge.connect()`, then
+   `auth.seedLastUserId(ctx.user.id, ctx.tenant)` once `connect()` resolves —
+   from a **parent** of `AuthGate`, not inside gated children.
+
+## Root wiring (SSR — React #418)
+
+`AuthGate` / `SilentCallback` defer `window` reads to an effect. Your **root layout** must
+not decide "is this the callback?" with `typeof window !== 'undefined' && window.location…`
+at render time: the server always sees `window` missing and renders the gated app; the
+client's first pass on `/silent-callback` wants a bare outlet. That subtree mismatch is
+React #418, and it can fire `bridge.connect()` inside a popup/hidden iframe.
+
+Ask the **router** for the path (identical on server and client):
+
+```tsx
+// TanStack Start — Next.js: usePathname() from next/navigation in a Client Component
+const pathname = useRouterState({ select: (s) => s.location.pathname })
+if (pathname === auth.callbackPath) return <Outlet />
+return (
+  <auth.AuthGate>
+    <App />
+  </auth.AuthGate>
+)
+```
+
+```tsx
+export const Route = createFileRoute('/silent-callback')({
+  ssr: false,
+  component: auth.SilentCallback,
+})
+```
+
+## Do NOT
+
+- Do not create your own `signInWithOAuth`/`exchangeCodeForSession` calls anywhere in the app
+  — every code path that can create a session goes through this package.
+- Do not add a `signOut()` call on a failed `ensureSession()` — a failed silent attempt is not
+  proof the user is logged out (see README's security-boundary section).
+- Do not read `window.location` at component render time to decide whether the current route
+  is the callback route — use **Root wiring** above.
+- Do not branch on `typeof window !== 'undefined'` around this package's exports — they are
+  already SSR-safe.
+
+## Host identity
+
+The gate waits for a seeded `{userId, tenant}` before opening. A leftover Supabase session
+is not enough. Unmigrated sibling documents may still write `{userId, at}` markers (no
+`tenant`); this app will not treat those as a completed rebind and will rerun silent SSO
+under the shared Web Lock — safe, just not a skip.
+
+Same-user **tenant** switches rebind. If the callback-document race loses and the leftover
+session is the same Supabase user, adoption cannot tell "fresh" from "old" and fail-closes
+(`signOut` + sign-in screen). That is intentional.
+
+## Configuration reference
+
+See `VibeAuthConfig` in the package's `.d.ts` for every option (including timeouts). The two
+REQUIRED fields are `supabase` (your own client, PKCE-configured) and `provider` (from the
+app's Supabase Auth → Providers setup — ask the user, never guess).

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright © 2026 Nominal. All rights reserved.
+
+This software and its source code are proprietary and confidential.
+The packages published from this repository are marked "UNLICENSED": no
+license or right to use, copy, modify, distribute, or create derivative
+works is granted except under a separate written agreement with Nominal.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

package/README.md

@@ -0,0 +1,103 @@
+# @nominalso/vibe-auth
+
+Silent Supabase OIDC login for **Nominal Vibe Apps** — a configurable, cross-document-safe
+auth gate that replaces a hand-copied per-app implementation of the
+[`silent-supabase-oidc-login`](../../standalone-agents/skills/silent-supabase-oidc-login/SKILL.md)
+skill. If your app authenticates through Supabase federated with the Nominal host's IdP
+(Descope), this package IS that flow — written once, fixed once, and configurable per app.
+
+> **For AI agents / Lovable:** see [`AGENTS.md`](./AGENTS.md) for the condensed integration
+> guide (including the SSR root-wiring recipe). To replace a hand-written
+> `silentAuth.ts`/`AuthGate.tsx` pair, follow the `silent-supabase-oidc-login` skill Step 1b.
+
+## Why this exists
+
+Six generated apps each carried a hand-copied version of this login flow. Five rounds of bug
+fixes had to be re-applied per app, and the copies drifted: one app grew a React hydration
+crash in its root route, three ended up mounting bridge providers inside the auth callback
+document, and all of them still carried a production bug where a stale session's failed
+boot-time refresh briefly flashed the sign-in screen. This package is that logic, fixed and
+written once.
+
+## Install
+
+```sh
+npm install @nominalso/vibe-auth
+```
+
+Peer dependencies: `react >=18`, `@supabase/supabase-js ^2`.
+
+## Quickstart
+
+```ts
+// src/lib/auth.ts — called synchronously, at module scope, imported eagerly.
+import { createVibeAuth } from '@nominalso/vibe-auth'
+import { supabase } from './supabaseClient' // YOUR existing client — this package never creates one
+
+export const auth = createVibeAuth({
+  supabase,
+  provider: 'custom:supabase-fedapp', // from your Supabase Auth → Providers config
+})
+```
+
+```tsx
+// the callback route — mount ONLY this, ungated, at the callback path
+// (default '/silent-callback'; see AGENTS.md for the SSR-safe recipe)
+import { auth } from '@/lib/auth'
+export default auth.SilentCallback
+```
+
+```tsx
+// wrap the whole app — it never renders until authenticated
+import { auth } from '@/lib/auth'
+
+function Root() {
+  return (
+    <auth.AuthGate>
+      <App />
+    </auth.AuthGate>
+  )
+}
+```
+
+```ts
+// wire the Nominal host bridge, before connect()
+import { auth } from '@/lib/auth'
+import { bridge } from './bridge'
+
+const unsub = auth.wireHostAuth(bridge)
+const ctx = await bridge.connect()
+auth.seedLastUserId(ctx.user.id, ctx.tenant)
+```
+
+See [`AGENTS.md`](./AGENTS.md) for SSR root wiring and host `seedLastUserId` rules.
+Timeouts live on `VibeAuthTimeouts` in the package `.d.ts`.
+
+## Why a client you own, not one this package creates
+
+Your `client.ts` is often Lovable-generated (marked "do not edit"), carries your generated
+`Database` types, and may have its own storage adapter (e.g. for Lovable preview brokering).
+This package only requires it: at `createVibeAuth()`, it best-effort-checks
+`auth.flowType === 'pkce'` and logs a loud `console.error` if it isn't — PKCE is a **security
+control**, not a preference (the `.d.ts` on `VibeAuthConfig` explains why).
+
+## What you get
+
+- `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.
+- `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()`.
+- Fully configurable timeouts (`VibeAuthTimeouts` in the `.d.ts`) — every value defaults to
+  what shipped after this flow's production incidents.
+
+## Security boundary
+
+`signOut()` calls made by this package (on host logout, on a failed identity-switch rebind)
+are **client-side, best-effort UX**: they stop rendering the app and drop the local session,
+but a persisted Supabase access token stays technically valid until it expires, and only this
+browser is affected. **Enforced logout must happen server-side** — OIDC back-channel logout
+revoking the Supabase refresh tokens (Supabase Admin API, per project). That back-channel
+receiver is infrastructure outside this package.