@tatara/cli 0.5.0 → 0.6.0

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 "@tatara/auth";
-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/generators/permission/files/src/modules/__moduleKebab__/permissions/__nameKebab__.permissions.ts

@@ -1,4 +1,4 @@
-import { definePermissions } from "#core/authz/catalog";
+import { definePermissions } from "@tatara/authz";
 
 export default definePermissions({
 	resources: {

package/templates/generators/resource/files+authz/src/modules/__moduleKebab__/permissions/__nameKebab__.permissions.ts

@@ -1,4 +1,4 @@
-import { definePermissions } from "#core/authz/catalog";
+import { definePermissions } from "@tatara/authz";
 
 export default definePermissions({
 	resources: {

package/templates/generators/route/files+authz/src/modules/__moduleKebab__/permissions/__nameKebab__.permissions.ts

@@ -1,4 +1,4 @@
-import { definePermissions } from "#core/authz/catalog";
+import { definePermissions } from "@tatara/authz";
 
 export default definePermissions({
 	resources: {

package/templates/versions.json

@@ -36,5 +36,6 @@
   "@tatara/db": "0.1.0",
   "@tatara/testing": "0.1.0",
   "@tatara/auth": "0.1.0",
-  "@tatara/keycloak": "0.1.0"
+  "@tatara/keycloak": "0.1.0",
+  "@tatara/authz": "0.1.0"
 }

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

@@ -1,31 +0,0 @@
-import { CACHE_TTL_MS } from "#core/authz/constants";
-import type { EffectivePermissions } from "#core/authz/types";
-
-const entries = new Map<string, { value: EffectivePermissions; expires: number }>();
-
-const key = (orgId: string, userId: string, roles: string[]) =>
-	`${orgId}:${userId}:${[...roles].sort().join(",")}`;
-
-export function getCached(orgId: string, userId: string, roles: string[]) {
-	const entry = entries.get(key(orgId, userId, roles));
-	if (!entry || entry.expires < Date.now()) return undefined;
-	return entry.value;
-}
-
-export function setCached(orgId: string, userId: string, roles: string[], value: EffectivePermissions) {
-	if (entries.size > 10_000) entries.clear();
-	entries.set(key(orgId, userId, roles), { value, expires: Date.now() + CACHE_TTL_MS });
-}
-
-/** Drops cached sets for one member (any org when orgId is omitted). */
-export function invalidateMember(userId: string, orgId?: string) {
-	for (const k of entries.keys()) {
-		const [o, u] = k.split(":");
-		if (u === userId && (!orgId || o === orgId)) entries.delete(k);
-	}
-}
-
-/** Role definitions changed: every cached set may be stale. */
-export function invalidateAll() {
-	entries.clear();
-}

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

@@ -1,85 +0,0 @@
-import { SCOPES, type Scope } from "#core/authz/constants";
-import type { SystemRoleKey } from "#core/authz/system-roles";
-
-export interface ActionSpec {
-	/** scoped actions are checked at own | team | org */
-	readonly scoped: boolean;
-}
-
-export type ResourceSpecs = Record<string, Record<string, ActionSpec>>;
-
-export type GrantTuple = readonly [resource: string, action: string, scope?: Scope];
-
-export interface PermissionSlice<R extends ResourceSpecs = ResourceSpecs> {
-	/** resources this module owns and the actions on them */
-	readonly resources: R;
-	/** grants this module adds to each built-in role, for its own resources */
-	readonly roleGrants?: Partial<Record<SystemRoleKey, readonly GrantTuple[]>>;
-}
-
-/** "resource:action" keys of one slice, for typed `requirePermission(...)` calls. */
-export type PermissionKeysOf<S> = S extends PermissionSlice<infer R>
-	? { [K in keyof R & string]: `${K}:${keyof R[K] & string}` }[keyof R & string]
-	: never;
-
-/** Default export of every `permissions/*.permissions.ts`; merged by `tatara sync`. */
-export function definePermissions<const R extends ResourceSpecs>(
-	slice: PermissionSlice<R>,
-): PermissionSlice<R> {
-	return slice;
-}
-
-export interface Catalog {
-	resources: ResourceSpecs;
-	keys: string[];
-	roleGrants: Partial<Record<SystemRoleKey, GrantTuple[]>>;
-}
-
-export function mergeCatalogs(...slices: PermissionSlice[]): Catalog {
-	const resources: Record<string, Record<string, ActionSpec>> = {};
-	const roleGrants: Partial<Record<SystemRoleKey, GrantTuple[]>> = {};
-	for (const slice of slices) {
-		for (const [resource, actions] of Object.entries(slice.resources)) {
-			if (resources[resource]) throw new Error(`Permission resource "${resource}" is declared twice`);
-			resources[resource] = actions;
-		}
-		for (const [role, grants] of Object.entries(slice.roleGrants ?? {})) {
-			const key = role as SystemRoleKey;
-			roleGrants[key] = [...(roleGrants[key] ?? []), ...(grants ?? [])];
-		}
-	}
-	const keys = Object.entries(resources).flatMap(([resource, actions]) =>
-		Object.keys(actions).map((action) => `${resource}:${action}`),
-	);
-	return { resources, keys, roleGrants };
-}
-
-/** Resources only built-in roles may grant: authorization itself. */
-export const META_RESOURCES: ReadonlySet<string> = new Set(["role", "member", "audit_log"]);
-
-export class InvalidGrantError extends Error {}
-
-/** Throws unless (resource, action, scope) exists in the catalog with a matching scope shape. */
-export function assertGrantValid(
-	catalog: Catalog,
-	grant: { resource: string; action: string; scope?: string | null },
-): void {
-	const spec = catalog.resources[grant.resource]?.[grant.action];
-	if (!spec) throw new InvalidGrantError(`Unknown permission ${grant.resource}:${grant.action}`);
-	const scope = grant.scope ?? null;
-	if (spec.scoped && !scope) {
-		throw new InvalidGrantError(
-			`${grant.resource}:${grant.action} is scoped; pass one of ${SCOPES.join(", ")}`,
-		);
-	}
-	if (spec.scoped && scope && !(SCOPES as readonly string[]).includes(scope)) {
-		throw new InvalidGrantError(`Scope "${scope}" must be one of ${SCOPES.join(", ")}`);
-	}
-	if (!spec.scoped && scope) {
-		throw new InvalidGrantError(`${grant.resource}:${grant.action} is not scoped; drop the scope`);
-	}
-}
-
-export function isScoped(catalog: Catalog, resource: string, action: string): boolean {
-	return catalog.resources[resource]?.[action]?.scoped === true;
-}

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

@@ -1,32 +0,0 @@
-/** Scope hierarchy: a grant at a higher rank satisfies a check at a lower one (org > team > own). */
-export const SCOPES = ["own", "team", "org"] as const;
-export type Scope = (typeof SCOPES)[number];
-
-export const SCOPE_RANK: Record<Scope, number> = { own: 1, team: 2, org: 3 };
-
-export const OVERLAY_EFFECTS = ["grant", "deny"] as const;
-export type OverlayEffect = (typeof OVERLAY_EFFECTS)[number];
-
-export const AUDIT_CHANGE_TYPES = [
-	"role_created",
-	"role_updated",
-	"role_deleted",
-	"member_role_assigned",
-	"member_role_revoked",
-	"overlay_granted",
-	"overlay_revoked",
-	"member_removed",
-] as const;
-export type AuditChangeType = (typeof AUDIT_CHANGE_TYPES)[number];
-
-/** Audit actor for changes made by the system rather than a user (e.g. org membership hooks). */
-export const SYSTEM_ACTOR = "system";
-
-/** Org used when the principal has none (single-tenant apps, users without an active org). */
-export const DEFAULT_ORG_ID = "default";
-
-/** Org id stored on system (built-in) roles; they apply to every org. */
-export const SYSTEM_ORG_ID = "";
-
-/** How long a resolved permission set is cached in-process. */
-export const CACHE_TTL_MS = 30_000;

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

@@ -1,21 +0,0 @@
-import { createMiddleware } from "hono/factory";
-import type { Scope } from "#core/authz/constants";
-import { checkPermission } from "#core/authz/resolver";
-import type { AppEnv } from "#core/http/context";
-import { ForbiddenError, UnauthorizedError } from "@tatara/http";
-import type { PermissionKey } from "#generated/permissions";
-
-/**
- * 401 without a principal, 403 unless it holds `resource:action` (at `scope` or wider).
- * Pair with `security: [{ bearerAuth: ["resource:action"] }]` so the route documents it.
- */
-export function requirePermission(permission: PermissionKey, scope?: Scope) {
-	return createMiddleware<AppEnv>(async (c, next) => {
-		const principal = c.get("principal");
-		if (!principal) throw new UnauthorizedError();
-		if (!(await checkPermission(principal, permission, scope))) {
-			throw new ForbiddenError(`Missing permission ${permission}${scope ? ` (${scope})` : ""}`);
-		}
-		await next();
-	});
-}

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

@@ -1,31 +0,0 @@
-import { definePermissions } from "#core/authz/catalog";
-
-/** Authorization's own resources; only built-in roles may grant them. */
-export default definePermissions({
-	resources: {
-		role: {
-			read: { scoped: false },
-			create: { scoped: false },
-			update: { scoped: false },
-			delete: { scoped: false },
-		},
-		member: {
-			read: { scoped: false },
-			update: { scoped: false },
-		},
-		audit_log: {
-			read: { scoped: false },
-		},
-	},
-	roleGrants: {
-		admin: [
-			["role", "read"],
-			["role", "create"],
-			["role", "update"],
-			["role", "delete"],
-			["member", "read"],
-			["member", "update"],
-			["audit_log", "read"],
-		],
-	},
-});