@tatara/cli 0.4.0 → 0.6.0

package/templates/features/better-auth/files/src/core/auth/sms.ts

@@ -1,14 +1,5 @@
+import { consoleSmsSender, type SmsSender } from "@tatara/auth";
 import { logger } from "#core/logging/logger";
 
-/** Implement this for your SMS provider and return it from `smsSender`. */
-export interface SmsSender {
-	send(to: string, text: string): Promise<void>;
-}
-
-const consoleSender: SmsSender = {
-	async send(to) {
-		logger.info({ to }, "sms not sent: no SMS provider configured (see src/core/auth/sms.ts)");
-	},
-};
-
-export const smsSender: SmsSender = consoleSender;
+/** Logs instead of sending. Replace with an SmsSender for your provider. */
+export const smsSender: SmsSender = consoleSmsSender(logger);

package/templates/features/better-auth/files/tests/helpers/auth.ts

@@ -1,5 +1,5 @@
+import { createTestUser as createUser, sessionHeaders } from "@tatara/auth/testing";
 import { auth } from "#core/auth/auth";
-import { newId } from "@tatara/db";
 // tatara:slot imports
 
 export interface AsUserOptions {
@@ -12,14 +12,13 @@ export interface AsUserOptions {
 
 /** Creates a verified user and returns their id. */
 export async function createTestUser(options: AsUserOptions = {}): Promise<string> {
-	const ctx = await auth.$context;
-	const user = await ctx.internalAdapter.createUser({
-		email: options.email ?? `user-${newId()}@example.com`,
-		name: options.name ?? "Test User",
-		emailVerified: true,
-		// tatara:slot user-fields
-	}, { method: "admin" });
-	return user.id;
+	return createUser(auth, {
+		email: options.email,
+		name: options.name,
+		fields: {
+			// tatara:slot user-fields
+		},
+	});
 }
 
 /** A new user with a real session; the token is sent as a bearer token. */
@@ -28,9 +27,7 @@ export async function authenticate(
 ): Promise<{ userId: string; headers: Record<string, string> }> {
 	// tatara:slot authenticate
 	const userId = await createTestUser(options);
-	const ctx = await auth.$context;
-	const session = await ctx.internalAdapter.createSession(userId);
-	return { userId, headers: { authorization: `Bearer ${session.token}` } };
+	return { userId, headers: await sessionHeaders(auth, userId) };
 }
 
 /** Headers that authenticate as a new user. */

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

@@ -34,5 +34,8 @@
   "@tatara/core": "0.1.0",
   "@tatara/http": "0.1.0",
   "@tatara/db": "0.1.0",
-  "@tatara/testing": "0.1.0"
+  "@tatara/testing": "0.1.0",
+  "@tatara/auth": "0.1.0",
+  "@tatara/keycloak": "0.1.0",
+  "@tatara/authz": "0.1.0"
 }

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

@@ -1,29 +0,0 @@
-import { createMiddleware } from "hono/factory";
-import type { Context } from "hono";
-import type { AppEnv, Principal } from "#core/http/context";
-import { ForbiddenError, UnauthorizedError } from "@tatara/http";
-
-/** 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-keycloak/files/src/core/auth/keycloak-plugin.ts

@@ -1,154 +0,0 @@
-import type { BetterAuthPlugin } from "better-auth";
-import { createAuthEndpoint } from "better-auth/api";
-import { z } from "zod";
-import {
-	type KeycloakClaims,
-	organizationOf,
-	rolesOf,
-	verifyAccessToken,
-} from "#core/auth/keycloak";
-import { logger } from "#core/logging/logger";
-
-export interface KeycloakPrincipal {
-	userId: string;
-	orgId: string | null;
-	roles: string[];
-	kind: "user" | "service";
-	claims: KeycloakClaims;
-}
-
-export interface KeycloakTokensOptions {
-	/** Record the token's organization as a better-auth organization + membership. */
-	organizations?: boolean;
-}
-
-type Adapter = Parameters<NonNullable<BetterAuthPlugin["init"]>>[0]["adapter"];
-
-const ACCOUNT_PROVIDER = "keycloak";
-
-async function ensureUser(adapter: Adapter, claims: KeycloakClaims): Promise<boolean> {
-	// an unverified email could claim someone else's address, so it is never stored
-	const verified = claims.email_verified === true && Boolean(claims.email);
-	const email = verified
-		? (claims.email as string).toLowerCase()
-		: `${claims.sub}@users.keycloak.invalid`;
-	const name = claims.name ?? claims.preferred_username ?? claims.sub;
-	const owner = await adapter.findOne<{ id: string }>({
-		model: "user",
-		where: [{ field: "email", value: email }],
-	});
-	const existing = await adapter.findOne<{ id: string }>({
-		model: "user",
-		where: [{ field: "id", value: claims.sub }],
-	});
-	if (existing) {
-		const emailFree = !owner || owner.id === claims.sub;
-		if (!emailFree) logger.warn({ sub: claims.sub }, "keycloak email belongs to another account");
-		await adapter.update({
-			model: "user",
-			where: [{ field: "id", value: claims.sub }],
-			update: {
-				name,
-				...(emailFree ? { email, emailVerified: verified } : {}),
-				updatedAt: new Date(),
-			},
-		});
-		return true;
-	}
-	if (owner) {
-		// never attach a Keycloak identity to an account that signs in another way
-		logger.warn({ sub: claims.sub }, "keycloak token email belongs to another account");
-		return false;
-	}
-	const now = new Date();
-	await adapter.create({
-		model: "user",
-		data: { id: claims.sub, email, emailVerified: verified, name, createdAt: now, updatedAt: now },
-		forceAllowId: true,
-	});
-	await adapter.create({
-		model: "account",
-		data: {
-			userId: claims.sub,
-			accountId: claims.sub,
-			providerId: ACCOUNT_PROVIDER,
-			createdAt: now,
-			updatedAt: now,
-		},
-	});
-	return true;
-}
-
-async function ensureMembership(adapter: Adapter, orgId: string, userId: string): Promise<void> {
-	const org = await adapter.findOne({
-		model: "organization",
-		where: [{ field: "id", value: orgId }],
-	});
-	if (!org) {
-		await adapter.create({
-			model: "organization",
-			data: { id: orgId, name: orgId, slug: orgId, createdAt: new Date() },
-			forceAllowId: true,
-		});
-	}
-	const member = await adapter.findOne({
-		model: "member",
-		where: [
-			{ field: "organizationId", value: orgId },
-			{ field: "userId", value: userId },
-		],
-	});
-	if (!member) {
-		await adapter.create({
-			model: "member",
-			data: { organizationId: orgId, userId, role: "member", createdAt: new Date() },
-		});
-	}
-}
-
-/**
- * Lets the API accept access tokens issued by Keycloak (a resource server).
- * Verified tokens become principals; their users and organizations are kept in better-auth's tables.
- */
-export function keycloakTokens(options: KeycloakTokensOptions = {}) {
-	// subjects already synced by this process; tokens are re-verified on every request regardless
-	const synced = new Set<string>();
-	return {
-		id: "keycloak-tokens",
-		endpoints: {
-			// no path: callable only on the server as auth.api.verifyKeycloakToken
-			verifyKeycloakToken: createAuthEndpoint(
-				{ method: "POST", body: z.object({ token: z.string() }) },
-				async (ctx): Promise<KeycloakPrincipal | null> => {
-					let claims: KeycloakClaims;
-					try {
-						claims = await verifyAccessToken(ctx.body.token);
-					} catch (error) {
-						logger.debug({ err: error }, "rejected keycloak token");
-						return null;
-					}
-					const isService = claims.preferred_username?.startsWith("service-account-") ?? false;
-					const orgId = organizationOf(claims);
-					if (!isService) {
-						const key = `${claims.sub}|${orgId ?? ""}|${claims.email ?? ""}`;
-						if (!synced.has(key)) {
-							const { adapter } = ctx.context;
-							if (!(await ensureUser(adapter, claims))) return null;
-							if (orgId && options.organizations)
-								await ensureMembership(adapter, orgId, claims.sub);
-							if (synced.size > 10_000) synced.clear();
-							synced.add(key);
-						}
-					}
-					return {
-						userId: claims.sub,
-						orgId,
-						roles: rolesOf(claims),
-						kind: isService ? "service" : "user",
-						claims,
-					};
-				},
-			),
-		},
-	} satisfies BetterAuthPlugin;
-}

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"],
-		],
-	},
-});

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 };
-	});
-}