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

package/template/src/lib/auth.ts

@@ -0,0 +1,279 @@
+import { waitUntil } from "cloudflare:workers";
+import { drizzleAdapter } from "@better-auth/drizzle-adapter";
+import { oauthProvider } from "@better-auth/oauth-provider";
+import { passkey } from "@better-auth/passkey";
+import { APIError, betterAuth } from "better-auth";
+import { admin, captcha, emailOTP, jwt, twoFactor } from "better-auth/plugins";
+import { tanstackStartCookies } from "better-auth/tanstack-start";
+import { eq } from "drizzle-orm";
+import type { Database } from "@/db";
+// Aliased: `user` is already the member role imported from ./permissions.
+import { user as userTable } from "@/db/schema";
+import { env } from "@/env";
+import { CAPTCHA_ENDPOINTS, DISABLED_AUTH_PATHS } from "@/lib/auth-paths";
+import { CAPTCHA_ENABLED } from "@/lib/captcha";
+import {
+	evaluateGithubSignup,
+	TWO_FACTOR_ISSUER,
+} from "@/services/account-security";
+import { canManageOAuthClients } from "@/services/admin-security";
+import {
+	MAX_PASSWORD_LENGTH,
+	MIN_PASSWORD_LENGTH,
+	normalizeDisplayName,
+	sanitizeDerivedDisplayName,
+} from "@/utils/input-rules";
+import { existingEmailSignup } from "./auth-plugins/existing-email-signup";
+import { fieldRules } from "./auth-plugins/field-rules";
+import { socialTwoFactor } from "./auth-plugins/social-two-factor";
+import {
+	ACCESS_TOKEN_TTL_SEC,
+	DAY,
+	EMAIL_VERIFICATION_EXPIRES_IN_SEC,
+} from "./auth-timing";
+import {
+	sendPasswordOtpEmail,
+	sendResetPasswordEmail,
+	sendVerificationEmail,
+} from "./email";
+import { issuerFromAuthUrl } from "./oauth-metadata";
+import { ac, admin as adminRole, superadmin, user } from "./permissions";
+import { userUpdateGuard } from "./user-update-guard";
+
+export { ACCESS_TOKEN_TTL_SEC } from "./auth-timing";
+
+/** Authorization-server identifier advertised in discovery / PRM. */
+export function getIssuer() {
+	return issuerFromAuthUrl(env.BETTER_AUTH_URL);
+}
+
+function audiences(): string[] {
+	if (env.BETTER_AUTH_AUDIENCES) {
+		return env.BETTER_AUTH_AUDIENCES.split(",")
+			.map((s) => s.trim())
+			.filter(Boolean);
+	}
+	return [env.APP_ORIGIN];
+}
+
+export function createAuth(db: Database) {
+	// Public client id: prefer server GITHUB_CLIENT_ID, fall back to the same
+	// Vite-public value the UI uses so button visibility and provider config
+	// cannot drift.
+	const githubClientId =
+		env.GITHUB_CLIENT_ID?.trim() ||
+		(typeof import.meta.env.VITE_GITHUB_CLIENT_ID === "string"
+			? import.meta.env.VITE_GITHUB_CLIENT_ID.trim()
+			: "") ||
+		undefined;
+	const githubConfigured =
+		Boolean(githubClientId) && Boolean(env.GITHUB_CLIENT_SECRET);
+
+	return betterAuth({
+		baseURL: env.BETTER_AUTH_URL,
+		disabledPaths: [...DISABLED_AUTH_PATHS],
+		database: drizzleAdapter(db, {
+			provider: "pg",
+		}),
+		trustedOrigins: [
+			"http://localhost:3000",
+			env.APP_ORIGIN,
+			env.BETTER_AUTH_URL,
+		].filter((v, i, a) => a.indexOf(v) === i),
+		telemetry: { enabled: false },
+		advanced: {
+			backgroundTasks: {
+				handler: (promise) => {
+					waitUntil(promise);
+				},
+			},
+		},
+		session: {
+			cookieCache: {
+				enabled: !import.meta.env.DEV,
+				maxAge: 360,
+			},
+		},
+		emailAndPassword: {
+			enabled: true,
+			requireEmailVerification: true,
+			minPasswordLength: MIN_PASSWORD_LENGTH,
+			maxPasswordLength: MAX_PASSWORD_LENGTH,
+			revokeSessionsOnPasswordReset: true,
+			sendResetPassword: async ({ user: u, url }) => {
+				await sendResetPasswordEmail({
+					to: u.email,
+					url,
+					name: u.name,
+					locale: (u as { locale?: string | null }).locale,
+				});
+			},
+		},
+		emailVerification: {
+			sendOnSignUp: true,
+			sendOnSignIn: true,
+			autoSignInAfterVerification: true,
+			expiresIn: EMAIL_VERIFICATION_EXPIRES_IN_SEC,
+			sendVerificationEmail: async ({ user: u, url }) => {
+				await sendVerificationEmail({
+					to: u.email,
+					url,
+					name: u.name,
+					locale: (u as { locale?: string | null }).locale,
+				});
+			},
+		},
+		...(githubConfigured
+			? {
+					socialProviders: {
+						github: {
+							clientId: githubClientId as string,
+							clientSecret: env.GITHUB_CLIENT_SECRET as string,
+						},
+					},
+				}
+			: {}),
+		user: {
+			additionalFields: {
+				tokensRevokedAt: { type: "date", required: false, input: false },
+				locale: { type: "string", required: false, input: true },
+			},
+		},
+		databaseHooks: {
+			user: {
+				create: {
+					before: async (newUser, context) => {
+						if (context?.path?.startsWith("/callback")) {
+							const u = newUser as {
+								email?: string;
+								emailVerified?: boolean;
+								name?: string;
+							};
+							const verdict = evaluateGithubSignup({
+								email: u.email,
+								emailVerified: Boolean(u.emailVerified),
+							});
+							if (!verdict.ok) {
+								throw new APIError("BAD_REQUEST", {
+									message: verdict.code,
+									code: verdict.code,
+								});
+							}
+							if (typeof u.name === "string") {
+								return {
+									data: {
+										...newUser,
+										name: sanitizeDerivedDisplayName(u.name),
+									},
+								};
+							}
+						}
+						if (typeof newUser.name === "string") {
+							try {
+								return {
+									data: {
+										...newUser,
+										name: normalizeDisplayName(newUser.name),
+									},
+								};
+							} catch {
+								throw new APIError("BAD_REQUEST", {
+									message: "Invalid display name.",
+								});
+							}
+						}
+						return { data: newUser };
+					},
+				},
+				update: {
+					before: async (data, context) => {
+						const guarded = userUpdateGuard(data);
+						if (!guarded.data || typeof guarded.data !== "object") {
+							return guarded;
+						}
+						const rest = { ...(guarded.data as Record<string, unknown>) };
+						// Same display-name rule on edit. Human-typed updates refuse
+						// invalid names; system-supplied names (e.g. provider sync) strip.
+						if (typeof rest.name === "string") {
+							if (context?.path === "/update-user") {
+								try {
+									rest.name = normalizeDisplayName(rest.name);
+								} catch (err) {
+									throw new APIError("BAD_REQUEST", {
+										message:
+											err instanceof Error ? err.message : "Invalid name.",
+									});
+								}
+							} else {
+								rest.name = sanitizeDerivedDisplayName(rest.name);
+							}
+						}
+						return { data: rest as typeof data };
+					},
+				},
+			},
+		},
+		plugins: [
+			jwt(),
+			oauthProvider({
+				loginPage: "/sign-in",
+				consentPage: "/oauth/consent",
+				validAudiences: audiences(),
+				clientPrivileges: ({ user: u }) => canManageOAuthClients(u),
+				allowDynamicClientRegistration: false,
+				allowUnauthenticatedClientRegistration: false,
+				accessTokenExpiresIn: ACCESS_TOKEN_TTL_SEC,
+				refreshTokenExpiresIn: 30 * DAY,
+			}),
+			...(CAPTCHA_ENABLED && env.TURNSTILE_SECRET_KEY
+				? [
+						captcha({
+							provider: "cloudflare-turnstile",
+							secretKey: env.TURNSTILE_SECRET_KEY,
+							endpoints: [...CAPTCHA_ENDPOINTS],
+						}),
+					]
+				: []),
+			admin({
+				ac,
+				roles: { admin: adminRole, superadmin, user },
+			}),
+			twoFactor({
+				issuer: TWO_FACTOR_ISSUER,
+			}),
+			emailOTP({
+				async sendVerificationOTP({ email, otp, type }) {
+					if (type !== "forget-password" && type !== "sign-in") return;
+					// This callback is handed an address, not a user, so the
+					// recipient's language costs one indexed lookup. An address with
+					// no account still gets a code (that is the plugin's own
+					// enumeration defence) — it just gets it in the base locale.
+					const [row] = await db
+						.select({ locale: userTable.locale })
+						.from(userTable)
+						.where(eq(userTable.email, email))
+						.limit(1);
+					await sendPasswordOtpEmail({
+						to: email,
+						otp,
+						type,
+						locale: row?.locale,
+					});
+				},
+			}),
+			passkey({
+				rpID: new URL(env.APP_ORIGIN).hostname,
+				rpName: env.EMAIL_FROM_NAME,
+			}),
+			existingEmailSignup(),
+			fieldRules(),
+			// After twoFactor so the social callback can tear down a full session.
+			socialTwoFactor(),
+			// Must be last.
+			tanstackStartCookies(),
+		],
+	});
+}
+
+// For better-auth schema generation only.
+export const auth = createAuth({} as unknown as Database);

package/template/src/lib/captcha.ts

@@ -0,0 +1,11 @@
+// Cloudflare Turnstile is enabled only in production builds that have a public
+// site key configured. The Better Auth captcha plugin (server) and the widget
+// (client) both read this SAME build-time constant, so they can never disagree:
+// no site key ⇒ plugin stays off, so the server never demands a token the
+// client can't mint. Vite inlines `import.meta.env.*` into both the worker and
+// browser bundles, which is what lets one module gate both sides.
+export const TURNSTILE_SITE_KEY = import.meta.env.VITE_TURNSTILE_SITE_KEY as
+	| string
+	| undefined;
+
+export const CAPTCHA_ENABLED = import.meta.env.PROD && !!TURNSTILE_SITE_KEY;

package/template/src/lib/email.tsx

@@ -0,0 +1,162 @@
+import { render } from "@react-email/render";
+import type { ReactElement } from "react";
+import { env } from "@/env";
+import { PasswordOtpEmail } from "@/integrations/react-email/PasswordOtpEmail";
+import { ResetPasswordEmail } from "@/integrations/react-email/ResetPasswordEmail";
+import { VerifyEmail } from "@/integrations/react-email/VerifyEmail";
+import * as m from "@/paraglide/messages";
+
+type EmailBinding = {
+	send: (msg: {
+		from: { email: string; name: string };
+		to: string;
+		subject: string;
+		html: string;
+		text: string;
+	}) => Promise<void>;
+};
+
+async function emailBinding(): Promise<EmailBinding | null> {
+	try {
+		const { env: CFEnv } = await import("cloudflare:workers");
+		// Through `unknown`: the generated `Env` declares `EMAIL` with wrangler's
+		// own message type, which is structurally unrelated to the narrow shape
+		// this module actually sends.
+		return (CFEnv as unknown as { EMAIL?: EmailBinding }).EMAIL ?? null;
+	} catch {
+		return null;
+	}
+}
+
+async function send(opts: {
+	to: string;
+	subject: string;
+	email: ReactElement;
+	devLabel: string;
+	/** Dev-only detail (URLs / OTPs). Never logged in production. */
+	devDetail: string;
+}): Promise<void> {
+	const [html, text] = await Promise.all([
+		render(opts.email),
+		render(opts.email, { plainText: true }),
+	]);
+	const binding = await emailBinding();
+	if (!binding) {
+		if (import.meta.env.DEV) {
+			console.warn(
+				`[email] ${opts.devLabel} for ${opts.to}: ${opts.devDetail}`,
+			);
+		} else {
+			console.warn(
+				`[email] ${opts.devLabel} skipped (no binding) for ${opts.to}`,
+			);
+		}
+		return;
+	}
+	try {
+		await binding.send({
+			from: { email: env.EMAIL_FROM, name: env.EMAIL_FROM_NAME },
+			to: opts.to,
+			subject: opts.subject,
+			html,
+			text,
+		});
+	} catch (error) {
+		if (import.meta.env.DEV) {
+			console.warn(
+				`[email] ${opts.devLabel} for ${opts.to}: ${opts.devDetail}`,
+				error,
+			);
+		} else {
+			console.warn(`[email] ${opts.devLabel} failed for ${opts.to}`, error);
+		}
+	}
+}
+
+/**
+ * The recipient's own language, not the sender's.
+ *
+ * An email is rendered inside whatever request happened to trigger it — a
+ * webhook, a cron, another person's session — so ambient locale is the wrong
+ * source. Callers pass the account's stored `user.locale`; an account that has
+ * never chosen one falls back to the base locale rather than to the locale of
+ * whoever caused the send.
+ */
+type MailLocale = "en" | "de";
+
+export function mailLocale(value: string | null | undefined): MailLocale {
+	return value === "de" ? "de" : "en";
+}
+
+export async function sendVerificationEmail(opts: {
+	to: string;
+	url: string;
+	name?: string;
+	locale?: string | null;
+}): Promise<void> {
+	const locale = mailLocale(opts.locale);
+	await send({
+		to: opts.to,
+		subject: m.email_verify_subject({}, { locale }),
+		email: (
+			<VerifyEmail
+				url={opts.url}
+				name={opts.name}
+				brandName={env.EMAIL_FROM_NAME}
+				locale={locale}
+			/>
+		),
+		devLabel: "verification link",
+		devDetail: opts.url,
+	});
+}
+
+export async function sendResetPasswordEmail(opts: {
+	to: string;
+	url: string;
+	name?: string;
+	locale?: string | null;
+}): Promise<void> {
+	const locale = mailLocale(opts.locale);
+	await send({
+		to: opts.to,
+		subject: m.email_reset_subject({}, { locale }),
+		email: (
+			<ResetPasswordEmail
+				url={opts.url}
+				name={opts.name}
+				brandName={env.EMAIL_FROM_NAME}
+				locale={locale}
+			/>
+		),
+		devLabel: "password reset link",
+		devDetail: opts.url,
+	});
+}
+
+export async function sendPasswordOtpEmail(opts: {
+	to: string;
+	otp: string;
+	type: "forget-password" | "sign-in";
+	locale?: string | null;
+}): Promise<void> {
+	const locale = mailLocale(opts.locale);
+	const subject =
+		opts.type === "forget-password"
+			? m.email_otp_subject_reset({}, { locale })
+			: m.email_otp_subject_signin({}, { locale });
+	await send({
+		to: opts.to,
+		subject,
+		email: (
+			<PasswordOtpEmail
+				otp={opts.otp}
+				purpose={opts.type}
+				brandName={env.EMAIL_FROM_NAME}
+				locale={locale}
+			/>
+		),
+		devLabel: "OTP",
+		devDetail: opts.otp,
+	});
+}

package/template/src/lib/github.ts

@@ -0,0 +1,18 @@
+/**
+ * GitHub OAuth public client id — safe to expose in the browser.
+ *
+ * Server and UI share this value so the button cannot appear when the issuer
+ * has no provider (or vice versa). Prefer `VITE_GITHUB_CLIENT_ID` (inlined for
+ * both bundles). `GITHUB_CLIENT_ID` is an optional server-only alias that must
+ * match when both are set.
+ */
+function githubPublicClientId(): string | undefined {
+	const fromVite =
+		typeof import.meta.env.VITE_GITHUB_CLIENT_ID === "string"
+			? import.meta.env.VITE_GITHUB_CLIENT_ID.trim()
+			: "";
+	return fromVite || undefined;
+}
+
+/** True when the sign-in/up UI should offer GitHub. */
+export const GITHUB_OAUTH_ENABLED = Boolean(githubPublicClientId());

package/template/src/lib/locale-cookie.ts

@@ -0,0 +1,12 @@
+/** Cookie written by the locale switcher so edge detect (if added) honors choice. */
+export const LOCALE_COOKIE = "PARAGLIDE_LOCALE";
+
+export function writeLocaleCookie(locale: string): void {
+	if (typeof document === "undefined") return;
+	const secure =
+		typeof window !== "undefined" && window.location.protocol === "https:"
+			? "; Secure"
+			: "";
+	// biome-ignore lint/suspicious/noDocumentCookie: plain sync cookie write; Cookie Store API not universal.
+	document.cookie = `${LOCALE_COOKIE}=${locale}; path=/; max-age=31536000; samesite=lax${secure}`;
+}

package/template/src/lib/localized-pages.ts

@@ -0,0 +1,25 @@
+/**
+ * Every Starter user-facing HTML path that receives a locale URL form.
+ *
+ * Machine paths (`/api/*`, `/.well-known/*`, webhooks) are intentionally
+ * omitted — the Paraglide identity catch-all leaves them unprefixed.
+ *
+ * Keep this list in sync with real routes under `src/routes/`. Nested
+ * dashboard/admin pages must appear here (or as a tree pattern in
+ * `paraglide.config.ts`) for full-app URL i18n.
+ */
+export const LOCALIZED_PAGES = [
+	"/",
+	"/sign-in",
+	"/sign-up",
+	"/forgot-password",
+	"/reset-password",
+	"/two-factor",
+	"/oauth/consent",
+	"/dashboard",
+	"/dashboard/account",
+	"/admin",
+	"/admin/users",
+	"/admin/audit",
+	"/admin/oauth-apps",
+] as const;

package/template/src/lib/oauth-metadata.ts

@@ -0,0 +1,19 @@
+/**
+ * OAuth discovery helpers for the Starter acting as issuer + resource.
+ * Pure builders so unit tests do not need Worker env.
+ */
+
+export function issuerFromAuthUrl(betterAuthUrl: string): string {
+	return `${betterAuthUrl.replace(/\/$/, "")}/api/auth`;
+}
+
+export function buildProtectedResourceMetadata(opts: {
+	resource: string;
+	issuer: string;
+}) {
+	return {
+		resource: opts.resource,
+		authorization_servers: [opts.issuer],
+		scopes_supported: ["openid", "profile", "email", "offline_access"] as const,
+	};
+}

package/template/src/lib/permissions.ts

@@ -0,0 +1,29 @@
+import { createAccessControl } from "better-auth/plugins/access";
+import { adminAc, defaultStatements } from "better-auth/plugins/admin/access";
+
+/**
+ * Access-control statements + roles for the Better Auth admin plugin.
+ * Starter roles: user / admin / superadmin only (no product-domain roles).
+ *
+ * Resources:
+ * - `config` — system settings including payment method toggles.
+ */
+export const statement = {
+	...defaultStatements, // user: [...], session: [...] from the admin plugin
+	config: ["read", "manage"],
+} as const;
+
+export const ac = createAccessControl(statement);
+
+export const user = ac.newRole({
+	config: [],
+});
+
+/** Full admin user/session powers + config. */
+export const admin = ac.newRole({
+	...adminAc.statements,
+	config: ["read", "manage"],
+});
+
+/** Alias: superadmin is the same capability set, distinguished only by name. */
+export const superadmin = admin;

package/template/src/lib/security-headers.ts

@@ -0,0 +1,20 @@
+/** Baseline security headers applied to every Worker response. */
+export const BASELINE_SECURITY_HEADERS: Record<string, string> = {
+	"X-Content-Type-Options": "nosniff",
+	"X-Frame-Options": "DENY",
+	"Referrer-Policy": "strict-origin-when-cross-origin",
+	"Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+};
+
+export function withSecurityHeaders(res: Response): Response {
+	const headers = new Headers(res.headers);
+	for (const [k, v] of Object.entries(BASELINE_SECURITY_HEADERS)) {
+		headers.set(k, v);
+	}
+	// Pass the body through untouched so streaming responses keep streaming.
+	return new Response(res.body, {
+		status: res.status,
+		statusText: res.statusText,
+		headers,
+	});
+}

package/template/src/lib/site.ts

@@ -0,0 +1,59 @@
+/**
+ * Site identity helpers for document head (title, OG, JSON-LD).
+ * Clone-time: set VITE_APP_TITLE / VITE_APP_ORIGIN (and server APP_ORIGIN).
+ */
+
+const trimSlash = (value: string) => value.replace(/\/+$/, "");
+
+function readOrigin(): string {
+	// Prefer public Vite env (available on client + build).
+	const viteOrigin = import.meta.env.VITE_APP_ORIGIN as string | undefined;
+	if (viteOrigin?.trim()) return trimSlash(viteOrigin.trim());
+
+	// Server-only: APP_ORIGIN from process (Workers / Node).
+	if (typeof process !== "undefined") {
+		const appOrigin = process.env.APP_ORIGIN?.trim();
+		if (appOrigin) return trimSlash(appOrigin);
+	}
+
+	// Browser fallback when env is not injected (local preview).
+	if (typeof window !== "undefined" && window.location?.origin) {
+		return trimSlash(window.location.origin);
+	}
+
+	return "";
+}
+
+/** Display name for <title>, PWA, and schema.org. */
+export const SITE_NAME =
+	(import.meta.env.VITE_APP_TITLE as string | undefined)?.trim() ||
+	"TanStack Starter";
+
+/**
+ * Absolute origin used for OG/JSON-LD URLs.
+ * Empty when unknown — structured data is then omitted.
+ */
+export const SITE_ORIGIN: string = readOrigin();
+
+/** Resolve a site-relative path to an absolute URL when origin is known. */
+export function abs(path: string): string {
+	const p = path.startsWith("/") ? path : `/${path}`;
+	return SITE_ORIGIN ? `${SITE_ORIGIN}${p}` : p;
+}
+
+export const DEFAULT_TITLE = `${SITE_NAME} — Platform SaaS starter`;
+export const DEFAULT_DESCRIPTION =
+	"Generic SaaS platform shell: auth, roles, Postgres Hyperdrive, email, Turnstile, optional payments, user dashboard, and admin console — no product domain. Clone and brand it.";
+
+/** Browser chrome tint — keep in sync with styles.css tokens. */
+export const THEME_COLOR_LIGHT = "#ffffff";
+export const THEME_COLOR_DARK = "#0a0a0a";
+
+/** Head meta for auth / dashboard / admin — never index transactional surfaces. */
+export const NOINDEX_META = [
+	{ name: "robots", content: "noindex, nofollow" },
+] as const;
+
+export function pageTitle(title: string): string {
+	return `${title} · ${SITE_NAME}`;
+}

package/template/src/lib/theme.ts

@@ -0,0 +1,42 @@
+export type ThemePreference = "light" | "dark" | "system";
+
+const THEME_STORAGE_KEY = "theme";
+
+export function readThemePreference(): ThemePreference {
+	if (typeof window === "undefined") return "system";
+	try {
+		const raw = localStorage.getItem(THEME_STORAGE_KEY);
+		if (raw === "light" || raw === "dark" || raw === "system") return raw;
+	} catch {
+		// ignore
+	}
+	return "system";
+}
+
+function resolveDark(preference: ThemePreference): boolean {
+	if (preference === "dark") return true;
+	if (preference === "light") return false;
+	if (typeof window === "undefined") return false;
+	return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+/** Apply theme to <html> and persist preference. */
+export function applyTheme(preference: ThemePreference): void {
+	if (typeof document === "undefined") return;
+	const dark = resolveDark(preference);
+	document.documentElement.classList.toggle("dark", dark);
+	document.documentElement.dataset.theme = preference;
+	try {
+		if (preference === "system") {
+			localStorage.removeItem(THEME_STORAGE_KEY);
+		} else {
+			localStorage.setItem(THEME_STORAGE_KEY, preference);
+		}
+	} catch {
+		// ignore quota / private mode
+	}
+}
+
+/** Inline FOUC-prevention script for document head. */
+export const THEME_INIT_SCRIPT =
+	"try{var k='theme';var t=localStorage.getItem(k);var d=t==='dark'||((t!=='light')&&matchMedia('(prefers-color-scheme: dark)').matches);document.documentElement.classList.toggle('dark',d);document.documentElement.dataset.theme=t==='light'||t==='dark'?t:'system'}catch(e){}";