@tatara/cli 0.5.0 → 0.6.0

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

@@ -1,98 +0,0 @@
-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;
-}

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

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

@@ -1,29 +0,0 @@
-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 "@tatara/http";
-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

@@ -1,84 +0,0 @@
-import { invalidateMember } from "#core/authz/cache";
-import { type OverlayEffect, type Scope, SYSTEM_ACTOR } 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 "@tatara/http";
-
-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 } });
-}
-
-/** Removes all of a user's access in an org; called when they stop being a member. */
-export async function removeMemberAccess(orgId: string, userId: string, actorId = SYSTEM_ACTOR) {
-	const removed = await store.removeMember(orgId, userId);
-	invalidateMember(userId, orgId);
-	if (removed.roles + removed.overlays > 0) {
-		await audit({
-			orgId,
-			actorId,
-			targetUserId: userId,
-			changeType: "member_removed",
-			before: removed,
-		});
-	}
-	return removed;
-}
-
-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

@@ -1,73 +0,0 @@
-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 "@tatara/http";
-
-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

@@ -1,34 +0,0 @@
-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/types.ts

@@ -1,87 +0,0 @@
-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>;
-	/** Deletes every role assignment and overlay the user has in the org. */
-	removeMember(orgId: string, userId: string): Promise<{ roles: number; overlays: number }>;
-	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

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