@ingram-tech/nk-auth 0.13.5 → 0.14.0

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;
+}