@ingram-tech/nk-auth 0.13.5 → 0.13.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-auth",
-	"version": "0.13.5",
+	"version": "0.13.6",
 	"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",
@@ -14,6 +14,9 @@
 	},
 	"files": [
 		"dist",
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx",
 		"migrations"
 	],
 	"exports": {
@@ -65,7 +68,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ingram-tech/nk-db": "^1.6.0",
+		"@ingram-tech/nk-db": "^2.0.0",
 		"bcrypt": "^6.0.0",
 		"jose": "^6.2.9",
 		"zod": "^4.4.3"
@@ -93,7 +96,7 @@
 	},
 	"devDependencies": {
 		"@better-auth/passkey": "^1.7.0",
-		"@ingram-tech/nk-dev": "0.11.1",
+		"@ingram-tech/nk-dev": "0.12.0",
 		"@types/bcrypt": "^6.0.0",
 		"@types/node": "^26.2.0",
 		"@types/pg": "^8.23.1",

package/src/client.ts

@@ -0,0 +1,44 @@
+/**
+ * Browser auth re-exports, at "@ingram-tech/nk-auth/client" so the server entry
+ * never pulls in React. A site builds its own client to preserve full plugin
+ * type inference:
+ *
+ *   "use client";
+ *   import {
+ *     createAuthClient, jwtClient, passkeyClient,
+ *   } from "@ingram-tech/nk-auth/client";
+ *
+ *   export const authClient = createAuthClient({
+ *     baseURL: process.env.NEXT_PUBLIC_SITE_URL,
+ *     plugins: [jwtClient(), passkeyClient()],
+ *   });
+ *
+ * This exposes the client auth call surface:
+ *   signUp.email / signIn.email / signIn.social / signOut / useSession,
+ *   plus passkey.* (register / authenticate).
+ */
+export { passkeyClient } from "@better-auth/passkey/client";
+export { jwtClient } from "better-auth/client/plugins";
+export { createAuthClient } from "better-auth/react";
+// Password-policy primitives (pure), so a reset form validates against the same
+// bounds the server enforces without a second import.
+export {
+	CREDENTIAL_PROVIDER_ID,
+	DEFAULT_MAX_PASSWORD_LENGTH,
+	DEFAULT_MIN_PASSWORD_LENGTH,
+	type PasswordPolicy,
+	passwordSchema,
+	type ResetPasswordError,
+	type ResetPasswordErrorCode,
+	validateNewPassword,
+} from "./password.js";
+// Re-exported here too so the client can set `basePath` without a server import.
+export { authBasePath } from "./paths.js";
+// Headless reset-/set-password controller (React hook); the site brings the shell.
+export {
+	type ResetPasswordClient,
+	type ResetPasswordStatus,
+	type UseResetPassword,
+	type UseResetPasswordOptions,
+	useResetPassword,
+} from "./reset-password.js";

package/src/gating-internals.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ *
+ * Beyond the `//` check, backslashes and ASCII controls must also be rejected:
+ * browsers treat `\` as `/` in http(s) URLs (so `/\evil.com` resolves to
+ * `https://evil.com/`) and the URL parser strips tab/newline (so an encoded
+ * `/\t/evil.com` collapses to `//evil.com`).
+ */
+export function safeNextParam(value: string | null | undefined): string | null {
+	if (!value) return null;
+	if (!value.startsWith("/") || value.startsWith("//")) return null;
+	// oxlint-disable-next-line no-control-regex -- rejecting control chars is the point
+	if (/[\\\u0000-\u001f\u007f]/.test(value)) 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: string,
+	opts: { next?: string | null; stale?: boolean },
+): string {
+	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;
+}

package/src/id.ts

@@ -0,0 +1,12 @@
+// The Ingram id codec is the standalone `id758` package, re-exported via
+// `@ingram-tech/nk-db/id` — the lowest package in
+// the graph — so a site can mint ids without pulling this auth slice. This
+// re-export keeps `@ingram-tech/nk-auth/id` (and Better Auth's
+// `advanced.database.generateId`, wired in `./options`) working unchanged. For
+// the typed prefix registry (`createIdRegistry`), import from `@ingram-tech/nk-db/id`.
+export {
+	base58Id,
+	fromPrefixedId,
+	toPrefixedId,
+	uuidGenerateId,
+} from "@ingram-tech/nk-db/id";

package/src/index.ts

@@ -0,0 +1,36 @@
+// Server entry — the Ingram Better Auth foundation. Browser re-exports live at
+// "@ingram-tech/nk-auth/client" so importing the server presets never pulls in
+// React. Focused subpaths (./jwt, ./organization, ./pool) let a site import
+// only what it needs (e.g. avoid bcrypt when it doesn't use passwords).
+
+export { type BackendJwtConfig, backendJwtOptions, verifyBackendJwt } from "./jwt.js";
+export { base58Id, fromPrefixedId, toPrefixedId, uuidGenerateId } from "./id.js";
+export { type AuthEnv, authEnv, authSecret, isConfigured } from "./keys.js";
+export {
+	type AuthEmailKind,
+	type AuthEmailMessage,
+	type AuthEmailUser,
+	bcryptPassword,
+	makeEmailSenders,
+	makePasskeyOptions,
+	type PasskeyConfig,
+	passkeyOptionsForBaseUrl,
+	type SendEmail,
+} from "./options.js";
+export {
+	lastActiveOrganizationHooks,
+	lastActiveOrganizationUserField,
+	nkOrganizationDefaults,
+} from "./organization.js";
+export {
+	CREDENTIAL_PROVIDER_ID,
+	DEFAULT_MAX_PASSWORD_LENGTH,
+	DEFAULT_MIN_PASSWORD_LENGTH,
+	type PasswordPolicy,
+	passwordSchema,
+	type ResetPasswordError,
+	type ResetPasswordErrorCode,
+	validateNewPassword,
+} from "./password.js";
+export { authBasePath } from "./paths.js";
+export { createAuthPool } from "./pool.js";

package/src/jwt.ts

@@ -0,0 +1,100 @@
+import type { JwtOptions } from "better-auth/plugins/jwt";
+import {
+	createRemoteJWKSet,
+	errors as joseErrors,
+	type JWTPayload,
+	jwtVerify,
+} from "jose";
+
+/**
+ * `jwt` plugin preset for a site's OWN backend API: a short-lived token with a
+ * specific `audience`, typically carrying extra claims the site adds via
+ * `auth.api.signJWT`. Defaults to EdDSA (Better Auth's default), with the JWKS
+ * exposed at `/api/auth/jwks` so the backend can verify it (`verifyBackendJwt`).
+ */
+
+export interface BackendJwtConfig {
+	/** Expected audience of the site's backend, e.g. "my-app-backend". */
+	audience: string;
+	/** Token lifetime, e.g. "15m". */
+	expirationTime?: string;
+	/**
+	 * Don't auto-attach the JWT to the `set-auth-jwt` response header — set when
+	 * the site mints tokens on demand via `auth.api.signJWT` instead.
+	 */
+	disableSettingJwtHeader?: boolean;
+}
+
+/** `jwt` plugin options for a backend-API token (custom audience). */
+export const backendJwtOptions = (config: BackendJwtConfig): JwtOptions => ({
+	disableSettingJwtHeader: config.disableSettingJwtHeader,
+	jwt: {
+		audience: config.audience,
+		expirationTime: config.expirationTime,
+	},
+});
+
+const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+// Forced-reload throttle (per JWKS URL). The no-matching-key path is reachable
+// by anyone who can send a request with a made-up `kid`, and `.reload()`
+// deliberately bypasses jose's cooldown — unthrottled, garbage tokens would
+// each cost a fresh fetch against the auth origin.
+const RELOAD_COOLDOWN_MS = 30_000;
+const lastForcedReload = new Map<string, number>();
+
+/**
+ * Verify a Better-Auth-minted backend JWT (EdDSA) against the issuer's JWKS.
+ * For use by the backend that consumes `backendJwtOptions` tokens. Throws on an
+ * invalid/expired token or audience/issuer mismatch; returns the claims.
+ *
+ * Hardened against Better Auth signing-key rotation: jose's `createRemoteJWKSet`
+ * refuses to refetch the JWKS for `cooldownDuration` (30s default) after any
+ * fetch, so a token signed with a freshly rotated key whose `kid` isn't yet in
+ * the cached set would fail for the *whole* cooldown window — a ~30s burst of
+ * auth failures on every request that verifies a token. On a no-matching-key
+ * miss we force a single `.reload()` (which bypasses the cooldown) and retry, so
+ * a rotation costs one extra fetch instead of a brief outage.
+ */
+export const verifyBackendJwt = async (params: {
+	token: string;
+	/** The issuer's JWKS endpoint, e.g. `${BETTER_AUTH_URL}/api/auth/jwks`. */
+	jwksUrl: string | URL;
+	audience: string;
+	issuer: string;
+}): Promise<JWTPayload> => {
+	const url =
+		typeof params.jwksUrl === "string" ? new URL(params.jwksUrl) : params.jwksUrl;
+	const cacheKey = url.toString();
+	let jwks = jwksCache.get(cacheKey);
+	if (!jwks) {
+		jwks = createRemoteJWKSet(url);
+		jwksCache.set(cacheKey, jwks);
+	}
+	const options = {
+		audience: params.audience,
+		issuer: params.issuer,
+		algorithms: ["EdDSA"],
+		// Tolerate a few seconds of clock skew between the minting and verifying
+		// hosts; jose's default of 0 fails legitimate tokens at exp/nbf boundaries.
+		clockTolerance: 5,
+	};
+	try {
+		const { payload } = await jwtVerify(params.token, jwks, options);
+		return payload;
+	} catch (err) {
+		if (!(err instanceof joseErrors.JWKSNoMatchingKey)) throw err;
+		// `kid` absent from the cached JWKS — almost always a just-rotated signing
+		// key. Force a refresh past the cooldown and retry exactly once, at most
+		// once per cooldown window so unknown-`kid` garbage can't hammer the
+		// issuer.
+		const now = Date.now();
+		if (now - (lastForcedReload.get(cacheKey) ?? 0) < RELOAD_COOLDOWN_MS) {
+			throw err;
+		}
+		lastForcedReload.set(cacheKey, now);
+		await jwks.reload();
+		const { payload } = await jwtVerify(params.token, jwks, options);
+		return payload;
+	}
+};

package/src/keys.ts

@@ -0,0 +1,118 @@
+/**
+ * Environment contract for @ingram-tech/nk-auth.
+ *
+ * Following the "each package owns its own env validation" pattern. Env vars are
+ * external input, so we parse them with Zod (per docs/code-style.md) rather than
+ * reading `process.env` ad hoc. `authEnv()` returns a validated, config-shaped
+ * object you can spread straight into your `betterAuth()` call.
+ *
+ * Required:
+ *   BETTER_AUTH_SECRET  — session/CSRF signing key (`openssl rand -hex 32`)
+ *   BETTER_AUTH_URL     — canonical site origin, e.g. "https://example.com"
+ *   DATABASE_URL        — direct Postgres connection for Better Auth (:5432)
+ *
+ * Outside production, BETTER_AUTH_SECRET falls back to a well-known insecure
+ * placeholder so local dev and tests run without hand-setting it (`nk dev` and
+ * plain `next dev` alike). In production it stays strictly required — a missing
+ * secret throws at startup rather than silently signing sessions with a value
+ * anyone could guess.
+ *
+ * Sites that derive their own `baseURL` / database connection can take just the
+ * secret's prod/dev rule via `authSecret()` instead of the whole `authEnv()`
+ * bundle — so that security-sensitive default is never re-implemented app-side.
+ */
+
+import { z } from "zod";
+
+/**
+ * Well-known, deliberately insecure secret used ONLY when NODE_ENV is not
+ * "production". Never applied to a production build — see `secretField`.
+ */
+const DEV_SECRET_PLACEHOLDER = "nk-dev-insecure-placeholder-not-for-production";
+
+/**
+ * In production the secret is required; everywhere else it defaults to the
+ * insecure placeholder. Read NODE_ENV at parse time (not module load) so the
+ * same process can be exercised under either mode.
+ */
+const secretField = () =>
+	process.env.NODE_ENV === "production"
+		? z.string().min(1)
+		: z.string().min(1).default(DEV_SECRET_PLACEHOLDER);
+
+const buildSchema = () =>
+	z.object({
+		BETTER_AUTH_SECRET: secretField(),
+		BETTER_AUTH_URL: z.string().url(),
+		DATABASE_URL: z.string().min(1),
+	});
+
+let warnedPlaceholder = false;
+
+/**
+ * Warn once when the insecure dev placeholder is in use, so a missing secret is
+ * visible in local logs without nagging on every call. Never fires in
+ * production, where `secretField()` makes the secret required.
+ */
+const warnIfPlaceholder = (secret: string): void => {
+	if (secret === DEV_SECRET_PLACEHOLDER && !warnedPlaceholder) {
+		warnedPlaceholder = true;
+		console.warn(
+			"@ingram-tech/nk-auth: BETTER_AUTH_SECRET is unset — using an insecure dev placeholder. Set it before deploying.",
+		);
+	}
+};
+
+/**
+ * Resolve just the session-signing secret, applying the same rule `authEnv()`
+ * does: strictly required in production, an insecure dev placeholder otherwise.
+ *
+ * For sites that derive their own `baseURL` and open their own database
+ * connection (so they don't want `authEnv()`'s all-or-nothing bundle) but still
+ * want nk-auth to own the secret's prod/dev fallback. Reaching for this keeps
+ * the security-sensitive default in one place instead of hand-copied into the
+ * app. Backed by the same `secretField()` schema as `authEnv()`.
+ */
+export const authSecret = (): string => {
+	const result = secretField().safeParse(process.env.BETTER_AUTH_SECRET);
+	if (!result.success) {
+		// secretField() only rejects a missing/empty secret in production (dev
+		// supplies the placeholder default), so that is the sole failure here.
+		throw new Error(
+			"@ingram-tech/nk-auth: BETTER_AUTH_SECRET is required (an unset secret is only allowed outside production)",
+		);
+	}
+	warnIfPlaceholder(result.data);
+	return result.data;
+};
+
+export interface AuthEnv {
+	secret: string;
+	baseURL: string;
+	databaseUrl: string;
+}
+
+/**
+ * Read and validate all nk-auth env vars at once. Throws a single error listing
+ * everything missing/invalid, so a misconfigured site fails fast at startup
+ * rather than at first sign-in.
+ */
+export const authEnv = (): AuthEnv => {
+	const result = buildSchema().safeParse(process.env);
+	if (!result.success) {
+		const issues = result.error.issues
+			.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+			.join(", ");
+		throw new Error(`@ingram-tech/nk-auth: invalid environment — ${issues}`);
+	}
+	const env = result.data;
+	warnIfPlaceholder(env.BETTER_AUTH_SECRET);
+	return {
+		secret: env.BETTER_AUTH_SECRET,
+		baseURL: env.BETTER_AUTH_URL,
+		databaseUrl: env.DATABASE_URL,
+	};
+};
+
+/** Whether nk-auth is fully configured (lets callers degrade in local/dev). */
+export const isConfigured = (): boolean => buildSchema().safeParse(process.env).success;

package/src/middleware.ts

@@ -0,0 +1,150 @@
+/**
+ * A loop-safe Next.js auth middleware factory, at
+ * "@ingram-tech/nk-auth/middleware". Middleware runs at the edge before a route
+ * renders, so it can only afford an **optimistic** check — the presence of a
+ * session cookie (`getSessionCookie`), not a database-validated session.
+ *
+ * That optimism is exactly what makes naive auth middleware loop. The validated
+ * server guard (see "@ingram-tech/nk-auth/server") sends an invalid-but-present
+ * session to the sign-in page; if the optimistic layer then bounces the sign-in
+ * page back ("you have a cookie, go to the app"), a stale cookie ping-pongs
+ * forever — and an RSC render can't clear the cookie to break out.
+ *
+ * So this factory enforces the one safe invariant *at construction*:
+ *
+ *   The sign-in path is never the target of an optimistic redirect.
+ *
+ * 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 { type NextRequest, NextResponse } from "next/server";
+import { NK_AUTH_PATH_HEADER, safeNextParam } from "./gating-internals.js";
+
+export interface AuthMiddlewareConfig {
+	/**
+	 * Path prefixes that require a session. A request without a session cookie
+	 * to any of these is redirected to `signInPath`. Matched with `startsWith`.
+	 */
+	protectedPaths: string[];
+	/** Where unauthenticated users are sent. Default `/login`. */
+	signInPath?: string;
+	/**
+	 * Optional front-door redirect: when a session cookie is present and the
+	 * path *exactly* equals one of these, redirect to `signedInRedirect`. Safe
+	 * because it never targets the sign-in path. Typically `["/"]`.
+	 */
+	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 function createAuthMiddleware(config: AuthMiddlewareConfig) {
+	const signInPath = config.signInPath ?? "/login";
+	const frontDoorPaths = config.frontDoorPaths ?? [];
+	const cookiePrefix = config.sessionCookiePrefix ?? "better-auth";
+
+	// Segment-boundary match: "/app" gates "/app" and "/app/x" but not
+	// "/application". Used for both the construction-time loop check and the
+	// per-request gate, so the two can't drift (a broader construction check
+	// would reject safe configs like protectedPaths ["/log"] + signInPath
+	// "/login", where "/login" is never actually gated).
+	const isProtected = (path: string): boolean =>
+		config.protectedPaths.some((p) => path === p || path.startsWith(`${p}/`));
+
+	// 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
+	// redirect, or a stale cookie loops.
+	if (isProtected(signInPath)) {
+		throw new Error(
+			`@ingram-tech/nk-auth: signInPath "${signInPath}" must not fall under protectedPaths — a cookie-less visit would redirect to itself forever.`,
+		);
+	}
+	if (frontDoorPaths.includes(signInPath)) {
+		throw new Error(
+			`@ingram-tech/nk-auth: signInPath "${signInPath}" must not be a frontDoorPath — it would reintroduce the stale-cookie redirect loop.`,
+		);
+	}
+	if (frontDoorPaths.length > 0 && !config.signedInRedirect) {
+		throw new Error(
+			"@ingram-tech/nk-auth: signedInRedirect is required when frontDoorPaths is set.",
+		);
+	}
+
+	return function middleware(request: NextRequest): 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;
+		}
+
+		const hasSessionCookie = !!getSessionCookie(request);
+
+		// 2. Unauthenticated (no cookie) on a protected path -> sign in, and
+		//    remember where they were going.
+		if (!hasSessionCookie && isProtected(path)) {
+			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 to = request.nextUrl.clone();
+			to.pathname = config.signedInRedirect;
+			to.search = "";
+			return NextResponse.redirect(to);
+		}
+
+		// 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 } });
+	};
+}

package/src/options.ts

@@ -0,0 +1,236 @@
+import type { PasskeyOptions } from "@better-auth/passkey";
+import type { BetterAuthOptions } from "better-auth";
+import bcrypt from "bcrypt";
+
+// `uuidGenerateId` (the `advanced.database.generateId` UUIDv7 generator) and the
+// base58 skin now live in the dependency-light `./id` module; re-exported here so
+// existing `from "@ingram-tech/nk-auth"` imports keep resolving.
+export { uuidGenerateId } from "./id.js";
+
+/**
+ * Portable Better Auth building blocks for Ingram sites.
+ *
+ * Deliberately NOT a `betterAuth()` wrapper: a site assembles its own instance
+ * and spreads these presets in. That keeps full plugin type inference at the
+ * call site (where `declaration` is off) and respects the prime directive — the
+ * site stays plain Better Auth, we just ship the shared config. JWT + org
+ * presets live in `./jwt` and `./organization`. See the package README.
+ */
+
+/**
+ * `emailAndPassword.password` config that hashes/verifies with bcrypt.
+ *
+ * @deprecated LEGACY SUPPORT ONLY. Do not wire this into a new site. It exists
+ * solely so sites with pre-existing **bcrypt** password hashes keep verifying.
+ * Better Auth's default is scrypt — new sites should omit this and use that
+ * default. Sites still on bcrypt should migrate hashes to scrypt and drop this;
+ * see the nk-auth README (§"Migrating bcrypt passwords to scrypt") for the path.
+ *
+ * NOTE: bcrypt silently truncates the password at **72 bytes**, so two passwords
+ * sharing their first 72 bytes verify as equal — even though the password policy
+ * allows up to {@link DEFAULT_MAX_PASSWORD_LENGTH} (128) characters. This is a
+ * property of bcrypt, not a bug here, and it's deliberately not length-guarded:
+ * a guard would break verification of the legacy long-password hashes this
+ * preset exists to support (bcrypt already truncated them at hash time). It is
+ * one more reason to migrate off bcrypt — scrypt has no such ceiling.
+ */
+export const bcryptPassword = {
+	hash: (password: string): Promise<string> => bcrypt.hash(password, 10),
+	verify: ({
+		hash,
+		password,
+	}: {
+		hash: string;
+		password: string;
+	}): Promise<boolean> => bcrypt.compare(password, hash),
+};
+
+export interface PasskeyConfig {
+	/** Relying-party id: the registrable domain, e.g. "example.com". */
+	rpId: string;
+	/** Relying-party display name. */
+	rpName: string;
+	/** Expected origin(s), e.g. "https://example.com". */
+	origin: string | string[];
+}
+
+/** Build `passkey` plugin options. Use as `passkey(makePasskeyOptions(cfg))`. */
+export const makePasskeyOptions = (cfg: PasskeyConfig): PasskeyOptions => ({
+	rpID: cfg.rpId,
+	rpName: cfg.rpName,
+	origin: cfg.origin,
+});
+
+/**
+ * Derive passkey options from the site's single base URL: `rpID` = the URL's
+ * hostname (the WebAuthn effective domain — host only, no scheme or port) and
+ * `origin` = the URL itself. This is the common case (one sign-in origin), and
+ * it keeps the relying-party id and the registered origin in lockstep so they
+ * can't drift. Pass the same value the instance signs sessions for, e.g.:
+ *
+ *   passkey(passkeyOptionsForBaseUrl(env.baseURL, "Example"))
+ *
+ * Reach for `makePasskeyOptions` directly when a site spans multiple origins or
+ * must register against a parent registrable domain (e.g. rpID "example.com"
+ * for an "app.example.com" origin).
+ */
+export const passkeyOptionsForBaseUrl = (
+	baseURL: string,
+	rpName: string,
+): PasskeyOptions =>
+	makePasskeyOptions({
+		rpId: new URL(baseURL).hostname,
+		rpName,
+		origin: baseURL,
+	});
+
+/**
+ * Which auth mail is being sent. Switch on this to pick a template — never on
+ * `subject`, which is English default copy a site is expected to replace.
+ */
+export type AuthEmailKind = "verify-email" | "reset-password" | "change-email";
+
+/** The subset of the Better Auth user these callbacks pass through. */
+export interface AuthEmailUser {
+	id: string;
+	email: string;
+	name?: string;
+}
+
+/** One outgoing auth mail, handed to the site's sender. */
+export interface AuthEmailMessage {
+	/** Discriminator — pick the template off this. */
+	kind: AuthEmailKind;
+	/**
+	 * Recipient. For `change-email` this is deliberately the user's CURRENT
+	 * address: confirming the move from the address that already owns the
+	 * account is what stops a hijacked session from walking off with it.
+	 */
+	to: string;
+	/**
+	 * Default English subject, for sites that don't localize. Prefer your own
+	 * translated copy — see the README.
+	 */
+	subject: string;
+	/** The one-time action link. */
+	url: string;
+	/** The raw token behind `url`, if you need to build your own link. */
+	token: string;
+	/** `id` lets you look up a locale/preferences; `name` personalizes copy. */
+	user: AuthEmailUser;
+	/** `change-email` only: the address the user is moving to. */
+	newEmail?: string;
+	/** The originating request — `Accept-Language` is a locale source. */
+	request?: Request;
+}
+
+/** Send one transactional email (wire to `@ingram-tech/nk-email`'s `sendEmail`). */
+export type SendEmail = (message: AuthEmailMessage) => Promise<unknown>;
+
+/**
+ * Email callbacks for `emailAndPassword.sendResetPassword`,
+ * `emailVerification.sendVerificationEmail` and
+ * `user.changeEmail.sendChangeEmailConfirmation`, routed through your sender.
+ *
+ * Spread all three in. Hand-writing them is a trap: `betterAuth()` infers its
+ * options generically, so TypeScript does NOT excess-property-check that object
+ * literal — a callback under a misremembered name (`sendChangeEmailVerification`
+ * is the one people reach for) compiles clean and simply never fires. The
+ * `PinnedEmailSenders` assertion below ties these three names to the real Better
+ * Auth options, so a rename upstream breaks this build instead of your site.
+ */
+export const makeEmailSenders = (send: SendEmail) => ({
+	sendResetPassword: async (
+		{ user, url, token }: { user: AuthEmailUser; url: string; token: string },
+		request?: Request,
+	): Promise<void> => {
+		await send({
+			kind: "reset-password",
+			to: user.email,
+			subject: "Reset your password",
+			url,
+			token,
+			user,
+			request,
+		});
+	},
+	sendVerificationEmail: async (
+		{ user, url, token }: { user: AuthEmailUser; url: string; token: string },
+		request?: Request,
+	): Promise<void> => {
+		await send({
+			kind: "verify-email",
+			to: user.email,
+			subject: "Verify your email",
+			url,
+			token,
+			user,
+			request,
+		});
+	},
+	sendChangeEmailConfirmation: async (
+		{
+			user,
+			newEmail,
+			url,
+			token,
+		}: {
+			user: AuthEmailUser;
+			newEmail: string;
+			url: string;
+			token: string;
+		},
+		request?: Request,
+	): Promise<void> => {
+		await send({
+			kind: "change-email",
+			to: user.email, // the CURRENT address — see AuthEmailMessage.to
+			subject: "Confirm your email change",
+			url,
+			token,
+			user,
+			newEmail,
+			request,
+		});
+	},
+});
+
+/**
+ * Compile-time pin: each sender above must stay assignable to the Better Auth
+ * option slot it is meant to fill, *addressed by that option's real name*.
+ *
+ * This exists because `betterAuth()` receives its options through a generic, so
+ * TypeScript does NOT excess-property-check the object literal a site passes it.
+ * A callback under a wrong-but-plausible name — `sendChangeEmailVerification`
+ * for `sendChangeEmailConfirmation`, say — therefore compiles cleanly at every
+ * call site and simply never fires, which is a silent no-op in production and
+ * exactly the bug this pin is here to prevent recurring.
+ *
+ * Indexing by key is what makes it bite: rename any of the three upstream and
+ * `NonNullable<…["theName"]>` stops resolving, breaking this build. It lives in
+ * source rather than in a `.test.ts` on purpose — `tsconfig.json` excludes test
+ * files, so a type-level assertion in one is never checked by anything.
+ */
+type PinnedEmailSenders = {
+	reset: NonNullable<
+		NonNullable<BetterAuthOptions["emailAndPassword"]>["sendResetPassword"]
+	>;
+	verify: NonNullable<
+		NonNullable<BetterAuthOptions["emailVerification"]>["sendVerificationEmail"]
+	>;
+	change: NonNullable<
+		NonNullable<
+			NonNullable<BetterAuthOptions["user"]>["changeEmail"]
+		>["sendChangeEmailConfirmation"]
+	>;
+};
+
+const _pinEmailSenders = (send: SendEmail): PinnedEmailSenders => {
+	const senders = makeEmailSenders(send);
+	return {
+		reset: senders.sendResetPassword,
+		verify: senders.sendVerificationEmail,
+		change: senders.sendChangeEmailConfirmation,
+	};
+};
+void _pinEmailSenders;

package/src/organization.ts

@@ -0,0 +1,80 @@
+import type { Pool } from "pg";
+
+/**
+ * Organization-plugin building blocks shared across Ingram sites. The site
+ * still calls `organization({ ...nkOrganizationDefaults, ac, roles, ... })`
+ * itself — these only supply the generic defaults + the active-org plumbing.
+ */
+
+/** Sensible Ingram defaults to spread into the `organization()` plugin. */
+export const nkOrganizationDefaults = {
+	/** Invitations valid for one week. */
+	invitationExpiresIn: 60 * 60 * 24 * 7,
+	/** The user who creates an org is its owner. */
+	creatorRole: "owner",
+} as const;
+
+/**
+ * `user.additionalFields` entry that records the user's last active org so it
+ * can be restored on the next sign-in. Spread into `user.additionalFields`.
+ */
+export const lastActiveOrganizationUserField = {
+	lastActiveOrganizationId: {
+		type: "string",
+		required: false,
+		input: false,
+		returned: true,
+	},
+} as const;
+
+interface SessionLike {
+	userId: string;
+	activeOrganizationId?: string | null;
+}
+
+/**
+ * `databaseHooks` that restore the user's last active organization on session
+ * create (only if they're still a member) and persist it on session update.
+ * Requires `lastActiveOrganizationUserField` in `user.additionalFields` and the
+ * Better Auth organization tables. Spread as `databaseHooks: lastActiveOrganizationHooks(pool)`.
+ */
+export const lastActiveOrganizationHooks = (pool: Pool) => ({
+	session: {
+		create: {
+			before: async (session: SessionLike) => {
+				if (session.activeOrganizationId) {
+					return;
+				}
+				const userResult = await pool.query<{
+					lastActiveOrganizationId: string | null;
+				}>('SELECT "lastActiveOrganizationId" FROM "user" WHERE id = $1', [
+					session.userId,
+				]);
+				const lastOrgId = userResult.rows[0]?.lastActiveOrganizationId;
+				if (!lastOrgId) {
+					return;
+				}
+				const memberResult = await pool.query(
+					'SELECT 1 FROM member WHERE "userId" = $1 AND "organizationId" = $2 LIMIT 1',
+					[session.userId, lastOrgId],
+				);
+				if (memberResult.rows.length === 0) {
+					return;
+				}
+				return { data: { ...session, activeOrganizationId: lastOrgId } };
+			},
+		},
+		update: {
+			after: async (session: SessionLike) => {
+				const orgId = session.activeOrganizationId;
+				if (typeof orgId !== "string" || !orgId) {
+					return;
+				}
+				await pool.query(
+					'UPDATE "user" SET "lastActiveOrganizationId" = $1 WHERE id = $2',
+					[orgId, session.userId],
+				);
+			},
+		},
+	},
+});

package/src/password.ts

@@ -0,0 +1,103 @@
+/**
+ * Password-policy primitives, shared by both ends of a site so the client form
+ * and the server validate against the *same* numbers. Pure (no `next`, `react`,
+ * or server imports) so it resolves identically from "@ingram-tech/nk-auth" and
+ * "@ingram-tech/nk-auth/client". Import from the "./password" subpath.
+ *
+ * The values mirror Better Auth's `emailAndPassword` defaults; if a site
+ * overrides `minPasswordLength` / `maxPasswordLength` in its `betterAuth()`
+ * config, pass the same numbers to `passwordSchema()` so the two stay in step.
+ */
+import { z } from "zod";
+
+/**
+ * The Better Auth `account.providerId` value for an email/password credential
+ * (as opposed to a social provider like "google"). This is Better Auth's own
+ * table shape, not ours — centralised here so no consuming site hard-codes the
+ * string. See {@link import("./server.js").createAuthHelpers}'s
+ * `hasCredentialAccount`.
+ */
+export const CREDENTIAL_PROVIDER_ID = "credential";
+
+/** Better Auth's default `emailAndPassword.minPasswordLength`. */
+export const DEFAULT_MIN_PASSWORD_LENGTH = 8;
+
+/** Better Auth's default `emailAndPassword.maxPasswordLength`. */
+export const DEFAULT_MAX_PASSWORD_LENGTH = 128;
+
+export interface PasswordPolicy {
+	/** Minimum length. Default {@link DEFAULT_MIN_PASSWORD_LENGTH}. */
+	minLength?: number;
+	/** Maximum length. Default {@link DEFAULT_MAX_PASSWORD_LENGTH}. */
+	maxLength?: number;
+}
+
+/**
+ * A Zod schema for a new password, honouring the resolved policy. Use it on both
+ * the client (form validation) and the server (before calling Better Auth) so
+ * neither side drifts from the other or from the instance's configured bounds.
+ */
+export function passwordSchema(policy: PasswordPolicy = {}): z.ZodString {
+	const min = policy.minLength ?? DEFAULT_MIN_PASSWORD_LENGTH;
+	const max = policy.maxLength ?? DEFAULT_MAX_PASSWORD_LENGTH;
+	return z
+		.string()
+		.min(min, `Password must be at least ${min} characters.`)
+		.max(max, `Password must be at most ${max} characters.`);
+}
+
+/**
+ * The failure reasons of a "choose a new password + confirm it" form, as a
+ * stable `code` (switch on it for i18n) plus an English `message` fallback.
+ * `reset_failed` is the server rejecting the reset token (invalid / expired).
+ */
+export type ResetPasswordErrorCode =
+	| "password_too_short"
+	| "password_too_long"
+	| "passwords_do_not_match"
+	| "reset_failed";
+
+export interface ResetPasswordError {
+	code: ResetPasswordErrorCode;
+	message: string;
+	/** Present on `password_too_short`. */
+	minLength?: number;
+	/** Present on `password_too_long`. */
+	maxLength?: number;
+}
+
+/**
+ * Validate a new-password pair (the field and its confirmation) against the
+ * policy. Returns the first {@link ResetPasswordError}, or null when valid. Pure
+ * so it is unit-testable and reusable outside React; {@link
+ * import("./client.js").useResetPassword} calls it before hitting the server.
+ */
+export function validateNewPassword(
+	newPassword: string,
+	confirmPassword: string,
+	policy: PasswordPolicy = {},
+): ResetPasswordError | null {
+	const min = policy.minLength ?? DEFAULT_MIN_PASSWORD_LENGTH;
+	const max = policy.maxLength ?? DEFAULT_MAX_PASSWORD_LENGTH;
+	if (newPassword.length < min) {
+		return {
+			code: "password_too_short",
+			message: `Password must be at least ${min} characters.`,
+			minLength: min,
+		};
+	}
+	if (newPassword.length > max) {
+		return {
+			code: "password_too_long",
+			message: `Password must be at most ${max} characters.`,
+			maxLength: max,
+		};
+	}
+	if (newPassword !== confirmPassword) {
+		return {
+			code: "passwords_do_not_match",
+			message: "Passwords do not match.",
+		};
+	}
+	return null;
+}

package/src/paths.ts

@@ -0,0 +1,19 @@
+/**
+ * Where Better Auth mounts in an Ingram site: **`/auth`**, not the framework
+ * default `/api/auth`. Auth is a first-class user-facing surface — sign-in,
+ * OAuth callbacks, the JWKS — not an internal machine API, so it lives at the
+ * site root alongside the other pages.
+ *
+ * Use it on both ends so server and client agree:
+ *
+ *   betterAuth({ basePath: authBasePath, ... })
+ *   createAuthClient({ baseURL, basePath: authBasePath, ... })
+ *
+ * and mount the catch-all at `app/auth/[...all]/route.ts`. OAuth redirect URIs
+ * then become `<site>/auth/callback/<provider>` and the JWKS `<site>/auth/jwks`.
+ *
+ * Sign-in pages share this namespace, and a page whose path matches a Better
+ * Auth endpoint shadows it (static segments beat the catch-all) — `nk doctor`
+ * flags such collisions.
+ */
+export const authBasePath = "/auth";

package/src/pool.ts

@@ -0,0 +1,26 @@
+import { createPool } from "@ingram-tech/nk-db";
+import type { Pool } from "pg";
+
+/**
+ * A `pg` Pool for Better Auth's direct database connection.
+ *
+ * @deprecated Thin alias for `createPool` from `@ingram-tech/nk-db` — the one
+ * place pool construction and TLS handling live. Kept so existing call sites
+ * (`lib/db.ts` calling `createAuthPool({ connectionString, caCert })`) keep
+ * working, and so Better Auth shares the **exact same pool implementation** as
+ * app queries — the "one pool per process" rule. Prefer importing `createPool`
+ * directly in new code.
+ *
+ * TLS handling (CA-verified when `caCert` is set; plain-TLS for other managed
+ * hosts; no TLS for localhost), and the local `max: 1` cap (for the PGlite
+ * socket), all live in `createPool`.
+ */
+export const createAuthPool = (config: {
+	connectionString: string;
+	/** PEM CA cert; when set, the server cert + hostname are verified. */
+	caCert?: string;
+}): Pool =>
+	createPool({
+		connectionString: config.connectionString,
+		caCert: config.caCert,
+	});

package/src/reset-password.ts

@@ -0,0 +1,128 @@
+/**
+ * Headless controller for a "set / reset your password" page — the token
+ * consumer at the end of Better Auth's forget-password round trip. nk-auth owns
+ * the *sender* (`makeEmailSenders.sendResetPassword`) and the endpoint contract;
+ * this closes the loop so a site never touches the `resetPassword` endpoint name
+ * or hand-rolls the invalid-token / success / validation state machine. The site
+ * brings its own shell (inputs, buttons, i18n) and wires it to what this returns.
+ *
+ * The same page serves both entry points, because both land on the identical URL
+ * with a `?token=`: the classic "I forgot my password" flow, and "set a password
+ * for my social-only account" (Better Auth's reset endpoint creates the
+ * credential when the user has none — see the package README).
+ *
+ *   "use client";
+ *   const { status, error, submit } = useResetPassword(authClient, { token });
+ *   if (status === "invalid") return <InvalidLink />;
+ *   if (status === "success") return <Done />;
+ *   // <form onSubmit={() => submit(pw, confirm)}> … {error && t(error.code)} …
+ */
+import { useCallback, useState } from "react";
+import {
+	type PasswordPolicy,
+	type ResetPasswordError,
+	validateNewPassword,
+} from "./password.js";
+
+export type ResetPasswordStatus =
+	/** No usable token in the URL — show an "invalid or expired link" message. */
+	| "invalid"
+	/** Token present; awaiting the user's new password. */
+	| "idle"
+	/** The reset request is in flight. */
+	| "submitting"
+	/** The password was set; the user can now sign in with it. */
+	| "success"
+	/** Validation failed, or the server rejected the reset — see `error`. */
+	| "error";
+
+/** The slice of a Better Auth client this hook calls. */
+export interface ResetPasswordClient {
+	resetPassword: (input: {
+		newPassword: string;
+		token: string;
+	}) => Promise<{ error?: { message?: string } | null }>;
+}
+
+export interface UseResetPasswordOptions extends PasswordPolicy {
+	/**
+	 * The reset token from the URL (`?token=`), or null when it is missing — e.g.
+	 * the link carried `?error=INVALID_TOKEN` instead. Null puts the controller in
+	 * the `invalid` state before any submit.
+	 */
+	token: string | null;
+}
+
+export interface UseResetPassword {
+	status: ResetPasswordStatus;
+	/** The current failure, or null. `code` is stable for i18n; `message` is an English fallback. */
+	error: ResetPasswordError | null;
+	/** Validate the pair against the policy, then call the reset endpoint. */
+	submit: (newPassword: string, confirmPassword: string) => Promise<void>;
+}
+
+const RESET_FAILED_FALLBACK = "Could not reset your password.";
+
+/**
+ * Drive a reset-password form. Returns the current `status`, the last `error`
+ * (with an i18n-friendly `code`), and a `submit(newPassword, confirmPassword)`
+ * that runs {@link validateNewPassword} against the policy before hitting the
+ * server. Pass the resolved `minLength` / `maxLength` when the site overrides
+ * Better Auth's defaults so client and server agree.
+ */
+export function useResetPassword(
+	client: ResetPasswordClient,
+	options: UseResetPasswordOptions,
+): UseResetPassword {
+	const { token, minLength, maxLength } = options;
+	const [status, setStatus] = useState<ResetPasswordStatus>(
+		token ? "idle" : "invalid",
+	);
+	const [error, setError] = useState<ResetPasswordError | null>(null);
+
+	const submit = useCallback(
+		async (newPassword: string, confirmPassword: string): Promise<void> => {
+			if (!token) {
+				setStatus("invalid");
+				return;
+			}
+
+			const validation = validateNewPassword(newPassword, confirmPassword, {
+				minLength,
+				maxLength,
+			});
+			if (validation) {
+				setError(validation);
+				setStatus("error");
+				return;
+			}
+
+			setError(null);
+			setStatus("submitting");
+			try {
+				const { error: resetError } = await client.resetPassword({
+					newPassword,
+					token,
+				});
+				if (resetError) {
+					setError({
+						code: "reset_failed",
+						message: resetError.message ?? RESET_FAILED_FALLBACK,
+					});
+					setStatus("error");
+					return;
+				}
+				setStatus("success");
+			} catch (err) {
+				setError({
+					code: "reset_failed",
+					message: err instanceof Error ? err.message : RESET_FAILED_FALLBACK,
+				});
+				setStatus("error");
+			}
+		},
+		[token, minLength, maxLength, client],
+	);
+
+	return { status, error, submit };
+}

package/src/server.ts

@@ -0,0 +1,184 @@
+/**
+ * Server-side session helpers for the App Router, at
+ * "@ingram-tech/nk-auth/server" so the framework-agnostic core entry never
+ * pulls in `next`. A site binds these once to its own Better Auth instance:
+ *
+ *   // lib/auth/session.ts
+ *   import { createAuthHelpers } from "@ingram-tech/nk-auth/server";
+ *   import { auth } from "@/lib/auth";
+ *
+ *   export const { getSession, getUser, requireSession, requireUser,
+ *     redirectIfAuthenticated } = createAuthHelpers(auth);
+ *
+ * These are the **validated** authority: they resolve through
+ * `auth.api.getSession`, which checks the session against the database — not
+ * merely the presence of a cookie. The read is memoized per request with React
+ * `cache()`, so a render fanning out many `getUser()` calls validates once,
+ * not once per call. 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 cookie resolves to "no session"
+ * and falls through to the form instead of ping-ponging forever.
+ */
+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 { CREDENTIAL_PROVIDER_ID } from "./password.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";
+
+/** The shape we need from a session: anything carrying a `user`. */
+interface SessionLike {
+	user: unknown;
+}
+
+/**
+ * The slice of a Better Auth instance these helpers touch. Generic over the
+ * site's session type `S`, so `getSession`/`getUser` return the site's fully
+ * inferred user shape (additional fields, org id, …) — no `any`, no casts.
+ */
+interface AuthLike<S extends SessionLike> {
+	api: {
+		getSession: (input: { headers: Headers }) => Promise<S | null>;
+		/**
+		 * Better Auth's `/list-accounts`: the auth methods linked to the current
+		 * session's user, each `{ providerId }` ("credential" for email/password,
+		 * or a social provider like "google"). Present on every real `betterAuth()`
+		 * instance; powers `getLinkedProviders` / `hasCredentialAccount` below.
+		 */
+		listUserAccounts: (input: {
+			headers: Headers;
+		}) => Promise<Array<{ providerId: string }>>;
+	};
+}
+
+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 function createAuthHelpers<S extends SessionLike>(
+	auth: AuthLike<S>,
+	options: AuthHelpersOptions = {},
+) {
+	const signInPath = options.signInPath ?? "/login";
+	const cookiePrefix = options.sessionCookiePrefix ?? "better-auth";
+
+	/**
+	 * The validated session ({ user, session, … }) or null. Memoized per request
+	 * via React `cache()`: the session cookie is constant within a request, so
+	 * every helper (and every component calling one) shares a single database
+	 * validation. Outside a request scope (scripts, tests) `cache()` degrades to
+	 * an uncached call.
+	 *
+	 * Caveat: code that mutates the session mid-request (e.g. a server action
+	 * updating the user) and then re-reads it through these helpers sees the
+	 * pre-mutation snapshot; re-read through `auth.api.getSession` directly if
+	 * that ever matters.
+	 */
+	const getSession = cache(async (): Promise<S | null> =>
+		auth.api.getSession({ headers: await headers() }),
+	);
+
+	/** The authenticated user, or null. */
+	async function getUser(): Promise<S["user"] | null> {
+		const session = await getSession();
+		return session?.user ?? null;
+	}
+
+	/**
+	 * 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(): Promise<string> {
+		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(): Promise<S["user"]> {
+		const user = await getUser();
+		// redirect() is typed `never`, so `user` narrows to non-null below.
+		if (!user) 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(): Promise<S> {
+		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
+	 * session, a present-but-invalid cookie is treated as signed-out and the
+	 * page renders instead of looping. Never do this in middleware.
+	 */
+	async function redirectIfAuthenticated(to: string): Promise<void> {
+		if (await getSession()) redirect(to);
+	}
+
+	/**
+	 * The `providerId`s linked to the current session's user — "credential" for
+	 * email/password, plus any social providers ("google", …). Empty when signed
+	 * out. Reads Better Auth's own `/list-accounts`, so a site never queries the
+	 * `account` table or hard-codes provider strings itself.
+	 */
+	async function getLinkedProviders(): Promise<string[]> {
+		const accounts = await auth.api.listUserAccounts({
+			headers: await headers(),
+		});
+		return accounts.map((account) => account.providerId);
+	}
+
+	/**
+	 * Whether the current user has an email/password credential. Drives the
+	 * "Change password" vs "Set password" decision on a security page: a user who
+	 * signed up purely through a social provider has none until they set one
+	 * (typically via the reset-password / forgot-password flow — see the
+	 * `useResetPassword` client hook). Returns false when signed out.
+	 */
+	async function hasCredentialAccount(): Promise<boolean> {
+		const providers = await getLinkedProviders();
+		return providers.includes(CREDENTIAL_PROVIDER_ID);
+	}
+
+	return {
+		getSession,
+		getUser,
+		requireSession,
+		requireUser,
+		redirectIfAuthenticated,
+		getLinkedProviders,
+		hasCredentialAccount,
+	};
+}