@flowdular/sdk 0.3.0 → 0.3.2

package/packages/harness/src/runtime.ts

@@ -1,6 +1,16 @@
 import { createHash } from 'node:crypto';
 import { AgentHarnessError } from './errors.ts';
-import { normalizeActor, type Actor, type UserActor } from '@flowdular/sdk/kernel';
+import {
+	APPROVAL_GRANT_MAX_TOKEN_LENGTH,
+	approvalGrantKeyringFromEnvironment,
+	approvalInputDigest,
+	normalizeActor,
+	verifyApprovalGrant,
+	type Actor,
+	type ApprovalGrantKeyring,
+	type ApprovalGrantReason,
+	type UserActor,
+} from '@flowdular/sdk/kernel';
 import {
 	boundToolOutput,
 	toolTimeoutMs,
@@ -49,10 +59,16 @@ export interface AgentExecutionRequest {
 	readonly definition: AgentExecutionDefinition;
 	readonly permissionSnapshot: readonly string[];
 	readonly toolGrants: readonly string[];
+	/* Signed approval grants (`issueApprovalGrant`) for the external or
+	   destructive tools this run may call, each bound to one tool id and one
+	   input digest. Absent means no such tool is offered. */
+	readonly grants?: readonly string[];
 	/* Absent keeps the v1 text behavior. */
 	readonly outputContract?: AgentOutputContract;
 }
 
+export const MAX_APPROVAL_GRANTS = 16;
+
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue =
 	| JsonPrimitive
@@ -153,6 +169,10 @@ export interface AgentTool {
 	readonly contractVersion?: number;
 	readonly outputSchema?: Readonly<Record<string, unknown>>;
 	readonly risk?: 'read' | 'workspace-write' | 'external' | 'destructive';
+	/* A CLI capability the runner admits in development and test only. The
+	   harness reads FD_ENV or NODE_ENV the way the runner does and refuses it
+	   elsewhere, grant or not. */
+	readonly localOnly?: boolean;
 	/* Run-time admission on top of the permission snapshot. A tool declaring one
 	   is offered to the model as usual and refused per call when the gate says so. */
 	readonly consent?: AgentToolConsent;
@@ -285,6 +305,23 @@ function assertExecutionRequest(request: AgentExecutionRequest): void {
 		);
 	}
 	boundedText(request.input, 'input', 1, 100_000);
+	if (request.grants !== undefined) {
+		if (
+			!Array.isArray(request.grants) ||
+			request.grants.length > MAX_APPROVAL_GRANTS ||
+			request.grants.some(
+				(grant) =>
+					typeof grant !== 'string' ||
+					grant.length < 1 ||
+					grant.length > APPROVAL_GRANT_MAX_TOKEN_LENGTH,
+			)
+		) {
+			throw new AgentHarnessError(
+				'INVALID_INPUT',
+				`grants must be at most ${MAX_APPROVAL_GRANTS} tokens of at most ${APPROVAL_GRANT_MAX_TOKEN_LENGTH} characters.`,
+			);
+		}
+	}
 	boundedText(request.definition.name, 'definition.name', 2, 120);
 	boundedText(request.definition.instructions, 'instructions', 8, 40_000);
 	providerReference(request.definition.provider);
@@ -387,13 +424,75 @@ function toolFailure(error: unknown): { code: string; message: string } {
 }
 
 /**
- * `external` is the ceiling no unattended caller crosses: the CLI runner
- * refuses it, `defineCliAgentTool` and `defineApiAgentTool` refuse to build it,
- * and a hand-built tool object is refused here as well, before the model is
- * ever told the tool exists.
+ * `external` is the ceiling no unattended caller crosses on its own: the CLI
+ * runner, `defineCliAgentTool` for a destructive capability, and a hand-built
+ * tool object here all run only under a signed approval grant naming the tool
+ * and the input, before the model is ever told the tool exists.
  */
-function admissibleRisk(tool: AgentTool): boolean {
-	return tool.risk !== 'external';
+function requiresApprovalGrant(tool: AgentTool): boolean {
+	return (
+		tool.risk === 'external' ||
+		(tool.risk === 'destructive' && tool.transport === 'cli')
+	);
+}
+
+type GrantRefusal = ApprovalGrantReason | 'APPROVAL_GRANT_CONSUMED';
+
+interface RunApprovalGrants {
+	/** Tokens that verify for this tenant, by the tool id they name. */
+	readonly byTool: ReadonlyMap<string, readonly string[]>;
+	/** Why the first refused token was refused, per tool, for the denial event. */
+	readonly refusals: ReadonlyMap<string, GrantRefusal>;
+}
+
+/* The same reading the CLI runner applies to a localOnly capability. */
+function localOnlyRefused(tool: AgentTool): boolean {
+	const environment =
+		process.env.FD_ENV ?? process.env.NODE_ENV ?? 'development';
+	return (
+		tool.localOnly === true &&
+		environment !== 'development' &&
+		environment !== 'test'
+	);
+}
+
+/* Signature, key and tenant are settled once per run; the input digest is
+   settled per call, because the model chooses the input. A token that is
+   invalid or expired is so for every tool, and is recorded against each. */
+function runApprovalGrants(
+	keyring: ApprovalGrantKeyring | undefined,
+	request: AgentExecutionRequest,
+	tools: ReadonlyMap<string, AgentTool>,
+): RunApprovalGrants {
+	const byTool = new Map<string, string[]>();
+	const refusals = new Map<string, GrantRefusal>();
+	if (!keyring) return { byTool, refusals };
+	const gated = [...tools.values()].filter(requiresApprovalGrant);
+	for (const token of request.grants ?? []) {
+		let reason: ApprovalGrantReason = 'APPROVAL_GRANT_MISMATCH';
+		let matched = false;
+		for (const tool of gated) {
+			const verified = verifyApprovalGrant(keyring, token, {
+				tenantId: request.tenantId,
+				capabilityId: tool.id,
+			});
+			if (verified.ok) {
+				byTool.set(tool.id, [...(byTool.get(tool.id) ?? []), token]);
+				matched = true;
+				break;
+			}
+			reason = verified.reason;
+			if (reason !== 'APPROVAL_GRANT_MISMATCH') break;
+		}
+		/* A token that verifies for no tool is refused for every gated tool: it
+		   was signed for another tenant or capability, or not by this platform. */
+		if (!matched) {
+			for (const other of gated) {
+				if (!refusals.has(other.id)) refusals.set(other.id, reason);
+			}
+		}
+	}
+	return { byTool, refusals };
 }
 
 /* A refusal code comes from module code, so it is bounded to the shape an
@@ -466,12 +565,16 @@ export class AgentHarness {
 	readonly #tools: ReadonlyMap<string, AgentTool>;
 	readonly #authorizeToolAccess: AgentToolAccessAuthorizer;
 	readonly #tracer: AgentTracer | undefined;
+	readonly #approvalGrants: ApprovalGrantKeyring | undefined;
 
 	constructor(options: {
 		readonly providers: readonly AgentProvider[];
 		readonly tools?: readonly AgentTool[];
 		readonly authorizeToolAccess?: AgentToolAccessAuthorizer;
 		readonly tracer?: AgentTracer;
+		/* Verifies the approval grants a run carries. Absent reads
+		   FD_APPROVAL_GRANT_KEY; without either, no external tool ever runs. */
+		readonly approvalGrants?: ApprovalGrantKeyring;
 	}) {
 		const providers = new Map<string, AgentProvider>();
 		for (const provider of options.providers) {
@@ -506,6 +609,8 @@ export class AgentHarness {
 		   permanent credential. */
 		this.#authorizeToolAccess = options.authorizeToolAccess ?? (() => []);
 		this.#tracer = options.tracer;
+		this.#approvalGrants =
+			options.approvalGrants ?? approvalGrantKeyringFromEnvironment();
 	}
 
 	providers(): readonly string[] {
@@ -624,9 +729,17 @@ export class AgentHarness {
 			);
 		};
 		const initialPermissions = await livePermissions();
+		const grantKeyring = this.#approvalGrants;
+		const approvals = runApprovalGrants(grantKeyring, request, this.#tools);
+		const admissible = (tool: AgentTool): boolean =>
+			!localOnlyRefused(tool) &&
+			(!requiresApprovalGrant(tool) || approvals.byTool.has(tool.id));
+		/* One call per grant: a request approved once admits one invocation of
+		   the tool it names, however many times the model asks. */
+		const consumedGrants = new Set<string>();
 		const availableTools = [...this.#tools.values()]
 			.filter((tool) => snapshotGrants.has(tool.id))
-			.filter(admissibleRisk)
+			.filter(admissible)
 			.filter((tool) =>
 				tool.requiredPermissions.every((permission) =>
 					initialPermissions.has(permission),
@@ -670,14 +783,26 @@ export class AgentHarness {
 		): Promise<unknown> => {
 			const ordinal = ++toolCallOrdinal;
 			const tool = this.#tools.get(id);
-			if (tool && !admissibleRisk(tool)) {
+			if (tool && localOnlyRefused(tool)) {
+				emit('tool.denied', `Tool ${id} was denied.`, {
+					tool: id,
+					reason: 'TOOL_LOCAL_ONLY',
+				});
+				throw new AgentHarnessError(
+					'TOOL_LOCAL_ONLY',
+					`Tool ${id} is a local-only capability and cannot run in this environment.`,
+				);
+			}
+			if (tool && !admissible(tool)) {
+				const refusal = approvals.refusals.get(id);
 				emit('tool.denied', `Tool ${id} was denied.`, {
 					tool: id,
 					reason: 'TOOL_RISK_REFUSED',
+					...(refusal ? { grant: refusal } : {}),
 				});
 				throw new AgentHarnessError(
 					'TOOL_RISK_REFUSED',
-					`Tool ${id} declares external risk and cannot run unattended.`,
+					`Tool ${id} declares ${tool.risk} risk and runs only under an approval grant.`,
 				);
 			}
 			if (!tool || !grantedIds.has(id)) {
@@ -748,6 +873,40 @@ export class AgentHarness {
 				});
 				throw error;
 			}
+			if (requiresApprovalGrant(tool)) {
+				const expected = {
+					tenantId: request.tenantId,
+					capabilityId: id,
+					inputDigest: approvalInputDigest(input),
+				};
+				let refusal: GrantRefusal = 'APPROVAL_GRANT_MISMATCH';
+				const admitted =
+					grantKeyring !== undefined &&
+					(approvals.byTool.get(id) ?? []).some((token) => {
+						const verified = verifyApprovalGrant(grantKeyring, token, expected);
+						if (!verified.ok) {
+							refusal = verified.reason;
+							return false;
+						}
+						if (consumedGrants.has(verified.claims.requestId)) {
+							refusal = 'APPROVAL_GRANT_CONSUMED';
+							return false;
+						}
+						consumedGrants.add(verified.claims.requestId);
+						return true;
+					});
+				if (!admitted) {
+					emit('tool.denied', `Tool ${id} was denied.`, {
+						tool: id,
+						reason: 'TOOL_RISK_REFUSED',
+						grant: refusal,
+					});
+					throw new AgentHarnessError(
+						'TOOL_RISK_REFUSED',
+						`Tool ${id} has no approval grant for this input.`,
+					);
+				}
+			}
 			if (tool.consent) {
 				/* Foreign code: a throw is a refusal, never a crash. The run deadline
 				   already bounds it, because the provider call this runs inside races

package/packages/harness/src/tool-adapters.ts

@@ -30,6 +30,7 @@ export interface CliAgentToolDefinition extends AgentToolBase {
 	readonly capability: {
 		readonly id: string;
 		readonly risk: CapabilityRisk;
+		readonly localOnly?: boolean;
 	};
 }
 
@@ -40,14 +41,11 @@ function dottedIdentifier(value: string, field: string): string {
 	return value;
 }
 
+/* An external tool builds as any other; the harness offers and runs it only
+   under an approval grant naming the tool and the input. */
 export function defineApiAgentTool(
 	definition: ApiAgentToolDefinition,
 ): AgentTool {
-	if (definition.risk === 'external') {
-		throw new Error(
-			`Tool ${definition.id} declares external risk and cannot be registered as an unattended agent tool.`,
-		);
-	}
 	return Object.freeze({
 		id: dottedIdentifier(definition.id, 'Tool id'),
 		transport: 'api' as const,
@@ -80,17 +78,11 @@ export function defineApiAgentTool(
 	});
 }
 
+/* An external or destructive capability builds as any other; the harness runs
+   the tool only under an approval grant naming the tool and the input. */
 export function defineCliAgentTool(
 	definition: CliAgentToolDefinition,
 ): AgentTool {
-	if (
-		definition.capability.risk === 'external' ||
-		definition.capability.risk === 'destructive'
-	) {
-		throw new Error(
-			`CLI capability ${definition.capability.id} requires an approval receipt and cannot be registered as an unattended agent tool.`,
-		);
-	}
 	return Object.freeze({
 		id: dottedIdentifier(definition.id, 'Tool id'),
 		transport: 'cli' as const,
@@ -104,6 +96,7 @@ export function defineCliAgentTool(
 			? {}
 			: { outputSchema: definition.outputSchema }),
 		...(definition.risk === undefined ? {} : { risk: definition.risk }),
+		...(definition.capability.localOnly === true ? { localOnly: true } : {}),
 		...(definition.consent === undefined
 			? {}
 			: { consent: definition.consent }),

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/index.ts

@@ -63,6 +63,26 @@ 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,

package/packages/server/src/endpoint.ts

@@ -1,6 +1,7 @@
 import { ServerRoute, type Context } from '@octanejs/app-core';
 import { serverLogger } from './log.ts';
 import { serverMetrics } from './metrics.ts';
+import { MODULE_INACTIVE, routeActiveForTenant } from './module-activation.ts';
 import {
 	formatTraceParent,
 	runWithTrace,
@@ -11,6 +12,8 @@ import { serverTracer, type Span } from './trace/tracer.ts';
 export interface EndpointIdentity {
 	readonly subjectId: string;
 	readonly permissions: ReadonlySet<string>;
+	/** The workspace the identity acts in; the module activation gate reads it. */
+	readonly tenantId?: string;
 }
 
 export interface EndpointExecutionContext {
@@ -131,6 +134,19 @@ export function defineEndpoint(
 						traceparent,
 					);
 				}
+				if (
+					identity.tenantId !== undefined &&
+					!(await routeActiveForTenant(serverRoute, identity.tenantId))
+				) {
+					status = 403;
+					return problem(
+						403,
+						MODULE_INACTIVE,
+						'This module is inactive in the workspace.',
+						requestId,
+						traceparent,
+					);
+				}
 			}
 
 			const response = await definition.handler({
@@ -171,7 +187,7 @@ export function defineEndpoint(
 		}
 	};
 
-	const serverRoute = new ServerRoute({
+	const serverRoute: ServerRoute = new ServerRoute({
 		path: definition.path,
 		methods: definition.methods.map((method) => method.toUpperCase()),
 		handler: (context) => {