@tatara/cli 0.1.1 → 0.1.3

package/dist/bin.mjs

@@ -527,7 +527,7 @@ async function dev(project, flags = {}) {
 	if (project.has("admin")) urls.push(`Admin API   http://localhost:${env.ADMIN_PORT ?? "3001"}/docs`);
 	if (project.has("email")) urls.push(`Mailpit     http://localhost:${env.MAILPIT_UI_PORT ?? "8025"}`);
 	if (project.has("storage")) urls.push(`Storage UI  http://localhost:${env.STORAGE_CONSOLE_PORT ?? "9001"}`);
-	if (project.has("keycloak")) urls.push(`Keycloak    http://localhost:${env.KEYCLOAK_PORT ?? "8080"}/admin (admin/admin)`);
+	if (project.has("auth-keycloak")) urls.push(`Keycloak    http://localhost:${env.KEYCLOAK_PORT ?? "8080"}/admin (admin/admin)`);
 	console.log(`\n${urls.map((u) => `  ${pc.green("➜")} ${u}`).join("\n")}\n`);
 	return new Promise((resolve) => {
 		const stop = () => {
@@ -553,7 +553,7 @@ const PACKAGES = {
 	drizzle: ["drizzle-orm", "drizzle-kit"],
 	prisma: ["@prisma/client", "prisma"],
 	"better-auth": ["better-auth"],
-	keycloak: ["jose"],
+	"auth-keycloak": ["jose"],
 	jobs: ["bullmq", "ioredis"]
 };
 async function doctor(project) {
@@ -1450,10 +1450,63 @@ const authOrgs = {
 		...adminFields
 	]
 };
-const keycloak = {
-	id: "keycloak",
-	kind: "auth",
-	label: "Keycloak",
+const KEYCLOAK_AGENTS = `### Keycloak
+
+- The API also accepts Keycloak access tokens (\`Authorization: Bearer <token>\`). The
+  \`keycloakTokens()\` better-auth plugin (\`src/core/auth/keycloak-plugin.ts\`) verifies signature,
+  issuer, audience \`__APP_NAME__-api\` and expiry; login happens in the frontend via OIDC (PKCE)
+  against the \`__APP_NAME__-web\` client.
+- The token's subject is the user id. The user (and a \`keycloak\` account) is created in
+  better-auth's tables on first use; a token whose email already belongs to another account is
+  rejected. Service-account tokens become \`kind: "service"\` principals with no user row.
+- Roles come from the token (realm roles, \`roles\`, and client roles for the API); a role named like
+  a built-in authz role grants it. The organization comes from the \`organization\` claim.
+- Local dev realm: \`keycloak/realm.json\` (users alice/alice with admin, bob/bob).
+  \`__PM_EXEC__ tatara run keycloak:token --user alice\` prints a token for curl.
+- Tests sign tokens with a local key: \`keycloakToken()\` from \`#tests/helpers/auth\`.
+`;
+const KEYCLOAK_TEST_HELPER = [
+	"const { publicKey, privateKey } = await generateKeyPair(\"RS256\");",
+	"setKeySource(async (header) => {",
+	"	if (header.kid !== \"test\") throw new Error(\"unknown key\");",
+	"	return publicKey;",
+	"});",
+	"",
+	"export interface KeycloakTokenOptions {",
+	"	sub?: string;",
+	"	email?: string;",
+	"	emailVerified?: boolean;",
+	"	roles?: string[];",
+	"	organization?: string[] | Record<string, unknown>;",
+	"	username?: string;",
+	"	issuer?: string;",
+	"	audience?: string;",
+	"	expiresIn?: string | number;",
+	"}",
+	"",
+	"/** Signs an access token the API accepts, as if Keycloak issued it. */",
+	"export async function keycloakToken(options: KeycloakTokenOptions = {}): Promise<string> {",
+	"	const sub = options.sub ?? newId();",
+	"	return new SignJWT({",
+	"		email: options.email ?? `user-${sub}@example.com`,",
+	"		email_verified: options.emailVerified ?? true,",
+	"		preferred_username: options.username ?? `user-${sub.slice(0, 8)}`,",
+	"		roles: options.roles ?? [\"user\"],",
+	"		...(options.organization ? { organization: options.organization } : {}),",
+	"	})",
+	"		.setProtectedHeader({ alg: \"RS256\", kid: \"test\" })",
+	"		.setSubject(sub)",
+	"		.setIssuer(options.issuer ?? issuer)",
+	"		.setAudience(options.audience ?? env.KEYCLOAK_AUDIENCE)",
+	"		.setIssuedAt()",
+	"		.setExpirationTime(options.expiresIn ?? \"5m\")",
+	"		.sign(privateKey);",
+	"}"
+].join("\n");
+const authKeycloak = {
+	id: "auth-keycloak",
+	kind: "auth-method",
+	label: "Keycloak tokens",
 	dependencies: ["jose"],
 	env: [
 		{
@@ -1501,30 +1554,72 @@ const keycloak = {
 	} },
 	slots: [
 		{
-			file: "src/core/auth/users.ts",
-			slot: "upsert",
-			when: ["drizzle", "postgres"],
-			content: "await db\n	.insert(users)\n	.values(values)\n	.onConflictDoUpdate({ target: users.id, set: { email: values.email, name: values.name, updatedAt: new Date() } });"
+			file: "src/core/auth/auth.ts",
+			slot: "imports",
+			content: "import { keycloakTokens } from \"#core/auth/keycloak-plugin\";"
+		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "plugins",
+			unless: ["auth-orgs"],
+			content: "keycloakTokens(),",
+			order: 800
+		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "plugins",
+			when: ["auth-orgs"],
+			content: "keycloakTokens({ organizations: true }),",
+			order: 800
+		},
+		{
+			file: "src/core/auth/principal.ts",
+			slot: "no-session",
+			content: [
+				"if (!session) {",
+				"	const header = c.req.header(\"authorization\");",
+				"	const token = header?.startsWith(\"Bearer \") ? header.slice(7) : undefined;",
+				"	const principal = token ? await auth.api.verifyKeycloakToken({ body: { token } }) : null;",
+				"	if (principal) c.set(\"principal\", principal);",
+				"}"
+			].join("\n")
 		},
 		{
-			file: "src/core/auth/users.ts",
-			slot: "upsert",
-			when: ["drizzle", "mysql"],
-			content: "await db\n	.insert(users)\n	.values(values)\n	.onDuplicateKeyUpdate({ set: { email: values.email, name: values.name } });"
+			file: "tests/helpers/auth.ts",
+			slot: "imports",
+			content: "import { generateKeyPair, SignJWT } from \"jose\";"
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "imports",
+			content: "import { issuer, setKeySource } from \"#core/auth/keycloak\";"
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "imports",
+			content: "import { env } from \"#core/config/env\";"
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "helpers",
+			content: KEYCLOAK_TEST_HELPER
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "authenticate",
+			unless: ["auth-orgs"],
+			content: [
+				"if (options.roles) {",
+				"	const sub = newId();",
+				"	const token = await keycloakToken({ sub, roles: options.roles, email: options.email });",
+				"	return { userId: sub, headers: { authorization: `Bearer ${token}` } };",
+				"}"
+			].join("\n")
 		},
 		{
 			file: "AGENTS.md",
 			slot: "sections",
-			content: `### Keycloak
-
-- The API is a resource server: it verifies Keycloak access tokens (signature, issuer,
-  audience \`__APP_NAME__-api\`, expiry). Login happens in the frontend via OIDC (PKCE) against
-  the \`__APP_NAME__-web\` client.
-- Roles come from the token's \`roles\` claim (realm roles) and client roles for the API.
-- Local dev realm: \`keycloak/realm.json\` (users alice/alice with admin, bob/bob).
-  \`__PM_EXEC__ tatara run keycloak:token --user alice\` prints a token for curl.
-- Tests sign tokens with a local key; see \`#tests/helpers/auth\`.
-`
+			content: KEYCLOAK_AGENTS
 		}
 	]
 };
@@ -1914,7 +2009,7 @@ const FEATURES = Object.fromEntries([
 	authPhoneOtp,
 	authPassword,
 	authOrgs,
-	keycloak,
+	authKeycloak,
 	auth,
 	authz,
 	jobs,
@@ -1938,12 +2033,12 @@ function validateOptions(input) {
 	const hasDb = options.database !== "none";
 	if (options.auth !== "none" && !hasDb) throw new OptionsError(`Auth (${options.auth}) needs a database.`);
 	if (options.auth === "better-auth") {
-		if (options.authMethods.filter((m) => m !== "orgs").length === 0) throw new OptionsError("better-auth needs at least one sign-in method: email-otp, phone-otp or password.");
+		if (options.authMethods.filter((m) => m !== "orgs").length === 0) throw new OptionsError("better-auth needs at least one sign-in method: email-otp, phone-otp, password or keycloak.");
 	} else if (options.authMethods.length > 0) throw new OptionsError("Auth methods only apply to better-auth.");
 	for (const addon of options.addons) {
 		if ((addon === "authz" || addon === "admin") && options.auth === "none") throw new OptionsError(`The ${addon} add-on needs an auth provider.`);
 		if (addon === "authz" && !hasDb) throw new OptionsError("The authz add-on needs a database.");
-		if (addon === "admin" && options.auth === "better-auth" && !options.authMethods.includes("orgs")) throw new OptionsError("The admin add-on with better-auth needs the \"orgs\" method (it provides user roles).");
+		if (addon === "admin" && options.auth === "better-auth" && !options.authMethods.includes("orgs") && !options.authMethods.includes("keycloak")) throw new OptionsError("The admin add-on with better-auth needs the \"orgs\" or \"keycloak\" method (they provide user roles).");
 	}
 	return options;
 }
@@ -2211,7 +2306,7 @@ async function renderApp(options, generate = {}) {
 	if (compose) files.set("compose.yaml", compose);
 	if (options.packageManager === "pnpm") files.set("pnpm-workspace.yaml", pnpmWorkspace(features));
 	const config = {
-		$schema: "https://raw.githubusercontent.com/mohammed-bageri/tatara/main/schema/tatara.json",
+		$schema: "https://raw.githubusercontent.com/mohammed-bageri/tatara-cli/main/schema/tatara.json",
 		version: cliVersion(),
 		name: options.name,
 		orm: options.orm,
@@ -2550,17 +2645,25 @@ const DATABASES = [
 	"mysql",
 	"none"
 ];
-const AUTHS = [
-	"better-auth",
-	"keycloak",
-	"none"
-];
+const AUTHS = ["better-auth", "none"];
 const METHODS = [
 	"email-otp",
 	"phone-otp",
 	"password",
+	"keycloak",
 	"orgs"
 ];
+/** `--auth keycloak` (before 0.1.2) is better-auth with the keycloak method. */
+function normalizeAuthFlags(flags) {
+	if (flags.auth !== "keycloak") return flags;
+	const methods = new Set((flags.authMethods ?? "").split(",").filter(Boolean));
+	methods.add("keycloak");
+	return {
+		...flags,
+		auth: "better-auth",
+		authMethods: [...methods].join(",")
+	};
+}
 const ADDONS = [
 	"authz",
 	"jobs",
@@ -2628,22 +2731,14 @@ async function prompt(name, flags) {
 	let auth = "none";
 	if (database !== "none") auth = flags.auth ? oneOf(flags.auth, AUTHS, "auth") : answer(await p.select({
 		message: "Auth",
-		options: [
-			{
-				value: "better-auth",
-				label: "better-auth",
-				hint: "sign-in handled by the API"
-			},
-			{
-				value: "keycloak",
-				label: "Keycloak",
-				hint: "API verifies Keycloak tokens"
-			},
-			{
-				value: "none",
-				label: "None"
-			}
-		]
+		options: [{
+			value: "better-auth",
+			label: "better-auth",
+			hint: "sign-in handled by the API"
+		}, {
+			value: "none",
+			label: "None"
+		}]
 	}));
 	let authMethods = [];
 	if (auth === "better-auth") authMethods = flags.authMethods ? listOf(flags.authMethods, METHODS, "auth-methods") : answer(await p.multiselect({
@@ -2662,6 +2757,11 @@ async function prompt(name, flags) {
 				value: "password",
 				label: "Email + password"
 			},
+			{
+				value: "keycloak",
+				label: "Keycloak tokens",
+				hint: "API accepts Keycloak access tokens"
+			},
 			{
 				value: "orgs",
 				label: "Organizations + roles",
@@ -2736,7 +2836,8 @@ async function run(cmd, args, cwd, label) {
 	}
 	spinner?.stop(label);
 }
-async function newApp(dir, flags) {
+async function newApp(dir, rawFlags) {
+	const flags = normalizeAuthFlags(rawFlags);
 	const interactive = !flags.yes && process.stdout.isTTY;
 	if (interactive) p.intro(pc.bold("tatara"));
 	let target = dir;
@@ -2917,7 +3018,7 @@ server.on("exit", () => process.exit(0));
 //#endregion
 //#region src/bin.ts
 const program = new Command("tatara").description("Create and grow opinionated Hono backends").version(cliVersion());
-program.command("new").description("Create a new app").argument("[dir]", "directory to create").option("--orm <orm>", "drizzle | prisma | none").option("--db <database>", "postgres | mysql | none").option("--auth <provider>", "better-auth | keycloak | none").option("--auth-methods <list>", "email-otp,phone-otp,password,orgs (better-auth)").option("--addons <list>", "authz,jobs,admin,storage,email,i18n").option("--pm <pm>", "pnpm | npm | bun").option("-y, --yes", "skip prompts and use flags/defaults").option("--no-install", "do not install dependencies").option("--no-git", "do not initialise git").action(async (dir, flags) => {
+program.command("new").description("Create a new app").argument("[dir]", "directory to create").option("--orm <orm>", "drizzle | prisma | none").option("--db <database>", "postgres | mysql | none").option("--auth <provider>", "better-auth | none (keycloak = better-auth with --auth-methods keycloak)").option("--auth-methods <list>", "email-otp,phone-otp,password,orgs (better-auth)").option("--addons <list>", "authz,jobs,admin,storage,email,i18n").option("--pm <pm>", "pnpm | npm | bun").option("-y, --yes", "skip prompts and use flags/defaults").option("--no-install", "do not install dependencies").option("--no-git", "do not initialise git").action(async (dir, flags) => {
 	await newApp(dir, flags);
 });
 program.command("sync").description("Regenerate src/generated from discovered module files").option("--quiet", "no output").action(async (flags) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tatara/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Create and grow opinionated Hono backends",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohammed-bageri/tatara-cli.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/mohammed-bageri/tatara-cli#readme",
+  "bugs": {
+    "url": "https://github.com/mohammed-bageri/tatara-cli/issues"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit"

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

@@ -0,0 +1,154 @@
+import type { BetterAuthPlugin } from "better-auth";
+import { createAuthEndpoint } from "better-auth/api";
+import { z } from "zod";
+import {
+	type KeycloakClaims,
+	organizationOf,
+	rolesOf,
+	verifyAccessToken,
+} from "#core/auth/keycloak";
+import { logger } from "#core/logging/logger";
+
+export interface KeycloakPrincipal {
+	userId: string;
+	orgId: string | null;
+	roles: string[];
+	kind: "user" | "service";
+	claims: KeycloakClaims;
+}
+
+export interface KeycloakTokensOptions {
+	/** Record the token's organization as a better-auth organization + membership. */
+	organizations?: boolean;
+}
+
+type Adapter = Parameters<NonNullable<BetterAuthPlugin["init"]>>[0]["adapter"];
+
+const ACCOUNT_PROVIDER = "keycloak";
+
+async function ensureUser(adapter: Adapter, claims: KeycloakClaims): Promise<boolean> {
+	// an unverified email could claim someone else's address, so it is never stored
+	const verified = claims.email_verified === true && Boolean(claims.email);
+	const email = verified
+		? (claims.email as string).toLowerCase()
+		: `${claims.sub}@users.keycloak.invalid`;
+	const name = claims.name ?? claims.preferred_username ?? claims.sub;
+	const owner = await adapter.findOne<{ id: string }>({
+		model: "user",
+		where: [{ field: "email", value: email }],
+	});
+	const existing = await adapter.findOne<{ id: string }>({
+		model: "user",
+		where: [{ field: "id", value: claims.sub }],
+	});
+	if (existing) {
+		const emailFree = !owner || owner.id === claims.sub;
+		if (!emailFree) logger.warn({ sub: claims.sub }, "keycloak email belongs to another account");
+		await adapter.update({
+			model: "user",
+			where: [{ field: "id", value: claims.sub }],
+			update: {
+				name,
+				...(emailFree ? { email, emailVerified: verified } : {}),
+				updatedAt: new Date(),
+			},
+		});
+		return true;
+	}
+	if (owner) {
+		// never attach a Keycloak identity to an account that signs in another way
+		logger.warn({ sub: claims.sub }, "keycloak token email belongs to another account");
+		return false;
+	}
+	const now = new Date();
+	await adapter.create({
+		model: "user",
+		data: { id: claims.sub, email, emailVerified: verified, name, createdAt: now, updatedAt: now },
+		forceAllowId: true,
+	});
+	await adapter.create({
+		model: "account",
+		data: {
+			userId: claims.sub,
+			accountId: claims.sub,
+			providerId: ACCOUNT_PROVIDER,
+			createdAt: now,
+			updatedAt: now,
+		},
+	});
+	return true;
+}
+
+async function ensureMembership(adapter: Adapter, orgId: string, userId: string): Promise<void> {
+	const org = await adapter.findOne({
+		model: "organization",
+		where: [{ field: "id", value: orgId }],
+	});
+	if (!org) {
+		await adapter.create({
+			model: "organization",
+			data: { id: orgId, name: orgId, slug: orgId, createdAt: new Date() },
+			forceAllowId: true,
+		});
+	}
+	const member = await adapter.findOne({
+		model: "member",
+		where: [
+			{ field: "organizationId", value: orgId },
+			{ field: "userId", value: userId },
+		],
+	});
+	if (!member) {
+		await adapter.create({
+			model: "member",
+			data: { organizationId: orgId, userId, role: "member", createdAt: new Date() },
+		});
+	}
+}
+
+/**
+ * Lets the API accept access tokens issued by Keycloak (a resource server).
+ * Verified tokens become principals; their users and organizations are kept in better-auth's tables.
+ */
+export function keycloakTokens(options: KeycloakTokensOptions = {}) {
+	// subjects already synced by this process; tokens are re-verified on every request regardless
+	const synced = new Set<string>();
+	return {
+		id: "keycloak-tokens",
+		endpoints: {
+			// no path: callable only on the server as auth.api.verifyKeycloakToken
+			verifyKeycloakToken: createAuthEndpoint(
+				{ method: "POST", body: z.object({ token: z.string() }) },
+				async (ctx): Promise<KeycloakPrincipal | null> => {
+					let claims: KeycloakClaims;
+					try {
+						claims = await verifyAccessToken(ctx.body.token);
+					} catch (error) {
+						logger.debug({ err: error }, "rejected keycloak token");
+						return null;
+					}
+					const isService = claims.preferred_username?.startsWith("service-account-") ?? false;
+					const orgId = organizationOf(claims);
+					if (!isService) {
+						const key = `${claims.sub}|${orgId ?? ""}|${claims.email ?? ""}`;
+						if (!synced.has(key)) {
+							const { adapter } = ctx.context;
+							if (!(await ensureUser(adapter, claims))) return null;
+							if (orgId && options.organizations)
+								await ensureMembership(adapter, orgId, claims.sub);
+							if (synced.size > 10_000) synced.clear();
+							synced.add(key);
+						}
+					}
+					return {
+						userId: claims.sub,
+						orgId,
+						roles: rolesOf(claims),
+						kind: isService ? "service" : "user",
+						claims,
+					};
+				},
+			),
+		},
+	} satisfies BetterAuthPlugin;
+}

package/templates/features/auth-keycloak/files/src/core/auth/tests/keycloak-tokens.test.ts

@@ -0,0 +1,109 @@
+import { generateKeyPair, SignJWT } from "jose";
+import { beforeEach, describe, expect, it } from "vitest";
+import { auth } from "#core/auth/auth";
+import { issuer } from "#core/auth/keycloak";
+import { env } from "#core/config/env";
+import { newId } from "#core/db/id";
+import { api } from "#tests/helpers/api";
+import { createTestUser, keycloakToken } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+interface Me {
+	data: { userId: string; orgId: string | null; roles: string[]; kind: string };
+}
+
+const bearer = (token: string) => ({ authorization: `Bearer ${token}` });
+const me = (token: string) => api.get<Me>("/api/me", { headers: bearer(token) });
+
+// read through better-auth's adapter so the tests work with any ORM
+async function find<T>(model: string, where: Record<string, string>): Promise<T | null> {
+	const { adapter } = await auth.$context;
+	return adapter.findOne<T>({
+		model,
+		where: Object.entries(where).map(([field, value]) => ({ field, value })),
+	});
+}
+type UserRow = { email: string; emailVerified: boolean };
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("Keycloak access tokens", () => {
+	it("authenticates a valid token as the token's subject", async () => {
+		const sub = newId();
+		const res = await me(await keycloakToken({ sub, roles: ["teacher"] }));
+		expect(res.status).toBe(200);
+		expect(res.body.data).toMatchObject({ userId: sub, kind: "user", orgId: null });
+		expect(res.body.data.roles).toContain("teacher");
+	});
+
+	it("creates the local user and links a keycloak account on first use", async () => {
+		const sub = newId();
+		await me(await keycloakToken({ sub, email: "kc@example.com" }));
+		const user = await find<UserRow>("user", { id: sub });
+		expect(user?.email).toBe("kc@example.com");
+		const account = await find<{ accountId: string }>("account", {
+			userId: sub,
+			providerId: "keycloak",
+		});
+		expect(account?.accountId).toBe(sub);
+	});
+
+	it.each([
+		["an expired token", { expiresIn: Math.floor(Date.now() / 1000) - 60 }],
+		["a token from another issuer", { issuer: "https://evil.example.com/realms/app" }],
+		["a token for another audience", { audience: "someone-else" }],
+	])("rejects %s", async (_label, options) => {
+		expect((await me(await keycloakToken(options))).status).toBe(401);
+	});
+
+	it("rejects a token signed with an unknown key", async () => {
+		const { privateKey } = await generateKeyPair("RS256");
+		const forged = await new SignJWT({ roles: ["admin"] })
+			.setProtectedHeader({ alg: "RS256", kid: "test" })
+			.setSubject(newId())
+			.setIssuer(issuer)
+			.setAudience(env.KEYCLOAK_AUDIENCE)
+			.setExpirationTime("5m")
+			.sign(privateKey);
+		expect((await me(forged)).status).toBe(401);
+	});
+
+	it("rejects a bearer value that is not a token", async () => {
+		expect((await me("not-a-token")).status).toBe(401);
+	});
+
+	it("treats service-account tokens as services without a user row", async () => {
+		const sub = newId();
+		const res = await me(await keycloakToken({ sub, username: "service-account-billing" }));
+		expect(res.body.data).toMatchObject({ userId: sub, kind: "service" });
+		expect(await find<UserRow>("user", { id: sub })).toBeNull();
+	});
+
+
+	it("rejects a token whose email belongs to another account", async () => {
+		await createTestUser({ email: "taken@example.com" });
+		const sub = newId();
+		expect((await me(await keycloakToken({ sub, email: "taken@example.com" }))).status).toBe(401);
+		expect(await find<UserRow>("user", { id: sub })).toBeNull();
+	});
+
+
+	it("does not store an email Keycloak has not verified", async () => {
+		const sub = newId();
+		await me(await keycloakToken({ sub, email: "victim@example.com", emailVerified: false }));
+		const user = await find<UserRow>("user", { id: sub });
+		expect(user?.email).not.toBe("victim@example.com");
+		expect(user?.emailVerified).toBe(false);
+	});
+
+	it("keeps the old email when the token's new email belongs to another account", async () => {
+		await createTestUser({ email: "taken@example.com" });
+		const sub = newId();
+		await me(await keycloakToken({ sub, email: "first@example.com" }));
+		const res = await me(await keycloakToken({ sub, email: "taken@example.com" }));
+		expect(res.status).toBe(200);
+		expect((await find<UserRow>("user", { id: sub }))?.email).toBe("first@example.com");
+	});
+});

package/templates/features/auth-keycloak/files+auth-orgs/src/core/auth/tests/keycloak-organizations.test.ts

@@ -0,0 +1,36 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { auth } from "#core/auth/auth";
+import { newId } from "#core/db/id";
+import { api } from "#tests/helpers/api";
+import { keycloakToken } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+interface Me {
+	data: { orgId: string | null };
+}
+
+const me = (token: string) =>
+	api.get<Me>("/api/me", { headers: { authorization: `Bearer ${token}` } });
+
+// read through better-auth's adapter so the tests work with any ORM
+async function find<T>(model: string, where: Record<string, string>): Promise<T | null> {
+	const { adapter } = await auth.$context;
+	return adapter.findOne<T>({
+		model,
+		where: Object.entries(where).map(([field, value]) => ({ field, value })),
+	});
+}
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("Keycloak access tokens with organizations", () => {
+	it("takes the organization from the token and records the membership", async () => {
+		const sub = newId();
+		const res = await me(await keycloakToken({ sub, organization: ["riyadh-school"] }));
+		expect(res.body.data.orgId).toBe("riyadh-school");
+		expect(await find("organization", { id: "riyadh-school" })).not.toBeNull();
+		expect(await find("member", { organizationId: "riyadh-school", userId: sub })).not.toBeNull();
+	});
+});

package/templates/features/auth-keycloak/files+authz/src/core/auth/tests/keycloak-authz.test.ts

@@ -0,0 +1,23 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { syncSystemRoles } from "#core/authz/services/sync";
+import { api } from "#tests/helpers/api";
+import { keycloakToken } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+const bearer = (token: string) => ({ authorization: `Bearer ${token}` });
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("Keycloak access tokens with authz", () => {
+	it("lets token roles match built-in authz roles", async () => {
+		await syncSystemRoles();
+		const admin = await keycloakToken({ roles: ["admin"] });
+		const user = await keycloakToken({ roles: ["user"] });
+		expect((await api.get("/api/authorization/roles", { headers: bearer(admin) })).status).toBe(
+			200,
+		);
+		expect((await api.get("/api/authorization/roles", { headers: bearer(user) })).status).toBe(403);
+	});
+});

package/templates/features/base/files/README.md

@@ -1,6 +1,6 @@
 # __APP_NAME__
 
-A Hono API created with [tatara](https://github.com/mohammed-bageri/tatara).
+A Hono API created with [tatara](https://github.com/mohammed-bageri/tatara-cli).
 
 ## Getting started
 

package/templates/features/better-auth/files/src/core/auth/principal.ts

@@ -36,5 +36,6 @@ export const attachPrincipal = createMiddleware<AppEnv>(async (c, next) => {
 			claims: {},
 		});
 	}
+	// tatara:slot no-session
 	await next();
 });

package/templates/features/better-auth/files/tests/helpers/auth.ts

@@ -26,6 +26,7 @@ export async function createTestUser(options: AsUserOptions = {}): Promise<strin
 export async function authenticate(
 	options: AsUserOptions = {},
 ): Promise<{ userId: string; headers: Record<string, string> }> {
+	// tatara:slot authenticate
 	const userId = await createTestUser(options);
 	const ctx = await auth.$context;
 	const session = await ctx.internalAdapter.createSession(userId);
@@ -38,3 +39,4 @@ export async function asUser(options: AsUserOptions = {}): Promise<Record<string
 	// tatara:slot as-user
 	return user.headers;
 }
+// tatara:slot helpers

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

@@ -1,27 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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;
-}

package/templates/features/keycloak/files+drizzle/src/core/auth/users.ts

@@ -1,18 +0,0 @@
-import type { KeycloakClaims } from "#core/auth/keycloak";
-import { users } from "#core/auth/db/user.schema";
-import { db } from "#core/db/client";
-
-const known = new Set<string>();
-
-/** Creates the local user row for a token subject the first time it is seen. */
-export async function ensureLocalUser(claims: KeycloakClaims): Promise<void> {
-	if (known.has(claims.sub)) return;
-	const values = {
-		id: claims.sub,
-		email: claims.email ?? null,
-		name: claims.name ?? claims.preferred_username ?? null,
-	};
-	// tatara:slot upsert
-	if (known.size > 10_000) known.clear();
-	known.add(claims.sub);
-}

package/templates/features/keycloak/files+drizzle+mysql/src/core/auth/db/user.schema.ts

@@ -1,10 +0,0 @@
-import { mysqlTable, timestamp, varchar } from "drizzle-orm/mysql-core";
-
-/** Local copy of Keycloak users (id = token subject), created on first request. */
-export const users = mysqlTable("users", {
-	id: varchar({ length: 36 }).primaryKey(),
-	email: varchar({ length: 255 }),
-	name: varchar({ length: 255 }),
-	createdAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
-	updatedAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
-});

package/templates/features/keycloak/files+drizzle+postgres/src/core/auth/db/user.schema.ts

@@ -1,10 +0,0 @@
-import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
-
-/** Local copy of Keycloak users (id = token subject), created on first request. */
-export const users = pgTable("users", {
-	id: text().primaryKey(),
-	email: text(),
-	name: text(),
-	createdAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
-	updatedAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
-});

package/templates/features/keycloak/files+prisma/prisma/models/user.prisma

@@ -1,10 +0,0 @@
-/// Local copy of Keycloak users (id = token subject), created on first request.
-model User {
-  id        String   @id @db.VarChar(36)
-  email     String?  @db.VarChar(255)
-  name      String?  @db.VarChar(255)
-  createdAt DateTime @default(now()) @map("created_at")
-  updatedAt DateTime @default(now()) @updatedAt @map("updated_at")
-
-  @@map("users")
-}

package/templates/features/keycloak/files+prisma/src/core/auth/users.ts

@@ -1,13 +0,0 @@
-import type { KeycloakClaims } from "#core/auth/keycloak";
-import { db } from "#core/db/client";
-
-const known = new Set<string>();
-
-/** Creates the local user row for a token subject the first time it is seen. */
-export async function ensureLocalUser(claims: KeycloakClaims): Promise<void> {
-	if (known.has(claims.sub)) return;
-	const data = { email: claims.email ?? null, name: claims.name ?? claims.preferred_username ?? null };
-	await db.user.upsert({ where: { id: claims.sub }, create: { id: claims.sub, ...data }, update: data });
-	if (known.size > 10_000) known.clear();
-	known.add(claims.sub);
-}