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

package/template/src/__tests__/admin-http-surface.test.ts

@@ -0,0 +1,311 @@
+/**
+ * Peer protection must hold against Better Auth's own HTTP surface, not only
+ * server functions. The admin plugin mounts `/admin/*` routes that check
+ * `hasPermission` alone — without disabledPaths, a console fetch could demote
+ * a superadmin. Server-side `auth.api.*` still reaches those endpoints.
+ *
+ * Also measures DISABLED_AUTH_PATHS against routes plugins actually mount so a
+ * plugin upgrade cannot silently remount a surface believed closed.
+ *
+ * Starter omits the api-key plugin and product roles (no `provider`).
+ */
+
+import { drizzleAdapter } from "@better-auth/drizzle-adapter";
+import { passkey } from "@better-auth/passkey";
+import { betterAuth } from "better-auth";
+import { admin, emailOTP, twoFactor } from "better-auth/plugins";
+import { describe, expect, it } from "vitest";
+import { DISABLED_AUTH_PATHS } from "@/lib/auth-paths";
+import { ac, admin as adminRole, superadmin, user } from "@/lib/permissions";
+import {
+	AUTH_DDL,
+	cookieHeaders,
+	insertPasskey,
+	PASSKEY_DDL,
+} from "./auth-harness";
+import { createTestDatabase, hasTestDatabase } from "./test-db";
+
+const BASE = "http://localhost:3000";
+const PW = "Passw0rd!";
+
+async function makeAuth() {
+	const db = await createTestDatabase(AUTH_DDL);
+	const auth = betterAuth({
+		baseURL: BASE,
+		secret: "admin-http-surface-test-secret",
+		telemetry: { enabled: false },
+		database: drizzleAdapter(db, { provider: "pg" }),
+		emailAndPassword: { enabled: true },
+		disabledPaths: [...DISABLED_AUTH_PATHS],
+		plugins: [
+			admin({
+				ac,
+				roles: { admin: adminRole, superadmin, user },
+			}),
+		],
+	});
+	return { auth, db };
+}
+
+async function signedInAs(
+	auth: Awaited<ReturnType<typeof makeAuth>>["auth"],
+	db: Awaited<ReturnType<typeof makeAuth>>["db"],
+	email: string,
+	role: string,
+) {
+	const { eq } = await import("drizzle-orm");
+	const { user: userTable } = await import("@/db/auth.schema");
+	const res = await auth.api.signUpEmail({
+		body: { email, password: PW, name: role },
+		returnHeaders: true,
+	});
+	await db
+		.update(userTable)
+		.set({ role, emailVerified: true })
+		.where(eq(userTable.email, email));
+	const [row] = await db
+		.select({ id: userTable.id })
+		.from(userTable)
+		.where(eq(userTable.email, email));
+	return { headers: cookieHeaders(res.headers), id: row.id };
+}
+
+const roleOf = async (
+	db: Awaited<ReturnType<typeof makeAuth>>["db"],
+	id: string,
+) => {
+	const { eq } = await import("drizzle-orm");
+	const { user: userTable } = await import("@/db/auth.schema");
+	const [row] = await db
+		.select({ role: userTable.role, banned: userTable.banned })
+		.from(userTable)
+		.where(eq(userTable.id, id));
+	return row;
+};
+
+const post = (
+	auth: Awaited<ReturnType<typeof makeAuth>>["auth"],
+	path: string,
+	body: unknown,
+	headers: Headers,
+) =>
+	auth.handler(
+		new Request(`${BASE}/api/auth${path}`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				cookie: headers.get("cookie") ?? "",
+			},
+			body: JSON.stringify(body),
+		}),
+	);
+
+describe.skipIf(!hasTestDatabase)("the admin plugin's HTTP surface", () => {
+	it("does not let an administrator demote a superadmin", async () => {
+		const { auth, db } = await makeAuth();
+		const actor = await signedInAs(auth, db, "admin@test.local", "admin");
+		const target = await signedInAs(auth, db, "root@test.local", "superadmin");
+
+		const res = await post(
+			auth,
+			"/admin/set-role",
+			{ userId: target.id, role: "user" },
+			actor.headers,
+		);
+
+		expect(res.status).not.toBe(200);
+		expect((await roleOf(db, target.id)).role).toBe("superadmin");
+	});
+
+	it("does not let an administrator promote themselves", async () => {
+		const { auth, db } = await makeAuth();
+		const actor = await signedInAs(auth, db, "admin@test.local", "admin");
+
+		const res = await post(
+			auth,
+			"/admin/set-role",
+			{ userId: actor.id, role: "superadmin" },
+			actor.headers,
+		);
+
+		expect(res.status).not.toBe(200);
+		expect((await roleOf(db, actor.id)).role).toBe("admin");
+	});
+
+	it("does not let an administrator ban a peer", async () => {
+		const { auth, db } = await makeAuth();
+		const actor = await signedInAs(auth, db, "admin@test.local", "admin");
+		const target = await signedInAs(auth, db, "peer@test.local", "admin");
+
+		const res = await post(
+			auth,
+			"/admin/ban-user",
+			{ userId: target.id },
+			actor.headers,
+		);
+
+		expect(res.status).not.toBe(200);
+		expect((await roleOf(db, target.id)).banned).toBeFalsy();
+	});
+
+	it("does not let an administrator hard-delete anyone", async () => {
+		const { auth, db } = await makeAuth();
+		const actor = await signedInAs(auth, db, "admin@test.local", "admin");
+		const target = await signedInAs(auth, db, "victim@test.local", "user");
+
+		const res = await post(
+			auth,
+			"/admin/remove-user",
+			{ userId: target.id },
+			actor.headers,
+		);
+
+		expect(res.status).not.toBe(200);
+		expect(await roleOf(db, target.id)).toBeTruthy();
+	});
+
+	it("still reaches admin operations server-side via auth.api", async () => {
+		const { auth, db } = await makeAuth();
+		const actor = await signedInAs(auth, db, "admin@test.local", "admin");
+		const target = await signedInAs(auth, db, "victim@test.local", "user");
+
+		await auth.api.setRole({
+			body: { userId: target.id, role: "admin" },
+			headers: actor.headers,
+		});
+
+		expect((await roleOf(db, target.id)).role).toBe("admin");
+	});
+});
+
+/**
+ * Routes managed plugins mount that stay reachable on purpose.
+ */
+const PUBLIC_BY_DESIGN = new Set([
+	"/two-factor/verify-totp",
+	"/two-factor/verify-backup-code",
+]);
+
+describe.skipIf(!hasTestDatabase)("the disabled-path list", () => {
+	it("declares every route of every plugin whose surface it controls", async () => {
+		// Measured, not assumed: diff mounted routes with vs without each plugin.
+		const db = await createTestDatabase(AUTH_DDL);
+		const base = {
+			baseURL: BASE,
+			secret: "admin-http-surface-test-secret",
+			telemetry: { enabled: false },
+			database: drizzleAdapter(db, { provider: "pg" }),
+			emailAndPassword: { enabled: true },
+		};
+		const pathsOf = (plugins: Parameters<typeof betterAuth>[0]["plugins"]) =>
+			new Set(
+				Object.values(
+					betterAuth({ ...base, plugins }).api as Record<
+						string,
+						{ path?: string }
+					>,
+				)
+					.map((endpoint) => endpoint?.path)
+					.filter((p): p is string => typeof p === "string"),
+			);
+		const stock = pathsOf([]);
+		const declared = DISABLED_AUTH_PATHS as readonly string[];
+
+		// No api-key plugin — not a Starter platform default.
+		const managed = [
+			["admin", admin({ ac, roles: { admin: adminRole, superadmin, user } })],
+			["two-factor", twoFactor()],
+			["email-otp", emailOTP({ async sendVerificationOTP() {} })],
+		] as const;
+
+		const undeclared: string[] = [];
+		for (const [name, plugin] of managed) {
+			const mounted = [...pathsOf([plugin])].filter((p) => !stock.has(p));
+			expect(mounted.length, `${name} mounted no routes`).toBeGreaterThan(0);
+			undeclared.push(
+				...mounted.filter(
+					(p) => !declared.includes(p) && !PUBLIC_BY_DESIGN.has(p),
+				),
+			);
+		}
+
+		expect(undeclared).toEqual([]);
+	});
+
+	it("has no stale admin entry — every disabled admin path is still mounted", async () => {
+		const { auth } = await makeAuth();
+		const adminMounted = Object.values(
+			auth.api as Record<string, { path?: string }>,
+		)
+			.map((endpoint) => endpoint?.path)
+			.filter((p): p is string => typeof p === "string")
+			.filter((p) => p.startsWith("/admin/"));
+
+		expect([...adminMounted].sort()).toEqual(
+			(DISABLED_AUTH_PATHS as readonly string[])
+				.filter((p) => p.startsWith("/admin/"))
+				.slice()
+				.sort(),
+		);
+	});
+});
+
+describe.skipIf(!hasTestDatabase)(
+	"credential-mutating routes the server fns guard",
+	() => {
+		it("POST /change-password is off — OTP flow with eviction is the only path", async () => {
+			const { auth } = await makeAuth();
+			const signedUp = await auth.api.signUpEmail({
+				body: { email: "pw@example.com", password: PW, name: "PW" },
+				returnHeaders: true,
+			});
+
+			const res = await post(
+				auth,
+				"/change-password",
+				{ currentPassword: PW, newPassword: "Changed1!" },
+				cookieHeaders(signedUp.headers),
+			);
+
+			expect(res.status).toBe(404);
+			await expect(
+				auth.api.signInEmail({
+					body: { email: "pw@example.com", password: PW },
+				}),
+			).resolves.toBeTruthy();
+		});
+
+		it("POST /passkey/delete-passkey is off — removal stays fresh-gated", async () => {
+			const db = await createTestDatabase(AUTH_DDL + PASSKEY_DDL);
+			const auth = betterAuth({
+				baseURL: BASE,
+				secret: "admin-http-surface-test-secret",
+				telemetry: { enabled: false },
+				database: drizzleAdapter(db, { provider: "pg" }),
+				emailAndPassword: { enabled: true },
+				disabledPaths: [...DISABLED_AUTH_PATHS],
+				plugins: [passkey({ rpID: "localhost", rpName: "Starter" })],
+			});
+			const signedUp = await auth.api.signUpEmail({
+				body: { email: "pk@example.com", password: PW, name: "PK" },
+				returnHeaders: true,
+			});
+			const pkId = await insertPasskey(db, signedUp.response.user.id);
+
+			const res = await auth.handler(
+				new Request(`${BASE}/api/auth/passkey/delete-passkey`, {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						cookie: cookieHeaders(signedUp.headers).get("cookie") ?? "",
+					},
+					body: JSON.stringify({ id: pkId }),
+				}),
+			);
+
+			expect(res.status).toBe(404);
+			const { passkey: pkTable } = await import("@/db/auth.schema");
+			expect(await db.select().from(pkTable)).toHaveLength(1);
+		});
+	},
+);

package/template/src/__tests__/admin-peer-protection.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Administrators are peers: none may ban, demote, or revoke credentials of an
+ * admin or superadmin, and none may change their own role. superadmin is a
+ * protected label, not a higher-privilege tier.
+ *
+ * Last-admin checks hit real (temp) user rows — pure role matrices alone cannot
+ * prove the SQL count.
+ */
+import { describe, expect, it } from "vitest";
+import type { Database as AppDatabase } from "@/db";
+import { user } from "@/db/schema";
+import {
+	assertAdminMayActOn,
+	assertNotLastAdmin,
+	isAdminRole,
+} from "@/services/admin-security";
+import { HttpError } from "@/utils/api-error";
+import { createTestDatabase, hasTestDatabase } from "./test-db";
+
+const ACTOR = "actor-admin";
+const TARGET = "target";
+
+describe("administrator peer protection", () => {
+	it("lets an administrator ban, demote and revoke an ordinary user", () => {
+		const act = (extra: Record<string, unknown>) =>
+			assertAdminMayActOn({
+				actorId: ACTOR,
+				targetId: TARGET,
+				targetRole: "user",
+				...extra,
+			});
+
+		expect(() => act({ banning: true })).not.toThrow();
+		expect(() => act({ nextRole: "admin" })).not.toThrow();
+		expect(() => act({ revokingCredentials: true })).not.toThrow();
+	});
+
+	for (const peerRole of ["admin", "superadmin"] as const) {
+		const act = (extra: Record<string, unknown>) =>
+			assertAdminMayActOn({
+				actorId: ACTOR,
+				targetId: TARGET,
+				targetRole: peerRole,
+				...extra,
+			});
+
+		// A bare Error would reach the client without a status, so the query
+		// client's "a 4xx is a refusal, not a flake" rule would miss it and retry
+		// a decision that can never change.
+		it(`refuses to ban a ${peerRole} with a 403`, () => {
+			expect(() => act({ banning: true })).toThrow(HttpError);
+			try {
+				act({ banning: true });
+				expect.unreachable();
+			} catch (e) {
+				expect((e as HttpError).status).toBe(403);
+				expect((e as HttpError).error).toBe("forbidden");
+			}
+		});
+
+		it(`refuses to demote a ${peerRole}`, () => {
+			expect(() => act({ nextRole: "user" })).toThrow(/administrator/i);
+		});
+
+		it(`refuses to revoke a ${peerRole}'s credentials`, () => {
+			expect(() => act({ revokingCredentials: true })).toThrow(
+				/administrator/i,
+			);
+		});
+
+		it(`still lets a ${peerRole} be unbanned`, () => {
+			expect(() => act({ banning: false })).not.toThrow();
+		});
+
+		it(`leaves a ${peerRole}'s other fields editable`, () => {
+			expect(() => act({})).not.toThrow();
+		});
+	}
+
+	it("refuses an administrator changing their own role", () => {
+		expect(() =>
+			assertAdminMayActOn({
+				actorId: ACTOR,
+				targetId: ACTOR,
+				targetRole: "admin",
+				nextRole: "user",
+			}),
+		).toThrow(/own role/i);
+	});
+
+	it("does not refuse a self-update that leaves the role alone", () => {
+		expect(() =>
+			assertAdminMayActOn({
+				actorId: ACTOR,
+				targetId: ACTOR,
+				targetRole: "admin",
+				nextRole: "admin",
+			}),
+		).not.toThrow();
+	});
+
+	it("treats admin and superadmin as administrator roles", () => {
+		expect(isAdminRole("admin")).toBe(true);
+		expect(isAdminRole("superadmin")).toBe(true);
+		expect(isAdminRole("user")).toBe(false);
+		expect(isAdminRole(null)).toBe(false);
+	});
+});
+
+// Temp table: assertNotLastAdmin only reads `user`; shared rls_test is never
+// truncated, so counting needs its own isolation.
+async function makeUserTable(): Promise<AppDatabase> {
+	return createTestDatabase(`
+		CREATE TEMP TABLE "user" (
+			id TEXT PRIMARY KEY,
+			name TEXT NOT NULL,
+			email TEXT NOT NULL,
+			email_verified BOOLEAN NOT NULL DEFAULT false,
+			two_factor_enabled BOOLEAN DEFAULT false,
+			image TEXT,
+			created_at TIMESTAMP NOT NULL DEFAULT now(),
+			updated_at TIMESTAMP NOT NULL DEFAULT now(),
+			role TEXT,
+			banned BOOLEAN DEFAULT false,
+			ban_reason TEXT,
+			ban_expires TIMESTAMP,
+			tokens_revoked_at TIMESTAMP,
+			locale TEXT
+		);
+	`);
+}
+
+const seed = (db: AppDatabase, rows: Array<[string, string | null, boolean]>) =>
+	db.insert(user).values(
+		rows.map(([id, role, banned]) => ({
+			id,
+			name: id,
+			email: `${id}@peer.test`,
+			role,
+			banned,
+		})),
+	);
+
+describe.skipIf(!hasTestDatabase)("the last usable administrator", () => {
+	it("counts a superadmin as an administrator", async () => {
+		const db = await makeUserTable();
+		await seed(db, [
+			["a1", "admin", false],
+			["s1", "superadmin", false],
+		]);
+
+		await expect(assertNotLastAdmin(db, "a1")).resolves.toBeUndefined();
+	});
+
+	it("refuses when the only other administrator is a banned superadmin", async () => {
+		const db = await makeUserTable();
+		await seed(db, [
+			["a1", "admin", false],
+			["s1", "superadmin", true],
+		]);
+
+		await expect(assertNotLastAdmin(db, "a1")).rejects.toThrow(
+			/last administrator/i,
+		);
+	});
+
+	it("refuses when the target is the only administrator left", async () => {
+		const db = await makeUserTable();
+		await seed(db, [
+			["s1", "superadmin", false],
+			["u1", "user", false],
+		]);
+
+		await expect(assertNotLastAdmin(db, "s1")).rejects.toThrow(
+			/last administrator/i,
+		);
+	});
+});

package/template/src/__tests__/auth-harness.ts

@@ -0,0 +1,104 @@
+import type { Database as AppDatabase } from "@/db";
+
+/**
+ * Core Better Auth tables for temp-table suites (column names match the
+ * generated auth schema / platform migration).
+ */
+export const AUTH_DDL = `
+	CREATE TEMP TABLE "user" (
+		id TEXT PRIMARY KEY,
+		name TEXT NOT NULL,
+		email TEXT NOT NULL UNIQUE,
+		email_verified BOOLEAN DEFAULT false NOT NULL,
+		two_factor_enabled boolean default false,
+		image TEXT,
+		created_at TIMESTAMP DEFAULT now() NOT NULL,
+		updated_at TIMESTAMP DEFAULT now() NOT NULL,
+		role TEXT,
+		banned BOOLEAN DEFAULT false,
+		ban_reason TEXT,
+		ban_expires TIMESTAMP,
+		tokens_revoked_at TIMESTAMP,
+		locale TEXT
+	);
+	CREATE TEMP TABLE "session" (
+		id TEXT PRIMARY KEY,
+		expires_at TIMESTAMP NOT NULL,
+		token TEXT NOT NULL UNIQUE,
+		created_at TIMESTAMP DEFAULT now() NOT NULL,
+		updated_at TIMESTAMP NOT NULL,
+		ip_address TEXT,
+		user_agent TEXT,
+		user_id TEXT NOT NULL,
+		impersonated_by TEXT
+	);
+	CREATE TEMP TABLE "account" (
+		id TEXT PRIMARY KEY,
+		account_id TEXT NOT NULL,
+		provider_id TEXT NOT NULL,
+		user_id TEXT NOT NULL,
+		access_token TEXT,
+		refresh_token TEXT,
+		id_token TEXT,
+		access_token_expires_at TIMESTAMP,
+		refresh_token_expires_at TIMESTAMP,
+		scope TEXT,
+		password TEXT,
+		created_at TIMESTAMP DEFAULT now() NOT NULL,
+		updated_at TIMESTAMP NOT NULL
+	);
+	CREATE TEMP TABLE "verification" (
+		id TEXT PRIMARY KEY,
+		identifier TEXT NOT NULL,
+		value TEXT NOT NULL,
+		expires_at TIMESTAMP NOT NULL,
+		created_at TIMESTAMP DEFAULT now() NOT NULL,
+		updated_at TIMESTAMP DEFAULT now() NOT NULL
+	);
+	CREATE TEMP TABLE "two_factor" (
+		id TEXT PRIMARY KEY,
+		secret TEXT NOT NULL,
+		backup_codes TEXT NOT NULL,
+		user_id TEXT NOT NULL,
+		verified BOOLEAN DEFAULT true,
+		failed_verification_count INTEGER DEFAULT 0,
+		locked_until TIMESTAMP
+	);
+`;
+
+export const PASSKEY_DDL = `
+	CREATE TEMP TABLE "passkey" (
+		id TEXT PRIMARY KEY, name TEXT, public_key TEXT NOT NULL, user_id TEXT NOT NULL,
+		credential_id TEXT NOT NULL, counter INTEGER NOT NULL, device_type TEXT NOT NULL,
+		backed_up BOOLEAN NOT NULL, transports TEXT, created_at TIMESTAMP, aaguid TEXT
+	);
+`;
+
+export async function insertPasskey(
+	db: AppDatabase,
+	userId: string,
+	id = "pk-1",
+) {
+	const { passkey: pk } = await import("@/db/auth.schema");
+	await db.insert(pk).values({
+		id,
+		name: "Starter",
+		publicKey: "fake-public-key",
+		userId,
+		credentialID: `cred-${id}`,
+		counter: 0,
+		deviceType: "singleDevice",
+		backedUp: false,
+		createdAt: new Date(),
+	});
+	return id;
+}
+
+/** Turn a returnHeaders response into a Cookie header for follow-up calls. */
+export function cookieHeaders(headers: Headers): Headers {
+	const cookie = headers
+		.getSetCookie()
+		.map((c) => c.split(";")[0])
+		.join("; ");
+	return new Headers({ cookie });
+}

package/template/src/__tests__/auth-rate-limit.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { authRateLimitKey } from "@/services/auth-rate-limit";
+
+const req = (method: string, path: string, ip?: string) =>
+	new Request(`https://starter.test${path}`, {
+		method,
+		headers: ip ? { "cf-connecting-ip": ip } : undefined,
+	});
+
+describe("authRateLimitKey", () => {
+	it("keys sensitive POST endpoints by ip + path", () => {
+		expect(
+			authRateLimitKey(req("POST", "/api/auth/sign-in/email", "1.2.3.4")),
+		).toBe("1.2.3.4:/api/auth/sign-in/email");
+	});
+
+	it("throttles every sensitive action", () => {
+		for (const p of [
+			"/api/auth/sign-up/email",
+			"/api/auth/forget-password",
+			"/api/auth/request-password-reset",
+			"/api/auth/reset-password",
+			"/api/auth/send-verification-email",
+		]) {
+			expect(authRateLimitKey(req("POST", p, "9.9.9.9"))).toBe(`9.9.9.9:${p}`);
+		}
+	});
+
+	it("does not throttle GET, or non-sensitive POST paths", () => {
+		expect(
+			authRateLimitKey(req("GET", "/api/auth/sign-in/email", "1.2.3.4")),
+		).toBeNull();
+		expect(
+			authRateLimitKey(req("POST", "/api/auth/get-session", "1.2.3.4")),
+		).toBeNull();
+	});
+
+	it("falls back to a stable key when the edge IP header is absent", () => {
+		expect(authRateLimitKey(req("POST", "/api/auth/sign-in/email"))).toBe(
+			"unknown:/api/auth/sign-in/email",
+		);
+	});
+});