@0x0501/mystack 0.0.0-stage → 0.1.0-bootstrap.0

package/template/src/lib/auth-paths.ts

@@ -0,0 +1,94 @@
+/**
+ * Better Auth HTTP paths the router must not expose.
+ *
+ * `disabledPaths` only 404s the *router* — server-side `auth.api.*` calls still
+ * reach these endpoints, which is how the app uses every one of them. Kept in
+ * its own binding-free module so tests can assert the list against routes a
+ * real auth instance mounts.
+ *
+ * The Starter deliberately omits Better Auth's api-key plugin (not a platform
+ * default), so those paths are not listed here.
+ */
+
+/**
+ * OTPs are issued and consumed exclusively through account-security server
+ * fns, with the email always taken from the session. Public email-OTP sign-in
+ * would also bypass the social/password 2FA challenge design.
+ */
+const EMAIL_OTP_PATHS = [
+	"/email-otp/send-verification-otp",
+	"/email-otp/check-verification-otp",
+	"/email-otp/verify-email",
+	"/sign-in/email-otp",
+	"/email-otp/request-password-reset",
+	"/forget-password/email-otp",
+	"/email-otp/reset-password",
+	"/email-otp/request-email-change",
+	"/email-otp/change-email",
+] as const;
+
+/**
+ * 2FA management is OTP/TOTP-gated through account-security server fns, so
+ * password-gated HTTP endpoints stay off. `verify-totp` / `verify-backup-code`
+ * remain public — sign-in and enrollment confirmation need them.
+ */
+const TWO_FACTOR_PATHS = [
+	"/two-factor/enable",
+	"/two-factor/disable",
+	"/two-factor/generate-backup-codes",
+	"/two-factor/get-totp-uri",
+	"/two-factor/send-otp",
+	"/two-factor/verify-otp",
+] as const;
+
+/**
+ * The whole admin plugin surface. These routes check nothing but
+ * `hasPermission`, so a plain admin holding `user:set-role` could demote a
+ * superadmin over HTTP. Admin UI goes through `auth.api.*` and server fns.
+ */
+const ADMIN_PATHS = [
+	"/admin/set-role",
+	"/admin/create-user",
+	"/admin/update-user",
+	"/admin/list-users",
+	"/admin/list-user-sessions",
+	"/admin/unban-user",
+	"/admin/ban-user",
+	"/admin/impersonate-user",
+	"/admin/stop-impersonating",
+	"/admin/revoke-user-session",
+	"/admin/revoke-user-sessions",
+	"/admin/remove-user",
+	"/admin/set-user-password",
+	"/admin/get-user",
+	"/admin/has-permission",
+] as const;
+
+/**
+ * Endpoints Turnstile must gate. Explicit so captcha coverage tests pin the
+ * list against mounted password paths rather than trusting plugin defaults.
+ */
+export const CAPTCHA_ENDPOINTS = [
+	"/sign-up/email",
+	"/sign-in/email",
+	"/request-password-reset",
+] as const;
+
+/**
+ * Credential mutations whose guards live in account-security server fns.
+ * `/change-password` skips session eviction; `/passkey/delete-passkey` has no
+ * freshness gate in the library.
+ */
+const CREDENTIAL_MUTATION_PATHS = [
+	"/change-password",
+	"/passkey/delete-passkey",
+] as const;
+
+export const DISABLED_AUTH_PATHS = [
+	// jwt plugin session→JWT shortcut: tokens only through OAuth flow.
+	"/token",
+	...EMAIL_OTP_PATHS,
+	...TWO_FACTOR_PATHS,
+	...ADMIN_PATHS,
+	...CREDENTIAL_MUTATION_PATHS,
+] as const;

package/template/src/lib/auth-plugins/existing-email-signup.ts

@@ -0,0 +1,86 @@
+/**
+ * Re-registering an address that already has an account (ADR 0008).
+ *
+ * Stock Better Auth answers a duplicate sign-up with a synthetic success and
+ * silently discards the submitted password — so a consumer who "fixed a typo"
+ * by re-registering could never sign in after clicking the link. The previous
+ * fix stored the second password instead, which handed the account to anyone
+ * who merely knew the address: they re-register with a password of their
+ * choosing, the victim clicks the link *they* already received, and the account
+ * verifies under the attacker's password.
+ *
+ * So: re-registration writes nothing at all — not the password, not the name,
+ * not any other field, whatever the account's verification state. It re-sends
+ * the verification link when the account is still unverified (the one
+ * legitimate reason to re-register), and it tells the user the address is
+ * already registered.
+ *
+ * That message is deliberately **the same for verified and unverified
+ * accounts**. Differing copy would turn the endpoint into a finer oracle,
+ * distinguishing three states (absent / unverified / verified) instead of two.
+ * Disclosing existence at all is accepted here because the endpoint sits behind
+ * Turnstile and rate limiting, and the alternative was a silent credential
+ * overwrite.
+ */
+import type { BetterAuthPlugin } from "better-auth";
+import {
+	APIError,
+	createAuthMiddleware,
+	createEmailVerificationToken,
+} from "better-auth/api";
+
+export const EMAIL_ALREADY_REGISTERED_MESSAGE =
+	"This email is already registered. We've sent a verification link if it still needs one — otherwise sign in, or reset your password.";
+
+export function existingEmailSignup() {
+	return {
+		id: "existing-email-signup",
+		hooks: {
+			before: [
+				{
+					matcher(ctx) {
+						return ctx.path === "/sign-up/email";
+					},
+					handler: createAuthMiddleware(async (ctx) => {
+						const body = ctx.body as
+							| { email?: unknown; callbackURL?: unknown }
+							| undefined;
+						const email =
+							typeof body?.email === "string" ? body.email.trim() : "";
+						if (!email) return;
+
+						const existing = await ctx.context.internalAdapter.findUserByEmail(
+							email.toLowerCase(),
+						);
+						if (!existing?.user) return;
+
+						const send =
+							ctx.context.options.emailVerification?.sendVerificationEmail;
+						if (!existing.user.emailVerified && send) {
+							const token = await createEmailVerificationToken(
+								ctx.context.secret,
+								existing.user.email,
+								undefined,
+								ctx.context.options.emailVerification?.expiresIn,
+							);
+							const callbackURL =
+								typeof body?.callbackURL === "string" && body.callbackURL
+									? encodeURIComponent(body.callbackURL)
+									: encodeURIComponent("/");
+							const url = `${ctx.context.baseURL}/verify-email?token=${token}&callbackURL=${callbackURL}`;
+							await ctx.context.runInBackgroundOrAwait(
+								send({ user: existing.user, url, token }, ctx.request),
+							);
+						}
+
+						// One message for any existing address — see the note above.
+						throw new APIError("UNPROCESSABLE_ENTITY", {
+							message: EMAIL_ALREADY_REGISTERED_MESSAGE,
+							code: "USER_ALREADY_EXISTS",
+						});
+					}),
+				},
+			],
+		},
+	} satisfies BetterAuthPlugin;
+}

package/template/src/lib/auth-plugins/field-rules.ts

@@ -0,0 +1,84 @@
+/**
+ * Server-side field rules on the Better Auth HTTP surface (ADR 0008).
+ *
+ * The sign-up form's zod schema runs in the browser only, so these endpoints
+ * accept whatever is posted. Rules that need the raw request body — password
+ * composition, email limits — are enforced here, before Better Auth hashes or
+ * stores anything. Rules that belong to a stored column (e.g. display name)
+ * live in `databaseHooks` instead, so they cover every writer.
+ */
+import type { BetterAuthPlugin } from "better-auth";
+import { APIError, createAuthMiddleware } from "better-auth/api";
+import {
+	assertEmailLimits,
+	assertPasswordRules,
+	InvalidFieldError,
+} from "@/utils/input-rules";
+
+/**
+ * The paths that *set* a password, and the body field each uses.
+ *
+ * Sign-in is deliberately absent: an account whose stored password predates the
+ * 32-character maximum keeps working until its owner changes it. So are the
+ * paths that take a password to *prove* identity (`/two-factor/enable`,
+ * `/delete-user`) — the same reason.
+ */
+const PASSWORD_FIELD_BY_PATH: Record<string, "password" | "newPassword"> = {
+	"/sign-up/email": "password",
+	"/reset-password": "newPassword",
+	"/change-password": "newPassword",
+	"/email-otp/reset-password": "password",
+	"/admin/create-user": "password",
+	"/admin/set-user-password": "newPassword",
+};
+
+/** The paths that accept an address we will store. */
+const EMAIL_PATHS = new Set([
+	"/sign-up/email",
+	"/change-email",
+	"/email-otp/change-email",
+	"/admin/create-user",
+	"/admin/update-user",
+]);
+
+export function fieldRules() {
+	return {
+		id: "field-rules",
+		hooks: {
+			before: [
+				{
+					matcher(ctx) {
+						const path = ctx.path ?? "";
+						return path in PASSWORD_FIELD_BY_PATH || EMAIL_PATHS.has(path);
+					},
+					handler: createAuthMiddleware(async (ctx) => {
+						const body = ctx.body as Record<string, unknown> | undefined;
+						if (!body) return;
+						const path = ctx.path ?? "";
+
+						try {
+							const passwordField = PASSWORD_FIELD_BY_PATH[path];
+							if (passwordField) {
+								const password = body[passwordField];
+								if (typeof password === "string") assertPasswordRules(password);
+							}
+							if (EMAIL_PATHS.has(path)) {
+								// `/admin/update-user` posts `{ userId, data }`, so the
+								// address arrives nested; every other path is flat.
+								const fields =
+									(body.data as Record<string, unknown> | undefined) ?? body;
+								const email = fields.email ?? fields.newEmail;
+								if (typeof email === "string") assertEmailLimits(email.trim());
+							}
+						} catch (error) {
+							if (error instanceof InvalidFieldError) {
+								throw new APIError("BAD_REQUEST", { message: error.message });
+							}
+							throw error;
+						}
+					}),
+				},
+			],
+		},
+	} satisfies BetterAuthPlugin;
+}

package/template/src/lib/auth-plugins/social-two-factor.ts

@@ -0,0 +1,194 @@
+/**
+ * Second factor on social sign-in (ADR 0008).
+ *
+ * Better Auth's own 2FA hook matches only `/sign-in/email`,
+ * `/sign-in/username` and `/sign-in/phone-number` — the matcher is hardcoded in
+ * `better-auth/plugins/two-factor`, so it cannot be configured to cover the
+ * OAuth callback. A 2FA-enrolled account signing in with GitHub therefore got a
+ * complete, brand-new session with no code ever presented, which also cleared
+ * every fresh-session gate (passkey enrolment among them).
+ *
+ * This reproduces the teardown the password path already performs: delete the
+ * session row, clear the session cookie, null `newSession`, write the pending-
+ * challenge verification records, set the signed `two_factor` cookie. Because
+ * no session exists, every authenticated surface refuses the pending state by
+ * construction — no `aal`/`amr` flag to remember to check.
+ *
+ * One difference: the callback answers with a redirect rather than JSON, so
+ * instead of returning `{ twoFactorRedirect: true }` this rewrites the redirect
+ * target to the two-factor page, carrying the original destination.
+ */
+import type { BetterAuthPlugin } from "better-auth";
+import { createAuthMiddleware } from "better-auth/api";
+import { deleteSessionCookie, expireCookie } from "better-auth/cookies";
+import { generateRandomString } from "better-auth/crypto";
+
+/** Better Auth's own `two_factor` cookie name — not publicly re-exported. */
+const TWO_FACTOR_COOKIE = "two_factor";
+
+/** Ditto for `trust_device`, written by `/two-factor/verify-totp`. */
+const TRUST_DEVICE_COOKIE = "trust_device";
+
+/** `twoFactorCookieMaxAge ?? 600` in the twoFactor plugin; we leave it unset. */
+const CHALLENGE_MAX_AGE_SEC = 600;
+
+/** `trustDeviceMaxAge ?? 2592e3` in the twoFactor plugin; also left unset. */
+const TRUST_DEVICE_MAX_AGE_SEC = 2592e3;
+
+/** Where the browser lands to answer the challenge. */
+const TWO_FACTOR_PAGE = "/two-factor";
+
+// Returns the literal shape rather than a widened `BetterAuthPlugin`: annotating
+// the broad type erases the sibling plugins' endpoints from `auth.api`.
+export function socialTwoFactor() {
+	return {
+		id: "social-two-factor",
+		hooks: {
+			after: [
+				{
+					// The route is registered as `/callback/:id`; the dispatcher sets
+					// `path` to the route pattern, not the concrete provider path.
+					matcher(ctx) {
+						return ctx.path === "/callback/:id";
+					},
+					handler: createAuthMiddleware(async (ctx) => {
+						const data = ctx.context.newSession;
+						// Null on the account-link arm, on every redirectOnError path,
+						// and on the POST form_post pre-redirect arm.
+						if (!data) return;
+						if (!data.user.twoFactorEnabled) return;
+
+						// "Trust this device" is offered on our own challenge page, so
+						// it has to be honoured here too — otherwise the checkbox only
+						// ever works for the password path that wrote the cookie.
+						if (await deviceIsTrusted(ctx, data.user.id)) return;
+
+						// Same teardown, same order, as the password path.
+						// `true` = skipDontRememberMe: verify-totp reads that cookie
+						// later to decide the session lifetime.
+						deleteSessionCookie(ctx, true);
+						await ctx.context.internalAdapter.deleteSession(data.session.token);
+						ctx.context.setNewSession(null);
+
+						const cookie = ctx.context.createAuthCookie(TWO_FACTOR_COOKIE, {
+							maxAge: CHALLENGE_MAX_AGE_SEC,
+						});
+						const identifier = `2fa-${generateRandomString(20)}`;
+						const expiresAt = new Date(
+							Date.now() + CHALLENGE_MAX_AGE_SEC * 1000,
+						);
+						await ctx.context.internalAdapter.createVerificationValue({
+							value: data.user.id,
+							identifier,
+							expiresAt,
+						});
+						await ctx.context.internalAdapter.createVerificationValue({
+							value: "0",
+							identifier: `2fa-attempts-${identifier}`,
+							expiresAt,
+						});
+						await ctx.setSignedCookie(
+							cookie.name,
+							identifier,
+							ctx.context.secret,
+							cookie.attributes,
+						);
+
+						// The callback answers with a 302, so send the browser to the
+						// challenge instead of stranding it with a JSON body. The
+						// original destination rides along so it is not lost.
+						const target = new URL(TWO_FACTOR_PAGE, ctx.context.baseURL);
+						const original = ctx.context.responseHeaders?.get("location");
+						if (original) {
+							target.searchParams.set(
+								"redirect",
+								toRelative(original, ctx.context.baseURL),
+							);
+						}
+						throw ctx.redirect(`${target.pathname}${target.search}`);
+					}),
+				},
+			],
+		},
+	} satisfies BetterAuthPlugin;
+}
+
+/** `GenericEndpointContext`; `@better-auth/core` is not a resolvable import. */
+type HookContext = Parameters<typeof expireCookie>[0];
+
+/**
+ * The password path's trust-device check, verbatim (`two-factor/index.mjs`):
+ * the cookie carries `${token}!${identifier}`, the token is an HMAC over
+ * `${user.id}!${identifier}`, and the identifier must still resolve to a live
+ * verification row holding that same user id. A match rotates both record and
+ * cookie; anything else expires the cookie and falls through to the challenge.
+ */
+async function deviceIsTrusted(ctx: HookContext, userId: string) {
+	const attrs = ctx.context.createAuthCookie(TRUST_DEVICE_COOKIE, {
+		maxAge: TRUST_DEVICE_MAX_AGE_SEC,
+	});
+	const cookie = await ctx.getSignedCookie(attrs.name, ctx.context.secret);
+	if (!cookie) return false;
+
+	const [token, identifier] = cookie.split("!");
+	if (token && identifier && token === (await sign(ctx, userId, identifier))) {
+		const record =
+			await ctx.context.internalAdapter.findVerificationValue(identifier);
+		if (record && record.value === userId && record.expiresAt > new Date()) {
+			await ctx.context.internalAdapter.deleteVerificationByIdentifier(
+				identifier,
+			);
+			const next = `trust-device-${generateRandomString(32)}`;
+			await ctx.context.internalAdapter.createVerificationValue({
+				value: userId,
+				identifier: next,
+				expiresAt: new Date(Date.now() + TRUST_DEVICE_MAX_AGE_SEC * 1000),
+			});
+			await ctx.setSignedCookie(
+				attrs.name,
+				`${await sign(ctx, userId, next)}!${next}`,
+				ctx.context.secret,
+				attrs.attributes,
+			);
+			return true;
+		}
+	}
+	expireCookie(ctx, attrs);
+	return false;
+}
+
+/**
+ * `createHMAC("SHA-256", "base64urlnopad").sign` — `@better-auth/utils` is a
+ * transitive dependency of better-auth, not one we can import.
+ */
+async function sign(ctx: HookContext, userId: string, identifier: string) {
+	const bytes = new TextEncoder();
+	const key = await crypto.subtle.importKey(
+		"raw",
+		bytes.encode(ctx.context.secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["sign"],
+	);
+	const signature = await crypto.subtle.sign(
+		"HMAC",
+		key,
+		bytes.encode(`${userId}!${identifier}`),
+	);
+	return btoa(String.fromCharCode(...new Uint8Array(signature)))
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "");
+}
+
+/** Keep same-origin redirects relative; drop anything pointing elsewhere. */
+function toRelative(location: string, baseURL: string): string {
+	try {
+		const url = new URL(location, baseURL);
+		const base = new URL(baseURL);
+		if (url.origin !== base.origin) return "/";
+		return `${url.pathname}${url.search}${url.hash}`;
+	} catch {
+		return "/";
+	}
+}

package/template/src/lib/auth-timing.ts

@@ -0,0 +1,9 @@
+/** Shared auth / OAuth issuer timing constants (seconds). */
+
+const HOUR = 60 * 60;
+export const DAY = 24 * HOUR;
+
+/** OAuth access-token lifetime — single source for issuer config and helpers. */
+export const ACCESS_TOKEN_TTL_SEC = 6 * HOUR;
+
+export const EMAIL_VERIFICATION_EXPIRES_IN_SEC = HOUR;