@flowdular/sdk 0.2.4 → 0.3.1

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/approval-grant.ts

@@ -0,0 +1,310 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import {
+	KEYRING_KEY_BYTES,
+	KEYRING_MAX_PREVIOUS_KEYS,
+	keyFingerprint,
+	parsePreviousKeys,
+	type KeyringOptions,
+} from './keyring.ts';
+
+export const APPROVAL_GRANT_KEY_VARIABLE = 'FD_APPROVAL_GRANT_KEY';
+export const APPROVAL_GRANT_PREVIOUS_KEY_VARIABLE =
+	'FD_APPROVAL_GRANT_KEY_PREVIOUS';
+export const APPROVAL_GRANT_MAX_TOKEN_LENGTH = 2_048;
+export const APPROVAL_GRANT_INPUT_DIGEST_LENGTH = 64;
+
+const TOKEN_PREFIX = 'ag1';
+const MAX_CLAIM_LENGTH = 128;
+
+export type ApprovalGrantReason =
+	| 'APPROVAL_GRANT_INVALID'
+	| 'APPROVAL_GRANT_EXPIRED'
+	| 'APPROVAL_GRANT_MISMATCH';
+
+/**
+ * What one approved request lets one caller do with one input. The harness
+ * admits one tool call per grant within a run; the CLI runner has no platform
+ * connection to record use on, so a grant passed to it is bounded by
+ * `expiresAt` alone and the same token runs the same invocation again until
+ * then. The window is the approving module's to keep short.
+ */
+export interface ApprovalGrantClaims {
+	readonly v: 1;
+	readonly tenantId: string;
+	readonly capabilityId: string;
+	/** `approvalInputDigest` of the invocation input the approval was asked for. */
+	readonly inputDigest: string;
+	readonly requestId: string;
+	readonly issuedAt: number;
+	readonly expiresAt: number;
+	readonly nonce: string;
+}
+
+export type ApprovalGrantInput = Omit<ApprovalGrantClaims, 'v'>;
+
+export interface IssuedApprovalGrant {
+	readonly token: string;
+	readonly claims: ApprovalGrantClaims;
+	readonly keyId: string;
+}
+
+/** What a verifier holds the grant against; an absent digest is not checked. */
+export interface ApprovalGrantExpectation {
+	readonly tenantId: string;
+	readonly capabilityId: string;
+	readonly inputDigest?: string | undefined;
+}
+
+export type ApprovalGrantVerification =
+	| { readonly ok: true; readonly claims: ApprovalGrantClaims }
+	| {
+			readonly ok: false;
+			readonly reason: ApprovalGrantReason;
+			readonly message: string;
+	  };
+
+/**
+ * The HMAC key set behind approval grants: the current key signs, and every
+ * key kept from before a rotation still verifies, looked up by the fingerprint
+ * the token names.
+ */
+export interface ApprovalGrantKeyring {
+	readonly keyId: string;
+	readonly previousKeyIds: readonly string[];
+	key(keyId: string): Buffer | undefined;
+}
+
+export function createApprovalGrantKeyring(
+	options: KeyringOptions,
+): ApprovalGrantKeyring {
+	const previous = options.previous ?? [];
+	if (previous.length > KEYRING_MAX_PREVIOUS_KEYS) {
+		throw new Error(
+			`An approval grant keyring accepts at most ${KEYRING_MAX_PREVIOUS_KEYS} previous keys; ${previous.length} were given.`,
+		);
+	}
+	const keys = new Map<string, Buffer>();
+	const order: string[] = [];
+	for (const key of [options.current, ...previous]) {
+		if (key.byteLength !== KEYRING_KEY_BYTES) {
+			throw new Error(
+				`An approval grant key must be exactly ${KEYRING_KEY_BYTES} bytes.`,
+			);
+		}
+		const id = keyFingerprint(key);
+		if (keys.has(id)) continue;
+		keys.set(id, Buffer.from(key));
+		order.push(id);
+	}
+	return {
+		keyId: order[0]!,
+		previousKeyIds: order.slice(1),
+		key: (keyId) => keys.get(keyId),
+	};
+}
+
+function decodeKey(value: string, variable: string): Buffer {
+	const key = Buffer.from(value.trim(), 'base64');
+	if (key.byteLength !== KEYRING_KEY_BYTES) {
+		key.fill(0);
+		throw new Error(
+			`${variable} must be a base64-encoded ${KEYRING_KEY_BYTES}-byte key.`,
+		);
+	}
+	return key;
+}
+
+/** Absent when no key is configured: nothing can then be issued or verified. */
+export function approvalGrantKeyringFromEnvironment(
+	environment: NodeJS.ProcessEnv = process.env,
+): ApprovalGrantKeyring | undefined {
+	const current = environment[APPROVAL_GRANT_KEY_VARIABLE];
+	if (!current) return undefined;
+	return createApprovalGrantKeyring({
+		current: decodeKey(current, APPROVAL_GRANT_KEY_VARIABLE),
+		previous: parsePreviousKeys(
+			environment[APPROVAL_GRANT_PREVIOUS_KEY_VARIABLE],
+			(entry) => decodeKey(entry, APPROVAL_GRANT_PREVIOUS_KEY_VARIABLE),
+		),
+	});
+}
+
+function canonical(value: unknown): string {
+	if (value === null || typeof value !== 'object') {
+		return JSON.stringify(value === undefined ? null : value);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((entry) => canonical(entry)).join(',')}]`;
+	}
+	const entries = Object.entries(value as Record<string, unknown>)
+		.filter(([, entry]) => entry !== undefined)
+		.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+	return `{${entries
+		.map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)
+		.join(',')}}`;
+}
+
+/**
+ * The digest a grant binds to: the SHA-256 of the input serialised with
+ * object keys sorted, so the requester and the verifier agree on it
+ * whatever order either built the object in.
+ */
+export function approvalInputDigest(input: unknown): string {
+	return createHash('sha256').update(canonical(input), 'utf8').digest('hex');
+}
+
+function claimString(
+	value: unknown,
+	maximum = MAX_CLAIM_LENGTH,
+): string | undefined {
+	return typeof value === 'string' &&
+		value.length >= 1 &&
+		value.length <= maximum &&
+		!/[\s\u0000]/.test(value)
+		? value
+		: undefined;
+}
+
+function claimInteger(value: unknown): number | undefined {
+	return Number.isSafeInteger(value) && (value as number) >= 0
+		? (value as number)
+		: undefined;
+}
+
+function readClaims(value: unknown): ApprovalGrantClaims | undefined {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		return undefined;
+	}
+	const raw = value as Record<string, unknown>;
+	const tenantId = claimString(raw.tenantId);
+	const capabilityId = claimString(raw.capabilityId);
+	const inputDigest = claimString(
+		raw.inputDigest,
+		APPROVAL_GRANT_INPUT_DIGEST_LENGTH,
+	);
+	const requestId = claimString(raw.requestId);
+	const nonce = claimString(raw.nonce);
+	const issuedAt = claimInteger(raw.issuedAt);
+	const expiresAt = claimInteger(raw.expiresAt);
+	if (
+		raw.v !== 1 ||
+		tenantId === undefined ||
+		capabilityId === undefined ||
+		inputDigest === undefined ||
+		requestId === undefined ||
+		nonce === undefined ||
+		issuedAt === undefined ||
+		expiresAt === undefined ||
+		expiresAt <= issuedAt
+	) {
+		return undefined;
+	}
+	return {
+		v: 1,
+		tenantId,
+		capabilityId,
+		inputDigest,
+		requestId,
+		issuedAt,
+		expiresAt,
+		nonce,
+	};
+}
+
+function signature(key: Buffer, signed: string): Buffer {
+	return createHmac('sha256', key).update(signed, 'utf8').digest();
+}
+
+export function issueApprovalGrant(
+	keyring: ApprovalGrantKeyring,
+	input: ApprovalGrantInput,
+): IssuedApprovalGrant {
+	const claims = readClaims({ v: 1, ...input });
+	if (!claims) {
+		throw new Error('Approval grant claims are out of bounds.');
+	}
+	const payload = Buffer.from(canonical(claims), 'utf8').toString('base64url');
+	const signed = `${TOKEN_PREFIX}.${keyring.keyId}.${payload}`;
+	const token = `${signed}.${signature(keyring.key(keyring.keyId)!, signed).toString('base64url')}`;
+	if (token.length > APPROVAL_GRANT_MAX_TOKEN_LENGTH) {
+		throw new Error('Approval grant token exceeds the token bound.');
+	}
+	return { token, claims, keyId: keyring.keyId };
+}
+
+function invalid(message: string): ApprovalGrantVerification {
+	return { ok: false, reason: 'APPROVAL_GRANT_INVALID', message };
+}
+
+/**
+ * Signature first, then lifetime, then binding: a token that does not verify
+ * says nothing about who it was for, and one that has run out is refused
+ * before its claims are compared.
+ */
+export function verifyApprovalGrant(
+	keyring: ApprovalGrantKeyring,
+	token: string,
+	expected: ApprovalGrantExpectation,
+	now: number = Date.now(),
+): ApprovalGrantVerification {
+	if (
+		typeof token !== 'string' ||
+		token.length < 32 ||
+		token.length > APPROVAL_GRANT_MAX_TOKEN_LENGTH
+	) {
+		return invalid('The approval grant is not a token this platform issued.');
+	}
+	const [prefix, keyId, payload, supplied, extra] = token.split('.');
+	if (
+		prefix !== TOKEN_PREFIX ||
+		!keyId ||
+		!payload ||
+		!supplied ||
+		extra !== undefined
+	) {
+		return invalid('The approval grant is not a token this platform issued.');
+	}
+	const key = keyring.key(keyId);
+	if (!key) {
+		return invalid(
+			'The approval grant names a key this platform does not hold.',
+		);
+	}
+	const expectedSignature = signature(key, `${prefix}.${keyId}.${payload}`);
+	const suppliedSignature = Buffer.from(supplied, 'base64url');
+	if (
+		suppliedSignature.byteLength !== expectedSignature.byteLength ||
+		!timingSafeEqual(suppliedSignature, expectedSignature)
+	) {
+		return invalid('The approval grant signature does not verify.');
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+	} catch {
+		return invalid('The approval grant payload is unreadable.');
+	}
+	const claims = readClaims(parsed);
+	if (!claims) return invalid('The approval grant payload is out of bounds.');
+	if (claims.expiresAt <= now) {
+		return {
+			ok: false,
+			reason: 'APPROVAL_GRANT_EXPIRED',
+			message: 'The approval grant has expired.',
+		};
+	}
+	if (
+		claims.tenantId !== expected.tenantId ||
+		claims.capabilityId !== expected.capabilityId ||
+		(expected.inputDigest !== undefined &&
+			claims.inputDigest !== expected.inputDigest)
+	) {
+		return {
+			ok: false,
+			reason: 'APPROVAL_GRANT_MISMATCH',
+			message:
+				'The approval grant was issued for another workspace, capability or input.',
+		};
+	}
+	return { ok: true, claims };
+}

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