@ai-matrx/auth 0.0.0 → 0.1.0

package/dist/next.d.ts

@@ -0,0 +1,389 @@
+import { createServerClient, createBrowserClient } from '@supabase/ssr';
+import { b as AuthCookieValue, A as AuthCookie, a as AuthCookieOptions } from './auth-cookie-DWx6Q3xo.js';
+export { C as CreateAuthCookieArgs, D as DEFAULT_AUTH_COOKIE_NAME, c as createAuthCookie } from './auth-cookie-DWx6Q3xo.js';
+
+/**
+ * @ai-matrx/data/next — the Next.js Supabase binding.
+ *
+ * WHY THIS EXISTS (C22 / THE ALL-INCLUSIVE LAW): a Next.js app has FIVE
+ * distinct places that must construct a Supabase client — the browser, a
+ * Server Component, a Route Handler, the proxy/middleware, and an OAuth
+ * callback — and every one of them must pass the SAME auth-cookie options or
+ * it cannot see the session the others wrote. Before this module, matrx-frontend
+ * carried that construction five times, each with its own env guard, its own
+ * cookie adapter, and its own copy of the "do not run code between
+ * createServerClient and getUser()" hazard. Every app on the platform would
+ * have re-derived all five.
+ *
+ * The host now injects IDENTITY only — URL, publishable key, apex domain, the
+ * cookie names — and the package owns every hard part:
+ *
+ *  - env validation with a named, actionable error (never `process.env.X!`,
+ *    which fails as a cryptic `undefined.trim()` TypeError);
+ *  - the domain-wide cookie option construction on every single door;
+ *  - the SSR/browser split, including the Server-Component write that must be
+ *    swallowed because only the proxy may set cookies there;
+ *  - the browser singleton on a `globalThis` slot (module-level mutable state
+ *    is banned — dual ESM/CJS bundles would otherwise instantiate two clients
+ *    and split the session);
+ *  - the middleware session dance in ONE call: legacy-key migration, the
+ *    getUser() adjacency rule, session persistence under the new key, legacy
+ *    cookie clearing at the issuing scope, the no-store response headers, and
+ *    cookie carry-over onto redirects (dropping any one of these logs users
+ *    out at random, which is exactly how it was found).
+ *
+ * NO `next/*` IMPORT LIVES HERE. Next's own primitives (`cookies()`,
+ * `NextResponse`) arrive through structural seams the host passes in, so this
+ * module builds and tests outside Next and cannot drag the framework into a
+ * non-Next consumer's graph.
+ */
+
+/**
+ * A `Database` type as generated by Supabase. Deliberately structural: the
+ * package never imports a host's generated types, and a host that has not
+ * generated any still gets a working (untyped-rows) client.
+ */
+type DatabaseLike = Record<string, unknown>;
+type NextBrowserClient<DB extends DatabaseLike> = ReturnType<typeof createBrowserClient<DB>>;
+type NextServerClient<DB extends DatabaseLike> = ReturnType<typeof createServerClient<DB>>;
+/** A cookie to write, as `@supabase/ssr` hands it to `setAll`. */
+interface CookieToSet {
+    name: string;
+    value: string;
+    options?: Record<string, unknown> | undefined;
+}
+/**
+ * The subset of Next's `await cookies()` store this binding uses. Structural
+ * on purpose — `ReadonlyRequestCookies` satisfies it by shape.
+ */
+interface ServerCookieStore {
+    getAll(): readonly AuthCookieValue[];
+    set(name: string, value: string, options?: Record<string, unknown>): void;
+}
+/** The subset of `NextRequest["cookies"]` the middleware binding uses. */
+interface RequestCookieJar {
+    getAll(): readonly AuthCookieValue[];
+    set(name: string, value: string): void;
+}
+/**
+ * A cookie in Next's `ResponseCookies` shape: name, value, and every
+ * attribute FLAT on the same object.
+ *
+ * 🚨 THIS SHAPE IS LOAD-BEARING, and modelling it as `never` cost the platform
+ * a production outage (2026-09-01). `ResponseCookies.set` accepts either
+ * `(name, value, attrs)` or ONE flat object — it does NOT accept `@supabase/ssr`'s
+ * `{ name, value, options }`, and it does not throw on it either: it reads
+ * `name`/`value`, ignores the unknown `options` key, and serializes
+ * `sb-…-auth-v2.0=; Path=/`. Every attribute is lost. So:
+ *   · a token refresh wrote a HOST-ONLY session cookie shadowing the real
+ *     `.apex` one, and
+ *   · every chunk REMOVAL (`value: ""`, `maxAge: 0`) became a PERSISTENT EMPTY
+ *     host-only cookie instead of a deletion.
+ * Two same-name cookies then reach the server in one `Cookie` header, the
+ * empty one sorts first, `combineChunks`' `find()` takes it, and every server
+ * read answers anonymous while the tab still shows a signed-in user.
+ * `@supabase/ssr` cookies are converted with `toResponseCookie` at the single
+ * boundary below; the `never` that hid this is gone.
+ */
+interface ResponseCookie {
+    name: string;
+    value: string;
+    domain?: string | undefined;
+    path?: string | undefined;
+    maxAge?: number | undefined;
+    expires?: Date | number | undefined;
+    httpOnly?: boolean | undefined;
+    secure?: boolean | undefined;
+    sameSite?: boolean | "lax" | "strict" | "none" | undefined;
+    priority?: "low" | "medium" | "high" | undefined;
+    partitioned?: boolean | undefined;
+}
+/**
+ * The subset of `NextResponse["cookies"]` the middleware binding uses.
+ */
+interface ResponseCookieJar {
+    getAll(): ResponseCookie[];
+    set(cookie: ResponseCookie): void;
+}
+/** The subset of a `NextResponse` the middleware binding drives. */
+interface MiddlewareResponse {
+    cookies: ResponseCookieJar;
+    headers: {
+        get(name: string): string | null;
+        set(name: string, value: string): void;
+        /**
+         * Required for the split-jar heal. `ResponseCookies` keeps ONE entry per
+         * cookie NAME, so the same name cannot be expired at two Domain scopes
+         * through it — the second `set` replaces the first. The losing scope is
+         * expired with raw appended `Set-Cookie` headers instead.
+         */
+        append(name: string, value: string): void;
+    };
+}
+interface NextSupabaseConfig {
+    /**
+     * `process.env.NEXT_PUBLIC_SUPABASE_URL` — read STATICALLY at the call site.
+     * Next only inlines `NEXT_PUBLIC_*` into client bundles for static member
+     * accesses; a dynamic lookup inside this package would be `undefined` in
+     * every browser bundle.
+     */
+    supabaseUrl: string | undefined;
+    /** `process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, read statically. */
+    publishableKey: string | undefined;
+    /** The apex domain one login must span, e.g. `"aimatrx.com"`. */
+    apexDomain: string;
+    /** Auth cookie name. Defaults to the package's `sb-matrx-auth`. */
+    cookieName?: string;
+    /** A superseded storage key to migrate from and then clear. */
+    legacyCookieName?: string;
+    /**
+     * Host wrapper applied to the BROWSER client only — the one legitimate
+     * host seam here (diagnostics/error capture). It must not change query
+     * behavior; the package never inspects what it returns.
+     *
+     * `C extends object` because a Supabase client always IS one, and a real
+     * capture wrapper is a `Proxy` that must constrain the same way. Leaving
+     * `C` unconstrained made every honest host wrapper unassignable (found at
+     * matrx-frontend adoption, 0.5.1).
+     */
+    wrapBrowserClient?: <C extends object>(client: C) => C;
+}
+/** Cache-defeating headers every auth-cookie-bearing response must carry. */
+declare const AUTH_COOKIE_RESPONSE_HEADERS: Readonly<Record<string, string>>;
+/**
+ * Stamped on any response whose auth cookie jar was found split and healed.
+ * A shell that already rendered may be wearing an identity this pass could not
+ * see, and must say so rather than paint a signed-in screen of anonymous data.
+ */
+declare const SPLIT_COOKIE_JAR_HEADER = "x-matrx-split-jar";
+/**
+ * Stamped when this request's auth cookie jar held one storage key BOTH
+ * unchunked and chunked — see `AuthCookie.reconcile`. Distinct from
+ * `SPLIT_COOKIE_JAR_HEADER` because the person's experience is different and
+ * the screen must say the true thing:
+ *
+ *   split jar   → the tab still holds a session; the server just could not
+ *                 read it. "Sign in again" restores the page.
+ *   ambiguous   → we deliberately refused BOTH copies rather than risk
+ *                 resolving the wrong person, so this person has just been
+ *                 signed out BY US. That is an automatic intervention on
+ *                 somebody's session and it must not happen quietly: the
+ *                 browser's own read is anonymous too, so nothing else on the
+ *                 page can notice, and without this header the app shows a
+ *                 login screen with no explanation.
+ */
+declare const AMBIGUOUS_AUTH_COOKIE_HEADER = "x-matrx-auth-ambiguous";
+/**
+ * `@supabase/ssr`'s `{ name, value, options }` → Next's flat `ResponseCookie`.
+ * The ONE conversion boundary; see {@link ResponseCookie} for what skipping it
+ * cost.
+ */
+declare function toResponseCookie(cookie: CookieToSet): ResponseCookie;
+/**
+ * A `ResponseCookie` as a raw `Set-Cookie` header value, serialized the way
+ * Next's `ResponseCookies` serializes it. Needed because a response can only
+ * carry ONE entry per cookie NAME through `.cookies`, and `@supabase/ssr`
+ * deliberately writes some names TWICE — see `applyCookies`.
+ */
+declare function serializeSetCookie(cookie: ResponseCookie): string;
+/**
+ * Thrown when identity is missing. Named and actionable — the alternative
+ * (`process.env.X!`) surfaces as `Cannot read properties of undefined
+ * (reading 'trim')` from inside Supabase, which taught nobody anything.
+ */
+declare class MissingSupabaseIdentityError extends Error {
+    readonly variable: string;
+    constructor(variable: string);
+}
+/**
+ * ONE budget for the WHOLE identity resolve of a request, not one per socket.
+ *
+ * The 0.17.0 budget aborted each `/auth/v1/` socket at 2.5s. That was not
+ * enough, and 2026-09-21 proved it: auth-js retries a token refresh with
+ * exponential backoff for up to 30s (`AUTO_REFRESH_TICK_DURATION_MS`), and a
+ * per-socket abort is exactly the retryable error that keeps that loop going —
+ * five aborted attempts plus their pauses is ~15.5s, past Vercel's 15s task
+ * cap, and the proxy answered `504` while believing it had a budget.
+ *
+ * This wrapper holds a deadline from the FIRST identity call. While the
+ * deadline is open every identity call gets what is LEFT of it, aborting the
+ * socket (a `Promise.race` would leave it hanging and holding the Lambda).
+ * The moment an attempt aborts, or the deadline passes, the budget is
+ * EXHAUSTED and every further identity call answers synchronously with a
+ * synthetic `408 auth_budget_exhausted` — a non-retryable auth error — so
+ * auth-js stops its loop at once instead of sleeping through it. The whole
+ * resolve therefore costs at most the budget plus one 200ms backoff.
+ *
+ * `exhausted` is also the cookie gate: an exhausted budget must never write,
+ * expire or heal a cookie, because auth-js clears the session on a
+ * non-retryable refresh failure once the access token has truly expired, and
+ * that write is a logout caused by a slow network.
+ */
+interface AuthBudget {
+    fetch: typeof fetch;
+    readonly exhausted: boolean;
+}
+/**
+ * 🚨 A REFRESH THAT WAS SENT IS NEVER ABANDONED AT THE BUDGET (2026-10-07).
+ *
+ * `grant_type=refresh_token` ROTATES the refresh token on the auth server the
+ * moment it is processed. Aborting it at 2.5s did not stop the rotation — it only
+ * threw away the new tokens, so no cookie was written and the browser kept a
+ * refresh token the server had already spent. Past GoTrue's reuse window that
+ * token is refused and the person is signed out (and a server-rendered read made
+ * on the dropped session went out as `anon`: their own chats answered "sign in").
+ * So a refresh, once on the wire, runs to completion and its answer is used,
+ * bounded only by this ceiling — below Vercel's 15s proxy cap. A refresh that has
+ * NOT been sent yet still obeys the budget (nothing rotated, nothing lost).
+ */
+declare const AUTH_REFRESH_CEILING_MS = 8000;
+declare function createAuthBudget(timeoutMs: number, options?: {
+    refreshCeilingMs?: number;
+}): AuthBudget;
+interface MiddlewareSessionArgs<Response> {
+    /** `Host` header of the incoming request. */
+    host: string | null | undefined;
+    /** `request.cookies` */
+    requestCookies: RequestCookieJar;
+    /**
+     * The raw `Cookie` header (`request.headers.get("cookie")`). REQUIRED to
+     * detect and heal a split jar — `request.cookies` has already collapsed the
+     * duplicates. Without it this pass cannot see the shadow and cannot expire
+     * it, which is exactly how the "healed" 0.7.x build still left poisoned
+     * browsers poisoned.
+     */
+    cookieHeader?: string | null | undefined;
+    /** `() => NextResponse.next({ request })` — a FRESH response each call. */
+    createResponse: () => Response;
+    /** `(url) => NextResponse.redirect(url)` */
+    createRedirect: (url: URL) => Response;
+}
+interface MiddlewareSession<DB extends DatabaseLike, Response> {
+    /**
+     * The validated user, or `null`. Resolved via `getClaims()` — a local
+     * cryptographic verification of the access token, not a `getSession()` read.
+     *
+     * `null` is ambiguous on its own: check `authUnavailable` before treating it
+     * as "signed out". A transport failure produces `null` too, and acting on
+     * that as a logout is how a network blink bounces a signed-in person.
+     */
+    user: ({
+        id: string;
+    } & Record<string, unknown>) | null;
+    /** The client, in case the caller needs a further authenticated read. */
+    client: NextServerClient<DB>;
+    /** The response carrying every session cookie written during this pass. */
+    response: Response;
+    /**
+     * A redirect that CARRIES the session cookies and cache headers. Building a
+     * bare `NextResponse.redirect` here drops refreshed tokens on the floor and
+     * logs the user out on the next request.
+     */
+    redirect(url: URL): Response;
+    /**
+     * `true` when this request arrived with the same auth cookie at two Domain
+     * scopes. The response heals the jar, but the SHELL that already rendered
+     * may be holding an identity this pass could not see — a host that renders
+     * a signed-in shell must say so in words rather than paint a signed-in
+     * screen full of anonymous data.
+     */
+    splitCookieJar: boolean;
+    /**
+     * `true` when a storage key arrived BOTH unchunked and chunked and this pass
+     * therefore refused both copies rather than risk resolving the wrong person.
+     * The person has been signed out by us and must be told so.
+     */
+    ambiguousAuthCookies: boolean;
+    /**
+     * `true` when the auth authority could not be REACHED inside the resolve
+     * budget, so this pass has no opinion about who this is.
+     *
+     * The contract when it is set: `user` is `null` but the person is NOT signed
+     * out, not one auth cookie was written, expired or healed, and the host must
+     * neither bounce to login nor paint a signed-out screen as if it were
+     * settled. Let the request through; the client resolves auth itself and the
+     * next request re-resolves it here.
+     */
+    authUnavailable: boolean;
+}
+interface NextSupabase<DB extends DatabaseLike> {
+    /** The auth-cookie primitive this binding is built on. */
+    readonly authCookie: AuthCookie;
+    readonly cookieName: string;
+    optionsForHost(host: string | null | undefined): AuthCookieOptions;
+    browserOptions(): AuthCookieOptions;
+    /**
+     * The browser client. Memoized on a `globalThis` slot keyed by identity, so
+     * the ESM and CJS graphs of this package share ONE client and therefore one
+     * auth state — a per-module singleton would silently split them.
+     */
+    browserClient(): NextBrowserClient<DB>;
+    /**
+     * A Server Component / Server Action client over `await cookies()`.
+     * Cookie writes from a Server Component are swallowed by design: only the
+     * proxy may set cookies there, and it refreshes the session anyway.
+     */
+    serverClient(args: {
+        cookieStore: ServerCookieStore;
+        host: string | null | undefined;
+        /**
+         * The raw `Cookie` request header (`(await headers()).get("cookie")`).
+         * REQUIRED to see a split jar: `cookies()` collapses two same-name cookies
+         * to one before this code runs. Omitting it degrades this door to the
+         * collapsed view, where the surviving copy is whichever the browser sent
+         * last — a coin flip between the session and anonymous.
+         */
+        cookieHeader?: string | null | undefined;
+        /**
+         * See `routeClient`'s `appendSetCookie` — Next's `cookies()` store keys by
+         * NAME exactly like `ResponseCookies`, so a two-scope removal collapses
+         * here too. A Route Handler that signs somebody in MUST pass this (buffer
+         * the headers and append them onto the response it returns, last).
+         * A Server Component has no response to append to and its writes are
+         * swallowed anyway, so it correctly passes nothing.
+         */
+        appendSetCookie?: (header: string) => void;
+    }): NextServerClient<DB>;
+    /**
+     * A Route Handler client: reads the request's cookies, writes onto the
+     * response you are about to return.
+     */
+    routeClient(args: {
+        requestCookies: Pick<RequestCookieJar, "getAll">;
+        setCookie: (cookie: CookieToSet) => void;
+        host: string | null | undefined;
+        /** See `serverClient` — same collapse, same requirement. */
+        cookieHeader?: string | null | undefined;
+        /**
+         * `(header) => response.headers.append("Set-Cookie", header)`.
+         *
+         * 🚨 REQUIRED ON ANY DOOR THAT SIGNS SOMEBODY IN. `@supabase/ssr` removes a
+         * cookie at BOTH Domain scopes by emitting the SAME name twice, and every
+         * jar a host can pass to `setCookie` — `NextResponse.cookies`, Next's
+         * `cookies()` store — keeps ONE entry per NAME, so the second write
+         * REPLACES the first and the `.apex` removal is silently lost. That is how
+         * a stale UNCHUNKED auth cookie survives beside a fresh CHUNKED pair, and
+         * `combineChunks` then serves the STALE one — the previous person's
+         * session, to the person who just signed in (2026-09-08, R-O3).
+         *
+         * With this seam the duplicate goes out as a raw header instead. Without
+         * it the drop is announced loudly rather than swallowed.
+         *
+         * THE CALLER'S OBLIGATION: `ResponseCookies.set` re-serializes the whole
+         * `Set-Cookie` list from its own map and DISCARDS raw appends made since.
+         * Nothing may touch `response.cookies` after a header appended here.
+         */
+        appendSetCookie?: (header: string) => void;
+    }): NextServerClient<DB>;
+    /**
+     * THE middleware/proxy auth pass, entire. Runs legacy-key migration, builds
+     * the client, resolves `getUser()` with nothing in between, persists a
+     * migrated session under the current key, clears the superseded key at the
+     * scope this host issued it on, and stamps no-store headers on any response
+     * that carries cookies.
+     */
+    middlewareSession<Response extends MiddlewareResponse>(args: MiddlewareSessionArgs<Response>): Promise<MiddlewareSession<DB, Response>>;
+}
+declare function createNextSupabase<DB extends DatabaseLike = DatabaseLike>(config: NextSupabaseConfig): NextSupabase<DB>;
+
+export { AMBIGUOUS_AUTH_COOKIE_HEADER, AUTH_COOKIE_RESPONSE_HEADERS, AUTH_REFRESH_CEILING_MS, type AuthBudget, AuthCookie, AuthCookieOptions, AuthCookieValue, type CookieToSet, type DatabaseLike, type MiddlewareResponse, type MiddlewareSession, type MiddlewareSessionArgs, MissingSupabaseIdentityError, type NextBrowserClient, type NextServerClient, type NextSupabase, type NextSupabaseConfig, type RequestCookieJar, type ResponseCookie, type ResponseCookieJar, SPLIT_COOKIE_JAR_HEADER, type ServerCookieStore, createAuthBudget, createNextSupabase, serializeSetCookie, toResponseCookie };