@ingram-tech/nk-auth 0.6.0 → 0.7.1

package/README.md

@@ -17,8 +17,8 @@ only what you need from focused subpaths.
 | `createAuthPool` (`./pool`) | `pg` Pool with optional SSL CA verification |
 | `bcryptPassword`, `makeEmailSenders`, `makePasskeyOptions`, `uuidGenerateId` (`./`) | password migration, email hooks, passkeys, UUID ids |
 | `createServerSupabase` (`./`) | RLS-aware supabase-js client (attaches the session JWT) |
-| `createAuthHelpers` (`./server`) | validated App Router session helpers: `getSession` / `getUser` / `requireSession` / `requireUser` / `redirectIfAuthenticated` |
-| `createAuthMiddleware` (`./middleware`) | loop-safe edge middleware that only gates *unauthenticated* users off protected paths |
+| `createAuthHelpers`, `safeNext` (`./server`) | validated App Router session helpers (`getSession` / `getUser` / `requireSession` / `requireUser` / `redirectIfAuthenticated`) with automatic `next` + stale-cookie signalling; `safeNext` validates a `?next=` param |
+| `createAuthMiddleware` (`./middleware`) | loop-safe edge middleware: gates unauthenticated users off protected paths, preserves `next`, and clears a stale session cookie so a bad session self-heals |
 
 > **Supabase Auth → Better Auth + RLS migration?** Read
 > [`docs/better-auth-migration.md`](../../docs/better-auth-migration.md) — the
@@ -203,16 +203,25 @@ export const {
 // app/dashboard/page.tsx — gate a protected page (validated, DB-backed).
 import { requireUser } from "@/lib/auth/session";
 export default async function Dashboard() {
-	const user = await requireUser(); // -> /login when signed out
+	// -> /login?next=/dashboard when signed out (and ?stale=1 when the cookie is
+	// present-but-invalid, so middleware clears it). next/stale are automatic.
+	const user = await requireUser();
 	return <main>Hi {user.email}</main>;
 }
 
-// app/login/page.tsx — gate the sign-in page HERE, never in middleware.
+// app/login/page.tsx — gate the sign-in page HERE, never in middleware. Honor
+// `next` so sign-in returns the user to where they were headed.
 import { redirectIfAuthenticated } from "@/lib/auth/session";
+import { safeNext } from "@ingram-tech/nk-auth/server";
 import { LoginForm } from "./login-form";
-export default async function Login() {
-	await redirectIfAuthenticated("/dashboard"); // validated: a stale cookie
-	return <LoginForm />; // resolves to "signed out" and falls through to the form
+export default async function Login({
+	searchParams,
+}: {
+	searchParams: Promise<{ next?: string }>;
+}) {
+	const next = safeNext((await searchParams).next) ?? "/dashboard";
+	await redirectIfAuthenticated(next); // validated: a stale cookie resolves to
+	return <LoginForm next={next} />; // "signed out" and falls through to the form
 }
 ```
 
@@ -243,8 +252,17 @@ can only trust the cookie *exists*. The server helpers hit `auth.api.getSession`
 and check the session *contents*. When those disagree (revoked session, rotated
 secret, wiped DB) the validated layer wins and parks the user on `/login` — and
 because middleware refuses to bounce `/login`, the form renders instead of
-ping-ponging. Middleware is optional; sites that prefer one source of truth can
-use the server helpers alone.
+ping-ponging.
+
+**Self-heal.** A bad session doesn't strand the user. The guard redirects to
+`/login?next=<where they were>&stale=1`; middleware (the only pre-render place
+that can touch cookies) deletes the dead Better Auth cookies on the `stale`
+marker and bounces to a clean `/login?next=…`; signing in returns them to
+`next`. `next` for the cookie-less case is filled in by middleware directly; for
+the cookie-present case the guard reads it from the `x-nk-auth-path` header
+middleware injects — so the self-heal (next + clearing) needs the middleware.
+Sites that skip middleware still get validated gating from the server helpers,
+just without automatic `next`/clearing.
 
 ## RLS bridge (the important part)
 

package/dist/gating-internals.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Internal helpers shared by the server helpers and the middleware. Kept in a
+ * zero-`next` module so neither subpath imports the other (server pulls
+ * next/navigation, middleware pulls next/server — mixing them breaks the
+ * respective runtimes). Not a public export.
+ */
+/**
+ * Request header the middleware sets to the originally-requested path so a
+ * server-component guard — which Next.js otherwise gives no way to learn its own
+ * URL — can preserve it as a `next` param when it redirects to sign-in.
+ */
+export declare const NK_AUTH_PATH_HEADER = "x-nk-auth-path";
+/**
+ * Accept only an internal, non-protocol-relative path as a post-login redirect,
+ * so `next` can never be turned into an open redirect to another origin.
+ */
+export declare function safeNextParam(value: string | null | undefined): string | null;
+/**
+ * Build a sign-in URL: `signInPath`, plus `next` (when safe) so the user returns
+ * to where they were headed, plus a `stale=1` marker when a session cookie is
+ * present but invalid — the signal the middleware uses to clear the dead cookie.
+ */
+export declare function signInUrl(signInPath: string, opts: {
+    next?: string | null;
+    stale?: boolean;
+}): string;
+//# sourceMappingURL=gating-internals.d.ts.map

package/dist/gating-internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gating-internals.d.ts","sourceRoot":"","sources":["../src/gating-internals.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAI7E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACxB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7C,MAAM,CAOR"}

package/dist/gating-internals.js

@@ -0,0 +1,39 @@
+/**
+ * Internal helpers shared by the server helpers and the middleware. Kept in a
+ * zero-`next` module so neither subpath imports the other (server pulls
+ * next/navigation, middleware pulls next/server — mixing them breaks the
+ * respective runtimes). Not a public export.
+ */
+/**
+ * Request header the middleware sets to the originally-requested path so a
+ * server-component guard — which Next.js otherwise gives no way to learn its own
+ * URL — can preserve it as a `next` param when it redirects to sign-in.
+ */
+export const NK_AUTH_PATH_HEADER = "x-nk-auth-path";
+/**
+ * Accept only an internal, non-protocol-relative path as a post-login redirect,
+ * so `next` can never be turned into an open redirect to another origin.
+ */
+export function safeNextParam(value) {
+    if (!value)
+        return null;
+    if (!value.startsWith("/") || value.startsWith("//"))
+        return null;
+    return value;
+}
+/**
+ * Build a sign-in URL: `signInPath`, plus `next` (when safe) so the user returns
+ * to where they were headed, plus a `stale=1` marker when a session cookie is
+ * present but invalid — the signal the middleware uses to clear the dead cookie.
+ */
+export function signInUrl(signInPath, opts) {
+    const params = new URLSearchParams();
+    const next = safeNextParam(opts.next);
+    if (next)
+        params.set("next", next);
+    if (opts.stale)
+        params.set("stale", "1");
+    const qs = params.toString();
+    return qs ? `${signInPath}?${qs}` : signInPath;
+}
+//# sourceMappingURL=gating-internals.js.map

package/dist/gating-internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gating-internals.js","sourceRoot":"","sources":["../src/gating-internals.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAgC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACxB,UAAkB,EAClB,IAA+C;IAE/C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AAChD,CAAC"}

package/dist/middleware.d.ts

@@ -15,6 +15,12 @@ export interface AuthMiddlewareConfig {
     frontDoorPaths?: string[];
     /** Destination for the front-door redirect. Required when `frontDoorPaths` is set. */
     signedInRedirect?: string;
+    /**
+     * Cookie-name fragment for the cookies cleared on a stale session. Default
+     * `better-auth`, which matches `better-auth.session_token` and the
+     * `__Secure-…` production variant.
+     */
+    sessionCookiePrefix?: string;
 }
 export declare function createAuthMiddleware(config: AuthMiddlewareConfig): (request: NextRequest) => NextResponse;
 //# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,IAwBrC,SAAS,WAAW,KAAG,YAAY,CAyB9D"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG7D,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,IAyBrC,SAAS,WAAW,KAAG,YAAY,CAoD9D"}

package/dist/middleware.js

@@ -14,17 +14,24 @@
  *
  *   The sign-in path is never the target of an optimistic redirect.
  *
- * It will only ever (a) push *cookie-less* requests off `protectedPaths`, and
- * optionally (b) push *cookie-bearing* requests off a front door to the app. It
- * refuses to protect or front-door the sign-in path, because either would
- * reintroduce the loop. Sending a *signed-in* user away from /login is the job
- * of `redirectIfAuthenticated` in the server helpers, which validates first.
+ * It also owns the two things only middleware can do here:
+ *
+ *  - **Preserve the destination.** When it sends an unauthenticated user to
+ *    sign-in, it appends `?next=<requested path>`; and it injects an
+ *    `x-nk-auth-path` request header so the server guards can do the same for
+ *    the cookie-present-but-invalid case (an RSC can't otherwise learn its URL).
+ *  - **Clear a stale cookie.** The guard parks an invalid session at
+ *    `${signInPath}?stale=1`; middleware (the only pre-render place that can set
+ *    cookies) deletes the dead Better Auth cookies and bounces to a clean
+ *    sign-in URL, so a bad session self-heals instead of failing every request.
  */
 import { getSessionCookie } from "better-auth/cookies";
 import { NextResponse } from "next/server";
+import { NK_AUTH_PATH_HEADER, safeNextParam } from "./gating-internals";
 export function createAuthMiddleware(config) {
     const signInPath = config.signInPath ?? "/login";
     const frontDoorPaths = config.frontDoorPaths ?? [];
+    const cookiePrefix = config.sessionCookiePrefix ?? "better-auth";
     // Loop-safety, enforced once at construction rather than hoped-for per
     // request. The sign-in path is where the validated guard parks an
     // invalid-but-present session; it must never be the target of an optimistic
@@ -39,22 +46,49 @@ export function createAuthMiddleware(config) {
         throw new Error("@ingram-tech/nk-auth: signedInRedirect is required when frontDoorPaths is set.");
     }
     return function middleware(request) {
-        const hasSessionCookie = !!getSessionCookie(request);
         const path = request.nextUrl.pathname;
+        // 1. Stale-session handshake. The validated guard sends an invalid session
+        //    to `${signInPath}?stale=1&next=…`. Clear the dead Better Auth cookies
+        //    (only middleware can, pre-render) and bounce to a clean sign-in URL
+        //    that keeps `next`. After this the cookie is gone, so it can't re-arm.
+        if (path === signInPath && request.nextUrl.searchParams.get("stale") === "1") {
+            const to = request.nextUrl.clone();
+            to.searchParams.delete("stale");
+            const res = NextResponse.redirect(to);
+            for (const cookie of request.cookies.getAll()) {
+                if (cookie.name.includes(cookiePrefix))
+                    res.cookies.delete(cookie.name);
+            }
+            return res;
+        }
+        const hasSessionCookie = !!getSessionCookie(request);
+        // 2. Unauthenticated (no cookie) on a protected path -> sign in, and
+        //    remember where they were going.
         if (!hasSessionCookie &&
             config.protectedPaths.some((p) => path.startsWith(p))) {
-            const url = request.nextUrl.clone();
-            url.pathname = signInPath;
-            return NextResponse.redirect(url);
+            const original = request.nextUrl.pathname + request.nextUrl.search;
+            const to = request.nextUrl.clone();
+            to.pathname = signInPath;
+            to.search = "";
+            const next = safeNextParam(original);
+            if (next)
+                to.searchParams.set("next", next);
+            return NextResponse.redirect(to);
         }
+        // 3. Front door: a cookie-bearing visit to "/" (or configured) -> the app.
         if (hasSessionCookie &&
             config.signedInRedirect &&
             frontDoorPaths.includes(path)) {
-            const url = request.nextUrl.clone();
-            url.pathname = config.signedInRedirect;
-            return NextResponse.redirect(url);
+            const to = request.nextUrl.clone();
+            to.pathname = config.signedInRedirect;
+            to.search = "";
+            return NextResponse.redirect(to);
         }
-        return NextResponse.next();
+        // 4. Pass through, injecting the requested path so server guards can build
+        //    `next` for the cookie-present-but-invalid case.
+        const requestHeaders = new Headers(request.headers);
+        requestHeaders.set(NK_AUTH_PATH_HEADER, path + request.nextUrl.search);
+        return NextResponse.next({ request: { headers: requestHeaders } });
     };
 }
 //# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAoB,YAAY,EAAE,MAAM,aAAa,CAAC;AAoB7D,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAChE,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,QAAQ,CAAC;IACjD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;IAEnD,uEAAuE;IACvE,kEAAkE;IAClE,4EAA4E;IAC5E,qCAAqC;IACrC,IAAI,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CACd,qCAAqC,UAAU,8FAA8F,CAC7I,CAAC;IACH,CAAC;IACD,IAAI,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACd,qCAAqC,UAAU,sFAAsF,CACrI,CAAC;IACH,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACd,gFAAgF,CAChF,CAAC;IACH,CAAC;IAED,OAAO,SAAS,UAAU,CAAC,OAAoB;QAC9C,MAAM,gBAAgB,GAAG,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;QAEtC,IACC,CAAC,gBAAgB;YACjB,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EACpD,CAAC;YACF,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACpC,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC;YAC1B,OAAO,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAED,IACC,gBAAgB;YAChB,MAAM,CAAC,gBAAgB;YACvB,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,EAC5B,CAAC;YACF,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACpC,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CAAC;YACvC,OAAO,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAED,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Validate a `next` redirect param: returns it only if it's an internal,
+ * non-protocol-relative path, else null. Use on the login page before honoring
+ * `?next=` so it can't become an open redirect.
+ */
+export { safeNextParam as safeNext } from "./gating-internals";
 /** The shape we need from a session: anything carrying a `user`. */
 interface SessionLike {
     user: unknown;
@@ -14,12 +20,21 @@ interface AuthLike<S extends SessionLike> {
         }) => Promise<S | null>;
     };
 }
-export declare function createAuthHelpers<S extends SessionLike>(auth: AuthLike<S>): {
+export interface AuthHelpersOptions {
+    /** Where guards send unauthenticated users. Default `/login`. */
+    signInPath?: string;
+    /**
+     * Cookie-name fragment that identifies the Better Auth session cookie, used
+     * to detect a present-but-invalid (stale) cookie. Default `better-auth`,
+     * which matches `better-auth.session_token` and `__Secure-…` in production.
+     */
+    sessionCookiePrefix?: string;
+}
+export declare function createAuthHelpers<S extends SessionLike>(auth: AuthLike<S>, options?: AuthHelpersOptions): {
     getSession: () => Promise<S | null>;
     getUser: () => Promise<S["user"] | null>;
-    requireSession: (redirectTo?: string) => Promise<S>;
-    requireUser: (redirectTo?: string) => Promise<S["user"]>;
+    requireSession: () => Promise<S>;
+    requireUser: () => Promise<S["user"]>;
     redirectIfAuthenticated: (to: string) => Promise<void>;
 };
-export {};
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAwBA,oEAAoE;AACpE,UAAU,WAAW;IACpB,IAAI,EAAE,OAAO,CAAC;CACd;AAED;;;;GAIG;AACH,UAAU,QAAQ,CAAC,CAAC,SAAS,WAAW;IACvC,GAAG,EAAE;QACJ,UAAU,EAAE,CAAC,KAAK,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;KAC/D,CAAC;CACF;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;sBAE5C,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;mBAgBpB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;6CARG,OAAO,CAAC,CAAC,CAAC;0CAkBb,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;kCAa1B,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;EAWjE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE/D,oEAAoE;AACpE,UAAU,WAAW;IACpB,IAAI,EAAE,OAAO,CAAC;CACd;AAED;;;;GAIG;AACH,UAAU,QAAQ,CAAC,CAAC,SAAS,WAAW;IACvC,GAAG,EAAE;QACJ,UAAU,EAAE,CAAC,KAAK,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;KAC/D,CAAC;CACF;AAED,MAAM,WAAW,kBAAkB;IAClC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACtD,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,OAAO,GAAE,kBAAuB;sBAMH,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;mBAKpB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;0BAkClB,OAAO,CAAC,CAAC,CAAC;uBAXb,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;kCAuBL,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;EAWjE"}

package/dist/server.js

@@ -7,53 +7,76 @@
  *   import { createAuthHelpers } from "@ingram-tech/nk-auth/server";
  *   import { auth } from "@/lib/auth";
  *
- *   export const { getSession, getUser, requireUser, redirectIfAuthenticated } =
- *     createAuthHelpers(auth);
+ *   export const { getSession, getUser, requireSession, requireUser,
+ *     redirectIfAuthenticated } = createAuthHelpers(auth);
  *
  * These are the **validated** authority: every call hits `auth.api.getSession`,
  * which checks the session against the database — not merely the presence of a
- * cookie. That distinction is the whole point. The optimistic, cookie-presence
+ * cookie. When a guard finds no valid session it redirects to the sign-in page,
+ * preserving the requested path as `next` (read from the header the middleware
+ * injects) and, when a session cookie is present-but-invalid, adding `stale=1`
+ * so the middleware clears the dead cookie. The optimistic, cookie-presence
  * check belongs in middleware (see "@ingram-tech/nk-auth/middleware"); it may
  * only ever push *unauthenticated* users off protected routes. The decision to
  * send a signed-in user *away* from the sign-in page must run through
- * `redirectIfAuthenticated` here, so a stale or revoked cookie resolves to "no
- * session" and falls through to the form instead of ping-ponging forever.
+ * `redirectIfAuthenticated` here, so a stale cookie resolves to "no session"
+ * and falls through to the form instead of ping-ponging forever.
  */
-import { headers } from "next/headers";
+import { cookies, headers } from "next/headers";
 import { redirect } from "next/navigation";
-export function createAuthHelpers(auth) {
+import { NK_AUTH_PATH_HEADER, signInUrl } from "./gating-internals";
+/**
+ * Validate a `next` redirect param: returns it only if it's an internal,
+ * non-protocol-relative path, else null. Use on the login page before honoring
+ * `?next=` so it can't become an open redirect.
+ */
+export { safeNextParam as safeNext } from "./gating-internals";
+export function createAuthHelpers(auth, options = {}) {
+    const signInPath = options.signInPath ?? "/login";
+    const cookiePrefix = options.sessionCookiePrefix ?? "better-auth";
     /** The validated session ({ user, session, … }) or null. */
     async function getSession() {
         return auth.api.getSession({ headers: await headers() });
     }
-    /**
-     * Require a session or redirect, returning the full validated session (use
-     * when the caller needs more than the user — session id, active org, …).
-     */
-    async function requireSession(redirectTo = "/login") {
-        const session = await getSession();
-        // redirect() is typed `never`, so `session` narrows to non-null below.
-        if (!session)
-            redirect(redirectTo);
-        return session;
-    }
     /** The authenticated user, or null. */
     async function getUser() {
         const session = await getSession();
         return session?.user ?? null;
     }
     /**
-     * Require a signed-in user or redirect. Returns the user (non-null) so
-     * callers keep their `const user = await requireUser()` shape. `redirect()`
+     * The sign-in redirect for a request with no valid session: keep the
+     * requested path as `next` (from the middleware-injected header), and flag
+     * `stale=1` when a session cookie is present-but-invalid so the middleware
+     * clears it. The two reads are request-scoped and cached by Next.
+     */
+    async function signInTarget() {
+        const [h, c] = await Promise.all([headers(), cookies()]);
+        const next = h.get(NK_AUTH_PATH_HEADER);
+        const stale = c.getAll().some((ck) => ck.name.includes(cookiePrefix));
+        return signInUrl(signInPath, { next, stale });
+    }
+    /**
+     * Require a signed-in user or redirect to sign-in. Returns the user (non-null)
+     * so callers keep their `const user = await requireUser()` shape. `redirect()`
      * throws, so control never returns when signed out.
      */
-    async function requireUser(redirectTo = "/login") {
+    async function requireUser() {
         const user = await getUser();
         // redirect() is typed `never`, so `user` narrows to non-null below.
         if (!user)
-            redirect(redirectTo);
+            redirect(await signInTarget());
         return user;
     }
+    /**
+     * Require a session or redirect, returning the full validated session (use
+     * when the caller needs more than the user — session id, active org, …).
+     */
+    async function requireSession() {
+        const session = await getSession();
+        if (!session)
+            redirect(await signInTarget());
+        return session;
+    }
     /**
      * Redirect an already-signed-in user away (e.g. /login -> /dashboard). This
      * is the *correct* place to gate the sign-in page: because it validates the

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAkB3C,MAAM,UAAU,iBAAiB,CAAwB,IAAiB;IACzE,4DAA4D;IAC5D,KAAK,UAAU,UAAU;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED;;;OAGG;IACH,KAAK,UAAU,cAAc,CAAC,UAAU,GAAG,QAAQ;QAClD,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,uEAAuE;QACvE,IAAI,CAAC,OAAO;YAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;QACnC,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,uCAAuC;IACvC,KAAK,UAAU,OAAO;QACrB,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,OAAO,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,KAAK,UAAU,WAAW,CAAC,UAAU,GAAG,QAAQ;QAC/C,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;QAC7B,oEAAoE;QACpE,IAAI,CAAC,IAAI;YAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;OAKG;IACH,KAAK,UAAU,uBAAuB,CAAC,EAAU;QAChD,IAAI,MAAM,UAAU,EAAE;YAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,OAAO;QACN,UAAU;QACV,OAAO;QACP,cAAc;QACd,WAAW;QACX,uBAAuB;KACvB,CAAC;AACH,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;GAIG;AACH,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AA6B/D,MAAM,UAAU,iBAAiB,CAChC,IAAiB,EACjB,UAA8B,EAAE;IAEhC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,QAAQ,CAAC;IAClD,MAAM,YAAY,GAAG,OAAO,CAAC,mBAAmB,IAAI,aAAa,CAAC;IAElE,4DAA4D;IAC5D,KAAK,UAAU,UAAU;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,uCAAuC;IACvC,KAAK,UAAU,OAAO;QACrB,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,OAAO,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC;IAC9B,CAAC;IAED;;;;;OAKG;IACH,KAAK,UAAU,YAAY;QAC1B,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;QACtE,OAAO,SAAS,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,KAAK,UAAU,WAAW;QACzB,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;QAC7B,oEAAoE;QACpE,IAAI,CAAC,IAAI;YAAE,QAAQ,CAAC,MAAM,YAAY,EAAE,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;OAGG;IACH,KAAK,UAAU,cAAc;QAC5B,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,OAAO;YAAE,QAAQ,CAAC,MAAM,YAAY,EAAE,CAAC,CAAC;QAC7C,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,KAAK,UAAU,uBAAuB,CAAC,EAAU;QAChD,IAAI,MAAM,UAAU,EAAE;YAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,OAAO;QACN,UAAU;QACV,OAAO;QACP,cAAc;QACd,WAAW;QACX,uBAAuB;KACvB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-auth",
-	"version": "0.6.0",
+	"version": "0.7.1",
 	"description": "The Ingram Better Auth foundation: composable presets (org, dual-shape JWT, Supabase RLS bridge, active-org hooks, pg pool) for Next.js sites.",
 	"license": "MIT",
 	"type": "module",
@@ -61,7 +61,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ingram-tech/nk-db": "^0.3.0",
+		"@ingram-tech/nk-db": "^0.4.0",
 		"bcrypt": "^6.0.0",
 		"jose": "^6.0.0",
 		"zod": "^4.0.0"
@@ -93,7 +93,7 @@
 	},
 	"devDependencies": {
 		"@better-auth/passkey": "^1.6.0",
-		"@ingram-tech/typescript-config": "workspace:*",
+		"@ingram-tech/typescript-config": "0.1.0",
 		"@supabase/supabase-js": "^2.45.0",
 		"@types/bcrypt": "^6.0.0",
 		"@types/node": "^25.0.0",