@tatara/cli 0.9.1 → 0.10.0

package/dist/bin.mjs

@@ -865,6 +865,24 @@ const authz = {
 	label: "Permission system",
 	dependencies: ["@tatara/authz"],
 	slots: [
+		{
+			file: "src/core/authz/index.ts",
+			slot: "options",
+			unless: ["auth-orgs"],
+			content: "singleTenant: \"default\","
+		},
+		{
+			file: "src/modules/users/routes/authorization.routes.ts",
+			slot: "route-options",
+			when: ["auth-orgs"],
+			content: "use: [requireOrg()],"
+		},
+		{
+			file: "src/modules/users/routes/authorization.routes.ts",
+			slot: "imports",
+			when: ["auth-orgs"],
+			content: "import { requireOrg } from \"#modules/users/services/auth\";"
+		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "imports",
@@ -877,14 +895,15 @@ const authz = {
 		},
 		{
 			file: "tests/helpers/auth.ts",
-			slot: "options",
-			when: ["better-auth"],
-			content: "orgId?: string;"
+			slot: "as-user",
+			unless: ["auth-orgs"],
+			content: "await applyTestAccess(user.userId, options);"
 		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "as-user",
-			content: "await applyTestAccess(user.userId, options);"
+			when: ["auth-orgs"],
+			content: "await applyTestAccess(user.userId, { ...options, orgId: user.orgId });"
 		},
 		{
 			file: "AGENTS.md",
@@ -1001,11 +1020,32 @@ const admin = {
 	kind: "addon",
 	label: "Admin API app",
 	scripts: { "start:admin": "node dist/apps/admin/server.mjs" },
-	env: [{
-		key: "ADMIN_PORT",
-		schema: "z.coerce.number().int().default(3001)",
-		example: "3001"
-	}],
+	env: [
+		{
+			key: "ADMIN_PORT",
+			schema: "z.coerce.number().int().default(3001)",
+			example: "3001"
+		},
+		{
+			key: "ADMIN_URL",
+			schema: "localDefault(z.url(), \"http://localhost:3001\")",
+			example: "http://localhost:3001",
+			comment: "Where the admin app is served; staff sign in there"
+		},
+		{
+			key: "SEED_STAFF_EMAIL",
+			schema: "z.email().default(\"staff@example.com\")",
+			example: "staff@example.com",
+			comment: "Development staff account created by `db:seed` (never in production)"
+		},
+		{
+			key: "SEED_STAFF_PASSWORD",
+			schema: "z.string().min(10).optional()",
+			example: "",
+			secret: true,
+			comment: "Password for the development staff account (generated by tatara new)"
+		}
+	],
 	slots: [
 		{
 			file: "src/core/http/routes.ts",
@@ -1018,15 +1058,48 @@ const admin = {
 			content: "\"apps/admin/server\": \"src/apps/admin/server.ts\","
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "imports",
-			content: "import { requireRole } from \"@tatara/auth\";"
+			content: [
+				"import { requireRole } from \"@tatara/auth\";",
+				"import { except } from \"hono/combine\";",
+				"import { attachStaffPrincipal, staffAuth } from \"#modules/staff/services/auth\";"
+			].join("\n")
+		},
+		{
+			file: "src/apps/http.ts",
+			slot: "middleware",
+			order: 50,
+			content: "app.use(name === \"admin\" ? attachStaffPrincipal : attachPrincipal);"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
+			slot: "routes",
+			order: 2,
+			content: "if (name === \"admin\") app.on([\"GET\", \"POST\"], `${API_PREFIX}/auth/*`, (c) => staffAuth.handler(c.req.raw));"
+		},
+		{
+			file: "src/apps/http.ts",
 			slot: "routes",
 			order: 5,
-			content: "if (name === \"admin\") app.use(`${API_PREFIX}/*`, requireRole(\"admin\"));"
+			content: "if (name === \"admin\") app.use(`${API_PREFIX}/*`, except(`${API_PREFIX}/auth/*`, requireRole(\"staff\")));"
+		},
+		{
+			file: "src/core/authz/system-roles.ts",
+			slot: "roles",
+			content: "{ key: \"staff\", name: \"Staff\", description: \"Internal staff: platform permissions on the admin app.\" },"
+		},
+		{
+			file: "src/modules/staff/services/auth.ts",
+			slot: "resolvers",
+			when: ["auth-keycloak"],
+			content: "() => (c) => keycloakPrincipal(auth, c.req.header(\"authorization\")),"
+		},
+		{
+			file: "src/modules/staff/services/auth.ts",
+			slot: "imports",
+			when: ["auth-keycloak"],
+			content: "import { keycloakPrincipal } from \"@tatara/keycloak\";\nimport { auth } from \"#modules/users/services/auth\";"
 		},
 		{
 			file: "tests/helpers/api.ts",
@@ -1041,11 +1114,15 @@ const admin = {
 		{
 			file: "AGENTS.md",
 			slot: "sections",
-			content: `## Admin app
+			content: `## Admin app and staff
 
 - \`apps/admin\` is a second HTTP app on \`ADMIN_PORT\`. Routes with \`defineRoutes({ app: "admin", … })\`
-  are served only there, and every \`/api\` route on it requires the \`admin\` role.
-- Test it with \`adminApi\` from \`#tests/helpers/api\`.
+  are served only there, and every \`/api\` route on it needs a staff principal (role \`staff\`).
+- Staff are separate accounts (\`src/modules/staff\`, tables \`staff_*\`), with their own better-auth
+  mounted at \`/api/auth\` on the admin app. They never share a table or a session with users.
+  There's no staff sign-up; the dev account comes from \`SEED_STAFF_EMAIL\`/\`SEED_STAFF_PASSWORD\`.
+- Staff act in the \`platform\` org, so grant platform permissions to the built-in \`staff\` role.
+- Test it with \`adminApi\` from \`#tests/helpers/api\` and \`asStaff()\` from \`#tests/helpers/staff\`.
 `
 		}
 	]
@@ -1228,23 +1305,23 @@ const i18n = {
 	}],
 	slots: [
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "imports",
 			content: "import { detectLanguage } from \"#core/i18n/index\";"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "middleware",
 			order: 10,
 			content: "app.use(detectLanguage);"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "imports",
 			content: "import { t } from \"#core/i18n/index\";"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "error-options",
 			content: ["message: (err, c) =>", "	err.translatable ? t(c.get(\"language\"), `errors.${err.code}`, err.message) : err.message,"].join("\n")
 		},
@@ -1268,18 +1345,19 @@ const auth = {
 	dependencies: ["@tatara/auth"],
 	slots: [
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "imports",
-			content: "import { attachPrincipal } from \"#core/auth/principal\";"
+			content: "import { attachPrincipal } from \"#modules/users/services/auth\";"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "middleware",
 			order: 50,
+			unless: ["admin"],
 			content: "app.use(attachPrincipal);"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "routes",
 			order: 0,
 			content: [
@@ -1310,7 +1388,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\` (from \`@tatara/auth\`) in \`src/core/auth/sms.ts\`.
+- To send real SMS, implement \`SmsSender\` (from \`@tatara/auth\`) in \`src/modules/users/services/sms.ts\`.
 `;
 const drizzlePg = ["drizzle", "postgres"];
 const drizzleMy = ["drizzle", "mysql"];
@@ -1343,36 +1421,48 @@ const betterAuth = {
 	],
 	slots: [
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "imports",
-			content: "import { auth } from \"#core/auth/auth\";"
+			content: "import { auth } from \"#modules/users/services/auth\";"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "imports",
-			content: "import { outbox } from \"#core/auth/delivery\";"
+			content: "import { outbox } from \"#modules/users/services/delivery\";"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "imports",
 			content: "import { mergeAuthOpenApi } from \"@tatara/auth\";"
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "expose-headers",
 			content: "\"set-auth-token\","
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
+			slot: "openapi-options",
+			unless: ["admin"],
+			content: [
+				"async extend(document) {",
+				"	if (name === \"api\") await mergeAuthOpenApi(document, auth, `${API_PREFIX}/auth`);",
+				"},"
+			].join("\n")
+		},
+		{
+			file: "src/apps/http.ts",
 			slot: "openapi-options",
+			when: ["admin"],
 			content: [
 				"async extend(document) {",
 				"	if (name === \"api\") await mergeAuthOpenApi(document, auth, `${API_PREFIX}/auth`);",
+				"	if (name === \"admin\") await mergeAuthOpenApi(document, staffAuth, `${API_PREFIX}/auth`);",
 				"},"
 			].join("\n")
 		},
 		{
-			file: "src/core/http/app.ts",
+			file: "src/apps/http.ts",
 			slot: "routes",
 			order: 1,
 			content: [
@@ -1385,29 +1475,35 @@ const betterAuth = {
 			].join("\n")
 		},
 		{
-			file: "src/core/auth/delivery.ts",
+			file: "src/modules/users/services/delivery.ts",
 			slot: "email-delivery",
 			unless: ["email"],
 			content: "logger.info({ to: message.to, subject: message.subject }, \"email not sent: no email provider configured\");"
 		},
 		{
-			file: "src/core/auth/delivery.ts",
+			file: "src/modules/users/services/delivery.ts",
 			slot: "imports",
 			unless: ["email"],
 			content: "import { logger } from \"#core/logging/logger\";"
 		},
 		{
-			file: "src/core/auth/delivery.ts",
+			file: "src/modules/users/services/delivery.ts",
 			slot: "imports",
 			when: ["email"],
 			content: "import { sendEmail } from \"#core/email/send\";"
 		},
 		{
-			file: "src/core/auth/delivery.ts",
+			file: "src/modules/users/services/delivery.ts",
 			slot: "email-delivery",
 			when: ["email"],
 			content: "await sendEmail({ to: message.to, subject: message.subject, text: message.text });"
 		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "authenticated",
+			unless: ["auth-orgs"],
+			content: "return { userId, headers };"
+		},
 		{
 			file: "AGENTS.md",
 			slot: "sections",
@@ -1421,17 +1517,17 @@ const authEmailOtp = {
 	label: "Email OTP",
 	slots: [
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
-			content: "import { deliverEmail } from \"#core/auth/delivery\";"
+			content: "import { deliverEmail } from \"#modules/users/services/delivery\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
 			content: "import { emailOTP } from \"better-auth/plugins\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "plugins",
 			content: [
 				"emailOTP({",
@@ -1450,13 +1546,13 @@ const authEmailOtp = {
 };
 const phoneFields = [
 	{
-		file: "src/core/auth/db/auth.schema.ts",
+		file: "src/modules/users/db/auth.schema.ts",
 		slot: "user-fields",
 		when: drizzlePg,
 		content: "phoneNumber: text().unique(),\nphoneNumberVerified: boolean(),"
 	},
 	{
-		file: "src/core/auth/db/auth.schema.ts",
+		file: "src/modules/users/db/auth.schema.ts",
 		slot: "user-fields",
 		when: drizzleMy,
 		content: "phoneNumber: varchar({ length: 32 }).unique(),\nphoneNumberVerified: boolean(),"
@@ -1473,17 +1569,17 @@ const authPhoneOtp = {
 	label: "Phone OTP",
 	slots: [
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
-			content: "import { deliverSms } from \"#core/auth/delivery\";"
+			content: "import { deliverSms } from \"#modules/users/services/delivery\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
 			content: "import { phoneNumber } from \"better-auth/plugins\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "plugins",
 			content: [
 				"phoneNumber({",
@@ -1513,12 +1609,12 @@ const authPassword = {
 	}],
 	slots: [
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
-			content: "import { deliverEmail } from \"#core/auth/delivery\";"
+			content: "import { deliverEmail } from \"#modules/users/services/delivery\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "options",
 			content: [
 				"emailAndPassword: {",
@@ -1531,7 +1627,7 @@ const authPassword = {
 			].join("\n")
 		},
 		{
-			file: "src/core/auth/db/seed.ts",
+			file: "src/modules/users/db/seed.ts",
 			slot: "seed-after-user",
 			content: [
 				"if (env.SEED_ADMIN_PASSWORD) {",
@@ -1548,25 +1644,25 @@ const authPassword = {
 };
 const adminFields = [
 	{
-		file: "src/core/auth/db/auth.schema.ts",
+		file: "src/modules/users/db/auth.schema.ts",
 		slot: "user-fields",
 		when: drizzlePg,
 		content: "role: text(),\nbanned: boolean().default(false),\nbanReason: text(),\nbanExpires: timestamp({ withTimezone: true, mode: \"date\" }),"
 	},
 	{
-		file: "src/core/auth/db/auth.schema.ts",
+		file: "src/modules/users/db/auth.schema.ts",
 		slot: "user-fields",
 		when: drizzleMy,
 		content: "role: varchar({ length: 255 }),\nbanned: boolean().default(false),\nbanReason: text(),\nbanExpires: timestamp({ fsp: 3, mode: \"date\" }),"
 	},
 	{
-		file: "src/core/auth/db/auth.schema.ts",
+		file: "src/modules/users/db/auth.schema.ts",
 		slot: "session-fields",
 		when: drizzlePg,
 		content: "activeOrganizationId: text(),\nimpersonatedBy: text(),"
 	},
 	{
-		file: "src/core/auth/db/auth.schema.ts",
+		file: "src/modules/users/db/auth.schema.ts",
 		slot: "session-fields",
 		when: drizzleMy,
 		content: "activeOrganizationId: varchar({ length: 36 }),\nimpersonatedBy: varchar({ length: 36 }),"
@@ -1592,57 +1688,70 @@ const adminFields = [
 		content: ["activeOrganizationId String? @map(\"active_organization_id\") @db.VarChar(36)", "impersonatedBy       String? @map(\"impersonated_by\") @db.VarChar(36)"].join("\n")
 	},
 	{
-		file: "src/core/auth/adapter.ts",
+		file: "src/modules/users/services/adapter.ts",
 		slot: "imports",
 		when: ["drizzle"],
-		content: "import * as orgSchema from \"#core/auth/db/organization.schema\";"
+		content: "import * as orgSchema from \"#modules/users/db/organization.schema\";"
 	},
 	{
-		file: "src/core/auth/adapter.ts",
+		file: "src/modules/users/services/adapter.ts",
 		slot: "adapter-schema",
 		when: ["drizzle"],
 		content: "organization: orgSchema.organizations,\nmember: orgSchema.members,\ninvitation: orgSchema.invitations,"
 	}
 ];
+const JOIN_TEST_ORG = [
+	"/** Makes the user a member of `orgId` (a shared test org by default), creating it on first use. */",
+	"export async function joinTestOrg(userId: string, orgId = \"test-org\", role = \"member\"): Promise<string> {",
+	"	const { adapter } = await auth.$context;",
+	"	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,",
+	"		});",
+	"	}",
+	"	await adapter.create({",
+	"		model: \"member\",",
+	"		data: { organizationId: orgId, userId, role, createdAt: new Date() },",
+	"	});",
+	"	return orgId;",
+	"}"
+].join("\n");
 const authOrgs = {
 	id: "auth-orgs",
 	kind: "auth-method",
 	label: "Organizations + roles",
 	slots: [
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
 			content: "import { admin, organization } from \"better-auth/plugins\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "plugins",
 			unless: ["authz"],
 			content: "organization(),\nadmin(),",
 			order: 900
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "plugins",
 			when: ["authz"],
 			content: [
-				"organization({",
-				"	organizationHooks: {",
-				"		// authz rows outlive better-auth's member row; without this, re-adding restores old roles",
-				"		afterRemoveMember: async ({ member }) => {",
-				"			await removeMemberAccess(member.organizationId, member.userId);",
-				"		},",
-				"	},",
-				"}),",
+				"// a removed member's authz roles and overlays go with the membership",
+				"organization({ organizationHooks: authzOrganizationHooks(authz) }),",
 				"admin(),"
 			].join("\n"),
 			order: 900
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
 			when: ["authz"],
-			content: "import { removeMemberAccess } from \"#core/authz/index\";"
+			content: "import { authzOrganizationHooks } from \"@tatara/authz\";\nimport { authz } from \"#core/authz/index\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
@@ -1650,7 +1759,22 @@ const authOrgs = {
 			content: "...(options.roles ? { role: options.roles.join(\",\") } : {}),"
 		},
 		{
-			file: "src/core/auth/db/seed.ts",
+			file: "tests/helpers/auth.ts",
+			slot: "options",
+			content: "/** the org the user joins and acts in (default: a shared test org) */\norgId?: string;"
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "authenticated",
+			content: ["const orgId = await joinTestOrg(userId, options.orgId);", "return { userId, orgId, headers: { ...headers, \"x-org-id\": orgId } };"].join("\n")
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "helpers",
+			content: JOIN_TEST_ORG
+		},
+		{
+			file: "src/modules/users/db/seed.ts",
 			slot: "seed-user-fields",
 			content: "role: \"admin\","
 		},
@@ -1708,41 +1832,41 @@ const authKeycloak = {
 	} },
 	slots: [
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
 			content: "import { keycloakTokens } from \"@tatara/keycloak\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
-			content: "import { keycloak } from \"#core/auth/keycloak\";"
+			content: "import { keycloak } from \"#modules/users/services/keycloak\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
 			content: "import { logger } from \"#core/logging/logger\";"
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "plugins",
 			unless: ["auth-orgs"],
 			content: "keycloakTokens({ verifier: keycloak, logger }),",
 			order: 800
 		},
 		{
-			file: "src/core/auth/auth.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "plugins",
 			when: ["auth-orgs"],
 			content: "keycloakTokens({ verifier: keycloak, logger, organizations: true }),",
 			order: 800
 		},
 		{
-			file: "src/core/auth/principal.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "resolvers",
-			content: "(c) => keycloakPrincipal(auth, c.req.header(\"authorization\")),"
+			content: "(instance) => (c) => keycloakPrincipal(instance, c.req.header(\"authorization\")),"
 		},
 		{
-			file: "src/core/auth/principal.ts",
+			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
 			content: "import { keycloakPrincipal } from \"@tatara/keycloak\";"
 		},
@@ -1754,7 +1878,7 @@ const authKeycloak = {
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "imports",
-			content: "import { keycloak } from \"#core/auth/keycloak\";"
+			content: "import { keycloak } from \"#modules/users/services/keycloak\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
@@ -2213,7 +2337,6 @@ function validateOptions(input) {
 	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") && !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;
 }
@@ -2438,7 +2561,7 @@ function pnpmWorkspace(features) {
 }
 /** Tests of tatara's wiring, not of the app; generated apps leave them out. */
 function isFrameworkTest(path) {
-	return /^src\/core\/.+\/tests\/[^/]+\.test\.ts$/.test(path);
+	return path.startsWith("tests/tatara/") || /^src\/core\/.+\/tests\/[^/]+\.test\.ts$/.test(path);
 }
 /** Folds applicable variants into each feature so later steps see one flat definition. */
 function effectiveFeatures(options) {
@@ -2648,7 +2771,12 @@ function guardSlots(project, n) {
 	});
 	if (project.has("authz")) {
 		add("imports", "import { requirePermission } from \"#core/authz/index\";");
-		for (const [route, action] of Object.entries(ACTIONS)) add(`guard-${route}`, `middleware: [requirePermission("${n.kebab}:${action}")] as const,\nsecurity: [{ bearerAuth: ["${n.kebab}:${action}"] }],`);
+		const orgs = project.has("auth-orgs");
+		if (orgs) add("imports", "import { requireOrg } from \"#modules/users/services/auth\";");
+		for (const [route, action] of Object.entries(ACTIONS)) {
+			const guards = `${orgs ? "requireOrg(), " : ""}requirePermission("${n.kebab}:${action}")`;
+			add(`guard-${route}`, `middleware: [${guards}] as const,\nsecurity: [{ bearerAuth: ["${n.kebab}:${action}"] }],`);
+		}
 		add("auth-errors", "...errorResponses(401, 403),");
 	} else if (project.has("auth")) {
 		add("imports", "import { requireAuth } from \"@tatara/auth\";");
@@ -3156,11 +3284,16 @@ for (const [name, spec] of ${JSON.stringify(apps)}) {
 
 	for (const [path, item] of Object.entries(doc.paths ?? {})) {
 		for (const [method, op] of Object.entries(item)) {
+			const tags = op.tags ?? [];
 			const security = op.security ?? [];
 
-			// Parse access label based on security schemes
+			// Parse access label based on security schemes and tags
 			let access = "public";
-			if (security.length > 0) {
+
+			// Routes tagged "Auth" are from better-auth's merged document
+			if (tags.includes("Auth")) {
+				access = "better-auth";
+			} else if (security.length > 0) {
 				const labels = [];
 				for (const requirement of security) {
 					const schemes = Object.keys(requirement);
@@ -3185,7 +3318,8 @@ for (const [name, spec] of ${JSON.stringify(apps)}) {
 				access = labels.length > 1 ? labels.join(" OR ") : (labels[0] ?? "authenticated");
 			}
 
-			out.push({ app: name, method: method.toUpperCase(), path, summary: op.summary ?? "", access });
+			const summary = op.summary || op.description || "";
+			out.push({ app: name, method: method.toUpperCase(), path, summary, access });
 		}
 	}
 }
@@ -3445,7 +3579,7 @@ function importsOf(text, specifier) {
 }
 //#endregion
 //#region src/upgrade/codemods/groups.ts
-async function read$4(ctx, path) {
+async function read$5(ctx, path) {
 	return ctx.read(path).catch(() => void 0);
 }
 function sourceFiles(ctx) {
@@ -3458,7 +3592,7 @@ function sourceFiles(ctx) {
 async function blockersOf$1(ctx, group, sources) {
 	const blockers = [];
 	for (const path of [...group.regenerate, ...group.remove]) {
-		const text = await read$4(ctx, path);
+		const text = await read$5(ctx, path);
 		if (text === void 0) continue;
 		if (!await ctx.baseline.isUnchanged(path, text)) blockers.push(`${path} is customised`);
 	}
@@ -3598,6 +3732,140 @@ const addonPackages = {
 	}
 };
 //#endregion
+//#region src/upgrade/moves.ts
+/**
+* Files later CLIs generate somewhere else. An older codemod that regenerates an old path gets
+* what this CLI generates at the new one; the codemod of the release that moved it moves it.
+*/
+const MOVED_IN_0_10 = {
+	"src/core/http/app.ts": "src/apps/http.ts",
+	"src/core/auth/auth.ts": "src/modules/users/services/auth.ts",
+	"src/core/auth/adapter.ts": "src/modules/users/services/adapter.ts",
+	"src/core/auth/delivery.ts": "src/modules/users/services/delivery.ts",
+	"src/core/auth/sms.ts": "src/modules/users/services/sms.ts",
+	"src/core/auth/keycloak.ts": "src/modules/users/services/keycloak.ts",
+	"src/core/auth/db/seed.ts": "src/modules/users/db/seed.ts",
+	"src/core/auth/db/auth.schema.ts": "src/modules/users/db/auth.schema.ts",
+	"src/core/auth/db/organization.schema.ts": "src/modules/users/db/organization.schema.ts",
+	"src/core/auth/routes/me.routes.ts": "src/modules/users/routes/me.routes.ts",
+	"src/core/auth/commands/keycloak-token.ts": "src/modules/users/commands/keycloak-token.ts",
+	"src/core/authz/routes/authorization.routes.ts": "src/modules/users/routes/authorization.routes.ts"
+};
+/** Merged into another file in 0.10: nothing is generated in its place. */
+const MERGED_IN_0_10 = { "src/core/auth/principal.ts": "src/modules/users/services/auth.ts" };
+/** Where this CLI generates what used to be at `path` (the path itself if it never moved). */
+function currentPath(path) {
+	return MOVED_IN_0_10[path] ?? path;
+}
+//#endregion
+//#region src/upgrade/codemods/app-owned-auth.ts
+/** Import specifiers that moved, old → new; every name keeps working at the new place. */
+const SPECIFIERS = {
+	"#core/http/app": "#apps/http",
+	"#core/auth/auth": "#modules/users/services/auth",
+	"#core/auth/principal": "#modules/users/services/auth",
+	"#core/auth/adapter": "#modules/users/services/adapter",
+	"#core/auth/delivery": "#modules/users/services/delivery",
+	"#core/auth/sms": "#modules/users/services/sms",
+	"#core/auth/keycloak": "#modules/users/services/keycloak",
+	"#core/auth/db/auth.schema": "#modules/users/db/auth.schema",
+	"#core/auth/db/organization.schema": "#modules/users/db/organization.schema"
+};
+/** Files whose content this release changes in place (new imports, orgRole, single tenant). */
+const REGENERATED$2 = [
+	"src/core/http/context.ts",
+	"tests/helpers/auth.ts",
+	"src/core/authz/index.ts"
+];
+async function read$4(ctx, path) {
+	return ctx.read(path).catch(() => void 0);
+}
+/** Inserts the single-tenant option into an app's own createAuthz call, if it lacks one. */
+function withSingleTenant(text) {
+	if (text.includes("singleTenant")) return text;
+	return text.replace(/(createAuthz(?:<[^>]*>)?\(\{\n)/, "$1	singleTenant: \"default\",\n");
+}
+const STAFF_FILES = [
+	"src/modules/staff/services/auth.ts",
+	"src/modules/staff/services/adapter.ts",
+	"src/modules/staff/db/seed.ts",
+	"src/modules/staff/db/staff.schema.ts",
+	"prisma/models/staff.prisma",
+	"tests/helpers/staff.ts"
+];
+/** The admin app now signs in staff accounts of its own; the regenerated apps/http.ts imports them. */
+async function addStaff(ctx) {
+	for (const path of STAFF_FILES) {
+		if (await read$4(ctx, path) !== void 0) continue;
+		const text = await ctx.renderCurrent(path);
+		if (text !== void 0) await ctx.write(path, text);
+	}
+	const customisedEnv = [];
+	for (const path of [
+		"src/core/config/env.ts",
+		".env.example",
+		".env.test"
+	]) {
+		const text = await read$4(ctx, path);
+		if (text === void 0) continue;
+		if (await ctx.baseline.isUnchanged(path, text)) await ctx.regenerate(path);
+		else customisedEnv.push(path);
+	}
+	if (customisedEnv.length > 0) ctx.report.notes.push(`Add ADMIN_URL, SEED_STAFF_EMAIL and SEED_STAFF_PASSWORD to ${customisedEnv.join(", ")} (they are customised, so they were left as they are).`);
+	ctx.report.notes.push("The admin app now signs in staff accounts (src/modules/staff, tables staff_*) instead of users with the admin role. Run `tatara db generate` for the new tables, add { key: \"staff\" } to src/core/authz/system-roles.ts if you use authz, and grant your platform permissions to it.");
+}
+const appOwnedAuth = {
+	version: "0.10.0",
+	id: "app-owned-auth",
+	description: "Move auth into src/modules/users and HTTP wiring into src/apps; explicit org context",
+	async run(ctx) {
+		const { config } = ctx.project;
+		const orgs = config.authMethods.includes("orgs");
+		if (config.addons.includes("authz") && !orgs) {
+			const index = await read$4(ctx, "src/core/authz/index.ts");
+			const next = index && withSingleTenant(index);
+			if (next && next !== index) await ctx.write("src/core/authz/index.ts", next);
+		}
+		const blockers = [];
+		const moves = [];
+		for (const [from, to] of Object.entries(MOVED_IN_0_10)) {
+			const text = await read$4(ctx, from);
+			if (text === void 0) continue;
+			const there = await read$4(ctx, to);
+			if (there !== void 0 && there !== await ctx.renderCurrent(to)) blockers.push(`${to} already exists`);
+			else if (await ctx.baseline.isUnchanged(from, text)) moves.push([from, to]);
+			else blockers.push(`${from} is customised`);
+		}
+		const merged = [];
+		for (const from of Object.keys(MERGED_IN_0_10)) {
+			const text = await read$4(ctx, from);
+			if (text === void 0) continue;
+			if (await ctx.baseline.isUnchanged(from, text)) merged.push(from);
+			else blockers.push(`${from} is customised`);
+		}
+		if (blockers.length > 0) {
+			ctx.report.notes.push(`Auth was not moved into src/modules/users: ${blockers.join("; ")}. Compare with a newly generated app (auth in src/modules/users/services/auth.ts built with createAuthInstance, HTTP wiring in src/apps/http.ts) and move it by hand.`);
+			ctx.report.blocked.push("app-owned-auth");
+			return;
+		}
+		for (const [from, to] of moves) {
+			const next = await ctx.renderCurrent(to);
+			if (next !== void 0) await ctx.write(to, next);
+			await ctx.removeIfUnchanged(from);
+		}
+		for (const from of merged) await ctx.removeIfUnchanged(from);
+		for (const path of REGENERATED$2) {
+			const text = await read$4(ctx, path);
+			if (text !== void 0 && await ctx.baseline.isUnchanged(path, text)) await ctx.regenerate(path);
+		}
+		for (const [from, to] of Object.entries(SPECIFIERS)) await ctx.rewriteImports(from, to);
+		if (config.addons.includes("admin")) await addStaff(ctx);
+		const leftovers = await glob(["src/core/auth/**/*.ts"], { cwd: ctx.project.root });
+		if (leftovers.length > 0) ctx.report.notes.push(`Move these into src/modules/users (core must not hold auth flows): ${leftovers.join(", ")}`);
+		if (orgs) ctx.report.notes.push("Requests that act in an organization now name it (x-org-id header, or the session's active organization); authz no longer falls back to a default org.");
+	}
+};
+//#endregion
 //#region src/upgrade/codemods/auth-package.ts
 const AUTH = "@tatara/auth";
 const KEYCLOAK = "@tatara/keycloak";
@@ -4232,12 +4500,17 @@ const CODEMODS = [
 				await ctx.removeIfUnchanged(path);
 			}
 		}
-	}
+	},
+	appOwnedAuth
 ];
 //#endregion
 //#region src/upgrade/context.ts
 const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-function createContext(project, baseline, opts = {}) {
+function createContext(project, appBaseline, opts = {}) {
+	const ours = /* @__PURE__ */ new Map();
+	const baseline = { async isUnchanged(path, content) {
+		return ours.get(path) === hashContent(content) || appBaseline.isUnchanged(path, content);
+	} };
 	const report = {
 		ran: [],
 		written: [],
@@ -4257,6 +4530,7 @@ function createContext(project, baseline, opts = {}) {
 			const before = existsSync(abs(path)) ? await readFile(abs(path), "utf8") : void 0;
 			if (before === void 0 || await baseline.isUnchanged(path, before)) report.regenerated.push(path);
 		}
+		ours.set(path, hashContent(text));
 		if (opts.dryRun) return;
 		await mkdir(dirname(abs(path)), { recursive: true });
 		await writeFile(abs(path), text);
@@ -4309,7 +4583,7 @@ function createContext(project, baseline, opts = {}) {
 				addons,
 				packageManager
 			});
-			return (await rendered).get(path);
+			return (await rendered).get(currentPath(path));
 		},
 		async regenerate(path) {
 			const next = await ctx.renderCurrent(path);