@tatara/cli 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@tatara/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Create and grow opinionated Hono backends",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "tatara": "./dist/bin.mjs"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.1",
+    "commander": "15.0.0",
+    "picocolors": "1.1.1",
+    "tinyexec": "1.3.1",
+    "tinyglobby": "0.2.17",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "tsdown": "0.23.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/templates/features/admin/files/src/apps/admin/app.ts

@@ -0,0 +1,4 @@
+import { createHttpApp } from "#core/http/app";
+
+/** Internal/staff API on its own port; every /api route requires the admin role. */
+export const app = createHttpApp("admin", { title: "__APP_NAME__ admin API" });

package/templates/features/admin/files/src/apps/admin/server.ts

@@ -0,0 +1,5 @@
+import { app } from "#apps/admin/app";
+import { env } from "#core/config/env";
+import { startServer } from "#core/http/server";
+
+startServer(app, env.ADMIN_PORT, "admin");

package/templates/features/admin/files/src/modules/example/routes/admin-greeting.routes.ts

@@ -0,0 +1,24 @@
+import { createRoute } from "@hono/zod-openapi";
+import { currentPrincipal } from "#core/auth/middleware";
+import { errorResponses, jsonContent, success, successSchema } from "#core/http/response";
+import { createRouter, defineRoutes } from "#core/http/routes";
+import { greetingSchema } from "#modules/example/validators/greeting.validators";
+
+const router = createRouter();
+
+router.openapi(
+	createRoute({
+		method: "get",
+		path: "/",
+		tags: ["Example"],
+		summary: "Greet the signed-in admin",
+		security: [{ bearerAuth: ["admin"] }],
+		responses: {
+			200: jsonContent(successSchema(greetingSchema), "A greeting"),
+			...errorResponses(401, 403),
+		},
+	}),
+	(c) => c.json(success({ message: `Hello, admin ${currentPrincipal(c).userId}!` }), 200),
+);
+
+export default defineRoutes({ app: "admin", basePath: "/greetings", router });

package/templates/features/admin/files/src/modules/example/tests/admin.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { adminApi } from "#tests/helpers/api";
+import { asUser } from "#tests/helpers/auth";
+
+describe("admin app", () => {
+	it("requires authentication", async () => {
+		const res = await adminApi.get("/api/greetings");
+		expect(res.status).toBe(401);
+	});
+
+	it("forbids users without the admin role", async () => {
+		const res = await adminApi.get("/api/greetings", { headers: await asUser() });
+		expect(res.status).toBe(403);
+	});
+
+	it("serves admins", async () => {
+		const res = await adminApi.get("/api/greetings", { headers: await asUser({ roles: ["admin"] }) });
+		expect(res.status).toBe(200);
+	});
+});

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

@@ -0,0 +1,29 @@
+import { createMiddleware } from "hono/factory";
+import type { Context } from "hono";
+import type { AppEnv, Principal } from "#core/http/context";
+import { ForbiddenError, UnauthorizedError } from "#core/http/errors";
+
+/** 401 unless the request carries a valid session or token. */
+export function requireAuth() {
+	return createMiddleware<AppEnv>(async (c, next) => {
+		if (!c.get("principal")) throw new UnauthorizedError();
+		await next();
+	});
+}
+
+/** 401 without a principal, 403 unless it has at least one of the roles. */
+export function requireRole(...roles: string[]) {
+	return createMiddleware<AppEnv>(async (c, next) => {
+		const principal = c.get("principal");
+		if (!principal) throw new UnauthorizedError();
+		if (!principal.roles.some((role) => roles.includes(role))) throw new ForbiddenError();
+		await next();
+	});
+}
+
+/** The authenticated principal; use in handlers behind requireAuth(). */
+export function currentPrincipal(c: Context<AppEnv>): Principal {
+	const principal = c.get("principal");
+	if (!principal) throw new UnauthorizedError();
+	return principal;
+}

package/templates/features/auth/files/src/core/auth/routes/me.routes.ts

@@ -0,0 +1,36 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { currentPrincipal, requireAuth } from "#core/auth/middleware";
+import { errorResponses, jsonContent, success, successSchema } from "#core/http/response";
+import { createRouter, defineRoutes } from "#core/http/routes";
+
+const principalSchema = z
+	.object({
+		userId: z.string(),
+		orgId: z.string().nullable(),
+		roles: z.array(z.string()),
+		kind: z.enum(["user", "service"]),
+	})
+	.openapi("Principal");
+
+const router = createRouter();
+
+router.openapi(
+	createRoute({
+		method: "get",
+		path: "/",
+		tags: ["Auth"],
+		summary: "The authenticated principal",
+		middleware: [requireAuth()] as const,
+		security: [{ bearerAuth: [] }],
+		responses: {
+			200: jsonContent(successSchema(principalSchema), "Who is calling"),
+			...errorResponses(401),
+		},
+	}),
+	(c) => {
+		const { userId, orgId, roles, kind } = currentPrincipal(c);
+		return c.json(success({ userId, orgId, roles, kind }), 200);
+	},
+);
+
+export default defineRoutes({ app: "api", basePath: "/me", router });

package/templates/features/auth/files/src/core/auth/tests/me.test.ts

@@ -0,0 +1,25 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { api } from "#tests/helpers/api";
+import { asUser } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("GET /api/me", () => {
+	it("returns 401 without credentials", async () => {
+		const res = await api.get("/api/me");
+		expect(res.status).toBe(401);
+		expect(res.body).toMatchObject({ success: false, code: "UNAUTHORIZED" });
+	});
+
+	it("returns the principal for an authenticated user", async () => {
+		const res = await api.get<{ data: { userId: string; kind: string } }>("/api/me", {
+			headers: await asUser(),
+		});
+		expect(res.status).toBe(200);
+		expect(res.body.data.kind).toBe("user");
+		expect(res.body.data.userId).toBeTruthy();
+	});
+});

package/templates/features/auth-orgs/files+drizzle+mysql/src/core/auth/db/organization.schema.ts

@@ -0,0 +1,38 @@
+import { mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";
+import { users } from "#core/auth/db/auth.schema";
+
+export const organizations = mysqlTable("organizations", {
+	id: varchar({ length: 36 }).primaryKey(),
+	name: varchar({ length: 255 }).notNull(),
+	slug: varchar({ length: 255 }).notNull().unique(),
+	logo: text(),
+	metadata: text(),
+	createdAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
+});
+
+export const members = mysqlTable("members", {
+	id: varchar({ length: 36 }).primaryKey(),
+	organizationId: varchar({ length: 36 })
+		.notNull()
+		.references(() => organizations.id, { onDelete: "cascade" }),
+	userId: varchar({ length: 36 })
+		.notNull()
+		.references(() => users.id, { onDelete: "cascade" }),
+	role: varchar({ length: 64 }).notNull().default("member"),
+	createdAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
+});
+
+export const invitations = mysqlTable("invitations", {
+	id: varchar({ length: 36 }).primaryKey(),
+	organizationId: varchar({ length: 36 })
+		.notNull()
+		.references(() => organizations.id, { onDelete: "cascade" }),
+	email: varchar({ length: 255 }).notNull(),
+	role: varchar({ length: 64 }),
+	status: varchar({ length: 32 }).notNull().default("pending"),
+	expiresAt: timestamp({ fsp: 3, mode: "date" }).notNull(),
+	inviterId: varchar({ length: 36 })
+		.notNull()
+		.references(() => users.id, { onDelete: "cascade" }),
+	createdAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
+});

package/templates/features/auth-orgs/files+drizzle+postgres/src/core/auth/db/organization.schema.ts

@@ -0,0 +1,38 @@
+import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+import { users } from "#core/auth/db/auth.schema";
+
+export const organizations = pgTable("organizations", {
+	id: text().primaryKey(),
+	name: text().notNull(),
+	slug: text().notNull().unique(),
+	logo: text(),
+	metadata: text(),
+	createdAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
+});
+
+export const members = pgTable("members", {
+	id: text().primaryKey(),
+	organizationId: text()
+		.notNull()
+		.references(() => organizations.id, { onDelete: "cascade" }),
+	userId: text()
+		.notNull()
+		.references(() => users.id, { onDelete: "cascade" }),
+	role: text().notNull().default("member"),
+	createdAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
+});
+
+export const invitations = pgTable("invitations", {
+	id: text().primaryKey(),
+	organizationId: text()
+		.notNull()
+		.references(() => organizations.id, { onDelete: "cascade" }),
+	email: text().notNull(),
+	role: text(),
+	status: text().notNull().default("pending"),
+	expiresAt: timestamp({ withTimezone: true, mode: "date" }).notNull(),
+	inviterId: text()
+		.notNull()
+		.references(() => users.id, { onDelete: "cascade" }),
+	createdAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
+});

package/templates/features/auth-orgs/files+prisma/prisma/models/organization.prisma

@@ -0,0 +1,41 @@
+// better-auth organization plugin tables.
+
+model Organization {
+  id          String       @id @db.VarChar(36)
+  name        String       @db.VarChar(255)
+  slug        String       @unique @db.VarChar(255)
+  logo        String?      @db.Text
+  metadata    String?      @db.Text
+  createdAt   DateTime     @default(now()) @map("created_at")
+  members     Member[]
+  invitations Invitation[]
+
+  @@map("organizations")
+}
+
+model Member {
+  id             String       @id @db.VarChar(36)
+  organizationId String       @map("organization_id") @db.VarChar(36)
+  organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  userId         String       @map("user_id") @db.VarChar(36)
+  user           User         @relation(fields: [userId], references: [id], onDelete: Cascade)
+  role           String       @default("member") @db.VarChar(64)
+  createdAt      DateTime     @default(now()) @map("created_at")
+
+  @@map("members")
+}
+
+model Invitation {
+  id             String       @id @db.VarChar(36)
+  organizationId String       @map("organization_id") @db.VarChar(36)
+  organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  email          String       @db.VarChar(255)
+  role           String?      @db.VarChar(64)
+  status         String       @default("pending") @db.VarChar(32)
+  expiresAt      DateTime     @map("expires_at")
+  inviterId      String       @map("inviter_id") @db.VarChar(36)
+  inviter        User         @relation(fields: [inviterId], references: [id], onDelete: Cascade)
+  createdAt      DateTime     @default(now()) @map("created_at")
+
+  @@map("invitations")
+}

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

@@ -0,0 +1,31 @@
+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

@@ -0,0 +1,85 @@
+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/commands/grant-role.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { DEFAULT_ORG_ID, SYSTEM_ORG_ID } from "#core/authz/constants";
+import { store } from "#core/authz/db/store";
+import { assignRole } from "#core/authz/services/members";
+import { defineCommand } from "#core/commands/define";
+
+export default defineCommand({
+	name: "authz:grant-role",
+	description: "Assign a role (built-in key or custom role key) to a user in an org",
+	args: z.object({
+		user: z.string().min(1),
+		role: z.string().min(1),
+		org: z.string().default(DEFAULT_ORG_ID),
+	}),
+	async run({ user, role, org }, { logger }) {
+		const found = (await store.findRoleByKey(org, role)) ?? (await store.findRoleByKey(SYSTEM_ORG_ID, role));
+		if (!found) throw new Error(`No role "${role}" (run authz:sync-permissions first for built-in roles)`);
+		const added = await assignRole(null, org, user, found.id);
+		logger.info({ user, role, org, added }, added ? "role assigned" : "role already assigned");
+	},
+});

package/templates/features/authz/files/src/core/authz/commands/sync-permissions.ts

@@ -0,0 +1,11 @@
+import { defineCommand } from "#core/commands/define";
+import { syncSystemRoles } from "#core/authz/services/sync";
+
+export default defineCommand({
+	name: "authz:sync-permissions",
+	description: "Create/update built-in roles so their grants match the code (run on every deploy)",
+	async run(_args, { logger }) {
+		const result = await syncSystemRoles();
+		logger.info(result, "built-in roles in sync");
+	},
+});

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

@@ -0,0 +1,28 @@
+/** 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",
+] as const;
+export type AuditChangeType = (typeof AUDIT_CHANGE_TYPES)[number];
+
+/** 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/db/seed.ts

@@ -0,0 +1,10 @@
+import { syncSystemRoles } from "#core/authz/services/sync";
+import { defineSeed } from "#core/db/seed";
+
+export default defineSeed({
+	name: "authz:system-roles",
+	order: -10,
+	async run({ logger }) {
+		logger.info(await syncSystemRoles(), "built-in roles in sync");
+	},
+});

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

@@ -0,0 +1,21 @@
+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 "#core/http/errors";
+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

@@ -0,0 +1,31 @@
+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"],
+		],
+	},
+});

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

@@ -0,0 +1,98 @@
+import { getCached, setCached } from "#core/authz/cache";
+import { DEFAULT_ORG_ID, SCOPE_RANK, type Scope } from "#core/authz/constants";
+import { store } from "#core/authz/db/store";
+import { SYSTEM_ROLE_KEYS } from "#core/authz/system-roles";
+import { type EffectivePermissions, grantKey, type PermissionGrant } from "#core/authz/types";
+import type { Principal } from "#core/http/context";
+
+/** The org a principal acts in: its active org, or the default org. */
+export function orgOf(principal: Pick<Principal, "orgId">): string {
+	return principal.orgId ?? DEFAULT_ORG_ID;
+}
+
+/** Roles from the identity provider that match a built-in role key are honoured as that role. */
+function impliedRoles(principal: Pick<Principal, "roles">): string[] {
+	return principal.roles.filter((role) => SYSTEM_ROLE_KEYS.has(role));
+}
+
+/**
+ * Effective permissions = grants of the member's roles (assigned in the org, plus built-in
+ * roles implied by the identity provider) + active grant overlays − active deny overlays.
+ */
+export async function effectivePermissions(
+	principal: Pick<Principal, "userId" | "orgId" | "roles">,
+): Promise<EffectivePermissions> {
+	const orgId = orgOf(principal);
+	const implied = impliedRoles(principal);
+	const cached = getCached(orgId, principal.userId, implied);
+	if (cached) return cached;
+
+	const [{ roles, grants }, overlays] = await Promise.all([
+		store.roleGrants(orgId, principal.userId, implied),
+		store.activeOverlays(orgId, principal.userId, new Date()),
+	]);
+	const all: PermissionGrant[] = [...grants];
+	const denies = new Set<string>();
+	for (const overlay of overlays) {
+		const grant = { resource: overlay.resource, action: overlay.action, scope: overlay.scope };
+		if (overlay.effect === "deny") denies.add(grantKey(grant));
+		else all.push(grant);
+	}
+	const value = { grants: all, denies, roles };
+	setCached(orgId, principal.userId, implied, value);
+	return value;
+}
+
+/** Pure check against a resolved set: deny wins; scoped checks honour org > team > own. */
+export function allows(
+	permissions: EffectivePermissions,
+	resource: string,
+	action: string,
+	scope?: Scope,
+): boolean {
+	if (permissions.denies.has(`${resource}:${action}:${scope ?? "*"}`)) return false;
+	if (scope && permissions.denies.has(`${resource}:${action}:*`)) return false;
+	// a denied grant can never satisfy a check, even a narrower one
+	const live = permissions.grants.filter(
+		(g) => !permissions.denies.has(grantKey(g)) && !permissions.denies.has(`${g.resource}:${g.action}:*`),
+	);
+	if (!scope) {
+		return live.some((g) => g.resource === resource && g.action === action);
+	}
+	const required = SCOPE_RANK[scope];
+	return live.some(
+		(g) =>
+			g.resource === resource &&
+			g.action === action &&
+			g.scope !== null &&
+			SCOPE_RANK[g.scope] >= required,
+	);
+}
+
+export async function checkPermission(
+	principal: Pick<Principal, "userId" | "orgId" | "roles">,
+	permission: string,
+	scope?: Scope,
+): Promise<boolean> {
+	const [resource = "", action = ""] = permission.split(":");
+	return allows(await effectivePermissions(principal), resource, action, scope);
+}
+
+/**
+ * The widest scope the principal holds for a scoped action. Middleware proves the caller
+ * may act at some scope; services use this to decide which rows to return.
+ */
+export async function resolveScope(
+	principal: Pick<Principal, "userId" | "orgId" | "roles">,
+	permission: string,
+): Promise<Scope | null> {
+	const [resource = "", action = ""] = permission.split(":");
+	const permissions = await effectivePermissions(principal);
+	let best: Scope | null = null;
+	for (const g of permissions.grants) {
+		if (g.resource !== resource || g.action !== action || g.scope === null) continue;
+		if (permissions.denies.has(grantKey(g))) continue;
+		if (!best || SCOPE_RANK[g.scope] > SCOPE_RANK[best]) best = g.scope;
+	}
+	return best;
+}