@tatara/cli 0.0.0-stage → 0.1.0

package/templates/features/drizzle/files+postgres/src/core/db/migrate.ts

@@ -0,0 +1,13 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import pg from "pg";
+
+/** Applies ./drizzle migrations to the database at `url`. */
+export async function migrateDatabase(url: string): Promise<void> {
+	const pool = new pg.Pool({ connectionString: url, max: 1 });
+	try {
+		await migrate(drizzle({ client: pool }), { migrationsFolder: "drizzle" });
+	} finally {
+		await pool.end();
+	}
+}

package/templates/features/email/files/src/core/email/commands/send-test.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { defineCommand } from "#core/commands/define";
+import { sendEmail } from "#core/email/send";
+
+export default defineCommand({
+	name: "email:send-test",
+	description: "Send a test email (see it in Mailpit locally)",
+	args: z.object({ to: z.email().default("dev@example.com") }),
+	async run({ to }, { logger }) {
+		await sendEmail({ to, subject: "Test email", text: "It works." });
+		logger.info({ to }, "test email sent");
+	},
+});

package/templates/features/email/files/src/core/email/send.ts

@@ -0,0 +1,22 @@
+import { createTransport, type Transporter } from "nodemailer";
+import { env } from "#core/config/env";
+import { logger } from "#core/logging/logger";
+
+export interface EmailMessage {
+	to: string;
+	subject: string;
+	text: string;
+	html?: string;
+}
+
+let transport: Transporter | undefined;
+
+/** Sends through SMTP (Mailpit locally) or logs it when EMAIL_DRIVER=console. */
+export async function sendEmail(message: EmailMessage): Promise<void> {
+	if (env.EMAIL_DRIVER === "console") {
+		logger.info({ to: message.to, subject: message.subject }, "email (console driver)");
+		return;
+	}
+	transport ??= createTransport(env.SMTP_URL);
+	await transport.sendMail({ from: env.EMAIL_FROM, ...message });
+}

package/templates/features/email/files/src/core/email/tests/email.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+import { sendEmail } from "#core/email/send";
+
+describe("email", () => {
+	it("accepts a message with the test (console) driver", async () => {
+		await expect(sendEmail({ to: "a@example.com", subject: "Hi", text: "Hello" })).resolves.toBeUndefined();
+	});
+});

package/templates/features/i18n/files/src/core/i18n/index.ts

@@ -0,0 +1,41 @@
+import { createMiddleware } from "hono/factory";
+import { env } from "#core/config/env";
+import type { AppEnv } from "#core/http/context";
+import ar from "#locales/ar" with { type: "json" };
+import en from "#locales/en" with { type: "json" };
+
+type Dictionary = { [key: string]: string | Dictionary };
+
+const dictionaries: Record<string, Dictionary> = { en, ar };
+
+export const SUPPORTED_LANGUAGES = Object.keys(dictionaries);
+
+function lookup(dict: Dictionary | undefined, key: string): string | undefined {
+	let node: string | Dictionary | undefined = dict;
+	for (const part of key.split(".")) {
+		if (!node || typeof node === "string") return undefined;
+		node = node[part];
+	}
+	return typeof node === "string" ? node : undefined;
+}
+
+/** Translates `key` ("errors.NOT_FOUND"), falling back to the default language, then `fallback`. */
+export function t(language: string, key: string, fallback = key, vars: Record<string, string> = {}): string {
+	const text = lookup(dictionaries[language], key) ?? lookup(dictionaries[env.DEFAULT_LANGUAGE], key) ?? fallback;
+	return text.replace(/\{(\w+)\}/g, (_, name: string) => vars[name] ?? `{${name}}`);
+}
+
+/** ?lang, then the `lang` cookie, then Accept-Language; sets `c.var.language`. */
+export const detectLanguage = createMiddleware<AppEnv>(async (c, next) => {
+	const candidates = [
+		c.req.query("lang"),
+		/(?:^|;\s*)lang=([^;]+)/.exec(c.req.header("cookie") ?? "")?.[1],
+		...(c.req.header("accept-language") ?? "")
+			.split(",")
+			.map((part) => part.split(";")[0]?.trim().toLowerCase().split("-")[0]),
+	];
+	const language = candidates.find((l) => l && SUPPORTED_LANGUAGES.includes(l)) ?? env.DEFAULT_LANGUAGE;
+	c.set("language", language);
+	c.header("content-language", language);
+	await next();
+});

package/templates/features/i18n/files/src/core/i18n/tests/i18n.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { t } from "#core/i18n/index";
+import { api } from "#tests/helpers/api";
+
+describe("i18n", () => {
+	it("translates with a fallback to the default language", () => {
+		expect(t("ar", "errors.NOT_FOUND")).toBe("غير موجود");
+		expect(t("fr", "errors.NOT_FOUND")).toBe("Not found");
+		expect(t("en", "missing.key", "Fallback")).toBe("Fallback");
+	});
+
+	it("localizes error messages from Accept-Language", async () => {
+		const res = await api.get("/api/nope", { headers: { "accept-language": "ar-SA,ar;q=0.9" } });
+		expect(res.status).toBe(404);
+		const invalid = await api.get(`/api/greetings?name=${"x".repeat(60)}`, {
+			headers: { "accept-language": "ar" },
+		});
+		expect(invalid.body).toMatchObject({ code: "VALIDATION_ERROR", error: "الطلب غير صالح" });
+		expect(invalid.headers.get("content-language")).toBe("ar");
+	});
+});

package/templates/features/i18n/files/src/locales/ar.json

@@ -0,0 +1,10 @@
+{
+	"errors": {
+		"VALIDATION_ERROR": "الطلب غير صالح",
+		"UNAUTHORIZED": "يجب تسجيل الدخول",
+		"FORBIDDEN": "ليس لديك صلاحية للقيام بذلك",
+		"NOT_FOUND": "غير موجود",
+		"CONFLICT": "موجود مسبقاً",
+		"INTERNAL_ERROR": "حدث خطأ ما"
+	}
+}

package/templates/features/i18n/files/src/locales/en.json

@@ -0,0 +1,10 @@
+{
+	"errors": {
+		"VALIDATION_ERROR": "Invalid request",
+		"UNAUTHORIZED": "Authentication required",
+		"FORBIDDEN": "You do not have permission to do this",
+		"NOT_FOUND": "Not found",
+		"CONFLICT": "Already exists",
+		"INTERNAL_ERROR": "Something went wrong"
+	}
+}

package/templates/features/jobs/files/src/apps/cron/index.ts

@@ -0,0 +1,25 @@
+import { Cron } from "croner";
+import { withLock } from "#core/jobs/lock";
+import { logger } from "#core/logging/logger";
+import { handleSignals, onShutdown } from "#core/process/lifecycle";
+import { schedules } from "#generated/schedules";
+
+const jobs = schedules.map((schedule) => {
+	const log = logger.child({ schedule: schedule.name });
+	return new Cron(schedule.cron, { timezone: "UTC", protect: true, name: schedule.name }, async (self) => {
+		const tick = self.currentRun()?.toISOString() ?? new Date().toISOString();
+		const ran = await withLock(`schedule:${schedule.name}:${tick}`, schedule.lockTtlMs ?? 60_000, () =>
+			schedule.run({ logger: log }),
+		).catch((error: unknown) => {
+			log.error({ err: error }, "schedule failed");
+			return true;
+		});
+		if (!ran) log.debug("skipped: another process holds this tick");
+	});
+});
+
+onShutdown("cron", () => {
+	for (const job of jobs) job.stop();
+});
+handleSignals();
+logger.info({ schedules: schedules.map((s) => `${s.name} (${s.cron})`) }, "cron started");

package/templates/features/jobs/files/src/apps/worker/index.ts

@@ -0,0 +1,24 @@
+import { Worker } from "bullmq";
+import { env } from "#core/config/env";
+import { processJob } from "#core/jobs/process";
+import { QUEUE_NAME } from "#core/jobs/queue";
+import { redis } from "#core/jobs/redis";
+import { logger } from "#core/logging/logger";
+import { handleSignals, onShutdown } from "#core/process/lifecycle";
+import { consumers } from "#generated/consumers";
+
+const worker = new Worker(
+	QUEUE_NAME,
+	(job) =>
+		processJob(consumers, job.name, job.data, {
+			logger: logger.child({ jobId: job.id, topic: job.name }),
+			jobId: job.id ?? "",
+			attempt: job.attemptsMade + 1,
+		}),
+	{ connection: redis(), prefix: env.JOBS_PREFIX, concurrency: env.WORKER_CONCURRENCY },
+);
+
+worker.on("failed", (job, err) => logger.error({ err, jobId: job?.id, topic: job?.name }, "job failed"));
+onShutdown("worker", () => worker.close());
+handleSignals();
+logger.info({ topics: consumers.map((c) => c.topic) }, "worker started");

package/templates/features/jobs/files/src/core/jobs/commands/enqueue.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { defineCommand } from "#core/commands/define";
+import { enqueue } from "#core/jobs/queue";
+
+export default defineCommand({
+	name: "jobs:enqueue",
+	description: "Enqueue a job by topic with a JSON payload (for development and debugging)",
+	args: z.object({ topic: z.string().min(1), data: z.string().default("{}") }),
+	async run({ topic, data }, { logger }) {
+		const id = await enqueue(topic, JSON.parse(data) as unknown);
+		logger.info({ topic, id }, "job enqueued");
+	},
+});

package/templates/features/jobs/files/src/core/jobs/define.ts

@@ -0,0 +1,37 @@
+import type { z } from "zod";
+import type { Logger } from "#core/logging/logger";
+
+export interface JobContext {
+	logger: Logger;
+	jobId: string;
+	attempt: number;
+}
+
+export interface ConsumerDefinition<S extends z.ZodType = z.ZodType> {
+	/** job name, e.g. "billing.invoice-paid" */
+	topic: string;
+	description: string;
+	schema: S;
+	/** retries before the job is marked failed (default 3) */
+	attempts?: number;
+	handle(data: z.infer<S>, ctx: JobContext): Promise<void>;
+}
+
+/** Default export of every `consumers/*.ts`; run by the worker app. */
+export function defineConsumer<S extends z.ZodType>(definition: ConsumerDefinition<S>) {
+	return definition;
+}
+
+export interface ScheduleDefinition {
+	name: string;
+	/** cron expression (seconds optional), evaluated in UTC */
+	cron: string;
+	/** how long the run holds its lock; one run per tick across all cron processes */
+	lockTtlMs?: number;
+	run(ctx: { logger: Logger }): Promise<void>;
+}
+
+/** Default export of every `schedules/*.ts`; run by the cron app. */
+export function defineSchedule(definition: ScheduleDefinition): ScheduleDefinition {
+	return definition;
+}

package/templates/features/jobs/files/src/core/jobs/lock.ts

@@ -0,0 +1,17 @@
+import { randomUUID } from "node:crypto";
+import { redis } from "#core/jobs/redis";
+
+const RELEASE = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`;
+
+/** Runs `fn` only if this process wins the lock; returns false when another holder has it. */
+export async function withLock(key: string, ttlMs: number, fn: () => Promise<void>): Promise<boolean> {
+	const token = randomUUID();
+	const acquired = await redis().set(`lock:${key}`, token, "PX", ttlMs, "NX");
+	if (acquired !== "OK") return false;
+	try {
+		await fn();
+	} finally {
+		await redis().eval(RELEASE, 1, `lock:${key}`, token);
+	}
+	return true;
+}

package/templates/features/jobs/files/src/core/jobs/process.ts

@@ -0,0 +1,19 @@
+import type { ConsumerDefinition, JobContext } from "#core/jobs/define";
+
+export class UnknownTopicError extends Error {}
+
+/** Validates and runs one job; shared by the worker and by tests. */
+export async function processJob(
+	consumers: ConsumerDefinition[],
+	topic: string,
+	data: unknown,
+	ctx: JobContext,
+): Promise<void> {
+	const consumer = consumers.find((c) => c.topic === topic);
+	if (!consumer) throw new UnknownTopicError(`No consumer for topic "${topic}"`);
+	const parsed = consumer.schema.safeParse(data);
+	if (!parsed.success) {
+		throw new Error(`Invalid payload for ${topic}: ${parsed.error.message}`);
+	}
+	await consumer.handle(parsed.data, ctx);
+}

package/templates/features/jobs/files/src/core/jobs/queue.ts

@@ -0,0 +1,29 @@
+import { type JobsOptions, Queue } from "bullmq";
+import { env } from "#core/config/env";
+import { redis } from "#core/jobs/redis";
+import { onShutdown } from "#core/process/lifecycle";
+
+export const QUEUE_NAME = "__APP_NAME__-jobs";
+
+let queue: Queue | undefined;
+
+function getQueue(): Queue {
+	if (!queue) {
+		const q = new Queue(QUEUE_NAME, { connection: redis(), prefix: env.JOBS_PREFIX });
+		queue = q;
+		onShutdown("queue", () => q.close());
+	}
+	return queue;
+}
+
+/** Enqueues a job for the consumer with this topic. The consumer validates the payload. */
+export async function enqueue(topic: string, data: unknown, options: JobsOptions = {}): Promise<string> {
+	const job = await getQueue().add(topic, data, {
+		attempts: 3,
+		backoff: { type: "exponential", delay: 1000 },
+		removeOnComplete: 1000,
+		removeOnFail: 5000,
+		...options,
+	});
+	return job.id ?? "";
+}

package/templates/features/jobs/files/src/core/jobs/redis.ts

@@ -0,0 +1,17 @@
+import { Redis } from "ioredis";
+import { env } from "#core/config/env";
+import { onShutdown } from "#core/process/lifecycle";
+
+let client: Redis | undefined;
+
+/** Shared connection (BullMQ requires maxRetriesPerRequest: null). */
+export function redis(): Redis {
+	if (!client) {
+		const connection = new Redis(env.REDIS_URL, { maxRetriesPerRequest: null });
+		client = connection;
+		onShutdown("redis", async () => {
+			await connection.quit();
+		});
+	}
+	return client;
+}

package/templates/features/jobs/files/src/modules/example/consumers/send-welcome.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { defineConsumer } from "#core/jobs/define";
+
+export default defineConsumer({
+	topic: "example.send-welcome",
+	description: "Example consumer: greets a new user",
+	schema: z.object({ name: z.string().min(1) }),
+	async handle({ name }, { logger }) {
+		logger.info({ name }, "welcome sent");
+	},
+});

package/templates/features/jobs/files/src/modules/example/schedules/heartbeat.ts

@@ -0,0 +1,9 @@
+import { defineSchedule } from "#core/jobs/define";
+
+export default defineSchedule({
+	name: "example.heartbeat",
+	cron: "*/5 * * * *",
+	async run({ logger }) {
+		logger.info("heartbeat");
+	},
+});

package/templates/features/jobs/files/src/modules/example/tests/jobs.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { withLock } from "#core/jobs/lock";
+import { processJob } from "#core/jobs/process";
+import { logger } from "#core/logging/logger";
+import { consumers } from "#generated/consumers";
+
+const ctx = { logger, jobId: "test", attempt: 1 };
+
+describe("jobs", () => {
+	it("runs the consumer for a topic with a valid payload", async () => {
+		await expect(processJob(consumers, "example.send-welcome", { name: "Ada" }, ctx)).resolves.toBeUndefined();
+	});
+
+	it("rejects an invalid payload", async () => {
+		await expect(processJob(consumers, "example.send-welcome", { name: "" }, ctx)).rejects.toThrow(
+			/Invalid payload/,
+		);
+	});
+
+	it("lets only one holder run a locked section", async () => {
+		const key = `test-${Date.now()}-${Math.random()}`;
+		let inner: boolean | undefined;
+		const outer = await withLock(key, 5000, async () => {
+			inner = await withLock(key, 5000, async () => {});
+		});
+		expect(outer).toBe(true);
+		expect(inner).toBe(false);
+	});
+});

package/templates/features/keycloak/files/keycloak/realm.json

@@ -0,0 +1,83 @@
+{
+	"realm": "__APP_NAME__",
+	"enabled": true,
+	"displayName": "__APP_NAME__ (development)",
+	"sslRequired": "none",
+	"accessTokenLifespan": 900,
+	"registrationAllowed": false,
+	"roles": {
+		"realm": [
+			{ "name": "user", "description": "Signed-in user" },
+			{ "name": "admin", "description": "Administrator" }
+		]
+	},
+	"clients": [
+		{
+			"clientId": "__APP_NAME__-api",
+			"name": "__APP_NAME__ API (token audience)",
+			"enabled": true,
+			"publicClient": false,
+			"bearerOnly": true,
+			"standardFlowEnabled": false,
+			"directAccessGrantsEnabled": false
+		},
+		{
+			"clientId": "__APP_NAME__-web",
+			"name": "__APP_NAME__ web (public, PKCE)",
+			"enabled": true,
+			"publicClient": true,
+			"standardFlowEnabled": true,
+			"directAccessGrantsEnabled": true,
+			"redirectUris": ["http://localhost:5173/*", "http://localhost:3000/*"],
+			"webOrigins": ["+"],
+			"attributes": { "pkce.code.challenge.method": "S256", "post.logout.redirect.uris": "+" },
+			"protocolMappers": [
+				{
+					"name": "api-audience",
+					"protocol": "openid-connect",
+					"protocolMapper": "oidc-audience-mapper",
+					"config": {
+						"included.client.audience": "__APP_NAME__-api",
+						"access.token.claim": "true",
+						"id.token.claim": "false"
+					}
+				},
+				{
+					"name": "realm-roles",
+					"protocol": "openid-connect",
+					"protocolMapper": "oidc-usermodel-realm-role-mapper",
+					"config": {
+						"claim.name": "roles",
+						"multivalued": "true",
+						"jsonType.label": "String",
+						"access.token.claim": "true",
+						"id.token.claim": "false",
+						"userinfo.token.claim": "false"
+					}
+				}
+			]
+		}
+	],
+	"users": [
+		{
+			"username": "alice",
+			"email": "alice@example.com",
+			"emailVerified": true,
+			"firstName": "Alice",
+			"lastName": "Admin",
+			"enabled": true,
+			"credentials": [{ "type": "password", "value": "alice", "temporary": false }],
+			"realmRoles": ["user", "admin"]
+		},
+		{
+			"username": "bob",
+			"email": "bob@example.com",
+			"emailVerified": true,
+			"firstName": "Bob",
+			"lastName": "User",
+			"enabled": true,
+			"credentials": [{ "type": "password", "value": "bob", "temporary": false }],
+			"realmRoles": ["user"]
+		}
+	]
+}

package/templates/features/keycloak/files/src/core/auth/commands/keycloak-token.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { issuer } from "#core/auth/keycloak";
+import { defineCommand } from "#core/commands/define";
+import { env } from "#core/config/env";
+
+export default defineCommand({
+	name: "keycloak:token",
+	description: "Print an access token for a dev-realm user (development only)",
+	args: z.object({
+		user: z.string().default("alice"),
+		password: z.string().optional(),
+		client: z.string().default("__APP_NAME__-web"),
+	}),
+	async run({ user, password, client }) {
+		if (env.NODE_ENV === "production") throw new Error("keycloak:token is for development only");
+		const res = await fetch(`${issuer}/protocol/openid-connect/token`, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "password",
+				client_id: client,
+				username: user,
+				password: password ?? user,
+			}),
+		});
+		const body = (await res.json()) as { access_token?: string; error_description?: string };
+		if (!res.ok || !body.access_token) {
+			throw new Error(`Keycloak refused: ${body.error_description ?? res.statusText}`);
+		}
+		console.log(body.access_token);
+	},
+});

package/templates/features/keycloak/files/src/core/auth/keycloak.ts

@@ -0,0 +1,58 @@
+import { createRemoteJWKSet, type JWTPayload, type JWTVerifyGetKey, jwtVerify } from "jose";
+import { env } from "#core/config/env";
+
+export const issuer = `${env.KEYCLOAK_URL.replace(/\/$/, "")}/realms/${env.KEYCLOAK_REALM}`;
+
+let keySource: JWTVerifyGetKey = createRemoteJWKSet(
+	new URL(`${issuer}/protocol/openid-connect/certs`),
+);
+
+/** Tests replace the realm's key set with a local one. */
+export function setKeySource(source: JWTVerifyGetKey): void {
+	keySource = source;
+}
+
+export interface KeycloakClaims extends JWTPayload {
+	sub: string;
+	email?: string;
+	name?: string;
+	preferred_username?: string;
+	azp?: string;
+	roles?: string[];
+	realm_access?: { roles?: string[] };
+	resource_access?: Record<string, { roles?: string[] }>;
+	organization?: string[] | Record<string, unknown>;
+}
+
+/** Verifies signature, issuer, audience and expiry. Throws when the token is not valid. */
+export async function verifyAccessToken(token: string): Promise<KeycloakClaims> {
+	const { payload } = await jwtVerify(token, keySource, {
+		issuer,
+		audience: env.KEYCLOAK_AUDIENCE,
+	});
+	if (typeof payload.sub !== "string") throw new Error("token has no subject");
+	return payload as KeycloakClaims;
+}
+
+export function rolesOf(claims: KeycloakClaims): string[] {
+	const roles = new Set<string>([
+		...(claims.roles ?? []),
+		...(claims.realm_access?.roles ?? []),
+		...(claims.resource_access?.[env.KEYCLOAK_AUDIENCE]?.roles ?? []),
+	]);
+	return [...roles];
+}
+
+/** Keycloak organizations put memberships in the `organization` claim; the first one wins. */
+export function organizationOf(claims: KeycloakClaims): string | null {
+	const org = claims.organization;
+	if (Array.isArray(org)) return org[0] ?? null;
+	if (org && typeof org === "object") {
+		const [first] = Object.entries(org);
+		if (!first) return null;
+		const [alias, value] = first;
+		const id = (value as { id?: unknown } | undefined)?.id;
+		return typeof id === "string" ? id : alias;
+	}
+	return null;
+}

package/templates/features/keycloak/files/src/core/auth/principal.ts

@@ -0,0 +1,27 @@
+import { createMiddleware } from "hono/factory";
+import { organizationOf, rolesOf, verifyAccessToken } from "#core/auth/keycloak";
+import { ensureLocalUser } from "#core/auth/users";
+import type { AppEnv } from "#core/http/context";
+
+/** Verifies `Authorization: Bearer <Keycloak access token>` into `c.var.principal`. */
+export const attachPrincipal = createMiddleware<AppEnv>(async (c, next) => {
+	const header = c.req.header("authorization");
+	const token = header?.startsWith("Bearer ") ? header.slice(7) : undefined;
+	if (token) {
+		try {
+			const claims = await verifyAccessToken(token);
+			const isService = claims.preferred_username?.startsWith("service-account-") ?? false;
+			if (!isService) await ensureLocalUser(claims);
+			c.set("principal", {
+				userId: claims.sub,
+				orgId: organizationOf(claims),
+				roles: rolesOf(claims),
+				kind: isService ? "service" : "user",
+				claims,
+			});
+		} catch (error) {
+			c.get("logger").debug({ err: error }, "rejected bearer token");
+		}
+	}
+	await next();
+});

package/templates/features/keycloak/files/tests/helpers/auth.ts

@@ -0,0 +1,52 @@
+import { generateKeyPair, SignJWT } from "jose";
+import { issuer, setKeySource } from "#core/auth/keycloak";
+import { env } from "#core/config/env";
+import { newId } from "#core/db/id";
+// tatara:slot imports
+
+const { publicKey, privateKey } = await generateKeyPair("RS256");
+setKeySource(async (header) => {
+	if (header.kid !== "test") throw new Error("unknown key");
+	return publicKey;
+});
+
+export interface AsUserOptions {
+	sub?: string;
+	email?: string;
+	roles?: string[];
+	orgId?: string;
+	// tatara:slot options
+}
+
+/** Signs a token the API accepts, as if Keycloak issued it for a new user. */
+export async function tokenFor(options: AsUserOptions = {}): Promise<string> {
+	const sub = options.sub ?? newId();
+	return new SignJWT({
+		email: options.email ?? `user-${sub}@example.com`,
+		preferred_username: `user-${sub.slice(0, 8)}`,
+		roles: options.roles ?? ["user"],
+		...(options.orgId ? { organization: [options.orgId] } : {}),
+	})
+		.setProtectedHeader({ alg: "RS256", kid: "test" })
+		.setSubject(sub)
+		.setIssuer(issuer)
+		.setAudience(env.KEYCLOAK_AUDIENCE)
+		.setIssuedAt()
+		.setExpirationTime("5m")
+		.sign(privateKey);
+}
+
+/** A new user (random subject) with a signed access token. */
+export async function authenticate(
+	options: AsUserOptions = {},
+): Promise<{ userId: string; headers: Record<string, string> }> {
+	const sub = options.sub ?? newId();
+	return { userId: sub, headers: { authorization: `Bearer ${await tokenFor({ ...options, sub })}` } };
+}
+
+/** Headers that authenticate as a new user. */
+export async function asUser(options: AsUserOptions = {}): Promise<Record<string, string>> {
+	const user = await authenticate(options);
+	// tatara:slot as-user
+	return user.headers;
+}