@flowdular/sdk 0.2.3 → 0.3.0

package/packages/kernel/src/acl.ts

@@ -1,3 +1,5 @@
+import { RegistryError } from './errors.ts';
+
 export interface Principal {
 	readonly id: string;
 	readonly permissions: ReadonlySet<string>;
@@ -18,3 +20,180 @@ export function authorize(
 	}
 	return { allowed: true, reason: 'granted' };
 }
+
+/* What a denied decision would need to become an allow. The kernel owns the
+   shape only: resolving a role or a scope to people, collecting their decisions
+   and recording the receipt belong to the module that owns approvals. */
+export interface ApprovalRequirement {
+	readonly roleKey?: string;
+	readonly scope?: string;
+	readonly decisions?: number;
+	readonly expiresInDays?: number;
+}
+
+export type PolicyDecision =
+	| { readonly allowed: true }
+	| {
+			readonly allowed: false;
+			readonly reason: string;
+			readonly requiresApproval?: {
+				readonly requirement: ApprovalRequirement;
+			};
+	  };
+
+export interface PolicyEvaluationContext<TRecord = unknown> {
+	readonly principal: Principal;
+	readonly permission: string;
+	readonly record: TRecord;
+	/** The domain operation, when one permission covers several. */
+	readonly action?: string;
+}
+
+export interface PolicyDefinition<TRecord = unknown> {
+	readonly id: string;
+	readonly permission: string;
+	evaluate(context: PolicyEvaluationContext<TRecord>): PolicyDecision;
+}
+
+/** A registered policy: the record is the permission's, so the registry keeps none. */
+export type Policy = PolicyDefinition<unknown>;
+
+export const MAX_POLICIES = 256;
+
+/* Permission ids and policy ids share one shape, so a policy id reads as
+   `<module>.<record>.<rule>` next to the permission it qualifies. */
+const POLICY_ID = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+
+const ALLOWED: PolicyDecision = Object.freeze({ allowed: true });
+const NO_POLICIES: readonly Policy[] = Object.freeze([]);
+
+export function definePolicy<TRecord = unknown>(
+	definition: PolicyDefinition<TRecord>,
+): Policy {
+	if (!POLICY_ID.test(definition.id)) {
+		throw new RegistryError(
+			'POLICY_INVALID',
+			`Policy ${definition.id} has an invalid id.`,
+		);
+	}
+	if (!POLICY_ID.test(definition.permission)) {
+		throw new RegistryError(
+			'POLICY_INVALID',
+			`Policy ${definition.id} names an invalid permission ${definition.permission}.`,
+		);
+	}
+	if (typeof definition.evaluate !== 'function') {
+		throw new RegistryError(
+			'POLICY_INVALID',
+			`Policy ${definition.id} has no evaluate function.`,
+		);
+	}
+	/* The record type belongs to the permission, not to the registry, which
+	   holds policies of every module at once. This is the one place the author's
+	   record type is erased, so a policy body stays typed. */
+	return Object.freeze({
+		id: definition.id,
+		permission: definition.permission,
+		evaluate: definition.evaluate as Policy['evaluate'],
+	});
+}
+
+export interface PolicyRegistry {
+	register(policy: Policy): void;
+	/** Registration order, which is evaluation order. Empty for an unknown permission. */
+	list(permission: string): readonly Policy[];
+	evaluate(
+		principal: Principal,
+		permission: string,
+		record: unknown,
+		action?: string,
+	): PolicyDecision;
+}
+
+export interface MutablePolicyRegistry extends PolicyRegistry {
+	seal(): void;
+}
+
+/* Policies are registered while the platform composes and become an immutable
+   catalog before start hooks run: a policy registered at request time would
+   change an authorization decision under the requests already in flight. */
+export function createPolicyRegistry(): MutablePolicyRegistry {
+	const ids = new Set<string>();
+	const byPermission = new Map<string, Policy[]>();
+	let sealed = false;
+	return {
+		register(policy) {
+			if (sealed) {
+				throw new RegistryError(
+					'POLICY_REGISTRY_SEALED',
+					'The policy registry is already sealed.',
+				);
+			}
+			if (ids.has(policy.id)) {
+				throw new RegistryError(
+					'POLICY_DUPLICATE',
+					`Policy ${policy.id} is already registered.`,
+				);
+			}
+			if (ids.size >= MAX_POLICIES) {
+				throw new RegistryError(
+					'POLICY_LIMIT',
+					`A platform registers at most ${MAX_POLICIES} policies.`,
+				);
+			}
+			ids.add(policy.id);
+			const registered = byPermission.get(policy.permission);
+			if (registered) registered.push(policy);
+			else byPermission.set(policy.permission, [policy]);
+		},
+		list(permission) {
+			const registered = byPermission.get(permission);
+			if (registered === undefined) return NO_POLICIES;
+			return Object.freeze([...registered]);
+		},
+		evaluate(principal, permission, record, action) {
+			const registered = byPermission.get(permission);
+			if (registered === undefined) return ALLOWED;
+			const context: PolicyEvaluationContext =
+				action === undefined
+					? { principal, permission, record }
+					: { principal, permission, record, action };
+			for (const policy of registered) {
+				const decision = evaluatePolicy(policy, context);
+				if (!decision.allowed) return decision;
+			}
+			return ALLOWED;
+		},
+		seal() {
+			sealed = true;
+		},
+	};
+}
+
+/* A policy is module code on the authorization path. A throwing policy denies
+   instead of escaping, so one faulty policy can never turn into an allow. */
+function evaluatePolicy(
+	policy: Policy,
+	context: PolicyEvaluationContext,
+): PolicyDecision {
+	try {
+		return policy.evaluate(context);
+	} catch {
+		return { allowed: false, reason: `policy-failed:${policy.id}` };
+	}
+}
+
+/** The permission scope first, then the policies that qualify it. */
+export function authorizeRecord(
+	registry: PolicyRegistry,
+	principal: Principal | null,
+	permission: string,
+	record: unknown,
+	action?: string,
+): PolicyDecision {
+	const scope = authorize(principal, permission);
+	if (!scope.allowed || !principal) {
+		return { allowed: false, reason: scope.reason };
+	}
+	return registry.evaluate(principal, permission, record, action);
+}

package/packages/kernel/src/capability-registry.ts

@@ -4,13 +4,33 @@ export interface PlatformCapabilityRegistry {
 	register<T>(id: string, capability: T): void;
 	get<T>(id: string): T | null;
 	has(id: string): boolean;
+	/* A view bound to one module's manifest declaration: register accepts only
+	   the ids under `provides`, get and has only the ids under `requires`; ids
+	   under `platform.` are kernel-owned and stay open both ways. The generated
+	   composition hands each module this view so the manifest stays the truth
+	   about who talks to whom. */
+	forModule(
+		moduleId: string,
+		declaration: ModuleCapabilityDeclaration,
+	): PlatformCapabilityRegistry;
 }
 
+export interface ModuleCapabilityDeclaration {
+	readonly provides?: readonly string[];
+	readonly requires?: readonly {
+		readonly id: string;
+		readonly optional?: boolean;
+	}[];
+}
+
+const CAPABILITY_ID = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+const PLATFORM_PREFIX = 'platform.';
+
 export function createPlatformCapabilityRegistry(): PlatformCapabilityRegistry {
 	const capabilities = new Map<string, unknown>();
-	return {
+	const root: PlatformCapabilityRegistry = {
 		register(id, capability) {
-			if (!/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/.test(id)) {
+			if (!CAPABILITY_ID.test(id)) {
 				throw new Error(`Platform capability ${id} has an invalid id.`);
 			}
 			if (capabilities.has(id)) {
@@ -24,5 +44,52 @@ export function createPlatformCapabilityRegistry(): PlatformCapabilityRegistry {
 		has(id) {
 			return capabilities.has(id);
 		},
+		forModule(moduleId, declaration) {
+			return scopedCapabilityRegistry(root, moduleId, declaration);
+		},
+	};
+	return root;
+}
+
+function scopedCapabilityRegistry(
+	root: PlatformCapabilityRegistry,
+	moduleId: string,
+	declaration: ModuleCapabilityDeclaration,
+): PlatformCapabilityRegistry {
+	const provides = new Set(declaration.provides ?? []);
+	const requires = new Set(
+		(declaration.requires ?? []).map((entry) => entry.id),
+	);
+	const readable = (id: string) =>
+		requires.has(id) || provides.has(id) || id.startsWith(PLATFORM_PREFIX);
+	const scoped: PlatformCapabilityRegistry = {
+		register(id, capability) {
+			if (!provides.has(id) && !id.startsWith(PLATFORM_PREFIX)) {
+				throw new Error(
+					`${moduleId} registers capability ${id} without declaring it under "provides" in module.json.`,
+				);
+			}
+			root.register(id, capability);
+		},
+		get<T>(id: string): T | null {
+			if (!readable(id)) {
+				throw new Error(
+					`${moduleId} resolves capability ${id} without declaring it under "requires" in module.json.`,
+				);
+			}
+			return root.get<T>(id);
+		},
+		has(id) {
+			if (!readable(id)) {
+				throw new Error(
+					`${moduleId} checks capability ${id} without declaring it under "requires" in module.json.`,
+				);
+			}
+			return root.has(id);
+		},
+		forModule(nestedModuleId, nestedDeclaration) {
+			return scopedCapabilityRegistry(root, nestedModuleId, nestedDeclaration);
+		},
 	};
+	return scoped;
 }

package/packages/kernel/src/data-class-registry.ts

@@ -0,0 +1,354 @@
+import { RegistryError } from './errors.ts';
+
+/* The platform-wide catalogue of the data a deployment holds. A module that
+   owns rows declares its classes while the platform composes; the registry is
+   sealed before start hooks run, so every reader sees the same declarations
+   for the life of the process. The owner keeps its own operations: a sweep, an
+   export and an erasure run inside the declaring module, on its own leases,
+   under its own tenant transaction, so the reader of the registry opens no
+   foreign table. */
+
+/** Where one exported row goes. The caller owns the ordering and the shape. */
+export interface DataClassExportSink {
+	write(row: Record<string, unknown>): Promise<void>;
+}
+
+export interface DataClassSweepInput {
+	readonly tenantId: string;
+	/** Rows whose retention timestamp is strictly older than this may go. */
+	readonly cutoff: Date;
+	/** Upper bound on rows this call may remove. */
+	readonly limit: number;
+}
+
+export interface DataClassExportInput {
+	readonly tenantId: string;
+	readonly sink: DataClassExportSink;
+}
+
+export interface DataClassExportSummary {
+	readonly rows: number;
+	/** Oldest and newest record time in the exported set, or null when empty. */
+	readonly from: Date | null;
+	readonly to: Date | null;
+}
+
+/** The person an erasure or a count is about. */
+export interface DataClassSubject {
+	readonly accountId: string;
+}
+
+export interface DataClassErasureInput {
+	readonly tenantId: string;
+	readonly subject: DataClassSubject;
+	/** Upper bound on rows this call may remove. */
+	readonly limit: number;
+}
+
+export interface DataClassErasureResult {
+	/** Rows the call took out of the class, and nothing else. */
+	readonly removed: number;
+	/**
+	 * Rows it kept but stripped of the subject, for a class whose row cannot go:
+	 * an append-only ledger, or a snapshot another person's row is part of. A
+	 * non-negative integer when present. The caller counts a redacted row as
+	 * progress the same way it counts a removed one, so a batch that only
+	 * redacts still moves the run on and `removed` goes on meaning what it says.
+	 */
+	readonly redacted?: number;
+	/**
+	 * True when rows of the subject are left that this call did not reach. The
+	 * caller repeats the call up to its own batch cap and records the class as
+	 * incomplete when the flag still stands.
+	 */
+	readonly truncated?: boolean;
+}
+
+export interface DataClassCountInput {
+	readonly tenantId: string;
+	readonly subject: DataClassSubject;
+}
+
+export interface DataClassDeclaration {
+	/** `^[a-z][a-z0-9-]*$`; the class id is `${moduleId}.${key}`. */
+	readonly key: string;
+	readonly label: string;
+	/** Days, or null for kept until a person deletes. Zero is refused. */
+	readonly defaultRetentionDays: number | null;
+	readonly exportable: boolean;
+	/** Required when `exportable` is false; it reaches the export manifest. */
+	readonly excludedReason?: string;
+	/**
+	 * Removes at most `limit` rows older than `cutoff` and answers how many it
+	 * removed. A class without this operation is never swept. The operation runs
+	 * inside the owner module and must use its own tenant-scoped transaction.
+	 */
+	readonly sweep?: (
+		input: DataClassSweepInput,
+	) => Promise<{ readonly removed: number }>;
+	/**
+	 * Writes every row of the class for one workspace into the sink. A class
+	 * without this operation is reported in the export manifest as excluded.
+	 * The operation runs inside the owner module and must use its own
+	 * tenant-scoped transaction.
+	 */
+	readonly export?: (
+		input: DataClassExportInput,
+	) => Promise<DataClassExportSummary>;
+	/**
+	 * Removes at most `limit` rows one subject owns and answers how many it
+	 * removed. A class without this operation is never erased: the plan and the
+	 * certificate name it as not erasable rather than pretending it was cleared.
+	 * The operation runs inside the owner module and must use its own
+	 * tenant-scoped transaction.
+	 */
+	readonly erase?: (
+		input: DataClassErasureInput,
+	) => Promise<DataClassErasureResult>;
+	/**
+	 * Rows the subject holds, without removing any. A class that cannot count
+	 * cheaply leaves the operation out or answers null, and the plan says the
+	 * count is unknown rather than guessing one.
+	 */
+	readonly count?: (input: DataClassCountInput) => Promise<number | null>;
+}
+
+export interface DataClassModuleEntry {
+	readonly moduleId: string;
+	readonly classes: readonly DataClassDeclaration[];
+}
+
+export interface PlatformDataClassRegistry {
+	/**
+	 * The platform form, for a module composed outside the module composition
+	 * and for a module naming the classes it owns. A bound view accepts only
+	 * its own id. Accepted while the platform composes; after `seal()` it
+	 * throws, so the catalogue a request reads is the one every module agreed
+	 * on at boot. A module that owns no class declares an empty list, so the
+	 * workspace can see it holds none.
+	 */
+	declare(moduleId: string, classes: readonly DataClassDeclaration[]): void;
+	/** The module form, available on a view bound by `forModule`. */
+	declare(classes: readonly DataClassDeclaration[]): void;
+	/** Returns a view that declares classes owned by one module only. */
+	forModule(moduleId: string): PlatformDataClassRegistry;
+	/**
+	 * Every module that declared, in composition order, including the ones that
+	 * declared nothing. A bound view answers the whole catalogue: the binding
+	 * limits what a module may declare, never what it may read.
+	 */
+	list(): readonly DataClassModuleEntry[];
+}
+
+export interface MutablePlatformDataClassRegistry
+	extends PlatformDataClassRegistry {
+	seal(): void;
+}
+
+/** Longest values the registry accepts; over any of them is a rejection. */
+export const DATA_CLASS_LIMITS = {
+	moduleId: 64,
+	key: 48,
+	classId: 96,
+	label: 120,
+	excludedReason: 200,
+	classesPerModule: 64,
+	/** 100 years. A longer period is a mistake, not a policy. */
+	retentionDays: 36_500,
+} as const;
+
+const MODULE_ID = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+const CLASS_KEY = /^[a-z][a-z0-9-]*$/;
+
+function refuse(message: string): never {
+	throw new RegistryError('DATA_CLASS_DECLARATION_INVALID', message);
+}
+
+export function createDataClassRegistry(): MutablePlatformDataClassRegistry {
+	/** Declaration order, so the registry reads the way composition ran. */
+	const modules = new Map<string, readonly DataClassDeclaration[]>();
+	/** Class id to owner, so a duplicate is refused in O(1). */
+	const owners = new Map<string, string>();
+	let sealed: readonly DataClassModuleEntry[] | null = null;
+
+	const snapshot = (): readonly DataClassModuleEntry[] =>
+		Object.freeze(
+			[...modules].map(([moduleId, classes]) => ({ moduleId, classes })),
+		);
+
+	const view = (boundModuleId?: string): PlatformDataClassRegistry => {
+		const self: PlatformDataClassRegistry = {
+			declare(
+				first: string | readonly DataClassDeclaration[],
+				second?: readonly DataClassDeclaration[],
+			): void {
+				const named = typeof first === 'string';
+				const moduleId = named ? first : boundModuleId;
+				const classes = named ? second : first;
+				if (moduleId === undefined) {
+					refuse(
+						'The platform data class registry needs a module id: call declare(moduleId, classes) or bind it with forModule(moduleId).',
+					);
+				}
+				if (boundModuleId !== undefined && moduleId !== boundModuleId) {
+					refuse(
+						`Module ${boundModuleId} cannot declare data classes owned by ${moduleId}.`,
+					);
+				}
+				declareClasses(moduleId, classes as readonly DataClassDeclaration[]);
+			},
+			forModule(moduleId: string): PlatformDataClassRegistry {
+				const normalized = moduleId.trim();
+				if (!normalized)
+					refuse('A module-bound data class registry needs an id.');
+				if (boundModuleId !== undefined && normalized !== boundModuleId) {
+					refuse(
+						`Module ${boundModuleId} cannot obtain the data class registrar for ${normalized}.`,
+					);
+				}
+				return boundModuleId === normalized ? self : view(normalized);
+			},
+			list(): readonly DataClassModuleEntry[] {
+				return sealed ?? snapshot();
+			},
+		};
+		return self;
+	};
+
+	function declareClasses(
+		moduleId: string,
+		classes: readonly DataClassDeclaration[],
+	): void {
+		if (sealed !== null) {
+			refuse(
+				`${moduleId} declared data classes after the platform started; declarations are accepted during composition only.`,
+			);
+		}
+		if (
+			typeof moduleId !== 'string' ||
+			moduleId.length > DATA_CLASS_LIMITS.moduleId ||
+			!MODULE_ID.test(moduleId)
+		) {
+			refuse(`"${String(moduleId)}" is not a module id.`);
+		}
+		if (modules.has(moduleId)) {
+			refuse(`${moduleId} declared its data classes twice.`);
+		}
+		if (!Array.isArray(classes)) {
+			refuse(`${moduleId} declared something other than a list of classes.`);
+		}
+		if (classes.length > DATA_CLASS_LIMITS.classesPerModule) {
+			refuse(
+				`${moduleId} declared ${classes.length} data classes; at most ${DATA_CLASS_LIMITS.classesPerModule} are accepted.`,
+			);
+		}
+		/* Nothing is recorded until every class of the module validated, so a
+		   refused declaration leaves the registry exactly as it was. */
+		const accepted = new Set<string>();
+		for (const declaration of classes) {
+			const classId = validated(moduleId, declaration);
+			const taken = owners.get(classId);
+			if (taken || accepted.has(classId)) {
+				refuse(
+					`${moduleId} declared ${classId}, which ${taken ?? moduleId} already owns.`,
+				);
+			}
+			accepted.add(classId);
+		}
+		modules.set(moduleId, Object.freeze([...classes]));
+		for (const classId of accepted) owners.set(classId, moduleId);
+	}
+
+	return {
+		...view(),
+		seal(): void {
+			if (sealed !== null) return;
+			sealed = snapshot();
+		},
+	};
+}
+
+/** Answers the class id, so a caller can index the declarations it accepted. */
+function validated(
+	moduleId: string,
+	declaration: DataClassDeclaration,
+): string {
+	if (typeof declaration !== 'object' || declaration === null) {
+		refuse(`${moduleId} declared something other than a data class.`);
+	}
+	const key = declaration.key;
+	if (
+		typeof key !== 'string' ||
+		key.length > DATA_CLASS_LIMITS.key ||
+		!CLASS_KEY.test(key)
+	) {
+		refuse(`${moduleId} declared "${String(key)}", which is not a class key.`);
+	}
+	const classId = `${moduleId}.${key}`;
+	if (classId.length > DATA_CLASS_LIMITS.classId) {
+		refuse(
+			`${classId} is longer than ${DATA_CLASS_LIMITS.classId} characters.`,
+		);
+	}
+	const label = declaration.label;
+	if (
+		typeof label !== 'string' ||
+		label.trim().length < 1 ||
+		label.length > DATA_CLASS_LIMITS.label
+	) {
+		refuse(
+			`${classId} needs a label of 1 to ${DATA_CLASS_LIMITS.label} characters.`,
+		);
+	}
+	const days = declaration.defaultRetentionDays;
+	if (
+		days !== null &&
+		(!Number.isSafeInteger(days) ||
+			days < 1 ||
+			days > DATA_CLASS_LIMITS.retentionDays)
+	) {
+		refuse(
+			`${classId} declared a default retention of ${String(days)}; it must be null or 1 to ${DATA_CLASS_LIMITS.retentionDays} days.`,
+		);
+	}
+	if (typeof declaration.exportable !== 'boolean') {
+		refuse(`${classId} must say whether it is exportable.`);
+	}
+	const reason = declaration.excludedReason;
+	if (!declaration.exportable) {
+		if (
+			typeof reason !== 'string' ||
+			reason.trim().length < 1 ||
+			reason.length > DATA_CLASS_LIMITS.excludedReason
+		) {
+			refuse(
+				`${classId} is not exportable and must state why in excludedReason.`,
+			);
+		}
+	}
+	if (
+		declaration.sweep !== undefined &&
+		typeof declaration.sweep !== 'function'
+	) {
+		refuse(`${classId} declared a sweep operation that is not a function.`);
+	}
+	if (
+		declaration.export !== undefined &&
+		typeof declaration.export !== 'function'
+	) {
+		refuse(`${classId} declared an export operation that is not a function.`);
+	}
+	if (
+		declaration.erase !== undefined &&
+		typeof declaration.erase !== 'function'
+	) {
+		refuse(`${classId} declared an erase operation that is not a function.`);
+	}
+	if (
+		declaration.count !== undefined &&
+		typeof declaration.count !== 'function'
+	) {
+		refuse(`${classId} declared a count operation that is not a function.`);
+	}
+	return classId;
+}