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

package/template/src/__tests__/query-unauthorized-redirect.test.ts

@@ -0,0 +1,95 @@
+// @vitest-environment jsdom
+
+/**
+ * Seam: the query layer, entered the way a page enters it.
+ *
+ * A user whose session expired mid-session used to watch the page crash or
+ * render zeros because a 401 arrived as the resolved query value. The remedy
+ * is one rule on the shared QueryClient: send them to sign-in and never cache
+ * the refusal as data.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { HttpError } from "@/utils/api-error";
+
+const { goToSignIn } = vi.hoisted(() => ({ goToSignIn: vi.fn() }));
+
+vi.mock("@/utils/auth-redirect", async (importActual) => ({
+	...(await importActual<typeof import("@/utils/auth-redirect")>()),
+	goToSignIn,
+}));
+
+const { getContext } = await import(
+	"@/integrations/tanstack-query/root-provider"
+);
+
+/** A guarded server function refusing the way the guard middleware refuses. */
+function refuses(status: number) {
+	return () => {
+		throw new HttpError({
+			status,
+			error: status === 401 ? "unauthorized" : "forbidden",
+			message: "Authentication required.",
+		});
+	};
+}
+
+/**
+ * Through the client's own defaults, so the retry policy under test is the one
+ * a page gets. `retry: false` is only for the transient-fault case.
+ */
+async function runQuery(queryFn: () => unknown, retry?: false) {
+	const { queryClient } = getContext();
+	await queryClient
+		.fetchQuery({ queryKey: ["guarded"], queryFn, retry })
+		.catch(() => {});
+	return queryClient;
+}
+
+describe("a guarded query refused mid-session", () => {
+	it("sends the user to sign-in, carrying where they were", async () => {
+		goToSignIn.mockClear();
+		window.history.replaceState({}, "", "/dashboard/account?tab=security");
+
+		await runQuery(refuses(401));
+
+		expect(goToSignIn).toHaveBeenCalledWith("/dashboard/account?tab=security");
+	});
+
+	it("never caches the refusal as data", async () => {
+		goToSignIn.mockClear();
+
+		const queryClient = await runQuery(refuses(401));
+
+		expect(queryClient.getQueryData(["guarded"])).toBeUndefined();
+	});
+
+	// If the retry policy is ever lost, the three default retries back off for
+	// ~7s — this fails by call count (and by timeout) rather than passing slowly.
+	it("is refused exactly once — a 4xx is deterministic, so the redirect is immediate", async () => {
+		goToSignIn.mockClear();
+		const queryFn = vi.fn(refuses(401));
+
+		await runQuery(queryFn);
+
+		expect(queryFn).toHaveBeenCalledTimes(1);
+		expect(goToSignIn).toHaveBeenCalledTimes(1);
+	});
+
+	it("leaves a 403 where it is — the session is fine, the permission is not", async () => {
+		goToSignIn.mockClear();
+
+		await runQuery(refuses(403));
+
+		expect(goToSignIn).not.toHaveBeenCalled();
+	});
+
+	it("does not mistake a network failure for an expired session", async () => {
+		goToSignIn.mockClear();
+
+		await runQuery(() => {
+			throw new TypeError("Failed to fetch");
+		}, false);
+
+		expect(goToSignIn).not.toHaveBeenCalled();
+	});
+});

package/template/src/__tests__/rls-policy.test.ts

@@ -0,0 +1,120 @@
+/**
+ * RLS policy integration (seam 6): real migrations, real `starter_app` role
+ * (NOBYPASSRLS). Temp-table suites cannot see policies (superuser BYPASSRLS).
+ *
+ * Platform invariant: ordinary users cannot read `admin_action`; admin and
+ * service contexts can.
+ */
+import { eq } from "drizzle-orm";
+import { describe, expect, it } from "vitest";
+import type { Database as AppDatabase } from "@/db";
+import { withRlsService, withRlsUser } from "@/db/helper";
+import { adminAction, user } from "@/db/schema";
+import { createRlsAppDatabase, hasTestDatabase } from "./test-rls-db";
+
+async function seedUser(
+	db: AppDatabase,
+	role: string | null = "user",
+): Promise<string> {
+	const id = crypto.randomUUID();
+	// `user` has no RLS — inserts work without a service GUC.
+	await db.insert(user).values({
+		id,
+		name: `rls-${id.slice(0, 8)}`,
+		email: `${id}@rls.test`,
+		role,
+	});
+	return id;
+}
+
+describe.skipIf(!hasTestDatabase)(
+	"admin_action RLS on the real schema (starter_app, NOBYPASSRLS)",
+	() => {
+		it("lets service write and read audit rows", async () => {
+			const db = createRlsAppDatabase();
+			const actorId = await seedUser(db, "admin");
+			const actionId = crypto.randomUUID();
+
+			await withRlsService(db, (tx) =>
+				tx.insert(adminAction).values({
+					id: actionId,
+					actorId,
+					action: "user.role_change",
+					targetType: "user",
+					targetId: actorId,
+					detail: { test: true },
+				}),
+			);
+
+			const rows = await withRlsService(db, (tx) =>
+				tx.select().from(adminAction).where(eq(adminAction.id, actionId)),
+			);
+			expect(rows).toHaveLength(1);
+			expect(rows[0].action).toBe("user.role_change");
+		});
+
+		it("lets an administrator read audit rows under withRlsUser", async () => {
+			const db = createRlsAppDatabase();
+			const adminId = await seedUser(db, "admin");
+			const actionId = crypto.randomUUID();
+
+			await withRlsService(db, (tx) =>
+				tx.insert(adminAction).values({
+					id: actionId,
+					actorId: adminId,
+					action: "oauth_client.create",
+					targetType: "oauth_client",
+					targetId: "client-1",
+				}),
+			);
+
+			const rows = await withRlsUser(db, adminId, (tx) =>
+				tx.select().from(adminAction).where(eq(adminAction.id, actionId)),
+			);
+			expect(rows).toHaveLength(1);
+		});
+
+		it("hides audit rows from an ordinary user under withRlsUser", async () => {
+			const db = createRlsAppDatabase();
+			const memberId = await seedUser(db, "user");
+			const adminId = await seedUser(db, "admin");
+			const actionId = crypto.randomUUID();
+
+			await withRlsService(db, (tx) =>
+				tx.insert(adminAction).values({
+					id: actionId,
+					actorId: adminId,
+					action: "user.ban",
+					targetType: "user",
+					targetId: memberId,
+				}),
+			);
+
+			const rows = await withRlsUser(db, memberId, (tx) =>
+				tx.select().from(adminAction).where(eq(adminAction.id, actionId)),
+			);
+			expect(rows).toHaveLength(0);
+		});
+
+		it("rejects ordinary-user writes to admin_action", async () => {
+			const db = createRlsAppDatabase();
+			const memberId = await seedUser(db, "user");
+			const actionId = crypto.randomUUID();
+
+			await expect(
+				withRlsUser(db, memberId, (tx) =>
+					tx.insert(adminAction).values({
+						id: actionId,
+						actorId: memberId,
+						action: "forged.action",
+					}),
+				),
+			).rejects.toThrow();
+
+			const rows = await withRlsService(db, (tx) =>
+				tx.select().from(adminAction).where(eq(adminAction.id, actionId)),
+			);
+			expect(rows).toHaveLength(0);
+		});
+	},
+);

package/template/src/__tests__/same-page-locale-href.test.ts

@@ -0,0 +1,47 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { samePageLocaleHref } from "@/utils/same-page-locale-href";
+
+beforeAll(async () => {
+	if (
+		typeof (globalThis as { URLPattern?: unknown }).URLPattern === "undefined"
+	) {
+		const mod = (await import("@inlang/paraglide-js/urlpattern-polyfill")) as {
+			URLPattern?: unknown;
+			default?: unknown;
+		};
+		(globalThis as { URLPattern?: unknown }).URLPattern =
+			mod.URLPattern ?? mod.default;
+	}
+});
+
+describe("samePageLocaleHref", () => {
+	it("localizes the path and preserves query + hash", () => {
+		expect(
+			samePageLocaleHref({
+				pathname: "/dashboard/account",
+				search: "?tab=security",
+				hash: "#sessions",
+				locale: "de",
+			}),
+		).toBe("/de/dashboard/account?tab=security#sessions");
+	});
+
+	it("keeps English on bare paths", () => {
+		expect(
+			samePageLocaleHref({
+				pathname: "/sign-in",
+				search: "?client_id=abc",
+				locale: "en",
+			}),
+		).toBe("/sign-in?client_id=abc");
+	});
+
+	it("delocalizes before re-localizing so switching de→en drops the prefix", () => {
+		expect(
+			samePageLocaleHref({
+				pathname: "/de/admin/users",
+				locale: "en",
+			}),
+		).toBe("/admin/users");
+	});
+});

package/template/src/__tests__/search-params-oauth.test.ts

@@ -0,0 +1,57 @@
+import { defaultParseSearch } from "@tanstack/react-router";
+import { describe, expect, it } from "vitest";
+import {
+	type SearchParamsRecord,
+	stringifySearch,
+} from "@/utils/search-params";
+
+/** TanStack's parse type is an opaque schema; for tests we re-read keys we know. */
+function asSearchRecord(
+	parsed: ReturnType<typeof defaultParseSearch>,
+): SearchParamsRecord {
+	return parsed as SearchParamsRecord;
+}
+
+/**
+ * Better Auth's oauth-provider signs authorize redirects with a multi-value
+ * `ba_param` list. The client rebuilds `oauth_query` from window.location.search
+ * using only those listed keys — so a JSON-array rewrite of ba_param makes
+ * sign-in POST /api/auth/sign-in/email return 400 invalid_signature.
+ */
+const FAITHFUL_OAUTH_QUERY =
+	"response_type=code&client_id=xmgWQuPvLVGwtMhwgryGAEWdUTjPSxpv&redirect_uri=http%3A%2F%2F127.0.0.1%3A38256%2Foauth%2Fcallback&scope=profile+email+offline_access+token%3Aread+token%3Awrite&state=testdebug123&code_challenge=UL6WGNhxgcvacdb5dpFLQ6Dn0A47pdt_vRsPu7YPcww&code_challenge_method=S256&exp=1784947726&ba_iat=1784947126487&ba_param=ba_iat&ba_param=ba_param&ba_param=client_id&ba_param=code_challenge&ba_param=code_challenge_method&ba_param=exp&ba_param=redirect_uri&ba_param=response_type&ba_param=scope&ba_param=state&sig=Z%2Bt0G2B3XBXoVZ1EX%2B%2BvJHDYz%2FB%2FzJKOmZHxVT4gQB8%3D";
+
+describe("stringifySearch (OAuth multi-value ba_param)", () => {
+	it("round-trips repeated ba_param keys instead of collapsing them to JSON", () => {
+		const parsed = asSearchRecord(defaultParseSearch(FAITHFUL_OAUTH_QUERY));
+		expect(Array.isArray(parsed.ba_param)).toBe(true);
+
+		const out = stringifySearch(parsed);
+		const outParams = new URLSearchParams(
+			out.startsWith("?") ? out.slice(1) : out,
+		);
+
+		expect(outParams.getAll("ba_param")).toEqual([
+			"ba_iat",
+			"ba_param",
+			"client_id",
+			"code_challenge",
+			"code_challenge_method",
+			"exp",
+			"redirect_uri",
+			"response_type",
+			"scope",
+			"state",
+		]);
+		// Must not be the JSON-array form the default serializer emits.
+		expect(outParams.get("ba_param")?.startsWith("[")).toBe(false);
+		expect(outParams.get("client_id")).toBe("xmgWQuPvLVGwtMhwgryGAEWdUTjPSxpv");
+		expect(outParams.get("sig")).toBeTruthy();
+	});
+
+	it("still stringifies plain single-value search params", () => {
+		expect(stringifySearch({ redirect: "/dashboard", ref: "abc" })).toBe(
+			"?redirect=%2Fdashboard&ref=abc",
+		);
+	});
+});

package/template/src/__tests__/security-headers.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { withSecurityHeaders } from "@/lib/security-headers";
+
+describe("baseline security headers", () => {
+	it("preserves status and body", async () => {
+		const res = withSecurityHeaders(
+			new Response("payload", { status: 201, statusText: "Created" }),
+		);
+		expect(res.status).toBe(201);
+		expect(await res.text()).toBe("payload");
+	});
+});

package/template/src/__tests__/server-fn-error-contract.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Seam: the application's own Start configuration, round-tripped through the
+ * real serializer.
+ *
+ * The defect being pinned is a *registration* failure, not a throwing failure.
+ * A test that asserts "the middleware throws an HttpError" passes happily
+ * against a production build that never registered the adapter — and in that
+ * build every refusal still arrives as a bare `Error` whose `.status` the
+ * shallow error serializer dropped. So the adapter list is read from
+ * `startInstance` itself and composed the way the framework composes it
+ * (user adapters ahead of the default `ShallowErrorPlugin`), then an HttpError
+ * is pushed through real seroval.
+ */
+import {
+	defaultSerovalPlugins,
+	makeSerovalPlugin,
+} from "@tanstack/router-core/ssr/client";
+import { fromJSON, toJSONAsync } from "seroval";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { startInstance } from "@/start";
+import {
+	HttpError,
+	methodNotAllowed,
+	userFacingMessage,
+	validated,
+} from "@/utils/api-error";
+
+/** What the client ends up holding after a server function rejects. */
+async function acrossTheServerFnBoundary(thrown: unknown) {
+	const { serializationAdapters } = await startInstance.getOptions();
+	const plugins = [
+		...(serializationAdapters ?? []).map(makeSerovalPlugin),
+		...defaultSerovalPlugins,
+	];
+	return fromJSON(await toJSONAsync(thrown, { plugins }), { plugins });
+}
+
+describe("a server function's refusal crossing the wire", () => {
+	it("arrives with its status, code, message and class intact", async () => {
+		const crossed = await acrossTheServerFnBoundary(
+			new HttpError({
+				status: 401,
+				error: "unauthorized",
+				message: "Authentication required.",
+			}),
+		);
+
+		expect(crossed).toBeInstanceOf(HttpError);
+		expect(crossed).toMatchObject({
+			status: 401,
+			error: "unauthorized",
+			message: "Authentication required.",
+		});
+	});
+});
+
+/**
+ * A 4xx `message` is trustworthy enough to render. Everything else (5xx,
+ * stray TypeError) carries internal detail and gets the caller's fallback.
+ */
+describe("the message a client may show the user", () => {
+	const fallback = "Something went wrong. Please try again.";
+
+	it("shows a 4xx message, because it was written for them", () => {
+		const refusal = new HttpError({
+			status: 400,
+			error: "invalid_param",
+			message: "Display name is required.",
+		});
+
+		expect(userFacingMessage(refusal, fallback)).toBe(
+			"Display name is required.",
+		);
+	});
+
+	it("hides a 5xx message, because it was not", () => {
+		const fault = new HttpError({
+			status: 500,
+			error: "internal",
+			message: "ECONNREFUSED 10.0.0.4:5432",
+		});
+
+		expect(userFacingMessage(fault, fallback)).toBe(fallback);
+	});
+
+	it("hides an ordinary Error, whose message is never intended for a user", () => {
+		expect(
+			userFacingMessage(new TypeError("p.map is not a function"), fallback),
+		).toBe(fallback);
+	});
+});
+
+describe("a validator's refusal", () => {
+	/** A field whose author wrote the rule out for the reader. */
+	const authored = z.object({
+		date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use the YYYY-MM-DD form."),
+	});
+	/** The same field with no message — the shape most of the codebase has. */
+	const bare = z.object({ date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/) });
+
+	// The cast is the point of the test: a validator's declared input describes
+	// what the *call site* may pass, while what actually arrives over the wire
+	// is whatever the caller sent. These are the shapes the type system promises
+	// cannot happen and the network delivers anyway.
+	function refusalFrom<T extends z.ZodType>(schema: T, input: unknown) {
+		try {
+			validated(schema)(input as z.input<T>);
+		} catch (error) {
+			return error;
+		}
+		throw new Error("expected the validator to refuse");
+	}
+
+	it("is a refusal and not a fault, so a malformed call is an expected 4xx", async () => {
+		const crossed = await acrossTheServerFnBoundary(
+			refusalFrom(authored, undefined),
+		);
+		expect(crossed).toBeInstanceOf(HttpError);
+		expect(crossed).toMatchObject({ status: 400, error: "invalid_param" });
+	});
+
+	it("states the rule the input broke, when the schema's author wrote one", async () => {
+		const crossed = await acrossTheServerFnBoundary(
+			refusalFrom(authored, { date: "3 August" }),
+		);
+		expect(userFacingMessage(crossed, "Something went wrong.")).toBe(
+			"Use the YYYY-MM-DD form.",
+		);
+	});
+
+	// zod's own wording is written for whoever wrote the schema: "Invalid
+	// string: must match pattern /^\d{4}-\d{2}-\d{2}$/" hands the reader a
+	// regular expression. Most schemas here carry no message, so this is the
+	// common case, not the edge one.
+	it("never falls back to zod's wording, which is written for a machine", () => {
+		const refusal = refusalFrom(bare, { date: "3 August" });
+		const shown = userFacingMessage(refusal, "Something went wrong.");
+		expect(shown).not.toContain("\\d");
+		expect(shown).not.toContain("Invalid");
+		expect(shown).not.toContain("pattern");
+	});
+
+	it("says nothing about the schema when the payload is missing entirely", () => {
+		const refusal = refusalFrom(bare, undefined);
+		const shown = userFacingMessage(refusal, "Something went wrong.");
+		expect(shown).not.toContain("date");
+		expect(shown).not.toContain("undefined");
+	});
+
+	it("passes valid input through, so the handler still receives parsed data", () => {
+		expect(validated(bare)({ date: "2026-08-03" })).toEqual({
+			date: "2026-08-03",
+		});
+	});
+});
+
+describe("an API route asked for a method it does not serve", () => {
+	// Without this, a POST-only route lets a browser's GET fall through to the
+	// app router, which answers 200 with the whole SPA shell — a webhook URL
+	// that renders a page instead of refusing.
+	it("answers 405 as JSON, and names the method it does serve", async () => {
+		const response = methodNotAllowed("POST");
+
+		expect(response.status).toBe(405);
+		expect(response.headers.get("allow")).toBe("POST");
+		expect(response.headers.get("content-type")).toContain("application/json");
+		await expect(response.json()).resolves.toMatchObject({
+			status: 405,
+			error: "method_not_allowed",
+		});
+	});
+});

package/template/src/__tests__/stripe.test.ts

@@ -0,0 +1,84 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import type { Database } from "@/db";
+import { handleStripeWebhook, verifyStripeSignature } from "@/services/stripe";
+
+/** A db that fails the test if the handler touches it. */
+const unusableDb = new Proxy({} as Database, {
+	get() {
+		throw new Error("handler reached the database on an unverified event");
+	},
+});
+
+function signedHeader(secret: string, body: string, at = Date.now() / 1000) {
+	const t = Math.floor(at);
+	const v1 = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
+	return `t=${t},v1=${v1}`;
+}
+
+describe("verifyStripeSignature", () => {
+	it("accepts a valid v1 signature", () => {
+		const body = '{"id":"evt_1"}';
+		expect(
+			verifyStripeSignature(
+				"whsec_test",
+				body,
+				signedHeader("whsec_test", body),
+			),
+		).toBe(true);
+	});
+
+	it("rejects a bad or missing signature", () => {
+		const body = '{"id":"evt_1"}';
+		expect(verifyStripeSignature("whsec_test", body, "t=1,v1=deadbeef")).toBe(
+			false,
+		);
+		expect(verifyStripeSignature("whsec_test", body, null)).toBe(false);
+		expect(verifyStripeSignature("whsec_test", body, "garbage")).toBe(false);
+	});
+
+	it("rejects a replayed signature outside the tolerance window", () => {
+		const body = '{"id":"evt_1"}';
+		const old = Date.now() / 1000 - 3600;
+		expect(
+			verifyStripeSignature(
+				"whsec_test",
+				body,
+				signedHeader("whsec_test", body, old),
+			),
+		).toBe(false);
+	});
+});
+
+describe("handleStripeWebhook", () => {
+	it("refuses an unverified event without touching the database", async () => {
+		const body = '{"type":"checkout.session.completed"}';
+		const result = await handleStripeWebhook(unusableDb, {
+			rawBody: body,
+			signature: "t=1,v1=deadbeef",
+			secret: "whsec_test",
+		});
+		expect(result).toBe("invalid_signature");
+	});
+
+	it("ignores every event type other than a completed checkout", async () => {
+		const body =
+			'{"type":"payment_intent.created","data":{"object":{"id":"pi_1"}}}';
+		const result = await handleStripeWebhook(unusableDb, {
+			rawBody: body,
+			signature: signedHeader("whsec_test", body),
+			secret: "whsec_test",
+		});
+		expect(result).toBe("noop");
+	});
+
+	it("refuses a signed body that is not JSON", async () => {
+		const body = "{not json";
+		const result = await handleStripeWebhook(unusableDb, {
+			rawBody: body,
+			signature: signedHeader("whsec_test", body),
+			secret: "whsec_test",
+		});
+		expect(result).toBe("invalid_payload");
+	});
+});

package/template/src/__tests__/test-db.ts

@@ -0,0 +1,32 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { afterEach, inject } from "vitest";
+import type { Database as AppDatabase } from "@/db";
+import * as schema from "@/db/schema";
+
+/**
+ * Whether this run has a Postgres container behind it.
+ *
+ * `SKIP_TESTCONTAINERS=1` (what `bun run test:unit` sets) makes global setup
+ * provide empty URIs. Suites that need a database gate on this with
+ * `describe.skipIf(!hasTestDatabase)` — the no-Docker path has to be green, or
+ * nobody can tell a missing container from a real regression.
+ */
+export const hasTestDatabase = process.env.SKIP_TESTCONTAINERS !== "1";
+
+const pools: Pool[] = [];
+
+afterEach(async () => {
+	await Promise.all(pools.splice(0).map((pool) => pool.end()));
+});
+
+/**
+ * Superuser pool against the run-wide testcontainer. Each call uses a single
+ * connection so CREATE TEMP TABLE DDL stays invisible to other tests.
+ */
+export async function createTestDatabase(ddl: string): Promise<AppDatabase> {
+	const pool = new Pool({ connectionString: inject("pgUri"), max: 1 });
+	pools.push(pool);
+	await pool.query(ddl);
+	return drizzle(pool, { schema }) as unknown as AppDatabase;
+}

package/template/src/__tests__/test-rls-db.ts

@@ -0,0 +1,23 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { afterEach, inject } from "vitest";
+import type { Database as AppDatabase } from "@/db";
+import * as schema from "@/db/schema";
+
+export { hasTestDatabase } from "./test-db";
+
+const pools: Pool[] = [];
+
+afterEach(async () => {
+	await Promise.all(pools.splice(0).map((pool) => pool.end()));
+});
+
+/**
+ * Real migrations as `starter_app` (NOBYPASSRLS). Shared for the run — isolate
+ * by unique user ids; do not truncate.
+ */
+export function createRlsAppDatabase(): AppDatabase {
+	const pool = new Pool({ connectionString: inject("pgRlsAppUri"), max: 1 });
+	pools.push(pool);
+	return drizzle(pool, { schema }) as unknown as AppDatabase;
+}