@ingram-tech/nk-auth 0.13.5 → 0.14.0

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,245 @@
+/**
+ * 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 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 { 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 }>>;
+	};
+}
+
+/**
+ * The registry helpers for the ids a session carries. With these, every
+ * session read through the helpers presents `user.id` / `session.userId` as
+ * the user's public id and `session.activeOrganizationId` as the
+ * organization's, so app code compares session ids with `idColumn` reads in
+ * one form. Better Auth itself keeps working on raw uuids underneath.
+ */
+export interface SessionIds {
+	user: IdHelper;
+	organization?: IdHelper;
+}
+
+export interface AuthHelpersOptions {
+	/** Where guards send unauthenticated users. Default `/login`. */
+	signInPath?: string;
+	/**
+	 * Encode session ids to their public form on every read (see
+	 * {@link SessionIds}). Omit on a site that has no public id form: the
+	 * helpers then return Better Auth's raw uuids.
+	 */
+	ids?: SessionIds;
+	/**
+	 * 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;
+}
+
+const encodeIfString = (helper: IdHelper | undefined, value: unknown): unknown =>
+	helper && typeof value === "string" ? helper.encode(value) : value;
+
+/**
+ * A session with its ids in public form: `user.id`, `session.userId` and
+ * `session.activeOrganizationId` (each only when present and a string). Pure —
+ * Better Auth's own object is left untouched, since it is what the adapter
+ * writes back. `encode` is idempotent, so an already-public id is unchanged.
+ */
+export function encodeSessionIds<S extends SessionLike>(
+	session: S,
+	ids: SessionIds,
+): S {
+	const out: Record<string, unknown> = { ...(session as Record<string, unknown>) };
+	const user = session.user;
+	if (user && typeof user === "object" && "id" in user) {
+		out.user = { ...user, id: encodeIfString(ids.user, user.id) };
+	}
+	const inner = "session" in session ? session.session : undefined;
+	if (inner && typeof inner === "object") {
+		const rec = inner as Record<string, unknown>;
+		out.session = {
+			...rec,
+			...("userId" in rec
+				? { userId: encodeIfString(ids.user, rec.userId) }
+				: {}),
+			...("activeOrganizationId" in rec
+				? {
+						activeOrganizationId: encodeIfString(
+							ids.organization,
+							rec.activeOrganizationId,
+						),
+					}
+				: {}),
+		};
+	}
+	return out as S;
+}
+
+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> => {
+		const session = await auth.api.getSession({ headers: await headers() });
+		return session && options.ids
+			? encodeSessionIds(session, options.ids)
+			: session;
+	});
+
+	/** 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,
+	};
+}