@tatara/cli 0.4.0 → 0.6.0

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/auth-keycloak/files+authz/src/core/auth/tests/keycloak-authz.test.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it } from "vitest";
-import { syncSystemRoles } from "#core/authz/services/sync";
+import { authz } from "#core/authz/index";
 import { api } from "#tests/helpers/api";
 import { keycloakToken } from "#tests/helpers/auth";
 import { resetDatabase } from "#tests/helpers/db";
@@ -12,7 +12,7 @@ beforeEach(async () => {
 
 describe("Keycloak access tokens with authz", () => {
 	it("lets token roles match built-in authz roles", async () => {
-		await syncSystemRoles();
+		await authz.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(

package/templates/features/authz/files/src/core/authz/commands/grant-role.ts

@@ -1,7 +1,6 @@
 import { z } from "zod";
-import { DEFAULT_ORG_ID, SYSTEM_ORG_ID } from "#core/authz/constants";
-import { store } from "#core/authz/db/store";
-import { assignRole } from "#core/authz/services/members";
+import { DEFAULT_ORG_ID, SYSTEM_ORG_ID } from "@tatara/authz";
+import { authz } from "#core/authz/index";
 import { defineCommand } from "@tatara/core";
 
 export default defineCommand({
@@ -13,9 +12,10 @@ export default defineCommand({
 		org: z.string().default(DEFAULT_ORG_ID),
 	}),
 	async run({ user, role, org }, { logger }) {
-		const found = (await store.findRoleByKey(org, role)) ?? (await store.findRoleByKey(SYSTEM_ORG_ID, role));
+		const found = (await authz.store.findRoleByKey(org, role)) ??
+			(await authz.store.findRoleByKey(SYSTEM_ORG_ID, role));
 		if (!found) throw new Error(`No role "${role}" (run authz:sync-permissions first for built-in roles)`);
-		const added = await assignRole(null, org, user, found.id);
+		const added = await authz.assignRole(null, org, user, found.id);
 		logger.info({ user, role, org, added }, added ? "role assigned" : "role already assigned");
 	},
 });

package/templates/features/authz/files/src/core/authz/commands/sync-permissions.ts

@@ -1,11 +1,11 @@
 import { defineCommand } from "@tatara/core";
-import { syncSystemRoles } from "#core/authz/services/sync";
+import { authz } from "#core/authz/index";
 
 export default defineCommand({
 	name: "authz:sync-permissions",
 	description: "Create/update built-in roles so their grants match the code (run on every deploy)",
 	async run(_args, { logger }) {
-		const result = await syncSystemRoles();
+		const result = await authz.syncSystemRoles();
 		logger.info(result, "built-in roles in sync");
 	},
 });

package/templates/features/authz/files/src/core/authz/db/seed.ts

@@ -1,10 +1,10 @@
-import { syncSystemRoles } from "#core/authz/services/sync";
+import { authz } from "#core/authz/index";
 import { defineSeed } from "@tatara/db";
 
 export default defineSeed({
 	name: "authz:system-roles",
 	order: -10,
 	async run({ logger }) {
-		logger.info(await syncSystemRoles(), "built-in roles in sync");
+		logger.info(await authz.syncSystemRoles(), "built-in roles in sync");
 	},
 });

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

@@ -0,0 +1,9 @@
+import { createAuthz } from "@tatara/authz";
+import { store } from "#core/authz/db/store";
+import { SYSTEM_ROLES } from "#core/authz/system-roles";
+import { catalog, type PermissionKey } from "#generated/permissions";
+
+/** The app's authorization: its store, the permission catalog from `tatara sync`, built-in roles. */
+export const authz = createAuthz<PermissionKey>({ store, catalog, systemRoles: SYSTEM_ROLES });
+
+export const { checkPermission, removeMemberAccess, requirePermission, resolveScope } = authz;

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

@@ -1,281 +1,10 @@
-import { createRoute, z } from "@hono/zod-openapi";
-import { currentPrincipal, requireAuth } from "#core/auth/middleware";
-import { requirePermission } from "#core/authz/middleware";
-import { effectivePermissions, orgOf } from "#core/authz/resolver";
-import { listAudit } from "#core/authz/services/audit";
-import { addOverlay, assignRole, getMember, removeOverlay, revokeRole } from "#core/authz/services/members";
-import { createRole, deleteRole, listRoles, updateRole } from "#core/authz/services/roles";
-import type { OverlayRow } from "#core/authz/types";
-import {
-	auditEntrySchema,
-	createRoleSchema,
-	idParams,
-	memberSchema,
-	myPermissionsSchema,
-	overlayInputSchema,
-	roleSchema,
-	updateRoleSchema,
-	userOverlayParams,
-	userParams,
-	userRoleParams,
-} from "#core/authz/validators";
-import { errorResponses, jsonBody, jsonContent, success, successSchema } from "@tatara/http";
-import { createRouter, defineRoutes } from "#core/http/routes";
-import { catalog } from "#generated/permissions";
-
-const router = createRouter();
-const tags = ["Authorization"];
-const toOverlay = (o: OverlayRow) => ({
-	id: o.id,
-	resource: o.resource,
-	action: o.action,
-	scope: o.scope,
-	effect: o.effect,
-	reason: o.reason,
-	expiresAt: o.expiresAt ? o.expiresAt.toISOString() : null,
+import { authorizationRoutes } from "@tatara/authz";
+import { authz } from "#core/authz/index";
+import type { AppEnv } from "#core/http/context";
+import { defineRoutes } from "#core/http/routes";
+
+export default defineRoutes({
+	app: "api",
+	basePath: "/authorization",
+	router: authorizationRoutes<AppEnv>(authz),
 });
-
-router.openapi(
-	createRoute({
-		method: "get",
-		path: "/catalog",
-		tags,
-		summary: "Every permission the API knows",
-		middleware: [requireAuth()] as const,
-		security: [{ bearerAuth: [] }],
-		responses: {
-			200: jsonContent(
-				successSchema(z.object({ keys: z.array(z.string()), resources: z.record(z.string(), z.unknown()) })),
-				"Permission catalog",
-			),
-			...errorResponses(401),
-		},
-	}),
-	(c) => c.json(success({ keys: catalog.keys, resources: catalog.resources }), 200),
-);
-
-router.openapi(
-	createRoute({
-		method: "get",
-		path: "/me",
-		tags,
-		summary: "The caller's effective permissions in their org",
-		middleware: [requireAuth()] as const,
-		security: [{ bearerAuth: [] }],
-		responses: { 200: jsonContent(successSchema(myPermissionsSchema), "Effective permissions"), ...errorResponses(401) },
-	}),
-	async (c) => {
-		const principal = currentPrincipal(c);
-		const permissions = await effectivePermissions(principal);
-		return c.json(
-			success({
-				orgId: orgOf(principal),
-				roles: permissions.roles,
-				grants: permissions.grants,
-				denies: [...permissions.denies],
-			}),
-			200,
-		);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "get",
-		path: "/roles",
-		tags,
-		summary: "Built-in roles and the org's custom roles",
-		middleware: [requirePermission("role:read")] as const,
-		security: [{ bearerAuth: ["role:read"] }],
-		responses: { 200: jsonContent(successSchema(z.array(roleSchema)), "Roles"), ...errorResponses(401, 403) },
-	}),
-	async (c) => c.json(success(await listRoles(orgOf(currentPrincipal(c)))), 200),
-);
-
-router.openapi(
-	createRoute({
-		method: "post",
-		path: "/roles",
-		tags,
-		summary: "Create a custom role",
-		middleware: [requirePermission("role:create")] as const,
-		security: [{ bearerAuth: ["role:create"] }],
-		request: { body: jsonBody(createRoleSchema, "The role") },
-		responses: {
-			201: jsonContent(successSchema(roleSchema), "Created"),
-			...errorResponses(400, 409),
-			...errorResponses(401, 403),
-		},
-	}),
-	async (c) => {
-		const principal = currentPrincipal(c);
-		const role = await createRole(principal.userId, orgOf(principal), c.req.valid("json"));
-		return c.json(success(role), 201);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "patch",
-		path: "/roles/{id}",
-		tags,
-		summary: "Update a custom role",
-		middleware: [requirePermission("role:update")] as const,
-		security: [{ bearerAuth: ["role:update"] }],
-		request: { params: idParams, body: jsonBody(updateRoleSchema, "Fields to change") },
-		responses: {
-			200: jsonContent(successSchema(roleSchema), "Updated"),
-			...errorResponses(400, 404),
-			...errorResponses(401, 403),
-		},
-	}),
-	async (c) => {
-		const principal = currentPrincipal(c);
-		const role = await updateRole(principal.userId, orgOf(principal), c.req.valid("param").id, c.req.valid("json"));
-		return c.json(success(role), 200);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "delete",
-		path: "/roles/{id}",
-		tags,
-		summary: "Delete a custom role that no member holds",
-		middleware: [requirePermission("role:delete")] as const,
-		security: [{ bearerAuth: ["role:delete"] }],
-		request: { params: idParams },
-		responses: { 204: { description: "Deleted" }, ...errorResponses(400, 404, 409), ...errorResponses(401, 403) },
-	}),
-	async (c) => {
-		const principal = currentPrincipal(c);
-		await deleteRole(principal.userId, orgOf(principal), c.req.valid("param").id);
-		return c.body(null, 204);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "get",
-		path: "/members/{userId}",
-		tags,
-		summary: "A member's roles and overlays",
-		middleware: [requirePermission("member:read")] as const,
-		security: [{ bearerAuth: ["member:read"] }],
-		request: { params: userParams },
-		responses: { 200: jsonContent(successSchema(memberSchema), "Member"), ...errorResponses(401, 403) },
-	}),
-	async (c) => {
-		const member = await getMember(orgOf(currentPrincipal(c)), c.req.valid("param").userId);
-		return c.json(success({ ...member, overlays: member.overlays.map(toOverlay) }), 200);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "post",
-		path: "/members/{userId}/roles",
-		tags,
-		summary: "Assign a role to a member",
-		middleware: [requirePermission("member:update")] as const,
-		security: [{ bearerAuth: ["member:update"] }],
-		request: { params: userParams, body: jsonBody(z.object({ roleId: z.string() }), "Role") },
-		responses: {
-			200: jsonContent(successSchema(z.object({ assigned: z.boolean() })), "Assigned"),
-			...errorResponses(404),
-			...errorResponses(401, 403),
-		},
-	}),
-	async (c) => {
-		const principal = currentPrincipal(c);
-		const assigned = await assignRole(
-			principal.userId,
-			orgOf(principal),
-			c.req.valid("param").userId,
-			c.req.valid("json").roleId,
-		);
-		return c.json(success({ assigned }), 200);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "delete",
-		path: "/members/{userId}/roles/{roleId}",
-		tags,
-		summary: "Revoke a role from a member",
-		middleware: [requirePermission("member:update")] as const,
-		security: [{ bearerAuth: ["member:update"] }],
-		request: { params: userRoleParams },
-		responses: { 204: { description: "Revoked" }, ...errorResponses(404), ...errorResponses(401, 403) },
-	}),
-	async (c) => {
-		const principal = currentPrincipal(c);
-		const { userId, roleId } = c.req.valid("param");
-		await revokeRole(principal.userId, orgOf(principal), userId, roleId);
-		return c.body(null, 204);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "post",
-		path: "/members/{userId}/overlays",
-		tags,
-		summary: "Grant or deny one permission to a member",
-		middleware: [requirePermission("member:update")] as const,
-		security: [{ bearerAuth: ["member:update"] }],
-		request: { params: userParams, body: jsonBody(overlayInputSchema, "Overlay") },
-		responses: {
-			201: jsonContent(successSchema(z.object({ id: z.string() })), "Created"),
-			...errorResponses(400),
-			...errorResponses(401, 403),
-		},
-	}),
-	async (c) => {
-		const principal = currentPrincipal(c);
-		const body = c.req.valid("json");
-		const id = await addOverlay(principal.userId, orgOf(principal), c.req.valid("param").userId, {
-			...body,
-			expiresAt: body.expiresAt ? new Date(body.expiresAt) : null,
-		});
-		return c.json(success({ id }), 201);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "delete",
-		path: "/members/{userId}/overlays/{overlayId}",
-		tags,
-		summary: "Remove an overlay",
-		middleware: [requirePermission("member:update")] as const,
-		security: [{ bearerAuth: ["member:update"] }],
-		request: { params: userOverlayParams },
-		responses: { 204: { description: "Removed" }, ...errorResponses(404), ...errorResponses(401, 403) },
-	}),
-	async (c) => {
-		const principal = currentPrincipal(c);
-		const { userId, overlayId } = c.req.valid("param");
-		await removeOverlay(principal.userId, orgOf(principal), userId, overlayId);
-		return c.body(null, 204);
-	},
-);
-
-router.openapi(
-	createRoute({
-		method: "get",
-		path: "/audit",
-		tags,
-		summary: "Recent authorization changes in the org",
-		middleware: [requirePermission("audit_log:read")] as const,
-		security: [{ bearerAuth: ["audit_log:read"] }],
-		responses: { 200: jsonContent(successSchema(z.array(auditEntrySchema)), "Audit log"), ...errorResponses(401, 403) },
-	}),
-	async (c) => {
-		const rows = await listAudit(orgOf(currentPrincipal(c)));
-		return c.json(success(rows.map((r) => ({ ...r, at: r.at.toISOString() }))), 200);
-	},
-);
-
-export default defineRoutes({ app: "api", basePath: "/authorization", router });

package/templates/features/authz/files/src/core/authz/system-roles.ts

@@ -5,5 +5,3 @@ export const SYSTEM_ROLES = [
 ] as const;
 
 export type SystemRoleKey = (typeof SYSTEM_ROLES)[number]["key"];
-
-export const SYSTEM_ROLE_KEYS: ReadonlySet<string> = new Set(SYSTEM_ROLES.map((r) => r.key));

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

@@ -1,6 +1,5 @@
 import { beforeEach, describe, expect, it } from "vitest";
-import { allows } from "#core/authz/resolver";
-import type { EffectivePermissions } from "#core/authz/types";
+import { allows, type EffectivePermissions } from "@tatara/authz";
 import { api } from "#tests/helpers/api";
 import { asUser, authenticate } from "#tests/helpers/auth";
 import { applyTestAccess } from "#tests/helpers/authz";

package/templates/features/authz/files/tests/helpers/authz.ts

@@ -1,7 +1,5 @@
-import { DEFAULT_ORG_ID, SYSTEM_ORG_ID } from "#core/authz/constants";
-import { store } from "#core/authz/db/store";
-import { addOverlay, assignRole } from "#core/authz/services/members";
-import { syncSystemRoles } from "#core/authz/services/sync";
+import { DEFAULT_ORG_ID, SYSTEM_ORG_ID } from "@tatara/authz";
+import { authz } from "#core/authz/index";
 import type { SystemRoleKey } from "#core/authz/system-roles";
 import type { PermissionKey } from "#generated/permissions";
 
@@ -17,14 +15,14 @@ export async function applyTestAccess(userId: string, access: TestAccess): Promi
 	const orgId = access.orgId ?? DEFAULT_ORG_ID;
 	for (const key of access.permissions ?? []) {
 		const [resource = "", action = ""] = key.split(":");
-		await addOverlay(null, orgId, userId, { resource, action, effect: "grant" });
+		await authz.addOverlay(null, orgId, userId, { resource, action, effect: "grant" });
 	}
 	if (access.systemRoles?.length) {
-		await syncSystemRoles();
+		await authz.syncSystemRoles();
 		for (const roleKey of access.systemRoles) {
-			const role = await store.findRoleByKey(SYSTEM_ORG_ID, roleKey);
+			const role = await authz.store.findRoleByKey(SYSTEM_ORG_ID, roleKey);
 			if (!role) throw new Error(`Unknown built-in role ${roleKey}`);
-			await assignRole(null, orgId, userId, role.id);
+			await authz.assignRole(null, orgId, userId, role.id);
 		}
 	}
 }

package/templates/features/authz/files+drizzle/src/core/authz/db/store.ts

@@ -1,6 +1,6 @@
 import { and, count, desc, eq, gt, inArray, isNull, or } from "drizzle-orm";
-import type { OverlayEffect, Scope } from "#core/authz/constants";
-import { SYSTEM_ORG_ID } from "#core/authz/constants";
+import type { OverlayEffect, Scope } from "@tatara/authz";
+import { SYSTEM_ORG_ID } from "@tatara/authz";
 import {
 	authzAuditLog,
 	authzMemberRoles,
@@ -8,7 +8,7 @@ import {
 	authzRolePermissions,
 	authzRoles,
 } from "#core/authz/db/authz.schema";
-import type { AuthzStore, OverlayRow, PermissionGrant, RoleRow } from "#core/authz/types";
+import type { AuthzStore, OverlayRow, PermissionGrant, RoleRow } from "@tatara/authz";
 import { db } from "#core/db/client";
 import { newId } from "@tatara/db";
 

package/templates/features/authz/files+prisma/src/core/authz/db/store.ts

@@ -1,6 +1,6 @@
-import type { OverlayEffect, Scope } from "#core/authz/constants";
-import { SYSTEM_ORG_ID } from "#core/authz/constants";
-import type { AuthzStore, OverlayRow, PermissionGrant, RoleRow } from "#core/authz/types";
+import type { OverlayEffect, Scope } from "@tatara/authz";
+import { SYSTEM_ORG_ID } from "@tatara/authz";
+import type { AuthzStore, OverlayRow, PermissionGrant, RoleRow } from "@tatara/authz";
 import { db } from "#core/db/client";
 import { newId } from "@tatara/db";
 

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
+]);