@flowdular/sdk 0.2.4 → 0.3.1

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

package/packages/kernel/src/index.ts

@@ -1,5 +1,21 @@
-export { authorize } from './acl.ts';
-export type { AccessDecision, Principal } from './acl.ts';
+export {
+	authorize,
+	authorizeRecord,
+	createPolicyRegistry,
+	definePolicy,
+	MAX_POLICIES,
+} from './acl.ts';
+export type {
+	AccessDecision,
+	ApprovalRequirement,
+	MutablePolicyRegistry,
+	Policy,
+	PolicyDecision,
+	PolicyDefinition,
+	PolicyEvaluationContext,
+	PolicyRegistry,
+	Principal,
+} from './acl.ts';
 export { createPlatformAgentRegistry } from './agent-registry.ts';
 export type {
 	MutablePlatformAgentRegistry,
@@ -24,9 +40,67 @@ export type {
 	UserActor,
 	UserActorSource,
 } from './actor.ts';
+export {
+	createDataClassRegistry,
+	DATA_CLASS_LIMITS,
+} from './data-class-registry.ts';
+export type {
+	DataClassCountInput,
+	DataClassDeclaration,
+	DataClassErasureInput,
+	DataClassErasureResult,
+	DataClassExportInput,
+	DataClassExportSink,
+	DataClassExportSummary,
+	DataClassModuleEntry,
+	DataClassSubject,
+	DataClassSweepInput,
+	MutablePlatformDataClassRegistry,
+	PlatformDataClassRegistry,
+} from './data-class-registry.ts';
 export { createPlatformCapabilityRegistry } from './capability-registry.ts';
-export type { PlatformCapabilityRegistry } from './capability-registry.ts';
+export type {
+	ModuleCapabilityDeclaration,
+	PlatformCapabilityRegistry,
+} from './capability-registry.ts';
+export {
+	APPROVAL_GRANT_INPUT_DIGEST_LENGTH,
+	APPROVAL_GRANT_KEY_VARIABLE,
+	APPROVAL_GRANT_MAX_TOKEN_LENGTH,
+	APPROVAL_GRANT_PREVIOUS_KEY_VARIABLE,
+	approvalGrantKeyringFromEnvironment,
+	approvalInputDigest,
+	createApprovalGrantKeyring,
+	issueApprovalGrant,
+	verifyApprovalGrant,
+} from './approval-grant.ts';
+export type {
+	ApprovalGrantClaims,
+	ApprovalGrantExpectation,
+	ApprovalGrantInput,
+	ApprovalGrantKeyring,
+	ApprovalGrantReason,
+	ApprovalGrantVerification,
+	IssuedApprovalGrant,
+} from './approval-grant.ts';
 export { RegistryError } from './errors.ts';
+export {
+	createKeyring,
+	keyFingerprint,
+	KeyringError,
+	KEYRING_IV_BYTES,
+	KEYRING_KEY_BYTES,
+	KEYRING_MAX_PREVIOUS_KEYS,
+	KEYRING_TAG_BYTES,
+	parsePreviousKeys,
+} from './keyring.ts';
+export type {
+	Keyring,
+	KeyringErrorCode,
+	KeyringOptions,
+	SealedEnvelope,
+	StoredEnvelope,
+} from './keyring.ts';
 export {
 	DEFAULT_HISTORY_PAGE,
 	diffFields,
@@ -44,7 +118,10 @@ export type {
 	RecordChanges,
 	TrackedFields,
 } from './record-history.ts';
-export { createModuleRegistry } from './module-registry.ts';
+export {
+	capabilityProviders,
+	createModuleRegistry,
+} from './module-registry.ts';
 export {
 	assertSettingValue,
 	createModuleSettingsRuntime,
@@ -56,6 +133,7 @@ export type {
 	ModuleSettingChange,
 	ModuleSettingDefinition,
 	ModuleSettingEntry,
+	ModuleSettingKind,
 	ModuleSettingRecord,
 	ModuleSettingScope,
 	ModuleSettingsDeclaration,
@@ -87,4 +165,7 @@ export {
 	assertModuleDependency,
 	satisfiesModuleVersion,
 	compareModuleVersions,
+	incrementModuleVersion,
+	retargetModuleRange,
 } from './module-compatibility.ts';
+export type { ModuleVersionLevel } from './module-compatibility.ts';

package/packages/kernel/src/keyring.ts

@@ -0,0 +1,208 @@
+import {
+	createCipheriv,
+	createDecipheriv,
+	createHash,
+	randomBytes,
+} from 'node:crypto';
+
+export const KEYRING_KEY_BYTES = 32;
+export const KEYRING_IV_BYTES = 12;
+export const KEYRING_TAG_BYTES = 16;
+/* An open of an envelope without a key id tries every key in turn, so the ring
+   is bounded. A chain longer than this means a rotation was never finished. */
+export const KEYRING_MAX_PREVIOUS_KEYS = 8;
+
+export type KeyringErrorCode = 'KEY_UNKNOWN' | 'ENVELOPE_INVALID';
+
+/** A failure to open an envelope, with the code a caller may branch on. */
+export class KeyringError extends Error {
+	readonly code: KeyringErrorCode;
+
+	constructor(code: KeyringErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = 'KeyringError';
+		this.code = code;
+	}
+}
+
+/** An envelope this ring produced. `keyId` names the key that sealed it. */
+export interface SealedEnvelope {
+	readonly keyId: string;
+	readonly iv: Buffer;
+	readonly tag: Buffer;
+	readonly ciphertext: Buffer;
+}
+
+/**
+ * An envelope read back from storage. `keyId` is absent for rows written by an
+ * envelope format that never recorded one; those are opened by trying the
+ * current key and then each previous key.
+ */
+export interface StoredEnvelope {
+	readonly keyId?: string | undefined;
+	readonly iv: Uint8Array;
+	readonly tag: Uint8Array;
+	readonly ciphertext: Uint8Array;
+}
+
+export interface Keyring {
+	/** Fingerprint of the key every `seal` uses. */
+	readonly keyId: string;
+	readonly previousKeyIds: readonly string[];
+	knows(keyId: string): boolean;
+	seal(
+		plaintext: Uint8Array | string,
+		aad?: Uint8Array | string,
+	): SealedEnvelope;
+	open(envelope: StoredEnvelope, aad?: Uint8Array | string): Buffer;
+}
+
+export interface KeyringOptions {
+	readonly current: Uint8Array;
+	readonly previous?: readonly Uint8Array[] | undefined;
+}
+
+/**
+ * The key id the module envelope formats already store: the first 16 hex
+ * characters of the SHA-256 of the key material. Changing it would orphan every
+ * stored row, so it is fixed.
+ */
+export function keyFingerprint(key: Uint8Array): string {
+	return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+
+function assertKeyLength(key: Uint8Array, position: string): void {
+	if (key.byteLength !== KEYRING_KEY_BYTES) {
+		throw new Error(
+			`A keyring ${position} key must be exactly ${KEYRING_KEY_BYTES} bytes.`,
+		);
+	}
+}
+
+/* The cipher reads the bytes inside the call, so a payload that already is
+   bytes is passed through rather than copied. */
+function bytes(value: Uint8Array | string): Uint8Array {
+	return typeof value === 'string' ? Buffer.from(value, 'utf8') : value;
+}
+
+/**
+ * An AES-256-GCM key set: one current key that seals every new envelope, and
+ * the keys kept only to open envelopes written before the last rotation. An
+ * envelope carries the fingerprint of the key that sealed it, so opening is a
+ * lookup rather than a search, and a deployment can run with both keys while
+ * the stored rows are re-sealed.
+ */
+export function createKeyring(options: KeyringOptions): Keyring {
+	assertKeyLength(options.current, 'current');
+	const previous = options.previous ?? [];
+	if (previous.length > KEYRING_MAX_PREVIOUS_KEYS) {
+		throw new Error(
+			`A keyring accepts at most ${KEYRING_MAX_PREVIOUS_KEYS} previous keys; ${previous.length} were given.`,
+		);
+	}
+	const current = Buffer.from(options.current);
+	const currentKeyId = keyFingerprint(current);
+	const keys = new Map<string, Buffer>([[currentKeyId, current]]);
+	const order: Buffer[] = [current];
+	for (const key of previous) {
+		assertKeyLength(key, 'previous');
+		const id = keyFingerprint(key);
+		/* A key listed twice, or a previous list still naming the key that was
+		   promoted to current, is the same key under the same id. */
+		if (keys.has(id)) continue;
+		const copy = Buffer.from(key);
+		keys.set(id, copy);
+		order.push(copy);
+	}
+	const previousKeyIds = order.slice(1).map((key) => keyFingerprint(key));
+
+	const decrypt = (
+		key: Buffer,
+		envelope: StoredEnvelope,
+		aad: Uint8Array | undefined,
+	): Buffer => {
+		const decipher = createDecipheriv('aes-256-gcm', key, envelope.iv);
+		if (aad) decipher.setAAD(aad);
+		decipher.setAuthTag(envelope.tag);
+		return Buffer.concat([
+			decipher.update(envelope.ciphertext),
+			decipher.final(),
+		]);
+	};
+
+	return {
+		keyId: currentKeyId,
+		previousKeyIds,
+		knows: (keyId) => keys.has(keyId),
+		seal(plaintext, aad) {
+			const iv = randomBytes(KEYRING_IV_BYTES);
+			const cipher = createCipheriv('aes-256-gcm', current, iv);
+			if (aad !== undefined) cipher.setAAD(bytes(aad));
+			const ciphertext = Buffer.concat([
+				cipher.update(bytes(plaintext)),
+				cipher.final(),
+			]);
+			return { keyId: currentKeyId, iv, tag: cipher.getAuthTag(), ciphertext };
+		},
+		open(envelope, aad) {
+			if (
+				envelope.iv.byteLength !== KEYRING_IV_BYTES ||
+				envelope.tag.byteLength !== KEYRING_TAG_BYTES
+			) {
+				throw new KeyringError(
+					'ENVELOPE_INVALID',
+					'The envelope does not carry a 12-byte nonce and a 16-byte authentication tag.',
+				);
+			}
+			const additional = aad === undefined ? undefined : bytes(aad);
+			if (envelope.keyId !== undefined) {
+				const key = keys.get(envelope.keyId);
+				if (!key) {
+					throw new KeyringError(
+						'KEY_UNKNOWN',
+						`No key in this ring has the id ${envelope.keyId}.`,
+					);
+				}
+				try {
+					return decrypt(key, envelope, additional);
+				} catch (error) {
+					throw new KeyringError(
+						'ENVELOPE_INVALID',
+						'The envelope failed authentication under the key it names.',
+						{ cause: error },
+					);
+				}
+			}
+			/* No key id was stored, so the writer cannot be identified. Nothing
+			   distinguishes a missing key from a corrupt row here, and the code
+			   says so: KEY_UNKNOWN covers both. */
+			for (const key of order) {
+				try {
+					return decrypt(key, envelope, additional);
+				} catch {
+					continue;
+				}
+			}
+			throw new KeyringError(
+				'KEY_UNKNOWN',
+				'No key in this ring opens an envelope that carries no key id.',
+			);
+		},
+	};
+}
+
+/**
+ * Reads a comma-separated list of previous keys from one environment variable.
+ * Empty entries are dropped, so a trailing comma is not a configuration error.
+ */
+export function parsePreviousKeys<T>(
+	value: string | undefined,
+	decode: (entry: string) => T,
+): readonly T[] {
+	if (!value) return [];
+	return value
+		.split(',')
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0)
+		.map(decode);
+}