@ingram-tech/nk-auth 0.14.1 → 0.15.0

package/README.md

@@ -16,8 +16,8 @@ exactly one Better Auth copy in the app.
 | `createAuthPool` (`./pool`) | **deprecated** — alias of `createPool` from [`@ingram-tech/nk-db`](../nk-db); inject your app's shared pool instead |
 | `makeEmailSenders`, `makePasskeyOptions`, `passkeyOptionsForBaseUrl`, `uuidGenerateId` (`./`) | email hooks, passkeys (`passkeyOptionsForBaseUrl` derives `rpID`/`origin` from a single base URL), UUID ids |
 | `bcryptPassword` (`./`) | **legacy only** — bcrypt verifier for apps with pre-existing bcrypt hashes. New apps omit it (Better Auth defaults to scrypt). See [Migrating bcrypt passwords to scrypt](#migrating-bcrypt-passwords-to-scrypt) |
-| `createAuthHelpers`, `safeNext` (`./server`) | validated App Router session helpers (`getSession` / `getUser` / `requireSession` / `requireUser` / `redirectIfAuthenticated`), request-memoized via React `cache()`, 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 |
+| `createAuthHelpers`, `safeNext` (`./server`) | validated App Router session helpers (`getSession` / `getUser` / `requireSession` / `requireUser` / `signInTarget` / `redirectIfAuthenticated`), request-memoized via React `cache()`, with automatic `next` + stale-cookie signalling; `safeNext` validates a `?next=` param |
+| `createAuthMiddleware`, `withAuthPathHeader`, `clearStaleSession` (`./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; the last two are its `next`-header and stale-cookie halves, for a site with its own proxy |
 
 > **Data access + RLS** is owned by [`@ingram-tech/nk-db`](../nk-db); see §3.
 >
@@ -387,9 +387,52 @@ 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.
-An app that skips middleware still gets validated gating from the server helpers,
-just without automatic `next`/clearing.
+middleware injects.
+
+**Your own proxy.** An app that composes its own proxy (locale routing, tenant
+pinning, …) keeps validated gating from the server helpers, but the guards can
+only preserve `next` if something sets that header. Both halves of the
+middleware are exported on their own so a custom proxy adopts them without the
+optimistic gate; outside production the guards warn once when the header is
+missing, and `nk doctor` flags the shape.
+
+```ts
+// proxy.ts — a site with its own proxy
+import { clearStaleSession, withAuthPathHeader } from "@ingram-tech/nk-auth/middleware";
+import { localeProxy } from "@ingram-tech/nk-i18n/next";
+
+export function proxy(request: NextRequest) {
+	const stale = clearStaleSession(request, { signInPath: "/login" });
+	if (stale) return stale; // dead cookie cleared, `next` kept
+	const requestHeaders = new Headers(request.headers);
+	withAuthPathHeader(request, requestHeaders); // guards can now build `next`
+	return localeProxy(routing, request, { requestHeaders });
+}
+```
+
+(`createAuthMiddleware`'s middleware takes the same `{ requestHeaders }` option
+when you want the gate too.)
+
+**Your own guard.** A wrapper that layers something over `getUser()` (a profile
+lookup, say) redirects to `await signInTarget()`, the same URL `requireUser`
+would have used, with `next` and `stale` filled in:
+
+```ts
+const { getUser, signInTarget } = createAuthHelpers(auth);
+export async function requireProfile() {
+	const user = await getUser();
+	if (!user) redirect(await signInTarget());
+	return loadProfile(user.id);
+}
+```
+
+**Your own param.** Both `createAuthHelpers` and `createAuthMiddleware` take
+`nextParam` (default `next`) and `isSafeNext` (default `safeNext`, internal
+paths only). A site that already ships `?redirectTo=` with a trusted-origin
+allow-list passes `{ nextParam: "redirectTo", isSafeNext: isTrustedRedirect }`
+to both, and its sign-in page keeps validating with the same function. Whatever
+`isSafeNext` admits is where sign-in will send the user, so keep it as strict as
+`safeNext` on everything except the origins you own.
 
 ## 6. Passwords: change, set, and reset
 

package/dist/gating-internals.d.ts

@@ -21,12 +21,32 @@ export declare const NK_AUTH_PATH_HEADER = "x-nk-auth-path";
  */
 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.
+ * How a site names and validates its post-login redirect param. Shared by the
+ * middleware (which writes it for the cookie-less case) and the server helpers
+ * (which write it for the cookie-present-but-invalid case), so both halves agree
+ * on the one contract the sign-in page reads.
+ */
+export interface NextParamOptions {
+    /** Query param carrying the post-login destination. Default `next`. */
+    nextParam?: string;
+    /**
+     * Validate a candidate destination: return the value to redirect to, or null
+     * to drop it. Default {@link safeNextParam}, which admits only internal
+     * paths. A site with an existing trusted-origin allow-list plugs its own
+     * validator in here rather than forking the URL builder; whatever it admits
+     * is what its sign-in page will redirect to, so keep it as strict as
+     * `safeNextParam` on everything but the origins you own.
+     */
+    isSafeNext?: (value: string) => string | null;
+}
+/**
+ * Build a sign-in URL: `signInPath`, plus the next param (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;
+} & NextParamOptions): string;
 //# sourceMappingURL=gating-internals.d.ts.map

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

@@ -1 +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;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAM7E;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"}
+{"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;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAM7E;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;GAKG;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,GAAG,gBAAgB,GAChE,MAAM,CAQR"}

package/dist/gating-internals.js

@@ -30,15 +30,17 @@ export function safeNextParam(value) {
     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.
+ * Build a sign-in URL: `signInPath`, plus the next param (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);
+    const validate = opts.isSafeNext ?? safeNextParam;
+    const next = opts.next ? validate(opts.next) : null;
     if (next)
-        params.set("next", next);
+        params.set(opts.nextParam ?? "next", next);
     if (opts.stale)
         params.set("stale", "1");
     const qs = params.toString();

package/dist/gating-internals.js.map

@@ -1 +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;;;;;;;;GAQG;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,oFAAoF;IACpF,IAAI,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,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"}
+{"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;;;;;;;;GAQG;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,oFAAoF;IACpF,IAAI,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,OAAO,KAAK,CAAC;AACd,CAAC;AAsBD;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACxB,UAAkB,EAClB,IAAkE;IAElE,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,IAAI,aAAa,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,MAAM,EAAE,IAAI,CAAC,CAAC;IACrD,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

@@ -1,5 +1,47 @@
 import { type NextRequest, NextResponse } from "next/server";
-export interface AuthMiddlewareConfig {
+import { type NextParamOptions } from "./gating-internals.js";
+export type { NextParamOptions } from "./gating-internals.js";
+/**
+ * Forward the requested path + query to the app as the `x-nk-auth-path` request
+ * header, so a server guard can build `next` when it redirects to sign-in. The
+ * one line a custom proxy needs for `next` preservation:
+ *
+ *   const requestHeaders = new Headers(request.headers);
+ *   withAuthPathHeader(request, requestHeaders);
+ *   return localeProxy(routing, request, { requestHeaders });
+ *
+ * Set, never passed through: the header is ours to mint, so a client that sends
+ * one of its own can't choose where sign-in returns to.
+ */
+export declare function withAuthPathHeader(request: NextRequest, requestHeaders: Headers): void;
+export interface StaleSessionConfig {
+    /** The sign-in path the server guards redirect to. Default `/login`. */
+    signInPath?: string;
+    /** Cookie-name fragment of the cookies to clear. Default `better-auth`. */
+    sessionCookiePrefix?: string;
+}
+/**
+ * The stale-session handshake, on its own for a custom proxy. The validated
+ * guard sends a present-but-invalid session to `${signInPath}?stale=1&next=…`;
+ * this clears the dead Better Auth cookies (only middleware can, pre-render) and
+ * returns a redirect to the same URL minus `stale`, which keeps `next`. Returns
+ * null on every other request, so a proxy can short-circuit on it:
+ *
+ *   const stale = clearStaleSession(request, { signInPath: "/login" });
+ *   if (stale) return stale;
+ *
+ * After the redirect the cookie is gone, so the handshake can't re-arm.
+ */
+export declare function clearStaleSession(request: NextRequest, config?: StaleSessionConfig): NextResponse | null;
+export interface AuthMiddlewareOptions {
+    /**
+     * Headers to forward to the app, if the middleware has its own to add. A
+     * fresh copy of the request's headers is used when omitted; pass your own
+     * when you also set things like a tenant or locale header.
+     */
+    requestHeaders?: Headers;
+}
+export interface AuthMiddlewareConfig extends NextParamOptions {
     /**
      * Path prefixes that require a session. A request without a session cookie
      * to any of these is redirected to `signInPath`. Matched with `startsWith`.
@@ -22,5 +64,5 @@ export interface AuthMiddlewareConfig {
      */
     sessionCookiePrefix?: string;
 }
-export declare function createAuthMiddleware(config: AuthMiddlewareConfig): (request: NextRequest) => NextResponse;
+export declare function createAuthMiddleware(config: AuthMiddlewareConfig): (request: NextRequest, options?: AuthMiddlewareOptions) => 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":"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,aAiC5B,WAAW,KAAG,YAAY,CA6D9D"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAEN,KAAK,gBAAgB,EAErB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,WAAW,EACpB,cAAc,EAAE,OAAO,GACrB,IAAI,CAKN;AAED,MAAM,WAAW,kBAAkB;IAClC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,WAAW,EACpB,MAAM,GAAE,kBAAuB,GAC7B,YAAY,GAAG,IAAI,CA4BrB;AAED,MAAM,WAAW,qBAAqB;IACrC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC7D;;;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,aAkCtD,WAAW,YACX,qBAAqB,KAC5B,YAAY,CAgDf"}

package/dist/middleware.js

@@ -24,10 +24,70 @@
  *    `${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.
+ *
+ * Both halves are also exported on their own — {@link withAuthPathHeader} and
+ * {@link clearStaleSession} — for a site whose proxy composes several concerns
+ * (locale routing, tenant pinning, …) and does not want the optimistic gate.
+ * Without the header the server guards cannot preserve `next` at all, and they
+ * say so (a one-time warning outside production); wiring one line into your own
+ * proxy is enough to fix that.
  */
 import { getSessionCookie } from "better-auth/cookies";
 import { NextResponse } from "next/server";
-import { NK_AUTH_PATH_HEADER, safeNextParam } from "./gating-internals.js";
+import { NK_AUTH_PATH_HEADER, signInUrl, } from "./gating-internals.js";
+/**
+ * Forward the requested path + query to the app as the `x-nk-auth-path` request
+ * header, so a server guard can build `next` when it redirects to sign-in. The
+ * one line a custom proxy needs for `next` preservation:
+ *
+ *   const requestHeaders = new Headers(request.headers);
+ *   withAuthPathHeader(request, requestHeaders);
+ *   return localeProxy(routing, request, { requestHeaders });
+ *
+ * Set, never passed through: the header is ours to mint, so a client that sends
+ * one of its own can't choose where sign-in returns to.
+ */
+export function withAuthPathHeader(request, requestHeaders) {
+    requestHeaders.set(NK_AUTH_PATH_HEADER, request.nextUrl.pathname + request.nextUrl.search);
+}
+/**
+ * The stale-session handshake, on its own for a custom proxy. The validated
+ * guard sends a present-but-invalid session to `${signInPath}?stale=1&next=…`;
+ * this clears the dead Better Auth cookies (only middleware can, pre-render) and
+ * returns a redirect to the same URL minus `stale`, which keeps `next`. Returns
+ * null on every other request, so a proxy can short-circuit on it:
+ *
+ *   const stale = clearStaleSession(request, { signInPath: "/login" });
+ *   if (stale) return stale;
+ *
+ * After the redirect the cookie is gone, so the handshake can't re-arm.
+ */
+export function clearStaleSession(request, config = {}) {
+    const signInPath = config.signInPath ?? "/login";
+    const cookiePrefix = config.sessionCookiePrefix ?? "better-auth";
+    if (request.nextUrl.pathname !== signInPath ||
+        request.nextUrl.searchParams.get("stale") !== "1") {
+        return null;
+    }
+    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)) {
+            // `__Secure-`/`__Host-` cookies: browsers reject the deletion
+            // Set-Cookie unless it carries the Secure attribute itself, so a
+            // bare delete() would silently leave the dead cookie in place on
+            // HTTPS and re-run this handshake on every visit.
+            res.cookies.delete({
+                name: cookie.name,
+                path: "/",
+                secure: cookie.name.startsWith("__Secure-") ||
+                    cookie.name.startsWith("__Host-"),
+            });
+        }
+    }
+    return res;
+}
 export function createAuthMiddleware(config) {
     const signInPath = config.signInPath ?? "/login";
     const frontDoorPaths = config.frontDoorPaths ?? [];
@@ -51,32 +111,16 @@ export function createAuthMiddleware(config) {
     if (frontDoorPaths.length > 0 && !config.signedInRedirect) {
         throw new Error("@ingram-tech/nk-auth: signedInRedirect is required when frontDoorPaths is set.");
     }
-    return function middleware(request) {
+    return function middleware(request, options = {}) {
         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)) {
-                    // `__Secure-`/`__Host-` cookies: browsers reject the deletion
-                    // Set-Cookie unless it carries the Secure attribute itself, so a
-                    // bare delete() would silently leave the dead cookie in place on
-                    // HTTPS and re-run this handshake on every visit.
-                    res.cookies.delete({
-                        name: cookie.name,
-                        path: "/",
-                        secure: cookie.name.startsWith("__Secure-") ||
-                            cookie.name.startsWith("__Host-"),
-                    });
-                }
-            }
-            return res;
-        }
+        // 1. Stale-session handshake: clear the dead cookies and bounce to a clean
+        //    sign-in URL that keeps `next`.
+        const stale = clearStaleSession(request, {
+            signInPath,
+            sessionCookiePrefix: cookiePrefix,
+        });
+        if (stale)
+            return stale;
         const hasSessionCookie = !!getSessionCookie(request);
         // 2. Unauthenticated (no cookie) on a protected path -> sign in, and
         //    remember where they were going.
@@ -84,10 +128,11 @@ export function createAuthMiddleware(config) {
             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);
+            to.search = new URL(signInUrl(signInPath, {
+                next: original,
+                nextParam: config.nextParam,
+                isSafeNext: config.isSafeNext,
+            }), request.nextUrl).search;
             return NextResponse.redirect(to);
         }
         // 3. Front door: a cookie-bearing visit to "/" (or configured) -> the app.
@@ -101,8 +146,8 @@ export function createAuthMiddleware(config) {
         }
         // 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);
+        const requestHeaders = options.requestHeaders ?? new Headers(request.headers);
+        withAuthPathHeader(request, requestHeaders);
         return NextResponse.next({ request: { headers: requestHeaders } });
     };
 }

package/dist/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -25,12 +25,14 @@
  * and falls through to the form instead of ping-ponging forever.
  */
 import type { IdHelper } from "@ingram-tech/nk-db/id";
+import { type NextParamOptions } from "./gating-internals.js";
 /**
  * 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.js";
+export type { NextParamOptions } from "./gating-internals.js";
 /** The shape we need from a session: anything carrying a `user`. */
 interface SessionLike {
     user: unknown;
@@ -69,7 +71,7 @@ export interface SessionIds {
     user: IdHelper;
     organization?: IdHelper;
 }
-export interface AuthHelpersOptions {
+export interface AuthHelpersOptions extends NextParamOptions {
     /** Where guards send unauthenticated users. Default `/login`. */
     signInPath?: string;
     /**
@@ -97,6 +99,7 @@ export declare function createAuthHelpers<S extends SessionLike>(auth: AuthLike<
     getUser: () => Promise<S["user"] | null>;
     requireSession: () => Promise<S>;
     requireUser: () => Promise<S["user"]>;
+    signInTarget: () => Promise<string>;
     redirectIfAuthenticated: (to: string) => Promise<void>;
     getLinkedProviders: () => Promise<string[]>;
     hasCredentialAccount: () => Promise<boolean>;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAOtD;;;;GAIG;AACH,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAElE,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;QAC/D;;;;;WAKG;QACH,gBAAgB,EAAE,CAAC,KAAK,EAAE;YACzB,OAAO,EAAE,OAAO,CAAC;SACjB,KAAK,OAAO,CAAC,KAAK,CAAC;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC,CAAC;KAC7C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,CAAC,EAAE,QAAQ,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IAClC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACrD,OAAO,EAAE,CAAC,EACV,GAAG,EAAE,UAAU,GACb,CAAC,CAyBH;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACtD,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,OAAO,GAAE,kBAAuB;sBAiBG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;mBAQ1B,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;8BAU5B,OAAO,CAAC,MAAM,EAAE,CAAC;gCAcf,OAAO,CAAC,OAAO,CAAC;EAcvD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAItD,OAAO,EAEN,KAAK,gBAAgB,EAErB,MAAM,uBAAuB,CAAC;AAG/B;;;;GAIG;AACH,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,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;QAC/D;;;;;WAKG;QACH,gBAAgB,EAAE,CAAC,KAAK,EAAE;YACzB,OAAO,EAAE,OAAO,CAAC;SACjB,KAAK,OAAO,CAAC,KAAK,CAAC;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC,CAAC;KAC7C,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,CAAC,EAAE,QAAQ,CAAC;CACxB;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC3D,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACrD,OAAO,EAAE,CAAC,EACV,GAAG,EAAE,UAAU,GACb,CAAC,CAyBH;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACtD,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,OAAO,GAAE,kBAAuB;sBAiBG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;mBAQ1B,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;0BA+DlB,OAAO,CAAC,CAAC,CAAC;uBAXb,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;wBA3BjB,OAAO,CAAC,MAAM,CAAC;kCAkDH,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;8BAU5B,OAAO,CAAC,MAAM,EAAE,CAAC;gCAcf,OAAO,CAAC,OAAO,CAAC;EAevD"}

package/dist/server.js

@@ -1,7 +1,7 @@
 import { cookies, headers } from "next/headers";
 import { redirect } from "next/navigation";
 import { cache } from "react";
-import { NK_AUTH_PATH_HEADER, signInUrl } from "./gating-internals.js";
+import { NK_AUTH_PATH_HEADER, signInUrl, } from "./gating-internals.js";
 import { CREDENTIAL_PROVIDER_ID } from "./password.js";
 /**
  * Validate a `next` redirect param: returns it only if it's an internal,
@@ -65,17 +65,41 @@ export function createAuthHelpers(auth, options = {}) {
         const session = await getSession();
         return session?.user ?? null;
     }
+    // The missing-header warning fires once per helpers instance, not once per
+    // request: it is a wiring mistake, and a wiring mistake does not get less
+    // wrong the second time.
+    let warnedMissingHeader = false;
     /**
      * 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.
+     *
+     * Exported for a site that wraps the guards in its own (a profile lookup on
+     * top of `getUser()`, say): `redirect(await signInTarget())` gets `next` and
+     * `stale` right without re-deriving either.
+     *
+     * `next` depends on the `x-nk-auth-path` header, which only middleware can
+     * set. When it is absent the destination is silently lost — the user signs in
+     * and lands on the default page instead of the one they asked for — so
+     * outside production this says so once, naming the two ways to wire it.
      */
     async function signInTarget() {
         const [h, c] = await Promise.all([headers(), cookies()]);
         const next = h.get(NK_AUTH_PATH_HEADER);
+        if (next === null &&
+            !warnedMissingHeader &&
+            process.env.NODE_ENV !== "production") {
+            warnedMissingHeader = true;
+            console.warn(`@ingram-tech/nk-auth: \`next\` not preserved — no ${NK_AUTH_PATH_HEADER} request header. Mount createAuthMiddleware, or call withAuthPathHeader(request, requestHeaders) from "@ingram-tech/nk-auth/middleware" in your own proxy.`);
+        }
         const stale = c.getAll().some((ck) => ck.name.includes(cookiePrefix));
-        return signInUrl(signInPath, { next, stale });
+        return signInUrl(signInPath, {
+            next,
+            stale,
+            nextParam: options.nextParam,
+            isSafeNext: options.isSafeNext,
+        });
     }
     /**
      * Require a signed-in user or redirect to sign-in. Returns the user (non-null)
@@ -137,6 +161,7 @@ export function createAuthHelpers(auth, options = {}) {
         getUser,
         requireSession,
         requireUser,
+        signInTarget,
         redirectIfAuthenticated,
         getLinkedProviders,
         hasCredentialAccount,

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-auth",
-	"version": "0.14.1",
+	"version": "0.15.0",
 	"description": "The Ingram Better Auth foundation: composable presets (org, dual-shape JWT, active-org hooks, pg pool) for Next.js sites.",
 	"license": "MIT",
 	"type": "module",
@@ -96,7 +96,7 @@
 	},
 	"devDependencies": {
 		"@better-auth/passkey": "^1.7.0",
-		"@ingram-tech/nk-dev": "0.13.1",
+		"@ingram-tech/nk-dev": "0.14.0",
 		"@types/bcrypt": "^6.0.0",
 		"@types/node": "^26.2.0",
 		"@types/pg": "^8.23.1",

package/src/gating-internals.ts

@@ -30,17 +30,39 @@ export 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.
+ * How a site names and validates its post-login redirect param. Shared by the
+ * middleware (which writes it for the cookie-less case) and the server helpers
+ * (which write it for the cookie-present-but-invalid case), so both halves agree
+ * on the one contract the sign-in page reads.
+ */
+export interface NextParamOptions {
+	/** Query param carrying the post-login destination. Default `next`. */
+	nextParam?: string;
+	/**
+	 * Validate a candidate destination: return the value to redirect to, or null
+	 * to drop it. Default {@link safeNextParam}, which admits only internal
+	 * paths. A site with an existing trusted-origin allow-list plugs its own
+	 * validator in here rather than forking the URL builder; whatever it admits
+	 * is what its sign-in page will redirect to, so keep it as strict as
+	 * `safeNextParam` on everything but the origins you own.
+	 */
+	isSafeNext?: (value: string) => string | null;
+}
+
+/**
+ * Build a sign-in URL: `signInPath`, plus the next param (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: string,
-	opts: { next?: string | null; stale?: boolean },
+	opts: { next?: string | null; stale?: boolean } & NextParamOptions,
 ): string {
 	const params = new URLSearchParams();
-	const next = safeNextParam(opts.next);
-	if (next) params.set("next", next);
+	const validate = opts.isSafeNext ?? safeNextParam;
+	const next = opts.next ? validate(opts.next) : null;
+	if (next) params.set(opts.nextParam ?? "next", next);
 	if (opts.stale) params.set("stale", "1");
 	const qs = params.toString();
 	return qs ? `${signInPath}?${qs}` : signInPath;

package/src/middleware.ts

@@ -24,12 +24,108 @@
  *    `${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.
+ *
+ * Both halves are also exported on their own — {@link withAuthPathHeader} and
+ * {@link clearStaleSession} — for a site whose proxy composes several concerns
+ * (locale routing, tenant pinning, …) and does not want the optimistic gate.
+ * Without the header the server guards cannot preserve `next` at all, and they
+ * say so (a one-time warning outside production); wiring one line into your own
+ * proxy is enough to fix that.
  */
 import { getSessionCookie } from "better-auth/cookies";
 import { type NextRequest, NextResponse } from "next/server";
-import { NK_AUTH_PATH_HEADER, safeNextParam } from "./gating-internals.js";
+import {
+	NK_AUTH_PATH_HEADER,
+	type NextParamOptions,
+	signInUrl,
+} from "./gating-internals.js";
+
+export type { NextParamOptions } from "./gating-internals.js";
+
+/**
+ * Forward the requested path + query to the app as the `x-nk-auth-path` request
+ * header, so a server guard can build `next` when it redirects to sign-in. The
+ * one line a custom proxy needs for `next` preservation:
+ *
+ *   const requestHeaders = new Headers(request.headers);
+ *   withAuthPathHeader(request, requestHeaders);
+ *   return localeProxy(routing, request, { requestHeaders });
+ *
+ * Set, never passed through: the header is ours to mint, so a client that sends
+ * one of its own can't choose where sign-in returns to.
+ */
+export function withAuthPathHeader(
+	request: NextRequest,
+	requestHeaders: Headers,
+): void {
+	requestHeaders.set(
+		NK_AUTH_PATH_HEADER,
+		request.nextUrl.pathname + request.nextUrl.search,
+	);
+}
+
+export interface StaleSessionConfig {
+	/** The sign-in path the server guards redirect to. Default `/login`. */
+	signInPath?: string;
+	/** Cookie-name fragment of the cookies to clear. Default `better-auth`. */
+	sessionCookiePrefix?: string;
+}
+
+/**
+ * The stale-session handshake, on its own for a custom proxy. The validated
+ * guard sends a present-but-invalid session to `${signInPath}?stale=1&next=…`;
+ * this clears the dead Better Auth cookies (only middleware can, pre-render) and
+ * returns a redirect to the same URL minus `stale`, which keeps `next`. Returns
+ * null on every other request, so a proxy can short-circuit on it:
+ *
+ *   const stale = clearStaleSession(request, { signInPath: "/login" });
+ *   if (stale) return stale;
+ *
+ * After the redirect the cookie is gone, so the handshake can't re-arm.
+ */
+export function clearStaleSession(
+	request: NextRequest,
+	config: StaleSessionConfig = {},
+): NextResponse | null {
+	const signInPath = config.signInPath ?? "/login";
+	const cookiePrefix = config.sessionCookiePrefix ?? "better-auth";
+	if (
+		request.nextUrl.pathname !== signInPath ||
+		request.nextUrl.searchParams.get("stale") !== "1"
+	) {
+		return null;
+	}
+	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)) {
+			// `__Secure-`/`__Host-` cookies: browsers reject the deletion
+			// Set-Cookie unless it carries the Secure attribute itself, so a
+			// bare delete() would silently leave the dead cookie in place on
+			// HTTPS and re-run this handshake on every visit.
+			res.cookies.delete({
+				name: cookie.name,
+				path: "/",
+				secure:
+					cookie.name.startsWith("__Secure-") ||
+					cookie.name.startsWith("__Host-"),
+			});
+		}
+	}
+	return res;
+}
 
-export interface AuthMiddlewareConfig {
+export interface AuthMiddlewareOptions {
+	/**
+	 * Headers to forward to the app, if the middleware has its own to add. A
+	 * fresh copy of the request's headers is used when omitted; pass your own
+	 * when you also set things like a tenant or locale header.
+	 */
+	requestHeaders?: Headers;
+}
+
+export interface AuthMiddlewareConfig extends NextParamOptions {
 	/**
 	 * Path prefixes that require a session. A request without a session cookie
 	 * to any of these is redirected to `signInPath`. Matched with `startsWith`.
@@ -86,34 +182,19 @@ export function createAuthMiddleware(config: AuthMiddlewareConfig) {
 		);
 	}
 
-	return function middleware(request: NextRequest): NextResponse {
+	return function middleware(
+		request: NextRequest,
+		options: AuthMiddlewareOptions = {},
+	): NextResponse {
 		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)) {
-					// `__Secure-`/`__Host-` cookies: browsers reject the deletion
-					// Set-Cookie unless it carries the Secure attribute itself, so a
-					// bare delete() would silently leave the dead cookie in place on
-					// HTTPS and re-run this handshake on every visit.
-					res.cookies.delete({
-						name: cookie.name,
-						path: "/",
-						secure:
-							cookie.name.startsWith("__Secure-") ||
-							cookie.name.startsWith("__Host-"),
-					});
-				}
-			}
-			return res;
-		}
+		// 1. Stale-session handshake: clear the dead cookies and bounce to a clean
+		//    sign-in URL that keeps `next`.
+		const stale = clearStaleSession(request, {
+			signInPath,
+			sessionCookiePrefix: cookiePrefix,
+		});
+		if (stale) return stale;
 
 		const hasSessionCookie = !!getSessionCookie(request);
 
@@ -123,9 +204,14 @@ export function createAuthMiddleware(config: AuthMiddlewareConfig) {
 			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);
+			to.search = new URL(
+				signInUrl(signInPath, {
+					next: original,
+					nextParam: config.nextParam,
+					isSafeNext: config.isSafeNext,
+				}),
+				request.nextUrl,
+			).search;
 			return NextResponse.redirect(to);
 		}
 
@@ -143,8 +229,8 @@ export function createAuthMiddleware(config: AuthMiddlewareConfig) {
 
 		// 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);
+		const requestHeaders = options.requestHeaders ?? new Headers(request.headers);
+		withAuthPathHeader(request, requestHeaders);
 		return NextResponse.next({ request: { headers: requestHeaders } });
 	};
 }

package/src/server.ts

@@ -28,7 +28,11 @@ import type { IdHelper } from "@ingram-tech/nk-db/id";
 import { cookies, headers } from "next/headers";
 import { redirect } from "next/navigation";
 import { cache } from "react";
-import { NK_AUTH_PATH_HEADER, signInUrl } from "./gating-internals.js";
+import {
+	NK_AUTH_PATH_HEADER,
+	type NextParamOptions,
+	signInUrl,
+} from "./gating-internals.js";
 import { CREDENTIAL_PROVIDER_ID } from "./password.js";
 
 /**
@@ -37,6 +41,7 @@ import { CREDENTIAL_PROVIDER_ID } from "./password.js";
  * `?next=` so it can't become an open redirect.
  */
 export { safeNextParam as safeNext } from "./gating-internals.js";
+export type { NextParamOptions } from "./gating-internals.js";
 
 /** The shape we need from a session: anything carrying a `user`. */
 interface SessionLike {
@@ -75,7 +80,7 @@ export interface SessionIds {
 	organization?: IdHelper;
 }
 
-export interface AuthHelpersOptions {
+export interface AuthHelpersOptions extends NextParamOptions {
 	/** Where guards send unauthenticated users. Default `/login`. */
 	signInPath?: string;
 	/**
@@ -163,17 +168,46 @@ export function createAuthHelpers<S extends SessionLike>(
 		return session?.user ?? null;
 	}
 
+	// The missing-header warning fires once per helpers instance, not once per
+	// request: it is a wiring mistake, and a wiring mistake does not get less
+	// wrong the second time.
+	let warnedMissingHeader = false;
+
 	/**
 	 * 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.
+	 *
+	 * Exported for a site that wraps the guards in its own (a profile lookup on
+	 * top of `getUser()`, say): `redirect(await signInTarget())` gets `next` and
+	 * `stale` right without re-deriving either.
+	 *
+	 * `next` depends on the `x-nk-auth-path` header, which only middleware can
+	 * set. When it is absent the destination is silently lost — the user signs in
+	 * and lands on the default page instead of the one they asked for — so
+	 * outside production this says so once, naming the two ways to wire it.
 	 */
 	async function signInTarget(): Promise<string> {
 		const [h, c] = await Promise.all([headers(), cookies()]);
 		const next = h.get(NK_AUTH_PATH_HEADER);
+		if (
+			next === null &&
+			!warnedMissingHeader &&
+			process.env.NODE_ENV !== "production"
+		) {
+			warnedMissingHeader = true;
+			console.warn(
+				`@ingram-tech/nk-auth: \`next\` not preserved — no ${NK_AUTH_PATH_HEADER} request header. Mount createAuthMiddleware, or call withAuthPathHeader(request, requestHeaders) from "@ingram-tech/nk-auth/middleware" in your own proxy.`,
+			);
+		}
 		const stale = c.getAll().some((ck) => ck.name.includes(cookiePrefix));
-		return signInUrl(signInPath, { next, stale });
+		return signInUrl(signInPath, {
+			next,
+			stale,
+			nextParam: options.nextParam,
+			isSafeNext: options.isSafeNext,
+		});
 	}
 
 	/**
@@ -238,6 +272,7 @@ export function createAuthHelpers<S extends SessionLike>(
 		getUser,
 		requireSession,
 		requireUser,
+		signInTarget,
 		redirectIfAuthenticated,
 		getLinkedProviders,
 		hasCredentialAccount,