@tatara/cli 0.4.0 → 0.5.0

package/dist/bin.mjs

@@ -837,7 +837,7 @@ const admin = {
 		{
 			file: "src/core/http/app.ts",
 			slot: "imports",
-			content: "import { requireRole } from \"#core/auth/middleware\";"
+			content: "import { requireRole } from \"@tatara/auth\";"
 		},
 		{
 			file: "src/core/http/app.ts",
@@ -1077,6 +1077,7 @@ const auth = {
 	id: "auth",
 	kind: "auth",
 	label: "Auth (shared)",
+	dependencies: ["@tatara/auth"],
 	slots: [
 		{
 			file: "src/core/http/app.ts",
@@ -1107,7 +1108,7 @@ const auth = {
 
 - \`c.var.principal\` is set for every request with valid credentials: \`{ userId, orgId, roles, kind }\`.
 - Protect routes with \`middleware: [requireAuth()]\` or \`requireRole("admin")\` from
-  \`#core/auth/middleware\`, and declare \`security: [{ bearerAuth: [] }]\` so the route is
+  \`@tatara/auth\`, and declare \`security: [{ bearerAuth: [] }]\` so the route is
   documented as protected. Read the caller with \`currentPrincipal(c)\`.
 - In tests, \`asUser()\` from \`#tests/helpers/auth\` returns headers for a fresh authenticated user.
 `
@@ -1121,7 +1122,7 @@ const BETTER_AUTH_AGENTS = `### better-auth
 - Sessions work as cookies (browsers) and as \`Authorization: Bearer <session token>\` (mobile, APIs).
 - Outside production, every email and SMS is kept in an in-memory outbox:
   \`GET /api/dev/outbox?to=<address>\` returns the latest messages, including sign-in codes.
-- To send real SMS, implement \`SmsSender\` in \`src/core/auth/sms.ts\`.
+- To send real SMS, implement \`SmsSender\` (from \`@tatara/auth\`) in \`src/core/auth/sms.ts\`.
 `;
 const drizzlePg = ["drizzle", "postgres"];
 const drizzleMy = ["drizzle", "mysql"];
@@ -1161,12 +1162,12 @@ const betterAuth = {
 		{
 			file: "src/core/http/app.ts",
 			slot: "imports",
-			content: "import { outboxEnabled, readOutbox } from \"#core/auth/delivery\";"
+			content: "import { outbox } from \"#core/auth/delivery\";"
 		},
 		{
 			file: "src/core/http/app.ts",
 			slot: "imports",
-			content: "import { mergeAuthOpenApi } from \"#core/auth/openapi\";"
+			content: "import { mergeAuthOpenApi } from \"@tatara/auth\";"
 		},
 		{
 			file: "src/core/http/app.ts",
@@ -1178,7 +1179,7 @@ const betterAuth = {
 			slot: "openapi-options",
 			content: [
 				"async extend(document) {",
-				"	if (name === \"api\") await mergeAuthOpenApi(document, `${API_PREFIX}/auth`);",
+				"	if (name === \"api\") await mergeAuthOpenApi(document, auth, `${API_PREFIX}/auth`);",
 				"},"
 			].join("\n")
 		},
@@ -1189,8 +1190,8 @@ const betterAuth = {
 			content: [
 				"if (name === \"api\") {",
 				"	app.on([\"GET\", \"POST\"], `${API_PREFIX}/auth/*`, (c) => auth.handler(c.req.raw));",
-				"	if (outboxEnabled()) {",
-				"		app.get(`${API_PREFIX}/dev/outbox`, (c) => c.json({ messages: readOutbox(c.req.query(\"to\")) }));",
+				"	if (outbox.enabled) {",
+				"		app.get(`${API_PREFIX}/dev/outbox`, (c) => c.json({ messages: outbox.read(c.req.query(\"to\")) }));",
 				"	}",
 				"}"
 			].join("\n")
@@ -1468,64 +1469,11 @@ const authOrgs = {
 		...adminFields
 	]
 };
-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"],
+	dependencies: ["@tatara/keycloak", "jose"],
 	env: [
 		{
 			key: "KEYCLOAK_PORT",
@@ -1574,53 +1522,56 @@ const authKeycloak = {
 		{
 			file: "src/core/auth/auth.ts",
 			slot: "imports",
-			content: "import { keycloakTokens } from \"#core/auth/keycloak-plugin\";"
+			content: "import { keycloakTokens } from \"@tatara/keycloak\";"
+		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "imports",
+			content: "import { keycloak } from \"#core/auth/keycloak\";"
+		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "imports",
+			content: "import { logger } from \"#core/logging/logger\";"
 		},
 		{
 			file: "src/core/auth/auth.ts",
 			slot: "plugins",
 			unless: ["auth-orgs"],
-			content: "keycloakTokens(),",
+			content: "keycloakTokens({ verifier: keycloak, logger }),",
 			order: 800
 		},
 		{
 			file: "src/core/auth/auth.ts",
 			slot: "plugins",
 			when: ["auth-orgs"],
-			content: "keycloakTokens({ organizations: true }),",
+			content: "keycloakTokens({ verifier: keycloak, logger, 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")
+			slot: "resolvers",
+			content: "(c) => keycloakPrincipal(auth, c.req.header(\"authorization\")),"
 		},
 		{
-			file: "tests/helpers/auth.ts",
+			file: "src/core/auth/principal.ts",
 			slot: "imports",
-			content: "import { generateKeyPair, SignJWT } from \"jose\";"
+			content: "import { keycloakPrincipal } from \"@tatara/keycloak\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "imports",
-			content: "import { issuer, setKeySource } from \"#core/auth/keycloak\";"
+			content: "import { useTestKeys } from \"@tatara/keycloak/testing\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "imports",
-			content: "import { env } from \"#core/config/env\";"
+			content: "import { keycloak } from \"#core/auth/keycloak\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "helpers",
-			content: KEYCLOAK_TEST_HELPER
+			content: ["/** Signs an access token the API accepts, as if Keycloak issued it. */", "export const keycloakToken = await useTestKeys(keycloak);"].join("\n")
 		},
 		{
 			file: "tests/helpers/auth.ts",
@@ -1628,7 +1579,7 @@ const authKeycloak = {
 			unless: ["auth-orgs"],
 			content: [
 				"if (options.roles) {",
-				"	const sub = newId();",
+				"	const sub = crypto.randomUUID();",
 				"	const token = await keycloakToken({ sub, roles: options.roles, email: options.email });",
 				"	return { userId: sub, headers: { authorization: `Bearer ${token}` } };",
 				"}"
@@ -1637,7 +1588,21 @@ const authKeycloak = {
 		{
 			file: "AGENTS.md",
 			slot: "sections",
-			content: KEYCLOAK_AGENTS
+			content: `### Keycloak
+
+- The API also accepts Keycloak access tokens (\`Authorization: Bearer <token>\`). The
+  \`keycloakTokens()\` better-auth plugin (\`@tatara/keycloak\`) 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\`.
+`
 		}
 	]
 };
@@ -2491,7 +2456,7 @@ function guardSlots(project, n) {
 		for (const [route, action] of Object.entries(ACTIONS)) add(`guard-${route}`, `middleware: [requirePermission("${n.kebab}:${action}")] as const,\nsecurity: [{ bearerAuth: ["${n.kebab}:${action}"] }],`);
 		add("auth-errors", "...errorResponses(401, 403),");
 	} else if (project.has("auth")) {
-		add("imports", "import { requireAuth } from \"#core/auth/middleware\";");
+		add("imports", "import { requireAuth } from \"@tatara/auth\";");
 		for (const route of Object.keys(ACTIONS)) add(`guard-${route}`, "middleware: [requireAuth()] as const,\nsecurity: [{ bearerAuth: [] }],");
 		add("auth-errors", "...errorResponses(401),");
 	}
@@ -3221,6 +3186,147 @@ function createBaseline(project, deps) {
 	} };
 }
 //#endregion
+//#region src/upgrade/codemods/auth-package.ts
+const AUTH = "@tatara/auth";
+const KEYCLOAK = "@tatara/keycloak";
+const APP$1 = "src/core/http/app.ts";
+const HELPERS = "tests/helpers/auth.ts";
+function groups(keycloak) {
+	const all = [
+		{
+			name: "OpenAPI merge and dev outbox",
+			regenerate: [APP$1, "src/core/auth/delivery.ts"],
+			remove: ["src/core/auth/openapi.ts"],
+			exports: [{ specifier: "#core/auth/openapi" }, {
+				specifier: "#core/auth/delivery",
+				names: [
+					"outboxEnabled",
+					"readOutbox",
+					"OutboxMessage"
+				]
+			}]
+		},
+		{
+			name: "SMS sender",
+			regenerate: ["src/core/auth/sms.ts"],
+			remove: [],
+			exports: [{
+				specifier: "#core/auth/sms",
+				names: ["SmsSender"]
+			}]
+		},
+		{
+			name: "principal middleware",
+			regenerate: ["src/core/auth/principal.ts"],
+			remove: [],
+			exports: []
+		}
+	];
+	if (!keycloak) {
+		all.push({
+			name: "test helpers",
+			regenerate: [HELPERS],
+			remove: [],
+			exports: []
+		});
+		return all;
+	}
+	all.push({
+		name: "Keycloak",
+		regenerate: [
+			"src/core/auth/auth.ts",
+			"src/core/auth/keycloak.ts",
+			"src/core/auth/commands/keycloak-token.ts",
+			"src/core/auth/tests/keycloak-tokens.test.ts",
+			HELPERS
+		],
+		remove: ["src/core/auth/keycloak-plugin.ts"],
+		exports: [
+			{ specifier: "#core/auth/keycloak-plugin" },
+			{
+				specifier: "#core/auth/keycloak",
+				names: [
+					"issuer",
+					"setKeySource",
+					"verifyAccessToken",
+					"rolesOf",
+					"organizationOf",
+					"KeycloakClaims"
+				]
+			},
+			{
+				specifier: "#tests/helpers/auth",
+				names: ["KeycloakTokenOptions"]
+			}
+		]
+	});
+	return all;
+}
+async function read$2(ctx, path) {
+	return ctx.read(path).catch(() => void 0);
+}
+const escapeRegExp$1 = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** True when `text` imports `entry` (or one of its gone names). */
+function usesExport(text, entry) {
+	const from = new RegExp(`import\\s+(?:type\\s+)?([^;]*?)\\s+from\\s+["']${escapeRegExp$1(entry.specifier)}["']`, "g");
+	const gone = entry.names;
+	for (const match of text.matchAll(from)) {
+		if (!gone) return true;
+		const braces = (match[1] ?? "").match(/\{([^}]*)\}/);
+		if (!braces) return true;
+		if ((braces[1] ?? "").split(",").map((part) => part.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim()).some((name) => name && gone.includes(name))) return true;
+	}
+	return false;
+}
+/** Why the group can't move, or [] when it can. */
+async function blockersOf(ctx, group, sources) {
+	const blockers = [];
+	for (const path of [...group.regenerate, ...group.remove]) {
+		const text = await read$2(ctx, path);
+		if (text === void 0) continue;
+		if (!await ctx.baseline.isUnchanged(path, text)) blockers.push(`${path} is customised`);
+	}
+	const own = /* @__PURE__ */ new Set([...group.regenerate, ...group.remove]);
+	for (const path of sources) {
+		if (own.has(path)) continue;
+		const text = await ctx.read(path);
+		if (group.exports.some((entry) => usesExport(text, entry))) blockers.push(`${path} imports what moves`);
+	}
+	return blockers;
+}
+const authPackage = {
+	version: "0.5.0",
+	id: "auth-package",
+	description: "Use @tatara/auth (guards, principal, OpenAPI merge, outbox) and @tatara/keycloak",
+	async run(ctx) {
+		const { config } = ctx.project;
+		if (config.auth === "none") return;
+		const keycloak = config.authMethods.includes("keycloak");
+		await ctx.addDependency(AUTH, versionOf(AUTH));
+		if (keycloak) await ctx.addDependency(KEYCLOAK, versionOf(KEYCLOAK));
+		const sources = await glob(["src/**/*.ts", "tests/**/*.ts"], {
+			cwd: ctx.project.root,
+			ignore: ["src/generated/**"]
+		});
+		const ready = [];
+		for (const group of groups(keycloak)) {
+			const blockers = await blockersOf(ctx, group, sources);
+			if (blockers.length === 0) ready.push(group);
+			else ctx.report.notes.push(`${group.name} was not moved onto ${group.name === "Keycloak" ? KEYCLOAK : AUTH}: ${blockers.join("; ")}. Compare these files with a newly generated app and move them by hand.`);
+		}
+		for (const group of ready) {
+			for (const path of group.regenerate) {
+				if (await read$2(ctx, path) === void 0) continue;
+				const next = await ctx.renderCurrent(path);
+				if (next !== void 0) await ctx.write(path, next);
+			}
+			for (const path of group.remove) await ctx.removeIfUnchanged(path);
+		}
+		if (await ctx.removeIfUnchanged("src/core/auth/middleware.ts") === "kept") ctx.report.notes.push("src/core/auth/middleware.ts is customised; its imports still point at it.");
+		else await ctx.rewriteImports("#core/auth/middleware", AUTH);
+	}
+};
+//#endregion
 //#region src/upgrade/codemods/core-package.ts
 const CORE = "@tatara/core";
 /** Files @tatara/core replaces, with the import specifier apps used for each. */
@@ -3494,7 +3600,8 @@ const CODEMODS = [
 			]) await ctx.rewriteImports(specifier, HTTP);
 		}
 	},
-	dbTesting
+	dbTesting,
+	authPackage
 ];
 //#endregion
 //#region src/upgrade/context.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tatara/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Create and grow opinionated Hono backends",
   "type": "module",
   "license": "MIT",

package/templates/features/admin/files/src/modules/example/routes/admin-greeting.routes.ts

@@ -1,5 +1,5 @@
 import { createRoute } from "@hono/zod-openapi";
-import { currentPrincipal } from "#core/auth/middleware";
+import { currentPrincipal } from "@tatara/auth";
 import { errorResponses, jsonContent, success, successSchema } from "@tatara/http";
 import { createRouter, defineRoutes } from "#core/http/routes";
 import { greetingSchema } from "#modules/example/validators/greeting.validators";

package/templates/features/auth/files/src/core/auth/routes/me.routes.ts

@@ -1,5 +1,5 @@
 import { createRoute, z } from "@hono/zod-openapi";
-import { currentPrincipal, requireAuth } from "#core/auth/middleware";
+import { currentPrincipal, requireAuth } from "@tatara/auth";
 import { errorResponses, jsonContent, success, successSchema } from "@tatara/http";
 import { createRouter, defineRoutes } from "#core/http/routes";
 

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { issuer } from "#core/auth/keycloak";
+import { keycloak } from "#core/auth/keycloak";
 import { defineCommand } from "@tatara/core";
 import { env } from "#core/config/env";
 
@@ -13,7 +13,7 @@ export default defineCommand({
 	}),
 	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`, {
+		const res = await fetch(`${keycloak.issuer}/protocol/openid-connect/token`, {
 			method: "POST",
 			headers: { "content-type": "application/x-www-form-urlencoded" },
 			body: new URLSearchParams({

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

@@ -1,58 +1,9 @@
-import { createRemoteJWKSet, type JWTPayload, type JWTVerifyGetKey, jwtVerify } from "jose";
+import { keycloakVerifier } from "@tatara/keycloak";
 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;
-}
+/** Verifies access tokens from the realm; `keycloakTokens()` in auth.ts uses it. */
+export const keycloak = keycloakVerifier({
+	url: env.KEYCLOAK_URL,
+	realm: env.KEYCLOAK_REALM,
+	audience: env.KEYCLOAK_AUDIENCE,
+});

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

@@ -1,7 +1,7 @@
 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 { keycloak } from "#core/auth/keycloak";
 import { env } from "#core/config/env";
 import { newId } from "@tatara/db";
 import { api } from "#tests/helpers/api";
@@ -63,7 +63,7 @@ describe("Keycloak access tokens", () => {
 		const forged = await new SignJWT({ roles: ["admin"] })
 			.setProtectedHeader({ alg: "RS256", kid: "test" })
 			.setSubject(newId())
-			.setIssuer(issuer)
+			.setIssuer(keycloak.issuer)
 			.setAudience(env.KEYCLOAK_AUDIENCE)
 			.setExpirationTime("5m")
 			.sign(privateKey);

package/templates/features/authz/files/src/core/authz/routes/authorization.routes.ts

@@ -1,5 +1,5 @@
 import { createRoute, z } from "@hono/zod-openapi";
-import { currentPrincipal, requireAuth } from "#core/auth/middleware";
+import { currentPrincipal, requireAuth } from "@tatara/auth";
 import { requirePermission } from "#core/authz/middleware";
 import { effectivePermissions, orgOf } from "#core/authz/resolver";
 import { listAudit } from "#core/authz/services/audit";

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

@@ -1,36 +1,12 @@
+import { createOutbox } from "@tatara/auth";
 import { smsSender } from "#core/auth/sms";
 import { env } from "#core/config/env";
 // tatara:slot imports
 
-export interface OutboxMessage {
-	channel: "email" | "sms";
-	to: string;
-	subject?: string;
-	text: string;
-	/** one-time code, when the message carries one */
-	code?: string;
-	sentAt: string;
-}
-
-const outbox: OutboxMessage[] = [];
-
 /** Only with DEV_OUTBOX=true in development or test: the outbox exposes sign-in codes. */
-export function outboxEnabled(): boolean {
-	return env.DEV_OUTBOX && (env.NODE_ENV === "development" || env.NODE_ENV === "test");
-}
-
-/** Messages are kept here so tests and local sign-in can read codes. */
-function record(message: Omit<OutboxMessage, "sentAt">) {
-	if (!outboxEnabled()) return;
-	outbox.push({ ...message, sentAt: new Date().toISOString() });
-	if (outbox.length > 200) outbox.shift();
-}
-
-/** Newest first. Empty unless the outbox is enabled. */
-export function readOutbox(to?: string): OutboxMessage[] {
-	if (!outboxEnabled()) return [];
-	return outbox.filter((m) => !to || m.to === to).reverse();
-}
+export const outbox = createOutbox({
+	enabled: env.DEV_OUTBOX && (env.NODE_ENV === "development" || env.NODE_ENV === "test"),
+});
 
 export async function deliverEmail(message: {
 	to: string;
@@ -38,11 +14,11 @@ export async function deliverEmail(message: {
 	text: string;
 	code?: string;
 }): Promise<void> {
-	record({ channel: "email", ...message });
+	outbox.record({ channel: "email", ...message });
 	// tatara:slot email-delivery
 }
 
 export async function deliverSms(message: { to: string; text: string; code?: string }): Promise<void> {
-	record({ channel: "sms", ...message });
+	outbox.record({ channel: "sms", ...message });
 	await smsSender.send(message.to, message.text);
 }

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

@@ -1,41 +1,10 @@
-import { createMiddleware } from "hono/factory";
+import { principalMiddleware, sessionPrincipal } from "@tatara/auth";
 import { auth } from "#core/auth/auth";
 import type { AppEnv } from "#core/http/context";
+// tatara:slot imports
 
-/**
- * The session's active organization, or null once the user stops being a member of it.
- * better-auth leaves `activeOrganizationId` on the removed member's session.
- */
-async function activeMembership(userId: string, orgId: string | null | undefined) {
-	if (!orgId) return null;
-	const { adapter } = await auth.$context;
-	const member = await adapter.findOne({
-		model: "member",
-		where: [
-			{ field: "organizationId", value: orgId },
-			{ field: "userId", value: userId },
-		],
-	});
-	return member ? orgId : null;
-}
-
-/** Resolves the session (cookie or bearer token) into `c.var.principal`. */
-export const attachPrincipal = createMiddleware<AppEnv>(async (c, next) => {
-	const session = await auth.api.getSession({ headers: c.req.raw.headers });
-	if (session) {
-		const user = session.user as typeof session.user & { role?: string | null };
-		const s = session.session as typeof session.session & { activeOrganizationId?: string | null };
-		c.set("principal", {
-			userId: user.id,
-			orgId: await activeMembership(user.id, s.activeOrganizationId),
-			roles: (user.role ?? "user")
-				.split(",")
-				.map((role) => role.trim())
-				.filter(Boolean),
-			kind: "user",
-			claims: {},
-		});
-	}
-	// tatara:slot no-session
-	await next();
-});
+/** Sets `c.var.principal` from the first resolver that recognises the request's credentials. */
+export const attachPrincipal = principalMiddleware<AppEnv>([
+	(c) => sessionPrincipal(auth, c.req.raw.headers),
+	// tatara:slot resolvers
+]);

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

@@ -1,14 +1,5 @@
+import { consoleSmsSender, type SmsSender } from "@tatara/auth";
 import { logger } from "#core/logging/logger";
 
-/** Implement this for your SMS provider and return it from `smsSender`. */
-export interface SmsSender {
-	send(to: string, text: string): Promise<void>;
-}
-
-const consoleSender: SmsSender = {
-	async send(to) {
-		logger.info({ to }, "sms not sent: no SMS provider configured (see src/core/auth/sms.ts)");
-	},
-};
-
-export const smsSender: SmsSender = consoleSender;
+/** Logs instead of sending. Replace with an SmsSender for your provider. */
+export const smsSender: SmsSender = consoleSmsSender(logger);

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

@@ -1,5 +1,5 @@
+import { createTestUser as createUser, sessionHeaders } from "@tatara/auth/testing";
 import { auth } from "#core/auth/auth";
-import { newId } from "@tatara/db";
 // tatara:slot imports
 
 export interface AsUserOptions {
@@ -12,14 +12,13 @@ export interface AsUserOptions {
 
 /** Creates a verified user and returns their id. */
 export async function createTestUser(options: AsUserOptions = {}): Promise<string> {
-	const ctx = await auth.$context;
-	const user = await ctx.internalAdapter.createUser({
-		email: options.email ?? `user-${newId()}@example.com`,
-		name: options.name ?? "Test User",
-		emailVerified: true,
-		// tatara:slot user-fields
-	}, { method: "admin" });
-	return user.id;
+	return createUser(auth, {
+		email: options.email,
+		name: options.name,
+		fields: {
+			// tatara:slot user-fields
+		},
+	});
 }
 
 /** A new user with a real session; the token is sent as a bearer token. */
@@ -28,9 +27,7 @@ export async function authenticate(
 ): 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);
-	return { userId, headers: { authorization: `Bearer ${session.token}` } };
+	return { userId, headers: await sessionHeaders(auth, userId) };
 }
 
 /** Headers that authenticate as a new user. */

package/templates/versions.json

@@ -34,5 +34,7 @@
   "@tatara/core": "0.1.0",
   "@tatara/http": "0.1.0",
   "@tatara/db": "0.1.0",
-  "@tatara/testing": "0.1.0"
+  "@tatara/testing": "0.1.0",
+  "@tatara/auth": "0.1.0",
+  "@tatara/keycloak": "0.1.0"
 }

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

@@ -1,29 +0,0 @@
-import { createMiddleware } from "hono/factory";
-import type { Context } from "hono";
-import type { AppEnv, Principal } from "#core/http/context";
-import { ForbiddenError, UnauthorizedError } from "@tatara/http";
-
-/** 401 unless the request carries a valid session or token. */
-export function requireAuth() {
-	return createMiddleware<AppEnv>(async (c, next) => {
-		if (!c.get("principal")) throw new UnauthorizedError();
-		await next();
-	});
-}
-
-/** 401 without a principal, 403 unless it has at least one of the roles. */
-export function requireRole(...roles: string[]) {
-	return createMiddleware<AppEnv>(async (c, next) => {
-		const principal = c.get("principal");
-		if (!principal) throw new UnauthorizedError();
-		if (!principal.roles.some((role) => roles.includes(role))) throw new ForbiddenError();
-		await next();
-	});
-}
-
-/** The authenticated principal; use in handlers behind requireAuth(). */
-export function currentPrincipal(c: Context<AppEnv>): Principal {
-	const principal = c.get("principal");
-	if (!principal) throw new UnauthorizedError();
-	return principal;
-}

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

@@ -1,154 +0,0 @@
-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/better-auth/files/src/core/auth/openapi.ts

@@ -1,60 +0,0 @@
-import type { OpenAPIHono } from "@hono/zod-openapi";
-import { auth } from "#core/auth/auth";
-
-type JsonObject = Record<string, unknown>;
-type OpenApiDocument = ReturnType<OpenAPIHono["getOpenAPI31Document"]>;
-type Paths = NonNullable<OpenApiDocument["paths"]>;
-type Components = NonNullable<OpenApiDocument["components"]>;
-
-interface AuthDocument {
-	paths?: Record<string, JsonObject>;
-	components?: { schemas?: JsonObject; securitySchemes?: JsonObject };
-}
-
-const SCHEMA_REF = "#/components/schemas/";
-
-// better-auth names schemas like the app (User, Member, …); prefix them so neither side is overwritten
-function renameRefs(value: unknown, rename: (name: string) => string): AuthDocument {
-	return JSON.parse(
-		JSON.stringify(value).replaceAll(
-			new RegExp(`"\\$ref":"${SCHEMA_REF}([^"]+)"`, "g"),
-			(_match, name: string) => `"$ref":"${SCHEMA_REF}${rename(name)}"`,
-		),
-	) as AuthDocument;
-}
-
-function retag(paths: Record<string, JsonObject>, tag: string): Record<string, JsonObject> {
-	for (const operations of Object.values(paths)) {
-		for (const operation of Object.values(operations as Record<string, JsonObject>)) {
-			if (operation && typeof operation === "object") operation.tags = [tag];
-		}
-	}
-	return paths;
-}
-
-/** Adds better-auth's endpoints (served under `basePath`) to the app's OpenAPI document. */
-export async function mergeAuthOpenApi(document: OpenApiDocument, basePath: string): Promise<void> {
-	const authDoc = renameRefs(await auth.api.generateOpenAPISchema(), (name) => `Auth${name}`);
-
-	document.paths ??= {};
-	for (const [path, operations] of Object.entries(retag(authDoc.paths ?? {}, "Auth"))) {
-		document.paths[`${basePath}${path}`] = operations as Paths[string];
-	}
-
-	document.components ??= {};
-	document.components.schemas ??= {};
-	for (const [name, schema] of Object.entries(authDoc.components?.schemas ?? {})) {
-		document.components.schemas[`Auth${name}`] = schema as NonNullable<
-			Components["schemas"]
-		>[string];
-	}
-	document.components.securitySchemes = {
-		...(authDoc.components?.securitySchemes as Components["securitySchemes"]),
-		...document.components.securitySchemes,
-	};
-
-	document.tags = [
-		...(document.tags ?? []),
-		{ name: "Auth", description: "Sign-up, sign-in, sessions, organizations (better-auth)" },
-	];
-}