@tatara/cli 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,281 @@
+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, jsonContent, success, successSchema } from "#core/http/response";
+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,
+});
+
+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: jsonContent(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: jsonContent(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: jsonContent(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: jsonContent(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/services/audit.ts

@@ -0,0 +1,24 @@
+import type { AuditChangeType } from "#core/authz/constants";
+import { store } from "#core/authz/db/store";
+
+export async function audit(input: {
+	orgId: string;
+	actorId: string;
+	targetUserId?: string | null;
+	changeType: AuditChangeType;
+	before?: unknown;
+	after?: unknown;
+}): Promise<void> {
+	await store.writeAudit({
+		orgId: input.orgId,
+		actorId: input.actorId,
+		targetUserId: input.targetUserId ?? null,
+		changeType: input.changeType,
+		before: input.before,
+		after: input.after,
+	});
+}
+
+export function listAudit(orgId: string, limit = 50) {
+	return store.listAudit(orgId, limit);
+}

package/templates/features/authz/files/src/core/authz/services/grants.ts

@@ -0,0 +1,29 @@
+import { assertGrantValid, InvalidGrantError, META_RESOURCES } from "#core/authz/catalog";
+import type { Scope } from "#core/authz/constants";
+import type { PermissionGrant } from "#core/authz/types";
+import { BusinessRuleError } from "#core/http/errors";
+import { catalog } from "#generated/permissions";
+
+/** Validates grants against the catalog; custom roles and overlays may not grant meta resources. */
+export function validateGrants(
+	grants: { resource: string; action: string; scope?: string | null }[],
+	options: { allowMeta: boolean },
+): PermissionGrant[] {
+	return grants.map((grant) => {
+		try {
+			assertGrantValid(catalog, grant);
+		} catch (error) {
+			if (error instanceof InvalidGrantError) {
+				throw new BusinessRuleError("INVALID_GRANT", error.message);
+			}
+			throw error;
+		}
+		if (!options.allowMeta && META_RESOURCES.has(grant.resource)) {
+			throw new BusinessRuleError(
+				"META_GRANT_FORBIDDEN",
+				`${grant.resource}:${grant.action} can only be granted by built-in roles`,
+			);
+		}
+		return { resource: grant.resource, action: grant.action, scope: (grant.scope as Scope) ?? null };
+	});
+}

package/templates/features/authz/files/src/core/authz/services/members.ts

@@ -0,0 +1,68 @@
+import { invalidateMember } from "#core/authz/cache";
+import type { OverlayEffect, Scope } from "#core/authz/constants";
+import { store } from "#core/authz/db/store";
+import { audit } from "#core/authz/services/audit";
+import { validateGrants } from "#core/authz/services/grants";
+import { NotFoundError } from "#core/http/errors";
+
+export async function getMember(orgId: string, userId: string) {
+	const [roles, overlays] = await Promise.all([
+		store.memberRoles(orgId, userId),
+		store.listOverlays(orgId, userId),
+	]);
+	return { userId, orgId, roles, overlays };
+}
+
+export async function assignRole(actorId: string | null, orgId: string, userId: string, roleId: string) {
+	const role = await store.findRole(orgId, roleId);
+	if (!role) throw new NotFoundError("Role");
+	const added = await store.assignRole(orgId, userId, roleId, actorId);
+	invalidateMember(userId, orgId);
+	if (added && actorId) {
+		await audit({ orgId, actorId, targetUserId: userId, changeType: "member_role_assigned", after: { roleId, key: role.key } });
+	}
+	return added;
+}
+
+export async function revokeRole(actorId: string, orgId: string, userId: string, roleId: string) {
+	const removed = await store.revokeRole(orgId, userId, roleId);
+	if (!removed) throw new NotFoundError("Role assignment");
+	invalidateMember(userId, orgId);
+	await audit({ orgId, actorId, targetUserId: userId, changeType: "member_role_revoked", before: { roleId } });
+}
+
+export interface OverlayInput {
+	resource: string;
+	action: string;
+	scope?: Scope | null;
+	effect: OverlayEffect;
+	reason?: string | null;
+	expiresAt?: Date | null;
+}
+
+/** Per-user grant or deny, optionally expiring. Deny always wins over any grant. */
+export async function addOverlay(actorId: string | null, orgId: string, userId: string, input: OverlayInput) {
+	const [grant] = validateGrants([input], { allowMeta: input.effect === "deny" });
+	if (!grant) throw new NotFoundError("Permission");
+	const id = await store.addOverlay({
+		orgId,
+		userId,
+		...grant,
+		effect: input.effect,
+		grantedBy: actorId,
+		reason: input.reason ?? null,
+		expiresAt: input.expiresAt ?? null,
+	});
+	invalidateMember(userId, orgId);
+	if (actorId) {
+		await audit({ orgId, actorId, targetUserId: userId, changeType: "overlay_granted", after: { id, ...grant, effect: input.effect } });
+	}
+	return id;
+}
+
+export async function removeOverlay(actorId: string, orgId: string, userId: string, overlayId: string) {
+	const removed = await store.removeOverlay(orgId, userId, overlayId);
+	if (!removed) throw new NotFoundError("Overlay");
+	invalidateMember(userId, orgId);
+	await audit({ orgId, actorId, targetUserId: userId, changeType: "overlay_revoked", before: removed });
+}

package/templates/features/authz/files/src/core/authz/services/roles.ts

@@ -0,0 +1,73 @@
+import { invalidateAll } from "#core/authz/cache";
+import { store } from "#core/authz/db/store";
+import { audit } from "#core/authz/services/audit";
+import { validateGrants } from "#core/authz/services/grants";
+import { SYSTEM_ROLE_KEYS } from "#core/authz/system-roles";
+import type { RoleRow } from "#core/authz/types";
+import { BusinessRuleError, ConflictError, NotFoundError } from "#core/http/errors";
+
+export interface RoleInput {
+	key: string;
+	name: string;
+	description?: string | null;
+	grants: { resource: string; action: string; scope?: string | null }[];
+}
+
+export function listRoles(orgId: string): Promise<RoleRow[]> {
+	return store.listRoles(orgId);
+}
+
+async function customRole(orgId: string, roleId: string): Promise<RoleRow> {
+	const role = await store.findRole(orgId, roleId);
+	if (!role) throw new NotFoundError("Role");
+	if (role.isSystem) throw new BusinessRuleError("SYSTEM_ROLE_IMMUTABLE", "Built-in roles cannot be changed");
+	return role;
+}
+
+export async function createRole(actorId: string, orgId: string, input: RoleInput): Promise<RoleRow> {
+	if (SYSTEM_ROLE_KEYS.has(input.key)) {
+		throw new ConflictError(`"${input.key}" is a built-in role key`);
+	}
+	if (await store.findRoleByKey(orgId, input.key)) throw new ConflictError(`Role "${input.key}" exists`);
+	const grants = validateGrants(input.grants, { allowMeta: false });
+	const id = await store.createRole({
+		orgId,
+		key: input.key,
+		name: input.name,
+		description: input.description ?? null,
+		isSystem: false,
+		grants,
+	});
+	const role = await store.findRole(orgId, id);
+	if (!role) throw new NotFoundError("Role");
+	await audit({ orgId, actorId, changeType: "role_created", after: role });
+	return role;
+}
+
+export async function updateRole(
+	actorId: string,
+	orgId: string,
+	roleId: string,
+	input: Partial<Omit<RoleInput, "key">>,
+): Promise<RoleRow> {
+	const before = await customRole(orgId, roleId);
+	await store.updateRole(roleId, {
+		...(input.name === undefined ? {} : { name: input.name }),
+		...(input.description === undefined ? {} : { description: input.description }),
+		...(input.grants ? { grants: validateGrants(input.grants, { allowMeta: false }) } : {}),
+	});
+	invalidateAll();
+	const after = await customRole(orgId, roleId);
+	await audit({ orgId, actorId, changeType: "role_updated", before, after });
+	return after;
+}
+
+export async function deleteRole(actorId: string, orgId: string, roleId: string): Promise<void> {
+	const role = await customRole(orgId, roleId);
+	if (role.memberCount > 0) {
+		throw new ConflictError(`Role "${role.key}" is assigned to ${role.memberCount} member(s)`);
+	}
+	await store.deleteRole(roleId);
+	invalidateAll();
+	await audit({ orgId, actorId, changeType: "role_deleted", before: role });
+}

package/templates/features/authz/files/src/core/authz/services/sync.ts

@@ -0,0 +1,34 @@
+import { invalidateAll } from "#core/authz/cache";
+import { SYSTEM_ORG_ID } from "#core/authz/constants";
+import { store } from "#core/authz/db/store";
+import { validateGrants } from "#core/authz/services/grants";
+import { SYSTEM_ROLES } from "#core/authz/system-roles";
+import { grantKey } from "#core/authz/types";
+import { catalog } from "#generated/permissions";
+
+/** Creates or updates every built-in role so its grants match the code. Idempotent. */
+export async function syncSystemRoles(): Promise<{ created: string[]; updated: string[] }> {
+	const created: string[] = [];
+	const updated: string[] = [];
+	for (const meta of SYSTEM_ROLES) {
+		const grants = validateGrants(
+			(catalog.roleGrants[meta.key] ?? []).map(([resource, action, scope]) => ({ resource, action, scope })),
+			{ allowMeta: true },
+		);
+		const existing = await store.findRoleByKey(SYSTEM_ORG_ID, meta.key);
+		if (!existing) {
+			await store.createRole({ orgId: SYSTEM_ORG_ID, key: meta.key, name: meta.name, description: meta.description, isSystem: true, grants });
+			created.push(meta.key);
+			continue;
+		}
+		const want = new Set(grants.map(grantKey));
+		const have = new Set(existing.grants.map(grantKey));
+		const same = want.size === have.size && [...want].every((k) => have.has(k));
+		if (!same || existing.name !== meta.name || existing.description !== meta.description) {
+			await store.updateRole(existing.id, { name: meta.name, description: meta.description, grants });
+			updated.push(meta.key);
+		}
+	}
+	if (created.length || updated.length) invalidateAll();
+	return { created, updated };
+}

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

@@ -0,0 +1,9 @@
+/** Built-in roles. Add a key here, then grant it permissions in module permission files. */
+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." },
+] 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

@@ -0,0 +1,146 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { allows } from "#core/authz/resolver";
+import type { EffectivePermissions } from "#core/authz/types";
+import { api } from "#tests/helpers/api";
+import { asUser, authenticate } from "#tests/helpers/auth";
+import { applyTestAccess } from "#tests/helpers/authz";
+import { resetDatabase } from "#tests/helpers/db";
+
+const set = (grants: EffectivePermissions["grants"], denies: string[] = []): EffectivePermissions => ({
+	grants,
+	denies: new Set(denies),
+	roles: [],
+});
+
+describe("resolver", () => {
+	it("lets a deny overlay win over any grant", () => {
+		const p = set([{ resource: "role", action: "read", scope: null }], ["role:read:*"]);
+		expect(allows(p, "role", "read")).toBe(false);
+	});
+
+	it("does not let a denied wide grant satisfy a narrower check", () => {
+		const p = set([{ resource: "doc", action: "read", scope: "org" }], ["doc:read:org"]);
+		expect(allows(p, "doc", "read", "team")).toBe(false);
+		expect(allows(p, "doc", "read")).toBe(false);
+	});
+
+	it("honours the scope hierarchy org > team > own", () => {
+		const p = set([{ resource: "doc", action: "read", scope: "team" }]);
+		expect(allows(p, "doc", "read", "own")).toBe(true);
+		expect(allows(p, "doc", "read", "team")).toBe(true);
+		expect(allows(p, "doc", "read", "org")).toBe(false);
+	});
+});
+
+describe("/api/authorization", () => {
+	beforeEach(async () => {
+		await resetDatabase();
+	});
+
+	it("forbids listing roles without role:read", async () => {
+		const res = await api.get("/api/authorization/roles", { headers: await asUser() });
+		expect(res.status).toBe(403);
+	});
+
+	it("lets an admin list built-in roles", async () => {
+		const res = await api.get<{ data: { key: string; isSystem: boolean }[] }>(
+			"/api/authorization/roles",
+			{ headers: await asUser({ systemRoles: ["admin"] }) },
+		);
+		expect(res.status).toBe(200);
+		expect(res.body.data.filter((r) => r.isSystem).map((r) => r.key)).toEqual(["admin", "member"]);
+	});
+
+	it("rejects custom roles that grant authorization itself", async () => {
+		const res = await api.post(
+			"/api/authorization/roles",
+			{ key: "sneaky", name: "Sneaky", grants: [{ resource: "role", action: "update" }] },
+			{ headers: await asUser({ systemRoles: ["admin"] }) },
+		);
+		expect(res.status).toBe(400);
+		expect(res.body).toMatchObject({ code: "META_GRANT_FORBIDDEN" });
+	});
+
+	it("creates, assigns and audits a custom role", async () => {
+		const headers = await asUser({ systemRoles: ["admin"] });
+		const created = await api.post<{ data: { id: string } }>(
+			"/api/authorization/roles",
+			{ key: "auditor", name: "Auditor", grants: [] },
+			{ headers },
+		);
+		expect(created.status).toBe(201);
+		const member = await authenticate();
+		const assigned = await api.post(
+			`/api/authorization/members/${member.userId}/roles`,
+			{ roleId: created.body.data.id },
+			{ headers },
+		);
+		expect(assigned.status).toBe(200);
+		const read = await api.get<{ data: { roles: { key: string }[] } }>(
+			`/api/authorization/members/${member.userId}`,
+			{ headers },
+		);
+		expect(read.body.data.roles.map((r) => r.key)).toEqual(["auditor"]);
+		const audit = await api.get<{ data: { changeType: string }[] }>("/api/authorization/audit", {
+			headers,
+		});
+		expect(audit.body.data.map((a) => a.changeType)).toEqual(["member_role_assigned", "role_created"]);
+	});
+
+	it("denies a permission with an overlay even when a role grants it", async () => {
+		const member = await authenticate();
+		await applyTestAccess(member.userId, { systemRoles: ["admin"] });
+		const admin = await asUser({ systemRoles: ["admin"] });
+		const denied = await api.post(
+			`/api/authorization/members/${member.userId}/overlays`,
+			{ resource: "role", action: "read", effect: "deny" },
+			{ headers: admin },
+		);
+		expect(denied.status).toBe(201);
+		const res = await api.get("/api/authorization/roles", { headers: member.headers });
+		expect(res.status).toBe(403);
+	});
+
+	it("only removes an overlay for the member in the URL", async () => {
+		const admin = await asUser({ systemRoles: ["admin"] });
+		const alice = await authenticate();
+		const bob = await authenticate();
+		const created = await api.post<{ data: { id: string } }>(
+			`/api/authorization/members/${alice.userId}/overlays`,
+			{ resource: "role", action: "read", effect: "deny" },
+			{ headers: admin },
+		);
+		const wrong = await api.delete(
+			`/api/authorization/members/${bob.userId}/overlays/${created.body.data.id}`,
+			{ headers: admin },
+		);
+		expect(wrong.status).toBe(404);
+		const member = await api.get<{ data: { overlays: { id: string }[] } }>(
+			`/api/authorization/members/${alice.userId}`,
+			{ headers: admin },
+		);
+		expect(member.body.data.overlays.map((o) => o.id)).toEqual([created.body.data.id]);
+	});
+
+	it("reports the caller's effective permissions", async () => {
+		const res = await api.get<{ data: { roles: string[]; grants: { resource: string }[] } }>(
+			"/api/authorization/me",
+			{ headers: await asUser({ systemRoles: ["admin"] }) },
+		);
+		expect(res.status).toBe(200);
+		expect(res.body.data.roles).toEqual(["admin"]);
+		expect(res.body.data.grants.map((g) => g.resource)).toContain("audit_log");
+	});
+
+	it("never lets an overlay grant authorization itself", async () => {
+		const admin = await asUser({ systemRoles: ["admin"] });
+		const member = await authenticate();
+		const res = await api.post(
+			`/api/authorization/members/${member.userId}/overlays`,
+			{ resource: "role", action: "update", effect: "grant" },
+			{ headers: admin },
+		);
+		expect(res.status).toBe(400);
+		expect(res.body).toMatchObject({ code: "META_GRANT_FORBIDDEN" });
+	});
+});