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

package/template/src/utils/api-error.ts

@@ -0,0 +1,129 @@
+import type { z } from "zod";
+
+export type APIErrorProp = {
+	status: number;
+	error: string;
+	message: string;
+};
+
+export function APIError({ status, error, message }: APIErrorProp) {
+	return Response.json(
+		{
+			status,
+			error,
+			message,
+		},
+		{ status },
+	);
+}
+
+/**
+ * An API route's answer to a method it does not serve.
+ *
+ * Without one, a route that declares only POST leaves a browser's GET to fall
+ * through to the app router, which answers 200 with the whole SPA shell and no
+ * dehydrated router state — so the page loads and then fails to hydrate in the
+ * reader's browser. An API path has to answer as an API (ADR 0010).
+ *
+ * Routes wire this to GET and nothing else, deliberately. GET is the method a
+ * browser sends and the only one that produces the rendered body the failure
+ * needs; HEAD carries none, and answering OPTIONS here would put a 405 in front
+ * of a CORS preflight, which is a different question from this one.
+ */
+export function methodNotAllowed(allow: string) {
+	const response = APIError({
+		status: 405,
+		error: "method_not_allowed",
+		message: `This endpoint accepts ${allow} only.`,
+	});
+	response.headers.set("Allow", allow);
+	return response;
+}
+
+/**
+ * A server function's refusal, as an Error rather than a Response.
+ *
+ * A `Response` returned from server-fn middleware is stamped as a deliberate
+ * raw success and handed to the client as the resolved query value — so a 401
+ * arrives as *data*, TanStack Query caches it, and a component expecting an
+ * array crashes while one expecting an object renders a confident zero.
+ * Throwing this instead makes a refusal a rejected query, which nothing can
+ * mistake for a result.
+ *
+ * It survives the wire only because `src/start.ts` registers a serialization
+ * adapter for it. Without that, the router's shallow error serializer keeps
+ * `message` and drops every custom property — including `.status`.
+ *
+ * `APIError` above stays for route handlers and the OAuth surface, which
+ * legitimately answer with a `Response`.
+ */
+export class HttpError extends Error {
+	readonly status: number;
+	readonly error: string;
+
+	constructor({ status, error, message }: APIErrorProp) {
+		super(message);
+		this.name = "HttpError";
+		this.status = status;
+		this.error = error;
+	}
+}
+
+/**
+ * What a failed call may tell the user.
+ *
+ * Only a 4xx `HttpError` message is written for them — a refused name states
+ * the rule, so showing it is the difference between correcting the name and
+ * retrying it forever. Everything else (a 5xx, a stray `TypeError`) carries
+ * internal detail written for us, and gets the caller's own wording.
+ */
+export function userFacingMessage(error: unknown, fallback: string): string {
+	if (!(error instanceof HttpError)) return fallback;
+	return error.status >= 400 && error.status < 500 ? error.message : fallback;
+}
+
+/**
+ * What a caller is told when a field breaks a rule nobody wrote out.
+ *
+ * zod's own wording is written for whoever wrote the schema, not for the person
+ * who typed the value: "Invalid string: must match pattern /^\d{4}-\d{2}-\d{2}$/"
+ * hands the reader a regular expression, and "Too small: expected string to have
+ * >=1 characters" reads like a stack frame. Neither may be shown (ADR 0010).
+ */
+const INVALID_INPUT = "That input isn't valid.";
+
+/**
+ * The one way a server function declares its input (ADR 0010).
+ *
+ * `.validator(schema)` and `.validator((d) => schema.parse(d))` both leave the
+ * framework's `execValidator` to throw: the first as an `Error` whose message
+ * is a JSON dump of the schema's issues, the second as a bare `ZodError`.
+ * Neither carries `.status`, so a caller who mistypes a field is shown a dump
+ * written for nobody, and an expected 4xx reaches error reporting as a crash.
+ *
+ * Wrapping the schema makes that refusal a 400 like every other, which is all
+ * it takes — the status is what every downstream filter reads.
+ */
+export function validated<TSchema extends z.ZodType>(
+	schema: TSchema,
+): (input: z.input<TSchema>) => z.output<TSchema> {
+	// Declared as the schema's own input, not `unknown`: the framework reads this
+	// signature to decide whether `data` is required at the call site, and
+	// `unknown` accepts `undefined` — so typing it honestly would quietly make
+	// every wrapped server function's argument optional. Nothing is lost, since
+	// what actually arrives is parsed rather than trusted.
+	return (input: unknown) => {
+		// A message the schema's author wrote outranks this map, and a message zod
+		// would have generated does not — so an authored rule still reaches the
+		// reader while zod's own wording can never be what they see.
+		const parsed = schema.safeParse(input, { error: () => INVALID_INPUT });
+		if (parsed.success) return parsed.data;
+		throw new HttpError({
+			status: 400,
+			error: "invalid_param",
+			// The first issue's message only: its `path`, `code` and the shape of
+			// the rest of the array are internal.
+			message: parsed.error.issues[0]?.message ?? INVALID_INPUT,
+		});
+	};
+}

package/template/src/utils/auth-errors.ts

@@ -0,0 +1,157 @@
+import * as m from "@/paraglide/messages";
+
+/**
+ * Messages for the `?error=` codes the OAuth callback can bounce back with.
+ * `email_not_found` is Better Auth's built-in no-email rejection;
+ * `github_email_unverified` comes from the signup gate in
+ * `services/account-security`; `account_not_linked` is the built-in refusal to
+ * auto-link an unverified provider email onto an existing account.
+ */
+export function oauthErrorMessage(code: string | undefined): string | null {
+	switch (code) {
+		case undefined:
+			return null;
+		case "email_not_found":
+			return m.auth_oauth_no_email();
+		case "github_email_unverified":
+			return m.auth_oauth_email_unverified();
+		case "account_not_linked":
+			return m.auth_oauth_account_not_linked();
+		default:
+			return m.auth_oauth_generic();
+	}
+}
+
+/**
+ * The refusal codes `src/services/account-security.ts` returns, as copy.
+ *
+ * One map rather than a message per call site: every security action can
+ * return any of these, and a page that formats the code itself ends up showing
+ * `not_fresh` to someone who needs to be told to sign in again.
+ */
+export function accountSecurityErrorMessage(code: string): string {
+	switch (code) {
+		case "already_enabled":
+			return m.account_err_already_enabled();
+		case "cooldown":
+			return m.account_err_cooldown();
+		case "email_not_found":
+			return m.account_err_email_not_found();
+		case "github_email_unverified":
+			return m.account_err_github_email_unverified();
+		case "invalid_code":
+			return m.account_err_invalid_code();
+		case "not_enabled":
+			return m.account_err_not_enabled();
+		case "not_fresh":
+			return m.account_err_not_fresh();
+		case "too_many_attempts":
+			return m.account_err_too_many_attempts();
+		case "totp_required":
+			return m.account_err_totp_required();
+		case "unauthorized":
+			return m.account_err_unauthorized();
+		default:
+			return m.auth_error_generic();
+	}
+}
+
+/** Better Auth verification redirects use SCREAMING_SNAKE; OAuth uses snake_case. */
+const VERIFICATION_STYLE_CODE = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * Messages for `?error=` codes Better Auth appends when email verification
+ * fails and redirects to callbackURL (default `/` or `/sign-in`).
+ * Codes come from BASE_ERROR_CODES (TOKEN_EXPIRED, INVALID_TOKEN, …).
+ */
+export function verificationErrorMessage(
+	code: string | undefined,
+): string | null {
+	switch (code) {
+		case undefined:
+			return null;
+		case "TOKEN_EXPIRED":
+			return m.auth_verify_token_expired();
+		case "INVALID_TOKEN":
+			return m.auth_verify_token_invalid();
+		case "USER_NOT_FOUND":
+			return m.auth_verify_user_not_found();
+		default:
+			// Other verification-style codes (e.g. INVALID_USER). Leave OAuth
+			// snake_case codes (email_not_found, …) for oauthErrorMessage.
+			if (VERIFICATION_STYLE_CODE.test(code)) {
+				return m.auth_verify_generic();
+			}
+			return null;
+	}
+}
+
+/**
+ * Prefer verification copy, then OAuth copy, for a shared `?error=` query.
+ * Sign-in can receive either class of redirect.
+ */
+export function authQueryErrorMessage(code: string | undefined): string | null {
+	return verificationErrorMessage(code) ?? oauthErrorMessage(code);
+}
+
+/**
+ * Transport failures, which arrive as a thrown `TypeError` rather than an
+ * `{ error }` result — Safari says "Load failed", Chrome "Failed to fetch".
+ * Matched by message because neither carries a status or a code.
+ */
+const NETWORK_MESSAGE =
+	/^(Load failed|Failed to fetch|NetworkError when attempting to fetch resource\.?|Network request failed)$/i;
+
+type AuthCallError = {
+	message?: string | null;
+	status?: number;
+	statusCode?: number;
+};
+
+export type SettledAuthError = {
+	message: string;
+	status?: number;
+};
+
+/**
+ * Run a Better Auth client call that either returns `{ data, error }` or throws
+ * on transport failure. Never throws — always returns a settled `{ data, error }`
+ * so a page renders a banner instead of hitting the error boundary.
+ */
+export async function settleAuthCall<T = unknown>(
+	call: () => Promise<{ data?: T | null; error?: AuthCallError | null }>,
+): Promise<{ data: T; error: null } | { data: null; error: SettledAuthError }> {
+	try {
+		const result = await call();
+		if (result.error) {
+			const status =
+				typeof result.error.status === "number"
+					? result.error.status
+					: typeof result.error.statusCode === "number"
+						? result.error.statusCode
+						: undefined;
+			return {
+				data: null,
+				error: {
+					message: result.error.message?.trim() || m.auth_error_generic(),
+					...(status !== undefined ? { status } : {}),
+				},
+			};
+		}
+		return { data: result.data as T, error: null };
+	} catch (error) {
+		const message =
+			error instanceof Error ? error.message : String(error ?? "");
+		if (NETWORK_MESSAGE.test(message)) {
+			return { data: null, error: { message: m.auth_error_network() } };
+		}
+		return {
+			data: null,
+			error: {
+				message:
+					(error instanceof Error && error.message.trim()) ||
+					m.auth_error_generic(),
+			},
+		};
+	}
+}

package/template/src/utils/auth-redirect.ts

@@ -0,0 +1,61 @@
+/**
+ * Post-authentication navigation, shared by the sign-in page, the two-factor
+ * page, and the social/passkey buttons. Client-only (reads window).
+ */
+import { localizeHref } from "@/paraglide/runtime";
+
+/** Default landing after a successful sign-in when no ?redirect= is present. */
+export const DEFAULT_AFTER_AUTH_PATH = "/dashboard";
+
+/**
+ * Locale-prefix a Starter auth HTML path for the active locale.
+ * Machine paths (`/api/*`) must not go through this helper.
+ */
+export function localizedAuthPath(
+	path: "/sign-in" | "/sign-up" | "/two-factor" | "/forgot-password",
+): string {
+	return localizeHref(path);
+}
+
+export function safeRedirectPath(value: string | null): string {
+	if (!value) return DEFAULT_AFTER_AUTH_PATH;
+	if (!value.startsWith("/") || value.startsWith("//")) {
+		return DEFAULT_AFTER_AUTH_PATH;
+	}
+	if (value.includes("\\")) return DEFAULT_AFTER_AUTH_PATH;
+	if ([...value].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127)) {
+		return DEFAULT_AFTER_AUTH_PATH;
+	}
+	try {
+		const url = new URL(value, window.location.origin);
+		return url.origin === window.location.origin
+			? `${url.pathname}${url.search}${url.hash}`
+			: DEFAULT_AFTER_AUTH_PATH;
+	} catch {
+		return DEFAULT_AFTER_AUTH_PATH;
+	}
+}
+
+/**
+ * Send a user whose session died back to sign-in, carrying where they were so
+ * they land back on it. A full navigation rather than a router one: the session
+ * is gone, so every cached query behind it is stale too.
+ *
+ * Path is locale-prefixed so full-app URL i18n is preserved (e.g. `/de/sign-in`).
+ */
+export function goToSignIn(from: string): void {
+	const signIn = localizedAuthPath("/sign-in");
+	window.location.href = `${signIn}?redirect=${encodeURIComponent(from)}`;
+}
+
+/**
+ * Where to land after a completed authentication: resume an OAuth authorize
+ * flow if we arrived mid-authorize (a client_id in the signed query the login
+ * page carries), otherwise honor ?redirect or the user dashboard.
+ */
+export function afterAuthTarget(): string {
+	const query = window.location.search.replace(/^\?/, "");
+	const params = new URLSearchParams(query);
+	if (params.has("client_id")) return `/api/auth/oauth2/authorize?${query}`;
+	return safeRedirectPath(params.get("redirect"));
+}

package/template/src/utils/body-limit.ts

@@ -0,0 +1,84 @@
+/**
+ * Reading a request body behind a hard cap.
+ *
+ * A `Content-Length` check alone is bypassed by a chunked request — the header
+ * is absent and the guard never fires — so the cap has to count bytes as they
+ * arrive. Public webhooks must not buffer an unbounded body before the
+ * signature is verified.
+ *
+ * `readTextCapped` hands back the raw string, not parsed JSON: webhooks verify
+ * signatures over the exact characters received.
+ *
+ * Framework-agnostic and binding-free — no `cloudflare:workers` import.
+ */
+
+export class BodyTooLargeError extends Error {
+	constructor() {
+		super("Request body is too large.");
+		this.name = "BodyTooLargeError";
+	}
+}
+
+export class UnsupportedMediaTypeError extends Error {
+	constructor() {
+		super("Request body must be application/json.");
+		this.name = "UnsupportedMediaTypeError";
+	}
+}
+
+export type CappedReadOptions = {
+	maxBytes: number;
+	/** Require an `application/json` content type. Default true. */
+	requireJson?: boolean;
+};
+
+function assertJsonContentType(request: Request): void {
+	const header = request.headers.get("content-type") ?? "";
+	const mediaType = header.split(";")[0].trim().toLowerCase();
+	if (mediaType !== "application/json") throw new UnsupportedMediaTypeError();
+}
+
+/**
+ * Read the body as text, refusing anything over `maxBytes` whether or not a
+ * `Content-Length` was declared. Returns `""` when there is no body.
+ */
+export async function readTextCapped(
+	request: Request,
+	{ maxBytes, requireJson = true }: CappedReadOptions,
+): Promise<string> {
+	if (requireJson) assertJsonContentType(request);
+
+	const declared = request.headers.get("content-length");
+	if (declared && Number(declared) > maxBytes) throw new BodyTooLargeError();
+
+	const reader = request.body?.getReader();
+	if (!reader) return "";
+
+	const decoder = new TextDecoder();
+	let text = "";
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > maxBytes) {
+			await reader.cancel();
+			throw new BodyTooLargeError();
+		}
+		text += decoder.decode(value, { stream: true });
+	}
+
+	return text + decoder.decode();
+}
+
+/**
+ * Same cap, parsed. Returns `{}` for a body-less request.
+ */
+export async function readJsonCapped(
+	request: Request,
+	options: CappedReadOptions,
+): Promise<unknown> {
+	const text = await readTextCapped(request, options);
+	if (text === "") return {};
+	return JSON.parse(text);
+}

package/template/src/utils/cn.ts

@@ -0,0 +1,6 @@
+type ClassPart = string | false | null | undefined;
+
+/** Join class names, skipping falsy values. */
+export function cn(...parts: ClassPart[]): string {
+	return parts.filter(Boolean).join(" ");
+}

package/template/src/utils/input-rules.ts

@@ -0,0 +1,172 @@
+/**
+ * Server-side field rules. A route's zod schema runs in the browser only —
+ * Better Auth endpoints accept whatever is posted — so rules that matter live
+ * here. Free-form text is hardened, not sanitized.
+ */
+import { HttpError } from "@/utils/api-error";
+
+export const MAX_DISPLAY_NAME_LENGTH = 32;
+export const MAX_PASSKEY_NAME_LENGTH = 64;
+export const MAX_EMAIL_LENGTH = 254;
+export const MAX_EMAIL_LOCAL_LENGTH = 32;
+export const MIN_PASSWORD_LENGTH = 8;
+export const MAX_PASSWORD_LENGTH = 32;
+
+function isControl(cp: number, allowNewlines: boolean): boolean {
+	if (allowNewlines && (cp === 0x0a || cp === 0x0d || cp === 0x09))
+		return false;
+	return (cp >= 0x00 && cp <= 0x1f) || (cp >= 0x7f && cp <= 0x9f);
+}
+
+function isBidiOverride(cp: number): boolean {
+	return (
+		(cp >= 0x202a && cp <= 0x202e) ||
+		(cp >= 0x2066 && cp <= 0x2069) ||
+		cp === 0x200e ||
+		cp === 0x200f ||
+		cp === 0x061c
+	);
+}
+
+function isZeroWidth(cp: number): boolean {
+	return (cp >= 0x200b && cp <= 0x200d) || cp === 0xfeff;
+}
+
+function hasControl(value: string, allowNewlines: boolean): boolean {
+	for (const ch of value) {
+		if (isControl(ch.codePointAt(0) ?? 0, allowNewlines)) return true;
+	}
+	return false;
+}
+
+function has(value: string, predicate: (cp: number) => boolean): boolean {
+	for (const ch of value) {
+		if (predicate(ch.codePointAt(0) ?? 0)) return true;
+	}
+	return false;
+}
+
+/**
+ * A broken field rule, as a 400 rather than a bare `Error`.
+ *
+ * Extending `HttpError` is what carries `.status` across the wire (via the
+ * adapter in `src/start.ts`) and what lets `userFacingMessage` show the rule to
+ * the person who broke it. A plain `Error` here would reach the client with its
+ * message stripped, so a refused display name would read as a server fault.
+ */
+export class InvalidFieldError extends HttpError {
+	constructor(message: string) {
+		super({ status: 400, error: "invalid_param", message });
+		this.name = "InvalidFieldError";
+	}
+}
+
+function assertNoInvisibles(value: string, field: string): void {
+	if (has(value, isBidiOverride)) {
+		throw new InvalidFieldError(
+			`${field} cannot contain text-direction overrides.`,
+		);
+	}
+	if (has(value, isZeroWidth)) {
+		throw new InvalidFieldError(
+			`${field} cannot contain invisible characters.`,
+		);
+	}
+}
+
+export function normalizeDisplayName(raw: string): string {
+	const value = raw.normalize("NFKC").trim();
+	if (!value) throw new InvalidFieldError("Name is required.");
+	if (value.length > MAX_DISPLAY_NAME_LENGTH) {
+		throw new InvalidFieldError(
+			`Name is too long (maximum ${MAX_DISPLAY_NAME_LENGTH} characters).`,
+		);
+	}
+	if (hasControl(value, false)) {
+		throw new InvalidFieldError("Name cannot contain control characters.");
+	}
+	assertNoInvisibles(value, "Name");
+	return value;
+}
+
+export function sanitizeDerivedDisplayName(raw: string): string {
+	const value = [...raw.normalize("NFKC")]
+		.filter((ch) => {
+			const cp = ch.codePointAt(0) ?? 0;
+			return !isControl(cp, false) && !isBidiOverride(cp) && !isZeroWidth(cp);
+		})
+		.join("")
+		.trim()
+		.slice(0, MAX_DISPLAY_NAME_LENGTH);
+	return value || "User";
+}
+
+export function normalizeFreeformText(
+	raw: string,
+	field: string,
+	maxLength: number,
+): string {
+	const value = raw.normalize("NFKC").trim();
+	if (!value) throw new InvalidFieldError(`${field} is required.`);
+	if (value.length > maxLength) {
+		throw new InvalidFieldError(
+			`${field} is too long (maximum ${maxLength} characters).`,
+		);
+	}
+	if (hasControl(value, true)) {
+		throw new InvalidFieldError(`${field} cannot contain control characters.`);
+	}
+	assertNoInvisibles(value, field);
+	return value;
+}
+
+export function assertPasswordRules(password: string): void {
+	if (password.length < MIN_PASSWORD_LENGTH) {
+		throw new InvalidFieldError(
+			`Password must be at least ${MIN_PASSWORD_LENGTH} characters.`,
+		);
+	}
+	if (password.length > MAX_PASSWORD_LENGTH) {
+		throw new InvalidFieldError(
+			`Password must be at most ${MAX_PASSWORD_LENGTH} characters.`,
+		);
+	}
+	if (!/\p{L}/u.test(password)) {
+		throw new InvalidFieldError("Password must contain a letter.");
+	}
+	if (!/\p{Nd}/u.test(password)) {
+		throw new InvalidFieldError("Password must contain a digit.");
+	}
+	if (!/[^\p{L}\p{Nd}]/u.test(password)) {
+		throw new InvalidFieldError("Password must contain a symbol.");
+	}
+}
+
+export function assertEmailLimits(email: string): void {
+	if (email.length > MAX_EMAIL_LENGTH) {
+		throw new InvalidFieldError(
+			`Email must be at most ${MAX_EMAIL_LENGTH} characters.`,
+		);
+	}
+	const at = email.lastIndexOf("@");
+	const local = at === -1 ? email : email.slice(0, at);
+	if (local.length > MAX_EMAIL_LOCAL_LENGTH) {
+		throw new InvalidFieldError(
+			`The part of the email before @ must be at most ${MAX_EMAIL_LOCAL_LENGTH} characters.`,
+		);
+	}
+}
+
+export function assertPasskeyName(name: string): void {
+	normalizeFreeformText(name, "Passkey name", MAX_PASSKEY_NAME_LENGTH);
+}
+
+export const SUPPORTED_LOCALES = ["en", "de"] as const;
+export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+
+export function assertLocale(locale: string): SupportedLocale {
+	if ((SUPPORTED_LOCALES as readonly string[]).includes(locale)) {
+		return locale as SupportedLocale;
+	}
+	throw new InvalidFieldError("That locale isn't supported.");
+}

package/template/src/utils/locale-paths.ts

@@ -0,0 +1,18 @@
+/**
+ * Locale → path pairs for one user-facing page (English bare, German prefixed).
+ * Shared by Paraglide urlPatterns so English stays bare and German is prefixed.
+ */
+export function localizedLocalePaths(
+	page: string,
+): Array<readonly [string, string]> {
+	if (page === "/") {
+		return [
+			["en", "/"],
+			["de", "/de/"],
+		];
+	}
+	return [
+		["en", page],
+		["de", `/de${page}`],
+	];
+}

package/template/src/utils/same-page-locale-href.ts

@@ -0,0 +1,20 @@
+import { deLocalizeHref, type Locale, localizeHref } from "@/paraglide/runtime";
+
+/**
+ * Build a same-page language-switch href: localize the path, keep search and
+ * hash byte-for-byte. Pure over the compiled Paraglide runtime.
+ */
+export function samePageLocaleHref(input: {
+	pathname: string;
+	/** Including leading "?", or "". */
+	search?: string;
+	/** Including leading "#", or "". */
+	hash?: string;
+	locale: Locale;
+}): string {
+	const search = input.search ?? "";
+	const hash = input.hash ?? "";
+	const canonical = deLocalizeHref(input.pathname);
+	const path = localizeHref(canonical, { locale: input.locale });
+	return `${path}${search}${hash}`;
+}