@tatara/cli 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,85 @@
+import type { OverlayEffect, Scope } from "#core/authz/constants";
+
+export interface PermissionGrant {
+	resource: string;
+	action: string;
+	scope: Scope | null;
+}
+
+export interface OverlayRow extends PermissionGrant {
+	id: string;
+	orgId: string;
+	userId: string;
+	effect: OverlayEffect;
+	grantedBy: string | null;
+	reason: string | null;
+	expiresAt: Date | null;
+	createdAt: Date;
+}
+
+export interface RoleRow {
+	id: string;
+	orgId: string;
+	key: string;
+	name: string;
+	description: string | null;
+	isSystem: boolean;
+	grants: PermissionGrant[];
+	memberCount: number;
+}
+
+export interface AuditRow {
+	id: string;
+	orgId: string;
+	actorId: string;
+	targetUserId: string | null;
+	changeType: string;
+	before: unknown;
+	after: unknown;
+	at: Date;
+}
+
+/** A member's resolved permissions in one org. */
+export interface EffectivePermissions {
+	grants: PermissionGrant[];
+	/** "resource:action:scope|*" keys denied by overlays; deny always wins */
+	denies: Set<string>;
+	roles: string[];
+}
+
+export function grantKey(grant: PermissionGrant): string {
+	return `${grant.resource}:${grant.action}:${grant.scope ?? "*"}`;
+}
+
+/** Everything authz reads and writes; implemented once per ORM in #core/authz/db/store. */
+export interface AuthzStore {
+	roleGrants(orgId: string, userId: string, impliedRoleKeys: string[]): Promise<{
+		roles: string[];
+		grants: PermissionGrant[];
+	}>;
+	activeOverlays(orgId: string, userId: string, now: Date): Promise<OverlayRow[]>;
+	listRoles(orgId: string): Promise<RoleRow[]>;
+	findRole(orgId: string, roleId: string): Promise<RoleRow | null>;
+	findRoleByKey(orgId: string, key: string): Promise<RoleRow | null>;
+	createRole(input: {
+		orgId: string;
+		key: string;
+		name: string;
+		description: string | null;
+		isSystem: boolean;
+		grants: PermissionGrant[];
+	}): Promise<string>;
+	updateRole(
+		roleId: string,
+		input: { name?: string; description?: string | null; grants?: PermissionGrant[] },
+	): Promise<void>;
+	deleteRole(roleId: string): Promise<void>;
+	memberRoles(orgId: string, userId: string): Promise<RoleRow[]>;
+	assignRole(orgId: string, userId: string, roleId: string, by: string | null): Promise<boolean>;
+	revokeRole(orgId: string, userId: string, roleId: string): Promise<boolean>;
+	listOverlays(orgId: string, userId: string): Promise<OverlayRow[]>;
+	addOverlay(input: Omit<OverlayRow, "id" | "createdAt">): Promise<string>;
+	removeOverlay(orgId: string, userId: string, overlayId: string): Promise<OverlayRow | null>;
+	writeAudit(input: Omit<AuditRow, "id" | "at">): Promise<void>;
+	listAudit(orgId: string, limit: number): Promise<AuditRow[]>;
+}

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

@@ -0,0 +1,99 @@
+import { z } from "@hono/zod-openapi";
+import { OVERLAY_EFFECTS, SCOPES } from "#core/authz/constants";
+
+export const grantSchema = z
+	.object({
+		resource: z.string().min(1),
+		action: z.string().min(1),
+		scope: z.enum(SCOPES).nullable().optional(),
+	})
+	.openapi("PermissionGrant");
+
+export const roleSchema = z
+	.object({
+		id: z.string(),
+		key: z.string(),
+		name: z.string(),
+		description: z.string().nullable(),
+		isSystem: z.boolean(),
+		grants: z.array(grantSchema),
+		memberCount: z.number().int(),
+	})
+	.openapi("Role");
+
+export const createRoleSchema = z
+	.object({
+		key: z
+			.string()
+			.regex(/^[a-z][a-z0-9_]{1,62}$/, "lowercase letters, digits and underscores"),
+		name: z.string().trim().min(1).max(120),
+		description: z.string().max(1000).nullable().optional(),
+		grants: z.array(grantSchema).default([]),
+	})
+	.openapi("CreateRole");
+
+export const updateRoleSchema = createRoleSchema.omit({ key: true }).partial().openapi("UpdateRole");
+
+export const overlayInputSchema = z
+	.object({
+		resource: z.string().min(1),
+		action: z.string().min(1),
+		scope: z.enum(SCOPES).nullable().optional(),
+		effect: z.enum(OVERLAY_EFFECTS),
+		reason: z.string().max(500).nullable().optional(),
+		expiresAt: z.iso.datetime().nullable().optional(),
+	})
+	.openapi("OverlayInput");
+
+export const overlaySchema = z
+	.object({
+		id: z.string(),
+		resource: z.string(),
+		action: z.string(),
+		scope: z.enum(SCOPES).nullable(),
+		effect: z.enum(OVERLAY_EFFECTS),
+		reason: z.string().nullable(),
+		expiresAt: z.string().nullable(),
+	})
+	.openapi("Overlay");
+
+export const memberSchema = z
+	.object({
+		userId: z.string(),
+		orgId: z.string(),
+		roles: z.array(roleSchema),
+		overlays: z.array(overlaySchema),
+	})
+	.openapi("Member");
+
+export const myPermissionsSchema = z
+	.object({
+		orgId: z.string(),
+		roles: z.array(z.string()),
+		grants: z.array(grantSchema),
+		denies: z.array(z.string()),
+	})
+	.openapi("MyPermissions");
+
+export const auditEntrySchema = z
+	.object({
+		id: z.string(),
+		actorId: z.string(),
+		targetUserId: z.string().nullable(),
+		changeType: z.string(),
+		before: z.unknown(),
+		after: z.unknown(),
+		at: z.string(),
+	})
+	.openapi("AuditEntry");
+
+export const idParams = z.object({ id: z.string().openapi({ param: { name: "id", in: "path" } }) });
+export const userParams = z.object({
+	userId: z.string().openapi({ param: { name: "userId", in: "path" } }),
+});
+export const userRoleParams = userParams.extend({
+	roleId: z.string().openapi({ param: { name: "roleId", in: "path" } }),
+});
+export const userOverlayParams = userParams.extend({
+	overlayId: z.string().openapi({ param: { name: "overlayId", in: "path" } }),
+});

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

@@ -0,0 +1,30 @@
+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 type { SystemRoleKey } from "#core/authz/system-roles";
+import type { PermissionKey } from "#generated/permissions";
+
+export interface TestAccess {
+	/** unscoped permissions granted directly (as overlays) */
+	permissions?: PermissionKey[];
+	/** built-in roles assigned in the org */
+	systemRoles?: SystemRoleKey[];
+	orgId?: string;
+}
+
+export async function applyTestAccess(userId: string, access: TestAccess): Promise<void> {
+	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" });
+	}
+	if (access.systemRoles?.length) {
+		await syncSystemRoles();
+		for (const roleKey of access.systemRoles) {
+			const role = await store.findRoleByKey(SYSTEM_ORG_ID, roleKey);
+			if (!role) throw new Error(`Unknown built-in role ${roleKey}`);
+			await assignRole(null, orgId, userId, role.id);
+		}
+	}
+}

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

@@ -0,0 +1,262 @@
+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 {
+	authzAuditLog,
+	authzMemberRoles,
+	authzOverlays,
+	authzRolePermissions,
+	authzRoles,
+} from "#core/authz/db/authz.schema";
+import type { AuthzStore, OverlayRow, PermissionGrant, RoleRow } from "#core/authz/types";
+import { db } from "#core/db/client";
+import { newId } from "#core/db/id";
+
+const toScope = (scope: string): Scope | null => (scope === "" ? null : (scope as Scope));
+
+type RoleRecord = typeof authzRoles.$inferSelect;
+type OverlayRecord = typeof authzOverlays.$inferSelect;
+
+function toOverlay(row: OverlayRecord): OverlayRow {
+	return { ...row, scope: toScope(row.scope), effect: row.effect as OverlayEffect };
+}
+
+async function hydrate(roles: RoleRecord[], orgId: string): Promise<RoleRow[]> {
+	if (roles.length === 0) return [];
+	const ids = roles.map((r) => r.id);
+	const [grants, members] = await Promise.all([
+		db.select().from(authzRolePermissions).where(inArray(authzRolePermissions.roleId, ids)),
+		db
+			.select({ roleId: authzMemberRoles.roleId, total: count() })
+			.from(authzMemberRoles)
+			.where(and(eq(authzMemberRoles.orgId, orgId), inArray(authzMemberRoles.roleId, ids)))
+			.groupBy(authzMemberRoles.roleId),
+	]);
+	return roles.map((role) => ({
+		id: role.id,
+		orgId: role.orgId,
+		key: role.key,
+		name: role.name,
+		description: role.description,
+		isSystem: role.isSystem,
+		grants: grants
+			.filter((g) => g.roleId === role.id)
+			.map((g) => ({ resource: g.resource, action: g.action, scope: toScope(g.scope) })),
+		memberCount: members.find((m) => m.roleId === role.id)?.total ?? 0,
+	}));
+}
+
+const visibleTo = (orgId: string) => or(eq(authzRoles.orgId, SYSTEM_ORG_ID), eq(authzRoles.orgId, orgId));
+
+async function insertGrants(roleId: string, grants: PermissionGrant[]) {
+	if (grants.length === 0) return;
+	await db.insert(authzRolePermissions).values(
+		grants.map((g) => ({
+			id: newId(),
+			roleId,
+			resource: g.resource,
+			action: g.action,
+			scope: g.scope ?? "",
+		})),
+	);
+}
+
+export const store: AuthzStore = {
+	async roleGrants(orgId, userId, impliedRoleKeys) {
+		const assigned = await db
+			.select({ roleId: authzMemberRoles.roleId })
+			.from(authzMemberRoles)
+			.where(and(eq(authzMemberRoles.orgId, orgId), eq(authzMemberRoles.userId, userId)));
+		const implied = impliedRoleKeys.length
+			? await db
+					.select({ id: authzRoles.id })
+					.from(authzRoles)
+					.where(and(eq(authzRoles.orgId, SYSTEM_ORG_ID), inArray(authzRoles.key, impliedRoleKeys)))
+			: [];
+		const roleIds = [...new Set([...assigned.map((r) => r.roleId), ...implied.map((r) => r.id)])];
+		if (roleIds.length === 0) return { roles: [], grants: [] };
+		const [roles, grants] = await Promise.all([
+			db.select({ key: authzRoles.key }).from(authzRoles).where(inArray(authzRoles.id, roleIds)),
+			db.select().from(authzRolePermissions).where(inArray(authzRolePermissions.roleId, roleIds)),
+		]);
+		return {
+			roles: roles.map((r) => r.key),
+			grants: grants.map((g) => ({ resource: g.resource, action: g.action, scope: toScope(g.scope) })),
+		};
+	},
+
+	async activeOverlays(orgId, userId, now) {
+		const rows = await db
+			.select()
+			.from(authzOverlays)
+			.where(
+				and(
+					eq(authzOverlays.orgId, orgId),
+					eq(authzOverlays.userId, userId),
+					or(isNull(authzOverlays.expiresAt), gt(authzOverlays.expiresAt, now)),
+				),
+			);
+		return rows.map(toOverlay);
+	},
+
+	async listRoles(orgId) {
+		const roles = await db.select().from(authzRoles).where(visibleTo(orgId)).orderBy(authzRoles.key);
+		return hydrate(roles, orgId);
+	},
+
+	async findRole(orgId, roleId) {
+		const roles = await db
+			.select()
+			.from(authzRoles)
+			.where(and(eq(authzRoles.id, roleId), visibleTo(orgId)));
+		return (await hydrate(roles, orgId))[0] ?? null;
+	},
+
+	async findRoleByKey(orgId, key) {
+		const roles = await db
+			.select()
+			.from(authzRoles)
+			.where(and(eq(authzRoles.key, key), eq(authzRoles.orgId, orgId)));
+		return (await hydrate(roles, orgId))[0] ?? null;
+	},
+
+	async createRole(input) {
+		const id = newId();
+		await db.insert(authzRoles).values({
+			id,
+			orgId: input.orgId,
+			key: input.key,
+			name: input.name,
+			description: input.description,
+			isSystem: input.isSystem,
+		});
+		await insertGrants(id, input.grants);
+		return id;
+	},
+
+	async updateRole(roleId, input) {
+		const fields = {
+			...(input.name === undefined ? {} : { name: input.name }),
+			...(input.description === undefined ? {} : { description: input.description }),
+		};
+		await db
+			.update(authzRoles)
+			.set({ ...fields, updatedAt: new Date() })
+			.where(eq(authzRoles.id, roleId));
+		if (input.grants) {
+			await db.delete(authzRolePermissions).where(eq(authzRolePermissions.roleId, roleId));
+			await insertGrants(roleId, input.grants);
+		}
+	},
+
+	async deleteRole(roleId) {
+		await db.delete(authzRoles).where(eq(authzRoles.id, roleId));
+	},
+
+	async memberRoles(orgId, userId) {
+		const assigned = await db
+			.select({ roleId: authzMemberRoles.roleId })
+			.from(authzMemberRoles)
+			.where(and(eq(authzMemberRoles.orgId, orgId), eq(authzMemberRoles.userId, userId)));
+		if (assigned.length === 0) return [];
+		const roles = await db
+			.select()
+			.from(authzRoles)
+			.where(inArray(authzRoles.id, assigned.map((a) => a.roleId)));
+		return hydrate(roles, orgId);
+	},
+
+	async assignRole(orgId, userId, roleId, by) {
+		const existing = await db
+			.select({ id: authzMemberRoles.id })
+			.from(authzMemberRoles)
+			.where(
+				and(
+					eq(authzMemberRoles.orgId, orgId),
+					eq(authzMemberRoles.userId, userId),
+					eq(authzMemberRoles.roleId, roleId),
+				),
+			);
+		if (existing.length > 0) return false;
+		await db.insert(authzMemberRoles).values({ id: newId(), orgId, userId, roleId, assignedBy: by });
+		return true;
+	},
+
+	async revokeRole(orgId, userId, roleId) {
+		const where = and(
+			eq(authzMemberRoles.orgId, orgId),
+			eq(authzMemberRoles.userId, userId),
+			eq(authzMemberRoles.roleId, roleId),
+		);
+		const existing = await db.select({ id: authzMemberRoles.id }).from(authzMemberRoles).where(where);
+		if (existing.length === 0) return false;
+		await db.delete(authzMemberRoles).where(where);
+		return true;
+	},
+
+	async listOverlays(orgId, userId) {
+		const rows = await db
+			.select()
+			.from(authzOverlays)
+			.where(and(eq(authzOverlays.orgId, orgId), eq(authzOverlays.userId, userId)))
+			.orderBy(desc(authzOverlays.createdAt));
+		return rows.map(toOverlay);
+	},
+
+	async addOverlay(input) {
+		const id = newId();
+		const scope = input.scope ?? "";
+		await db
+			.delete(authzOverlays)
+			.where(
+				and(
+					eq(authzOverlays.orgId, input.orgId),
+					eq(authzOverlays.userId, input.userId),
+					eq(authzOverlays.resource, input.resource),
+					eq(authzOverlays.action, input.action),
+					eq(authzOverlays.scope, scope),
+					eq(authzOverlays.effect, input.effect),
+				),
+			);
+		await db.insert(authzOverlays).values({ ...input, id, scope });
+		return id;
+	},
+
+	async removeOverlay(orgId, userId, overlayId) {
+		const where = and(
+			eq(authzOverlays.orgId, orgId),
+			eq(authzOverlays.userId, userId),
+			eq(authzOverlays.id, overlayId),
+		);
+		const [row] = await db.select().from(authzOverlays).where(where);
+		if (!row) return null;
+		await db.delete(authzOverlays).where(where);
+		return toOverlay(row);
+	},
+
+	async writeAudit(input) {
+		await db.insert(authzAuditLog).values({
+			id: newId(),
+			orgId: input.orgId,
+			actorId: input.actorId,
+			targetUserId: input.targetUserId,
+			changeType: input.changeType,
+			before: input.before === undefined ? null : JSON.stringify(input.before),
+			after: input.after === undefined ? null : JSON.stringify(input.after),
+		});
+	},
+
+	async listAudit(orgId, limit) {
+		const rows = await db
+			.select()
+			.from(authzAuditLog)
+			.where(eq(authzAuditLog.orgId, orgId))
+			.orderBy(desc(authzAuditLog.id))
+			.limit(limit);
+		return rows.map((r) => ({
+			...r,
+			before: r.before ? (JSON.parse(r.before) as unknown) : null,
+			after: r.after ? (JSON.parse(r.after) as unknown) : null,
+		}));
+	},
+};

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

@@ -0,0 +1,90 @@
+import { boolean, index, mysqlTable, text, timestamp, uniqueIndex, varchar } from "drizzle-orm/mysql-core";
+
+const ts = () => timestamp({ fsp: 3, mode: "date" });
+const id = () => varchar({ length: 36 });
+const ref = () => varchar({ length: 255 });
+
+/** Built-in roles have orgId "" (they apply to every org); custom roles belong to one org. */
+export const authzRoles = mysqlTable(
+	"authz_roles",
+	{
+		id: id().primaryKey(),
+		orgId: ref().notNull().default(""),
+		key: varchar({ length: 64 }).notNull(),
+		name: varchar({ length: 120 }).notNull(),
+		description: text(),
+		isSystem: boolean().notNull().default(false),
+		createdAt: ts().notNull().defaultNow(),
+		updatedAt: ts().notNull().defaultNow(),
+	},
+	(t) => [uniqueIndex("authz_roles_org_key").on(t.orgId, t.key)],
+);
+
+/** scope "" means the action is unscoped (keeps unique keys identical on every database). */
+export const authzRolePermissions = mysqlTable(
+	"authz_role_permissions",
+	{
+		id: id().primaryKey(),
+		roleId: id()
+			.notNull()
+			.references(() => authzRoles.id, { onDelete: "cascade" }),
+		resource: varchar({ length: 64 }).notNull(),
+		action: varchar({ length: 64 }).notNull(),
+		scope: varchar({ length: 16 }).notNull().default(""),
+	},
+	(t) => [uniqueIndex("authz_role_permissions_grant").on(t.roleId, t.resource, t.action, t.scope)],
+);
+
+export const authzMemberRoles = mysqlTable(
+	"authz_member_roles",
+	{
+		id: id().primaryKey(),
+		orgId: ref().notNull(),
+		userId: ref().notNull(),
+		roleId: id()
+			.notNull()
+			.references(() => authzRoles.id, { onDelete: "cascade" }),
+		assignedBy: ref(),
+		assignedAt: ts().notNull().defaultNow(),
+	},
+	(t) => [
+		uniqueIndex("authz_member_roles_member_role").on(t.orgId, t.userId, t.roleId),
+		index("authz_member_roles_member").on(t.orgId, t.userId),
+	],
+);
+
+export const authzOverlays = mysqlTable(
+	"authz_overlays",
+	{
+		id: id().primaryKey(),
+		orgId: ref().notNull(),
+		userId: ref().notNull(),
+		resource: varchar({ length: 64 }).notNull(),
+		action: varchar({ length: 64 }).notNull(),
+		scope: varchar({ length: 16 }).notNull().default(""),
+		effect: varchar({ length: 8 }).notNull(),
+		grantedBy: ref(),
+		reason: text(),
+		expiresAt: ts(),
+		createdAt: ts().notNull().defaultNow(),
+	},
+	(t) => [
+		uniqueIndex("authz_overlays_grant").on(t.orgId, t.userId, t.resource, t.action, t.scope, t.effect),
+		index("authz_overlays_member").on(t.orgId, t.userId),
+	],
+);
+
+export const authzAuditLog = mysqlTable(
+	"authz_audit_log",
+	{
+		id: id().primaryKey(),
+		orgId: ref().notNull(),
+		actorId: ref().notNull(),
+		targetUserId: ref(),
+		changeType: varchar({ length: 48 }).notNull(),
+		before: text(),
+		after: text(),
+		at: ts().notNull().defaultNow(),
+	},
+	(t) => [index("authz_audit_log_org_at").on(t.orgId, t.at)],
+);

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

@@ -0,0 +1,88 @@
+import { boolean, index, pgTable, text, timestamp, uniqueIndex, varchar } from "drizzle-orm/pg-core";
+
+const ts = () => timestamp({ withTimezone: true, mode: "date" });
+
+/** Built-in roles have orgId "" (they apply to every org); custom roles belong to one org. */
+export const authzRoles = pgTable(
+	"authz_roles",
+	{
+		id: text().primaryKey(),
+		orgId: text().notNull().default(""),
+		key: varchar({ length: 64 }).notNull(),
+		name: varchar({ length: 120 }).notNull(),
+		description: text(),
+		isSystem: boolean().notNull().default(false),
+		createdAt: ts().notNull().defaultNow(),
+		updatedAt: ts().notNull().defaultNow(),
+	},
+	(t) => [uniqueIndex("authz_roles_org_key").on(t.orgId, t.key)],
+);
+
+/** scope "" means the action is unscoped (keeps unique keys identical on every database). */
+export const authzRolePermissions = pgTable(
+	"authz_role_permissions",
+	{
+		id: text().primaryKey(),
+		roleId: text()
+			.notNull()
+			.references(() => authzRoles.id, { onDelete: "cascade" }),
+		resource: varchar({ length: 64 }).notNull(),
+		action: varchar({ length: 64 }).notNull(),
+		scope: varchar({ length: 16 }).notNull().default(""),
+	},
+	(t) => [uniqueIndex("authz_role_permissions_grant").on(t.roleId, t.resource, t.action, t.scope)],
+);
+
+export const authzMemberRoles = pgTable(
+	"authz_member_roles",
+	{
+		id: text().primaryKey(),
+		orgId: text().notNull(),
+		userId: text().notNull(),
+		roleId: text()
+			.notNull()
+			.references(() => authzRoles.id, { onDelete: "cascade" }),
+		assignedBy: text(),
+		assignedAt: ts().notNull().defaultNow(),
+	},
+	(t) => [
+		uniqueIndex("authz_member_roles_member_role").on(t.orgId, t.userId, t.roleId),
+		index("authz_member_roles_member").on(t.orgId, t.userId),
+	],
+);
+
+export const authzOverlays = pgTable(
+	"authz_overlays",
+	{
+		id: text().primaryKey(),
+		orgId: text().notNull(),
+		userId: text().notNull(),
+		resource: varchar({ length: 64 }).notNull(),
+		action: varchar({ length: 64 }).notNull(),
+		scope: varchar({ length: 16 }).notNull().default(""),
+		effect: varchar({ length: 8 }).notNull(),
+		grantedBy: text(),
+		reason: text(),
+		expiresAt: ts(),
+		createdAt: ts().notNull().defaultNow(),
+	},
+	(t) => [
+		uniqueIndex("authz_overlays_grant").on(t.orgId, t.userId, t.resource, t.action, t.scope, t.effect),
+		index("authz_overlays_member").on(t.orgId, t.userId),
+	],
+);
+
+export const authzAuditLog = pgTable(
+	"authz_audit_log",
+	{
+		id: text().primaryKey(),
+		orgId: text().notNull(),
+		actorId: text().notNull(),
+		targetUserId: text(),
+		changeType: varchar({ length: 48 }).notNull(),
+		before: text(),
+		after: text(),
+		at: ts().notNull().defaultNow(),
+	},
+	(t) => [index("authz_audit_log_org_at").on(t.orgId, t.at)],
+);