@tatara/cli 0.12.0 → 0.13.1

package/dist/bin.mjs

@@ -84,6 +84,18 @@ const authz = {
 	label: "Permission system",
 	dependencies: ["@tatara/authz"],
 	slots: [
+		{
+			file: "src/core/authz/system-roles.ts",
+			slot: "admin",
+			unless: ["auth-keycloak"],
+			content: "{ key: \"admin\", name: \"Admin\", description: \"Full access, including roles and members.\" },"
+		},
+		{
+			file: "src/core/authz/system-roles.ts",
+			slot: "admin",
+			when: ["auth-keycloak"],
+			content: "{ key: \"admin\", name: \"Admin\", description: \"Full access, including roles and members.\", heldBy: \"identity\" },"
+		},
 		{
 			file: "src/core/authz/index.ts",
 			slot: "options",
@@ -136,8 +148,11 @@ const authz = {
 - Guard routes with \`middleware: [requirePermission("project:read")]\` from \`#core/authz/index\`
   and declare \`security: [{ bearerAuth: ["project:read"] }]\`. For scoped actions, call
   \`resolveScope(principal, "doc:read")\` in the service and filter rows by the returned scope.
-- Effective permissions = role grants (assigned roles + built-in roles whose key matches an
-  identity-provider role) + grant overlays − deny overlays. Deny always wins.
+- Effective permissions = grants of the caller's roles + grant overlays − deny overlays. Deny
+  always wins. Roles are assigned in authz (the org's creator gets \`admin\`); a built-in role with
+  \`heldBy: "members"\` goes to every member, \`heldBy: "identity"\` to holders of that identity role.
+- better-auth's member role is membership only (\`owner\` or \`member\`): \`authzPlugin\` in
+  \`src/modules/users/services/auth.ts\` refuses others and gives the creator \`admin\`.
 - Custom roles and grant overlays can never grant \`role\`, \`member\` or \`audit_log\`.
 - Built-in roles live in \`src/core/authz/system-roles.ts\`. \`authz:sync-permissions\` brings the database
   in line with them; \`deploy\` runs it every deploy, \`db:seed\` locally.
@@ -476,7 +491,7 @@ const admin = {
 		{
 			file: "src/core/authz/system-roles.ts",
 			slot: "roles",
-			content: "{ key: \"staff\", name: \"Staff\", description: \"Internal staff: platform permissions on the admin app.\" },"
+			content: "{ key: \"staff\", name: \"Staff\", description: \"Internal staff: platform permissions on the admin app.\", heldBy: \"identity\" },"
 		},
 		{
 			file: "src/modules/staff/services/auth.ts",
@@ -516,22 +531,6 @@ const admin = {
 		}
 	]
 };
-const MEMBERS = `/** The org's members, a page at a time. */
-async function* members(orgId: string) {
-	const { adapter } = await auth.$context;
-	for (let offset = 0; ; offset += 100) {
-		const page = await adapter.findMany<{ userId: string; role: string }>({
-			model: "member",
-			where: [{ field: "organizationId", value: orgId }],
-			limit: 100,
-			offset,
-			sortBy: { field: "id", direction: "asc" },
-		});
-		yield* page;
-		if (page.length < 100) return;
-	}
-}`;
-const hasRole = "m.role.split(\",\").map((r) => r.trim()).includes(role)";
 const notifications = {
 	id: "notifications",
 	kind: "addon",
@@ -606,7 +605,21 @@ const notifications = {
 			file: "src/modules/notifications/services/notifier.ts",
 			slot: "helpers",
 			when: ["auth-orgs"],
-			content: MEMBERS
+			content: `/** The org's members, a page at a time. */
+async function* members(orgId: string) {
+	const { adapter } = await auth.$context;
+	for (let offset = 0; ; offset += 100) {
+		const page = await adapter.findMany<{ userId: string; role: string }>({
+			model: "member",
+			where: [{ field: "organizationId", value: orgId }],
+			limit: 100,
+			offset,
+			sortBy: { field: "id", direction: "asc" },
+		});
+		yield* page;
+		if (page.length < 100) return;
+	}
+}`
 		},
 		{
 			file: "src/modules/notifications/services/notifier.ts",
@@ -616,7 +629,7 @@ const notifications = {
 			content: [
 				"recipients: {",
 				"	async *role(orgId, role) {",
-				`\t\tfor await (const m of members(orgId)) if (${hasRole}) yield m.userId;`,
+				`\t\tfor await (const m of members(orgId)) if (m.role.split(",").map((r) => r.trim()).includes(role)) yield m.userId;`,
 				"	},",
 				"	permission() {",
 				"		throw new Error(\"Notifying by permission needs the authz add-on\");",
@@ -630,8 +643,12 @@ const notifications = {
 			when: ["auth-orgs", "authz"],
 			content: [
 				"recipients: {",
+				"	// authz roles (assigned, or held by every member): better-auth's member role is only owner or member",
 				"	async *role(orgId, role) {",
-				`\t\tfor await (const m of members(orgId)) if (${hasRole}) yield m.userId;`,
+				"		for await (const m of members(orgId)) {",
+				"			const who = { userId: m.userId, orgId, orgRole: m.role, roles: [], kind: \"user\" as const, claims: {} };",
+				"			if ((await authz.effectivePermissions(who)).roles.includes(role)) yield m.userId;",
+				"		}",
 				"	},",
 				"	// the same check a request makes: built-in roles, assigned roles and overlays",
 				"	async *permission(orgId, permission) {",
@@ -647,7 +664,7 @@ const notifications = {
 			file: "src/modules/notifications/services/notifier.ts",
 			slot: "imports",
 			when: ["auth-orgs", "authz"],
-			content: "import { checkPermission } from \"#core/authz/index\";\nimport type { PermissionKey } from \"#generated/permissions\";"
+			content: "import { authz, checkPermission } from \"#core/authz/index\";\nimport type { PermissionKey } from \"#generated/permissions\";"
 		},
 		{
 			file: "src/modules/notifications/services/notifier.ts",
@@ -1546,16 +1563,15 @@ const authOrgs = {
 			slot: "plugins",
 			when: ["authz"],
 			content: [
-				"organization({",
-				"	organizationHooks: {",
-				"		// whoever creates an org administers it (pick another built-in role, or drop this)",
-				"		afterCreateOrganization: async ({ organization, member }) => {",
-				"			await authz.grantSystemRole(organization.id, member.userId, \"admin\", member.userId);",
-				"		},",
-				"		// authz roles and overlays go with the membership, so re-adding someone starts clean",
-				"		afterRemoveMember: async ({ member }) => {",
-				"			await authz.removeMemberAccess(member.organizationId, member.userId);",
-				"		},",
+				"organization(),",
+				"// better-auth keeps who is in which org (owner or member); authz decides what they may do.",
+				"// The creator gets admin (`creatorRole`). better-auth shows these lists, emails included,",
+				"// to any member: `endpoints` puts them behind an authz permission",
+				"authzPlugin(authz, {",
+				"	endpoints: {",
+				"		\"/organization/list-members\": \"member:read\",",
+				"		\"/organization/get-full-organization\": \"member:read\",",
+				"		\"/organization/list-invitations\": \"member:read\",",
 				"	},",
 				"}),",
 				"admin(),"
@@ -1566,7 +1582,7 @@ const authOrgs = {
 			file: "src/modules/users/services/auth.ts",
 			slot: "imports",
 			when: ["authz"],
-			content: "import { authz } from \"#core/authz/index\";"
+			content: "import { authzPlugin } from \"@tatara/authz/better-auth\";\nimport { authz } from \"#core/authz/index\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
@@ -3484,6 +3500,41 @@ const authzPackage = {
 	}
 };
 //#endregion
+//#region src/upgrade/codemods/authz-roles.ts
+const PATH = "src/core/authz/system-roles.ts";
+/** Adds `heldBy` to the role literal `{ key: "<key>", … }`, unless it has one. */
+function holdRole(text, key, heldBy) {
+	const start = text.search(new RegExp(`\\{\\s*key:\\s*"${key}"`));
+	if (start === -1) return text;
+	const end = text.indexOf("}", start);
+	if (end === -1) return text;
+	const literal = text.slice(start, end);
+	if (literal.includes("heldBy")) return text;
+	const body = literal.replace(/,?\s*$/, "");
+	return `${text.slice(0, start)}${body}, heldBy: "${heldBy}" ${text.slice(end)}`;
+}
+/** Roles only follow better-auth's member or user role where the app says so (`heldBy`). */
+const authzRoles = {
+	version: "0.13.0",
+	id: "authz-roles",
+	description: "Built-in roles say who holds them (heldBy); better-auth's member role is membership only",
+	async run(ctx) {
+		const { config } = ctx.project;
+		if (!config.addons.includes("authz")) return;
+		const text = await ctx.read(PATH).catch(() => void 0);
+		if (text !== void 0) {
+			let next = holdRole(text, "member", "members");
+			next = holdRole(next, "staff", "identity");
+			if (config.authMethods.includes("keycloak")) {
+				for (const [, key] of text.matchAll(/\{\s*key:\s*"([^"]+)"/g)) if (key && key !== "member") next = holdRole(next, key, "identity");
+			}
+			if (next !== text) await ctx.write(PATH, next);
+		}
+		ctx.report.notes.push("Built-in roles no longer follow better-auth's member role (or the user role, unless the role has heldBy: \"identity\"). Give access with authz roles (grantSystemRole, assignRole); `member` is held by every member (heldBy: \"members\").");
+		if (config.authMethods.includes("orgs")) ctx.report.notes.push("In src/modules/users/services/auth.ts, replace the organizationHooks that grant the creator's role and remove member access with authzPlugin(authz, { endpoints: { \"/organization/list-members\": \"member:read\", \"/organization/get-full-organization\": \"member:read\", \"/organization/list-invitations\": \"member:read\" } }) from @tatara/authz/better-auth, after organization(). It also keeps member roles to owner and member.");
+	}
+};
+//#endregion
 //#region src/upgrade/codemods/authz-stores.ts
 const group = {
 	name: "authz store",
@@ -3934,6 +3985,30 @@ const jobsDrivers = {
 	}
 };
 //#endregion
+//#region src/upgrade/codemods/notifier-roles.ts
+const NOTIFIER = "src/modules/notifications/services/notifier.ts";
+const TEST = "src/modules/notifications/tests/role-recipients.test.ts";
+/** `recipients.role` reads authz roles: better-auth's member role is only owner or member. */
+const notifierRoles = {
+	version: "0.13.1",
+	id: "notifier-roles",
+	description: "Notifying by role reaches holders of the authz role",
+	async run(ctx) {
+		const { config } = ctx.project;
+		const addons = config.addons;
+		if (!addons.includes("notifications") || !addons.includes("authz")) return;
+		if (!config.authMethods.includes("orgs")) return;
+		const text = await ctx.read(NOTIFIER).catch(() => void 0);
+		if (text === void 0) return;
+		if (await ctx.baseline.isUnchanged(NOTIFIER, text)) await ctx.regenerate(NOTIFIER);
+		else ctx.report.notes.push(`In ${NOTIFIER}, recipients.role should check authz roles: \`(await authz.effectivePermissions(who)).roles.includes(role)\` for each member, with who as in recipients.permission. Matching member.role finds nobody now that it is only owner or member.`);
+		if (await ctx.read(TEST).catch(() => void 0) === void 0) {
+			const test = await ctx.renderCurrent(TEST);
+			if (test !== void 0) await ctx.write(TEST, test);
+		}
+	}
+};
+//#endregion
 //#region src/upgrade/codemods/package-commands.ts
 /** Copies whose commands and seeds the packages contribute now (wired by `tatara sync`). */
 const COPIES = [
@@ -3985,7 +4060,9 @@ const CODEMODS = [
 	httpLimits,
 	jobsDrivers,
 	emailV2,
-	deployLedger
+	deployLedger,
+	authzRoles,
+	notifierRoles
 ];
 //#endregion
 //#region src/upgrade/context.ts

package/package.json

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

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

@@ -1,7 +1,10 @@
-/** Built-in roles. Add a key here, then grant it permissions in module permission files. */
+/**
+ * Built-in roles. Add a key here, then grant it permissions in module permission files. A role is
+ * held only by those it's assigned to, unless `heldBy` says every org member or an identity role.
+ */
 export const SYSTEM_ROLES = [
-	{ key: "admin", name: "Admin", description: "Full access, including roles and members." },
-	{ key: "member", name: "Member", description: "Default role for every member." },
+	// tatara:slot admin
+	{ key: "member", name: "Member", description: "Every member of the org.", heldBy: "members" },
 	// tatara:slot roles
 ] as const;
 

package/templates/features/notifications/files+auth-orgs+authz/src/modules/notifications/tests/role-recipients.test.ts

@@ -0,0 +1,34 @@
+import type { InlineDriver } from "@tatara/jobs";
+import { beforeEach, describe, expect, it } from "vitest";
+import { jobs } from "#core/jobs/index";
+import { notify } from "#modules/notifications/services/notifier";
+import { api } from "#tests/helpers/api";
+import { authenticate } from "#tests/helpers/auth";
+import { applyTestAccess } from "#tests/helpers/authz";
+import { resetDatabase } from "#tests/helpers/db";
+
+const drain = () => (jobs.driver as InlineDriver).drain();
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("notifying by role", () => {
+	it("reaches the members who hold the authz role, not better-auth's member role", async () => {
+		const admin = await authenticate();
+		await applyTestAccess(admin.userId, { systemRoles: ["admin"], orgId: admin.orgId });
+		const plain = await authenticate();
+		await notify({
+			orgId: admin.orgId as string,
+			to: { role: "admin" },
+			notification: "example.welcome",
+			data: { name: "Ada" },
+		});
+		await drain();
+		const count = async (headers: Record<string, string>) =>
+			(await api.get<{ data: { count: number } }>("/api/notifications/unread-count", { headers }))
+				.body.data.count;
+		expect(await count(admin.headers)).toBe(1);
+		expect(await count(plain.headers)).toBe(0);
+	});
+});

package/templates/versions.json

@@ -35,9 +35,9 @@
   "@tatara/http": "0.1.2",
   "@tatara/db": "0.2.2",
   "@tatara/testing": "0.1.1",
-  "@tatara/auth": "0.2.0",
+  "@tatara/auth": "0.2.1",
   "@tatara/keycloak": "0.1.2",
-  "@tatara/authz": "0.4.0",
+  "@tatara/authz": "0.5.0",
   "@tatara/storage": "0.2.0",
   "@tatara/email": "0.3.0",
   "@tatara/i18n": "0.1.0",