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

package/template/public/manifest.json

@@ -0,0 +1,25 @@
+{
+	"short_name": "Starter",
+	"name": "TanStack Starter",
+	"icons": [
+		{
+			"src": "/favicon.ico",
+			"sizes": "64x64 32x32 24x24 16x16",
+			"type": "image/x-icon"
+		},
+		{
+			"src": "/logo192.png",
+			"type": "image/png",
+			"sizes": "192x192"
+		},
+		{
+			"src": "/logo512.png",
+			"type": "image/png",
+			"sizes": "512x512"
+		}
+	],
+	"start_url": "/",
+	"display": "standalone",
+	"theme_color": "#ffffff",
+	"background_color": "#ffffff"
+}

package/template/public/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:

package/template/scripts/check-client-bundle.ts

@@ -0,0 +1,150 @@
+/**
+ * Guardrail: nothing server-only may reach `dist/client`.
+ * Run after `bun run build`: `bun run check:client-bundle`.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const CLIENT_DIST = join(ROOT, "dist", "client");
+const ENV_FILES = [join(ROOT, ".env"), join(ROOT, ".env.prod")];
+const TEXT = /\.(js|mjs|css|html|json|txt|map)$/;
+
+/**
+ * A marker only earns its place if it can fire on a *bundled, minified*
+ * artifact. Module specifiers (`drizzle-orm`) and local identifiers
+ * (`betterAuth`) are erased by bundling, so a marker written against them
+ * reports "ok" forever. The schema-shaped markers below are written against
+ * strings that survive: `Symbol.for("drizzle:…")` keys, property names, and
+ * SQL text baked into policy definitions.
+ *
+ * Verify a new marker by building a tree that genuinely leaks and watching it
+ * fail — a green run against an artifact that never contained the thing proves
+ * nothing.
+ */
+const MARKERS: [string, RegExp][] = [
+	["cloudflare:workers import", /cloudflare:workers/],
+	["node:async_hooks", /node:async_hooks|async_hooks/],
+	["server function factory", /createServerFn/],
+	["Hyperdrive binding", /HYPERDRIVE/],
+	["drizzle ORM", /drizzle-orm/],
+	// Drizzle brands every table object with these Symbol.for keys, so they
+	// survive minification and are present whenever a table definition — and
+	// with it every table and column name — reaches the browser.
+	["drizzle table definitions", /drizzle:(?:entityKind|Name|Columns|Schema)/],
+	["drizzle pg table class", /\bPgTable\b/],
+	// Policy predicates ship as SQL string literals. Leaking them tells a reader
+	// which GUC the RLS bypass trusts and what the predicate is.
+	["RLS policy definition", /app_private\.|rls_(?:policy|user_read|service_write)/],
+	["postgres driver", /node-postgres|pg-connection-string/],
+	["postgres connection string", /postgres(?:ql)?:\/\//],
+	["better-auth server factory", /betterAuth\(/],
+	["private key", /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/],
+	["stripe secret", /\b(?:sk_live_|sk_test_|whsec_)[A-Za-z0-9]{10,}/],
+];
+
+/**
+ * Keys whose value may legitimately appear client-side, named one at a time.
+ *
+ * Everything else is treated as a secret, so a newly added key is secret by
+ * default. The rule used to be the other way round — only keys *matching*
+ * `SECRET|KEY|TOKEN|PASSWORD|CREDENTIAL|DATABASE` were checked — which silently
+ * exempted anything named for what it is rather than what it holds
+ * (`SENTRY_DSN`, `..._PROXY_URL`, `ADMIN_BOOTSTRAP`).
+ */
+const CLIENT_SAFE_KEYS = new Set([
+	// The site's own public origin: canonical URLs, OG tags and the auth client
+	// all need it in the browser.
+	"APP_ORIGIN",
+	"BETTER_AUTH_URL",
+]);
+
+export function secretValues(
+	envFiles: string[] = ENV_FILES,
+): [string, string][] {
+	const pairs = envFiles
+		.filter((file) => existsSync(file))
+		.flatMap((file) => readFileSync(file, "utf8").split(/\r?\n/))
+		.filter((line) => /^\s*[A-Z0-9_]+=/.test(line))
+		.map((line) => {
+			const eq = line.indexOf("=");
+			const key = line.slice(0, eq).trim();
+			const raw = line.slice(eq + 1).trim();
+			const value = /^["']/.test(raw)
+				? raw.replace(/^["']|["']$/g, "")
+				: raw.replace(/(^|\s)#.*$/, "").trim();
+			return [key, value] as [string, string];
+		});
+
+	// Published on purpose, so their *value* is public wherever it comes from.
+	// A server-side key holding the same string as a `VITE_` one (e.g.
+	// `APP_ORIGIN` and `VITE_APP_ORIGIN`) is not a leak when it shows up.
+	const publicValues = new Set(
+		pairs
+			.filter(([key]) => /^(VITE_|PUBLIC_)/.test(key))
+			.map(([, value]) => value)
+			.filter((value) => value.length > 0),
+	);
+
+	return pairs.filter(
+		([key, value]) =>
+			value.length >= 8 &&
+			!/^(VITE_|PUBLIC_)/.test(key) &&
+			!CLIENT_SAFE_KEYS.has(key) &&
+			!publicValues.has(value),
+	);
+}
+
+function walk(dir: string): string[] {
+	const out: string[] = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...walk(path));
+		else if (TEXT.test(entry.name)) out.push(path);
+	}
+	return out;
+}
+
+export function findClientBundleLeaks(
+	clientDist: string = CLIENT_DIST,
+	secrets: [string, string][] = secretValues(),
+): string[] {
+	const hits: string[] = [];
+	for (const file of walk(clientDist)) {
+		const source = readFileSync(file, "utf8");
+		const name = relative(dirname(clientDist), file);
+		for (const [label, pattern] of MARKERS) {
+			if (pattern.test(source)) {
+				hits.push(`${name}: server-only marker — ${label}`);
+			}
+		}
+		for (const [key, value] of secrets) {
+			if (source.includes(value)) hits.push(`${name}: literal value of ${key}`);
+		}
+	}
+	return hits.sort();
+}
+
+if (import.meta.main) {
+	if (!existsSync(CLIENT_DIST)) {
+		console.error(
+			`No client bundle at ${CLIENT_DIST} — run \`bun run build\` first.`,
+		);
+		process.exit(1);
+	}
+	const secrets = secretValues();
+	const hits = findClientBundleLeaks(CLIENT_DIST, secrets);
+	if (hits.length > 0) {
+		console.error("Server-only code or secrets found in the client bundle:\n");
+		console.error(hits.map((hit) => `  ${hit}`).join("\n"));
+		console.error(
+			"\nMove the offending code into a server-only module (import only from" +
+				" server handlers / API routes).",
+		);
+		process.exit(1);
+	}
+	console.log(
+		`check:client-bundle ok (${walk(CLIENT_DIST).length} files, ${secrets.length} secret values checked)`,
+	);
+}

package/template/scripts/check-server-fns.ts

@@ -0,0 +1,290 @@
+/**
+ * Guardrail: every state-changing server function declares POST, and every
+ * server function that accepts input validates it.
+ *
+ *   bun run check:server-fns   (also chained into `bun run check`)
+ *
+ * `createServerFn()` defaults to GET, which puts the payload in the URL (logs,
+ * history, caches), makes the call replayable, and lets a same-origin prefetch
+ * or an XSS-driven fetch perform the write. The CSRF middleware in
+ * `src/start.ts` blocks cross-site and non-browser callers — not those. Pure
+ * reads stay on GET so loaders keep prefetching and caching.
+ *
+ * This class of rule regresses silently: the codebase drifted to 74 default-GET
+ * server functions without anyone deciding to. So it is checked in CI, and a
+ * test asserts zero violations.
+ *
+ * Analysis is name-based rather than type-directed: a set of writing symbols is
+ * seeded from anything containing a drizzle `.insert(`/`.update(`/`.delete(` or
+ * a mutating `auth.api.*` call, then grown transitively through callers. A false
+ * positive costs one `method: "POST"`, which is never wrong for a writer — so
+ * the analysis errs toward flagging.
+ *
+ * Escape hatch: annotate the `createServerFn(` line with `server-fn-ok` and a
+ * reason (e.g. a read that lazily backfills a row) so it is auditable in review.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "src");
+const ALLOW = "server-fn-ok";
+
+/**
+ * Drizzle writes, raw-SQL writes, and the Better Auth api calls that write.
+ *
+ * The verb is matched anywhere in the method name, not just at the start:
+ * `adminCreateOAuthClient` is a write, and anchoring on the prefix missed it.
+ */
+const DIRECT_WRITE_RE = new RegExp(
+	[
+		// drizzle
+		/\.(insert|update|delete)\(/.source,
+		// raw SQL
+		/sql`\s*(insert|update|delete)\s/.source,
+		// Better Auth's api. `check`/`verify` are in the list because they are
+		// writes the name hides: the OTP endpoints burn an attempt on a wrong code
+		// and delete the row on the last one, so a replayed GET consumes the
+		// victim's attempts. `send`/`request` are here for the same reason:
+		// `sendVerificationOTP` matches none of the other verbs ("Verification"
+		// does not contain "verify") yet it writes a verification row and sends an
+		// email — replayable, exactly what this rule forces onto POST. Nothing
+		// read-only in the auth surface we call (getSession, userHasPermission,
+		// list*, get*) contains either verb.
+		/auth\.api\.\w*(create|set|update|delete|ban|unban|revoke|remove|sign|send|request|approve|reject|mark|check|verify|consume)\w*\(/
+			.source,
+		// Better Auth's adapters, which several services write through directly
+		/(internalAdapter|adapter)\.\w*(create|update|delete)\w*\(/.source,
+	].join("|"),
+	"i",
+);
+
+/**
+ * A refusal returned from guard middleware, rather than thrown.
+ *
+ * TanStack Start treats a `Response` returned from server-fn middleware as a
+ * deliberate raw success: it stamps the response and hands the object to the
+ * client as the resolved query value, so a 401 arrives as *data* and TanStack
+ * Query caches it. The failure is silent by construction — the component
+ * either crashes on a shape it never expected or renders a confident zero to a
+ * user whose session just died. Throwing an `HttpError` makes it a rejected
+ * query instead.
+ *
+ * `throw new APIError(...)` (Better Auth's class, used inside plugin hooks) is
+ * a different symbol and deliberately does not match.
+ */
+const RETURNED_REFUSAL_RE = /\breturn\s+APIError\s*\(/;
+
+/**
+ * The annotation, on the line itself or in the comment block above it.
+ *
+ * Above it, because Biome relocates a trailing comment out of a multi-line
+ * argument list — a same-line-only hatch would stop applying the first time
+ * anyone ran the formatter, and the rule would fire on a decision that had
+ * already been made.
+ */
+function isAnnotated(lines: string[], at: number): boolean {
+	if (lines[at]?.includes(ALLOW)) return true;
+	for (let i = at - 1; i >= 0 && /^\s*(\/\/|\/\*|\*)/.test(lines[i]); i--) {
+		if (lines[i].includes(ALLOW)) return true;
+	}
+	return false;
+}
+
+export type Violation = {
+	file: string;
+	line: number;
+	symbol: string;
+	kind:
+		| "missing-post"
+		| "missing-validator"
+		| "bare-validator"
+		| "returned-refusal";
+	detail: string;
+};
+
+function walk(dir: string): string[] {
+	const out: string[] = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name === "__tests__") continue;
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...walk(path));
+		else if (/\.(ts|tsx)$/.test(entry.name)) out.push(path);
+	}
+	return out;
+}
+
+/**
+ * Every top-level declaration body, by name — `function NAME`, `const NAME =`,
+ * exported or not.
+ *
+ * Non-exported helpers count: a server fn that writes through a module-local
+ * function is still a writer, and indexing only exports both hid those helpers
+ * and threw away everything before the first `export` (which is exactly where
+ * they live).
+ */
+function topLevelFunctions(source: string): Map<string, string> {
+	const out = new Map<string, string>();
+	const pattern =
+		/^(?:export\s+)?(?:async\s+)?(?:function\s+(\w+)|const\s+(\w+)\s*=)/gm;
+	const starts: Array<{ name: string; at: number }> = [];
+	for (const m of source.matchAll(pattern)) {
+		starts.push({ name: m[1] ?? m[2], at: m.index ?? 0 });
+	}
+	starts.forEach((s, i) => {
+		out.set(s.name, source.slice(s.at, starts[i + 1]?.at ?? source.length));
+	});
+	return out;
+}
+
+type Declaration = {
+	name: string;
+	body: string;
+	file: string;
+	source: string;
+};
+
+/**
+ * Every declared name that writes, or reaches something that does. Grown to a
+ * fixpoint so a server fn three hops from the write is still caught. Matching
+ * is by bare name across files, which is what makes an alias import
+ * (`applyForProvider as applyForProviderSvc`) still resolve.
+ */
+function collectWriterNames(declarations: Declaration[]): Set<string> {
+	const writers = new Set<string>();
+	for (const d of declarations) {
+		if (DIRECT_WRITE_RE.test(d.body)) writers.add(d.name);
+	}
+	for (let changed = true; changed; ) {
+		changed = false;
+		for (const d of declarations) {
+			if (writers.has(d.name)) continue;
+			for (const writer of writers) {
+				// The declaration's own name never counts as a call to itself.
+				if (writer === d.name) continue;
+				if (new RegExp(`\\b${writer}\\w*\\s*\\(`).test(d.body)) {
+					writers.add(d.name);
+					changed = true;
+					break;
+				}
+			}
+		}
+	}
+	return writers;
+}
+
+export function findServerFnViolations(root: string = ROOT): Violation[] {
+	const declarations: Declaration[] = [];
+	for (const file of walk(root)) {
+		const source = readFileSync(file, "utf8");
+		for (const [name, body] of topLevelFunctions(source)) {
+			declarations.push({ name, body, file, source });
+		}
+	}
+	const writers = collectWriterNames(declarations);
+
+	const violations: Violation[] = [];
+	for (const home of declarations) {
+		const { name, body } = home;
+
+		// Guards only. Route handlers and the raw-HTTP OAuth surface both answer
+		// with a `Response` by contract, and neither lives here.
+		if (/[\\/]middlewares[\\/]/.test(home.file)) {
+			const bodyStart = home.source
+				.slice(0, home.source.indexOf(body))
+				.split("\n").length;
+			const lines = body.split("\n");
+			lines.forEach((text, i) => {
+				if (!RETURNED_REFUSAL_RE.test(text) || isAnnotated(lines, i)) return;
+				violations.push({
+					file: home.file,
+					line: bodyStart + i,
+					symbol: name,
+					kind: "returned-refusal",
+					detail:
+						"returns an APIError Response from middleware — throw an HttpError so the refusal is not delivered as data",
+				});
+			});
+		}
+
+		if (!body.includes("createServerFn")) continue;
+		const declaration = body.slice(body.indexOf("createServerFn"));
+		const line = home.source.slice(0, home.source.indexOf(body)).split("\n")
+			.length;
+		const declLine =
+			home.source
+				.split("\n")
+				.findIndex((l, i) => i >= line - 1 && l.includes("createServerFn")) + 1;
+		if (home.source.split("\n")[declLine - 1]?.includes(ALLOW)) continue;
+
+		const declaresPost = /createServerFn\(\s*\{[^}]*method:\s*"POST"/.test(
+			declaration,
+		);
+		const declaresValidator = /\.validator\(/.test(declaration);
+		// A schema handed straight to `.validator()` leaves the framework's
+		// `execValidator` to throw — an `Error` whose message is a JSON dump of
+		// zod's issues, carrying no `.status`. `validated()` turns that into a
+		// 400 like every other refusal, so it is the only accepted form.
+		// Matched by walking each occurrence rather than one lookahead: `\s*`
+		// backtracks, so `.validator(\n\tvalidated(` would satisfy a negative
+		// lookahead placed after it and report every wrapped call as bare.
+		const bareValidator = [...declaration.matchAll(/\.validator\(\s*/g)].some(
+			(hit) =>
+				!declaration
+					.slice((hit.index ?? 0) + hit[0].length)
+					.startsWith("validated("),
+		);
+		// The handler destructures `data` only when it takes input.
+		const acceptsInput = /\.handler\(\s*(?:async\s*)?\(\s*\{[^}]*\bdata\b/.test(
+			declaration,
+		);
+
+		if (!declaresPost && writers.has(name)) {
+			violations.push({
+				file: home.file,
+				line: declLine,
+				symbol: name,
+				kind: "missing-post",
+				detail: "reaches a write but does not declare method: \"POST\"",
+			});
+		}
+		if (acceptsInput && !declaresValidator) {
+			violations.push({
+				file: home.file,
+				line: declLine,
+				symbol: name,
+				kind: "missing-validator",
+				detail: "accepts input but declares no .validator()",
+			});
+		}
+		if (bareValidator) {
+			violations.push({
+				file: home.file,
+				line: declLine,
+				symbol: name,
+				kind: "bare-validator",
+				detail:
+					"passes a schema straight to .validator() — wrap it in validated() so a bad field is a 400, not a zod dump",
+			});
+		}
+	}
+
+	return violations.sort(
+		(a, b) => a.file.localeCompare(b.file) || a.line - b.line,
+	);
+}
+
+if (import.meta.main) {
+	const violations = findServerFnViolations();
+	if (violations.length > 0) {
+		console.error("Server function contract violations:");
+		for (const v of violations) {
+			console.error(`  ${v.file}:${v.line} ${v.symbol} — ${v.detail}`);
+		}
+		console.error(
+			`\nA handler that writes must declare createServerFn({ method: "POST" }), one that takes input must declare .validator(), and a guard middleware must throw an HttpError rather than return an APIError Response. If a case is genuinely fine, annotate the offending line with '${ALLOW}: <reason>'.`,
+		);
+		process.exit(1);
+	}
+	console.log("check:server-fns ok (writes are POST, inputs are validated)");
+}

package/template/scripts/check-sql-raw.ts

@@ -0,0 +1,50 @@
+/**
+ * Guardrail: forbid drizzle `sql.raw(...)` in app source.
+ *
+ *   bun run check:sql-raw   (also chained into `bun run check`)
+ *
+ * `sql.raw` interpolates its argument into SQL verbatim. With user input it is a
+ * SQL-injection vector, and an injection on the app connection can `SET`/`set_config`
+ * the USERSET `app.service` GUC to self-escalate past RLS (see is_admin() and
+ * src/db/helper.ts). The real fix — a dedicated BYPASSRLS service role — is deferred
+ * with H1. Until then this keeps the "no sql.raw + user input" precondition true.
+ *
+ * There are currently zero `sql.raw` uses. If you must add a *static, constant* one,
+ * annotate the line with `sql-raw-ok` (e.g. `sql.raw(FOO) // sql-raw-ok: constant`)
+ * so the guard skips it and the escape is auditable in review.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SRC = join(dirname(fileURLToPath(import.meta.url)), "..", "src");
+const ALLOW = "sql-raw-ok";
+
+function walk(dir: string): string[] {
+	const out: string[] = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...walk(path));
+		else if (/\.(ts|tsx)$/.test(entry.name)) out.push(path);
+	}
+	return out;
+}
+
+const hits: string[] = [];
+for (const file of walk(SRC)) {
+	const lines = readFileSync(file, "utf8").split("\n");
+	lines.forEach((line, i) => {
+		if (line.includes("sql.raw(") && !line.includes(ALLOW)) {
+			hits.push(`${file}:${i + 1}: ${line.trim()}`);
+		}
+	});
+}
+
+if (hits.length > 0) {
+	console.error("Forbidden sql.raw( usage (SQLi / RLS self-escalation vector):");
+	for (const h of hits) console.error(`  ${h}`);
+	console.error(`\nUse parameterized drizzle sql\`...\`. If truly static, annotate with '${ALLOW}'.`);
+	process.exit(1);
+}
+
+console.log("check:sql-raw ok (no unguarded sql.raw)");

package/template/scripts/compile-paraglide.ts

@@ -0,0 +1,12 @@
+import { compile } from "@inlang/paraglide-js";
+import { paraglideOptions } from "../paraglide.config";
+
+// Regenerate src/paraglide before Vitest, which doesn't run the Vite plugin.
+// `isServer` uses a Node-friendly check so the compiled runtime works in the
+// test runner as well as the app build.
+await compile({
+	...paraglideOptions,
+	isServer: "typeof window === 'undefined'",
+});
+
+console.log("✓ paraglide compiled (en, de)");

package/template/scripts/postgres/README.md

@@ -0,0 +1,76 @@
+# Local Postgres (Docker)
+
+First boot of `docker compose` runs every executable under this directory
+(`docker-entrypoint-initdb.d`). `create-app-role.sh` creates the runtime
+`starter_app` role with **NOBYPASSRLS**.
+
+## Credentials (defaults in repo root `.env.docker`)
+
+| Role | User | Password | Use |
+|------|------|----------|-----|
+| Superuser | `postgres` | `postgres_dev_password` | Drizzle migrate / seed |
+| App | `starter_app` | `starter_app_dev_password` | Worker via Hyperdrive |
+
+Database name: **`starter`**.
+
+```text
+# Migrations / seed (privileged) — host port = POSTGRES_PORT in .env.docker
+postgresql://postgres:postgres_dev_password@localhost:5432/starter
+
+# Runtime (app role — wrangler.jsonc localConnectionString)
+postgresql://starter_app:starter_app_dev_password@localhost:5432/starter
+```
+
+Postgres **inside** the container always listens on `5432`. Compose maps
+`localhost:${POSTGRES_PORT} → container:5432` (e.g. `5432:5432`).  
+Wrong: `5433:5433` — the host port is published but the container side is not
+where Postgres listens, so the host connects and nothing answers. To move only
+the host port, set `POSTGRES_PORT=5433` (Compose still maps it to `5432`) and
+update `DATABASE_MIGRATION_URL` plus `hyperdrive[].localConnectionString`.
+
+## Commands
+
+```bash
+bun run db:up      # start container
+bun run db:down    # stop container
+bun run db:reset   # wipe volume + recreate (destroys local data)
+bun run db:migrate # apply drizzle migrations
+bun run db:seed    # local admin + user
+```
+
+## Production / hosted Postgres
+
+Do **not** use `.env.docker` passwords. Create a dedicated app role with a
+strong secret (SQL editor or operator-run script), point Hyperdrive at it, and
+set `DATABASE_MIGRATION_URL` to a privileged direct URL for migrations only.
+
+Example production role (replace password):
+
+```sql
+CREATE ROLE starter_app
+  LOGIN
+  PASSWORD 'replace-with-strong-secret'
+  NOSUPERUSER
+  NOCREATEDB
+  NOCREATEROLE
+  NOINHERIT
+  NOBYPASSRLS;
+
+GRANT CONNECT ON DATABASE your_db TO starter_app;
+GRANT USAGE ON SCHEMA public TO starter_app;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO starter_app;
+GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO starter_app;
+ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public
+  GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO starter_app;
+ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public
+  GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO starter_app;
+```
+
+## Re-running init scripts
+
+`docker-entrypoint-initdb.d` runs **only on an empty data volume**. After the
+first `db:up`, changing `.env.docker` or these scripts requires:
+
+```bash
+bun run db:reset
+```

package/template/scripts/postgres/create-app-role.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Runs once on empty Postgres data dir (docker-entrypoint-initdb.d).
+# Creates the runtime app role used by Hyperdrive localConnectionString.
+# Passwords come from container env (.env.docker → docker-compose environment).
+
+set -Eeuo pipefail
+
+psql \
+	--set=ON_ERROR_STOP=1 \
+	--username "$POSTGRES_USER" \
+	--dbname "$POSTGRES_DB" \
+	--set=database_name="$POSTGRES_DB" \
+	--set=postgres_user="$POSTGRES_USER" \
+	--set=app_db_user="$APP_DB_USER" \
+	--set=app_db_password="$APP_DB_PASSWORD" <<'EOSQL'
+
+-- Runtime database user — CANNOT be the privileged superuser.
+-- NOBYPASSRLS so RLS policies always apply through Hyperdrive.
+CREATE ROLE :"app_db_user"
+  LOGIN
+  PASSWORD :'app_db_password'
+  NOSUPERUSER
+  NOCREATEDB
+  NOCREATEROLE
+  NOINHERIT
+  NOBYPASSRLS;
+
+GRANT CONNECT
+ON DATABASE :"database_name"
+TO :"app_db_user";
+
+GRANT USAGE
+ON SCHEMA public
+TO :"app_db_user";
+
+-- Existing tables / sequences (usually empty at init)
+GRANT SELECT, INSERT, UPDATE, DELETE
+ON ALL TABLES IN SCHEMA public
+TO :"app_db_user";
+
+GRANT USAGE, SELECT, UPDATE
+ON ALL SEQUENCES IN SCHEMA public
+TO :"app_db_user";
+
+-- Tables created later by Drizzle migrations under the superuser
+ALTER DEFAULT PRIVILEGES
+FOR ROLE :"postgres_user"
+IN SCHEMA public
+GRANT SELECT, INSERT, UPDATE, DELETE
+ON TABLES
+TO :"app_db_user";
+
+ALTER DEFAULT PRIVILEGES
+FOR ROLE :"postgres_user"
+IN SCHEMA public
+GRANT USAGE, SELECT, UPDATE
+ON SEQUENCES
+TO :"app_db_user";
+
+EOSQL