@ankhorage/flow 0.0.0-stage → 0.5.0

package/src/features/mcp/validateMcpSchema.ts

@@ -0,0 +1,269 @@
+import { createHash } from 'node:crypto';
+
+import { McpToolError } from './McpToolError.js';
+
+const MAX_DEPTH = 16;
+const TYPES = new Set(['null', 'boolean', 'number', 'integer', 'string', 'array', 'object']);
+const KEYS = new Set([
+  '$schema',
+  'title',
+  'description',
+  'type',
+  'const',
+  'enum',
+  'properties',
+  'required',
+  'additionalProperties',
+  'minProperties',
+  'maxProperties',
+  'items',
+  'minItems',
+  'maxItems',
+  'uniqueItems',
+  'minLength',
+  'maxLength',
+  'pattern',
+  'minimum',
+  'maximum',
+  'exclusiveMinimum',
+  'exclusiveMaximum',
+  'multipleOf',
+]);
+
+/*** Validates a closed supported JSON Schema and returns its stable argument matcher. */
+export const validateMcpSchema = (schema: Readonly<Record<string, unknown>>) => {
+  validateSchema(schema, 0);
+  return {
+    fingerprint: createHash('sha256').update(stableStringify(schema)).digest('hex'),
+    matches: (value: unknown): boolean => matches(schema, value),
+  };
+};
+
+/*** Rejects unsupported JSON Schema features instead of weakening validation. */
+const validateSchema = (schema: Readonly<Record<string, unknown>>, depth: number): void => {
+  if (depth > MAX_DEPTH)
+    throw new McpToolError('invalid_schema', 'MCP schema exceeds depth limit.');
+  if (Object.keys(schema).some((key) => !KEYS.has(key)))
+    throw new McpToolError(
+      'unsupported_schema',
+      'The MCP tool schema uses unsupported constraints.',
+    );
+  const { type } = schema;
+  if (typeof type !== 'string' || !TYPES.has(type))
+    throw new McpToolError('invalid_schema', 'MCP schemas require one supported type.');
+  validateJsonConstraints(schema);
+  if (type === 'object') validateObject(schema, depth);
+  if (type === 'array') validateArray(schema, depth);
+  if (type === 'string') validateString(schema);
+  if (type === 'number' || type === 'integer') validateNumber(schema);
+};
+
+/*** Validates portable const and enum declarations. */
+const validateJsonConstraints = (schema: Readonly<Record<string, unknown>>): void => {
+  if ('const' in schema && !isJson(schema.const))
+    throw new McpToolError('invalid_schema', 'MCP schema const must be JSON data.');
+  if (
+    'enum' in schema &&
+    (!Array.isArray(schema.enum) || !schema.enum.length || !schema.enum.every(isJson))
+  )
+    throw new McpToolError('invalid_schema', 'MCP schema enum must contain JSON data.');
+};
+
+/*** Requires a closed object schema with validated declared properties. */
+const validateObject = (schema: Readonly<Record<string, unknown>>, depth: number): void => {
+  const { properties, required, additionalProperties } = schema;
+  if (additionalProperties !== false)
+    throw new McpToolError(
+      'unsupported_schema',
+      'MCP object schemas must set additionalProperties to false.',
+    );
+  if (!isRecord(properties))
+    throw new McpToolError('invalid_schema', 'MCP object schemas need property definitions.');
+  Object.values(properties).forEach((property) => {
+    if (!isRecord(property))
+      throw new McpToolError('invalid_schema', 'MCP property schemas must be objects.');
+    validateSchema(property, depth + 1);
+  });
+  if (
+    required !== undefined &&
+    (!isUniqueStrings(required) || required.some((key) => !(key in properties)))
+  )
+    throw new McpToolError(
+      'invalid_schema',
+      'MCP required properties must be declared exactly once.',
+    );
+  validateBounds(
+    schema.minProperties,
+    schema.maxProperties,
+    'minProperties',
+    'maxProperties',
+    true,
+  );
+};
+
+/*** Requires an item schema so every array value is validated. */
+const validateArray = (schema: Readonly<Record<string, unknown>>, depth: number): void => {
+  if (!isRecord(schema.items))
+    throw new McpToolError('unsupported_schema', 'MCP array schemas require an item schema.');
+  validateSchema(schema.items, depth + 1);
+  if (schema.uniqueItems !== undefined && typeof schema.uniqueItems !== 'boolean')
+    throw new McpToolError('invalid_schema', 'MCP uniqueItems must be boolean.');
+  validateBounds(schema.minItems, schema.maxItems, 'minItems', 'maxItems', true);
+};
+
+/*** Validates string bounds and regular-expression patterns. */
+const validateString = (schema: Readonly<Record<string, unknown>>): void => {
+  validateBounds(schema.minLength, schema.maxLength, 'minLength', 'maxLength', true);
+  if (schema.pattern !== undefined) {
+    if (typeof schema.pattern !== 'string')
+      throw new McpToolError('invalid_schema', 'MCP pattern must be a string.');
+    try {
+      new RegExp(schema.pattern, 'u');
+    } catch {
+      throw new McpToolError('invalid_schema', 'MCP pattern must compile.');
+    }
+  }
+};
+
+/*** Validates finite numeric constraints. */
+const validateNumber = (schema: Readonly<Record<string, unknown>>): void => {
+  const values = [
+    schema.minimum,
+    schema.maximum,
+    schema.exclusiveMinimum,
+    schema.exclusiveMaximum,
+    schema.multipleOf,
+  ];
+  if (
+    values.some(
+      (value) => value !== undefined && (typeof value !== 'number' || !Number.isFinite(value)),
+    )
+  )
+    throw new McpToolError('invalid_schema', 'MCP numeric constraints must be finite numbers.');
+  if (typeof schema.multipleOf === 'number' && schema.multipleOf <= 0)
+    throw new McpToolError('invalid_schema', 'MCP multipleOf must be positive.');
+};
+
+/*** Validates ordered numeric or integer bounds. */
+const validateBounds = (
+  minimum: unknown,
+  maximum: unknown,
+  minimumKey: string,
+  maximumKey: string,
+  integers: boolean,
+): void => {
+  const valid = (value: unknown): value is number =>
+    typeof value === 'number' &&
+    Number.isFinite(value) &&
+    (!integers || (Number.isSafeInteger(value) && value >= 0));
+  if (minimum !== undefined && !valid(minimum))
+    throw new McpToolError('invalid_schema', `MCP ${minimumKey} is invalid.`);
+  if (maximum !== undefined && !valid(maximum))
+    throw new McpToolError('invalid_schema', `MCP ${maximumKey} is invalid.`);
+  if (typeof minimum === 'number' && typeof maximum === 'number' && minimum > maximum)
+    throw new McpToolError('invalid_schema', `MCP ${minimumKey} cannot exceed ${maximumKey}.`);
+};
+
+/*** Matches supported JSON Schema constraints without coercion. */
+const matches = (schema: Readonly<Record<string, unknown>>, value: unknown): boolean => {
+  const { type } = schema;
+  if (typeof type !== 'string' || !matchesType(type, value)) return false;
+  if ('const' in schema && stableStringify(schema.const) !== stableStringify(value)) return false;
+  if (
+    Array.isArray(schema.enum) &&
+    !schema.enum.some((item) => stableStringify(item) === stableStringify(value))
+  )
+    return false;
+  if (type === 'object') return matchesObject(schema, value);
+  if (type === 'array') return matchesArray(schema, value);
+  if (type === 'string') return matchesString(schema, value);
+  return (type !== 'number' && type !== 'integer') || matchesNumber(schema, value as number);
+};
+
+/*** Matches a closed object and each declared property schema. */
+const matchesObject = (schema: Readonly<Record<string, unknown>>, value: unknown): boolean => {
+  const { properties, required } = schema;
+  const minProperties = numberOr(schema.minProperties, 0);
+  const maxProperties = numberOr(schema.maxProperties, Infinity);
+  if (!isRecord(value) || !isRecord(properties)) return false;
+  const entries = Object.entries(value);
+  return (
+    entries.length >= minProperties &&
+    entries.length <= maxProperties &&
+    (!Array.isArray(required) ||
+      required.every((key) => typeof key === 'string' && key in value)) &&
+    entries.every(([key, item]) => {
+      const property = Object.entries(properties).find(([name]) => name === key)?.[1];
+      return isRecord(property) && matches(property, item);
+    })
+  );
+};
+
+/*** Matches array items, bounds, and deterministic uniqueness. */
+const matchesArray = (schema: Readonly<Record<string, unknown>>, value: unknown): boolean => {
+  const { items, uniqueItems = false } = schema;
+  const minItems = numberOr(schema.minItems, 0);
+  const maxItems = numberOr(schema.maxItems, Infinity);
+  return (
+    Array.isArray(value) &&
+    isRecord(items) &&
+    value.length >= minItems &&
+    value.length <= maxItems &&
+    (!uniqueItems || new Set(value.map(stableStringify)).size === value.length) &&
+    value.every((item) => matches(items, item))
+  );
+};
+
+/*** Matches string constraints. */
+const matchesString = (schema: Readonly<Record<string, unknown>>, value: unknown): boolean =>
+  typeof value === 'string' &&
+  [...value].length >= numberOr(schema.minLength, 0) &&
+  [...value].length <= numberOr(schema.maxLength, Infinity) &&
+  (typeof schema.pattern !== 'string' || new RegExp(schema.pattern, 'u').test(value));
+
+/*** Matches finite number constraints. */
+const matchesNumber = (schema: Readonly<Record<string, unknown>>, value: number): boolean =>
+  (typeof schema.minimum !== 'number' || value >= schema.minimum) &&
+  (typeof schema.maximum !== 'number' || value <= schema.maximum) &&
+  (typeof schema.exclusiveMinimum !== 'number' || value > schema.exclusiveMinimum) &&
+  (typeof schema.exclusiveMaximum !== 'number' || value < schema.exclusiveMaximum) &&
+  (typeof schema.multipleOf !== 'number' || Number.isInteger(value / schema.multipleOf));
+
+/*** Matches a JSON Schema primitive type. */
+const matchesType = (type: string, value: unknown): boolean =>
+  (type === 'null' && value === null) ||
+  (type === 'array' && Array.isArray(value)) ||
+  (type === 'object' && isRecord(value)) ||
+  (type === 'integer' && Number.isSafeInteger(value)) ||
+  (type === 'number' && typeof value === 'number' && Number.isFinite(value)) ||
+  (type === 'string' && typeof value === 'string') ||
+  (type === 'boolean' && typeof value === 'boolean');
+
+/*** Narrows unknown data to a non-array object. */
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+/*** Confirms a value is portable JSON data. */
+const isJson = (value: unknown): boolean =>
+  value === null ||
+  ['string', 'boolean'].includes(typeof value) ||
+  (typeof value === 'number' && Number.isFinite(value)) ||
+  (Array.isArray(value) && value.every(isJson)) ||
+  (isRecord(value) && Object.values(value).every(isJson));
+/*** Confirms a value is an array of unique non-empty strings. */
+const isUniqueStrings = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) &&
+  value.every((item) => typeof item === 'string' && item.length > 0) &&
+  new Set(value).size === value.length;
+/*** Returns a numeric schema value or its validated default. */
+const numberOr = (value: unknown, fallback: number): number =>
+  typeof value === 'number' ? value : fallback;
+/*** Serializes JSON data deterministically. */
+const stableStringify = (value: unknown): string =>
+  Array.isArray(value)
+    ? `[${value.map(stableStringify).join(',')}]`
+    : isRecord(value)
+      ? `{${Object.entries(value)
+          .sort(([left], [right]) => left.localeCompare(right))
+          .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
+          .join(',')}}`
+      : JSON.stringify(value);

package/src/features/security/FlowSecurityError.ts

@@ -0,0 +1,17 @@
+/*** Represents a stable, payload-redacted Flow security denial. */
+export class FlowSecurityError extends Error {
+  public constructor(
+    public readonly code:
+      | 'approval_pending'
+      | 'approval_rejected'
+      | 'idempotency_conflict'
+      | 'invalid_target'
+      | 'permission_denied'
+      | 'rate_limited'
+      | 'secret_unavailable',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'FlowSecurityError';
+  }
+}

package/src/features/security/application/createFlowSecurityPort.ts

@@ -0,0 +1,339 @@
+import type { SecretRef, SecretStoreAdapter } from '@ankhorage/contracts/secrets';
+
+import type {
+  FlowApprovalStorePort,
+  FlowOperationStorePort,
+  FlowRateLimitPort,
+  FlowResolvedSecrets,
+  FlowSecretCreateInput,
+  FlowSecretMetadata,
+  FlowSecretRevokeInput,
+  FlowSecurityActor,
+  FlowSecurityAuditEvent,
+  FlowSecurityAuditPort,
+  FlowSecurityGrant,
+  FlowSecurityOperation,
+  FlowSecurityOperationIdentity,
+  FlowSecurityPermit,
+  FlowSecurityPort,
+  FlowSecurityTarget,
+} from '../../../types/security.js';
+import { validateFlowSecurityTarget } from '../domain/validateFlowSecurityTarget.js';
+import { FlowSecurityError } from '../FlowSecurityError.js';
+
+const METADATA_CAPABILITY = 'secrets:metadata';
+const CREATE_CAPABILITY = 'secrets:create';
+const REVOKE_CAPABILITY = 'secrets:revoke';
+type FlowSecurityDenialReason = Exclude<
+  FlowSecurityAuditEvent['reason'],
+  'credential_create' | 'credential_revoke'
+>;
+
+/*** Creates the provider-neutral server-side authorization, approval, audit, and secret boundary. */
+export const createFlowSecurityPort = (input: {
+  readonly approvalStore: FlowApprovalStorePort;
+  readonly audit: FlowSecurityAuditPort;
+  readonly grants: readonly FlowSecurityGrant[];
+  readonly operationStore: FlowOperationStorePort;
+  readonly rateLimit: FlowRateLimitPort;
+  readonly secretStore: SecretStoreAdapter;
+}): FlowSecurityPort => ({
+  authorizeAsync: async (operation) => authorizeAsync(input, operation),
+  createSecretAsync: async (request) => createSecretAsync(input, request),
+  getSecretMetadataAsync: async ({ actor, ref }) => getSecretMetadataAsync(input, actor, ref),
+  revokeSecretAsync: async (request) => revokeSecretAsync(input, request),
+});
+
+/*** Authorizes and durably claims one exact operation before resolving any secret material. */
+const authorizeAsync = async (
+  input: Parameters<typeof createFlowSecurityPort>[0],
+  operation: FlowSecurityOperation,
+): Promise<FlowSecurityPermit> => {
+  const identity = identityOf(operation);
+  const targetHost = validateFlowSecurityTarget(identity.target);
+  if (!isGranted(input.grants, identity.actor, identity.capability))
+    return denyAsync(input.audit, identity, targetHost, 'permission_denied');
+  const approval = await input.approvalStore.getAsync(identity);
+  if (approval?.status === 'pending')
+    return denyAsync(input.audit, identity, targetHost, 'approval_pending');
+  if (approval?.status !== 'approved' || !sameIdentity(approval.operation, identity))
+    return denyAsync(input.audit, identity, targetHost, 'approval_rejected');
+  if (!(await input.operationStore.claimAsync(identity)))
+    return denyAsync(input.audit, identity, targetHost, 'idempotency_conflict');
+  try {
+    if (
+      !(await input.rateLimit.acquireAsync({
+        actor: identity.actor,
+        capability: identity.capability,
+        operationId: identity.operationId,
+      }))
+    )
+      return denyAfterReleaseAsync(input, identity, targetHost, 'rate_limited');
+    await writeAuditAsync(input.audit, identity, targetHost, 'permitted', 'permission_denied');
+    return createPermit(input, identity);
+  } catch (error) {
+    await input.operationStore.releaseAsync(identity);
+    throw error;
+  }
+};
+
+/*** Creates a one-use permit that atomically consumes the durable operation claim before side effects. */
+const createPermit = (
+  input: Parameters<typeof createFlowSecurityPort>[0],
+  identity: FlowSecurityOperationIdentity,
+): FlowSecurityPermit => ({
+  operation: identity,
+  executeAsync: async (callback) => {
+    if (!(await input.operationStore.consumeAsync(identity)))
+      throw new FlowSecurityError(
+        'idempotency_conflict',
+        'The operation permit has already been consumed.',
+      );
+    return resolveAndExecuteAsync(input, identity.actor, identity.secretRefs, callback);
+  },
+});
+
+/*** Releases an unconsumed claim before emitting a retryable denial. */
+const denyAfterReleaseAsync = async (
+  input: Parameters<typeof createFlowSecurityPort>[0],
+  identity: FlowSecurityOperationIdentity,
+  targetHost: string | undefined,
+  reason: FlowSecurityDenialReason,
+): Promise<never> => {
+  await input.operationStore.releaseAsync(identity);
+  return denyAsync(input.audit, identity, targetHost, reason);
+};
+
+/*** Creates a credential only after an explicit server-side scoped grant and redacted audit. */
+const createSecretAsync = async (
+  input: Parameters<typeof createFlowSecurityPort>[0],
+  request: FlowSecretCreateInput,
+): Promise<FlowSecretMetadata> => {
+  const actor = snapshotActor(request.actor);
+  if (!isGranted(input.grants, actor, CREATE_CAPABILITY))
+    return denyCredentialAsync(input.audit, actor, request.ref, CREATE_CAPABILITY);
+  await writeCredentialAuditAsync(input.audit, actor, request.ref, CREATE_CAPABILITY);
+  const result = await input.secretStore.create({
+    kind: request.kind,
+    payload: request.payload,
+    ...(request.provider === undefined ? {} : { provider: request.provider }),
+    ref: request.ref,
+    scope: scopeOf(actor),
+  });
+  if (!result.ok)
+    throw new FlowSecurityError('secret_unavailable', 'The requested secret is unavailable.');
+  return result.data;
+};
+
+/*** Returns metadata only after an explicit actor, tenant, project, and environment grant. */
+const getSecretMetadataAsync = async (
+  input: Parameters<typeof createFlowSecurityPort>[0],
+  actor: FlowSecurityActor,
+  ref: SecretRef,
+) => {
+  const identity = snapshotActor(actor);
+  if (!isGranted(input.grants, identity, METADATA_CAPABILITY))
+    throw new FlowSecurityError(
+      'permission_denied',
+      'The actor is not permitted to inspect secrets.',
+    );
+  const result = await input.secretStore.getMetadata({ scope: scopeOf(identity), ref });
+  if (!result.ok)
+    throw new FlowSecurityError('secret_unavailable', 'The requested secret is unavailable.');
+  return result.data;
+};
+
+/*** Revokes a credential only after an explicit server-side scoped grant and redacted audit. */
+const revokeSecretAsync = async (
+  input: Parameters<typeof createFlowSecurityPort>[0],
+  request: FlowSecretRevokeInput,
+): Promise<void> => {
+  const actor = snapshotActor(request.actor);
+  if (!isGranted(input.grants, actor, REVOKE_CAPABILITY))
+    return denyCredentialAsync(input.audit, actor, request.ref, REVOKE_CAPABILITY);
+  await writeCredentialAuditAsync(input.audit, actor, request.ref, REVOKE_CAPABILITY);
+  const result = await input.secretStore.remove({ ref: request.ref, scope: scopeOf(actor) });
+  if (!result.ok)
+    throw new FlowSecurityError('secret_unavailable', 'The requested secret is unavailable.');
+};
+
+/*** Resolves secrets only in the server-side callback after durable consumption succeeds. */
+const resolveAndExecuteAsync = async <T>(
+  input: Parameters<typeof createFlowSecurityPort>[0],
+  actor: FlowSecurityActor,
+  secretRefs: readonly SecretRef[],
+  callback: (secrets: FlowResolvedSecrets) => Promise<T>,
+): Promise<T> => {
+  const resolved = await Promise.all(
+    secretRefs.map(
+      async (ref) => [ref, await resolveSecretAsync(input.secretStore, actor, ref)] as const,
+    ),
+  );
+  return callback(Object.fromEntries(resolved));
+};
+
+/*** Resolves one published secret reference without exposing a provider error or payload in failures. */
+const resolveSecretAsync = async (
+  secretStore: SecretStoreAdapter,
+  actor: FlowSecurityActor,
+  ref: SecretRef,
+) => {
+  const result = await secretStore.resolve({ scope: scopeOf(actor), ref });
+  if (!result.ok)
+    throw new FlowSecurityError('secret_unavailable', 'A required secret is unavailable.');
+  return result.data;
+};
+
+/*** Creates a deterministic complete identity from untrusted operation input. */
+const identityOf = (operation: FlowSecurityOperation): FlowSecurityOperationIdentity =>
+  Object.freeze({
+    actor: snapshotActor(operation.actor),
+    capability: operation.capability,
+    idempotencyKey: operation.idempotencyKey,
+    operationId: operation.operationId,
+    secretRefs: Object.freeze(unique(operation.secretRefs ?? [])),
+    ...(operation.target
+      ? {
+          target: Object.freeze({
+            allowedHosts: Object.freeze([...operation.target.allowedHosts]),
+            url: operation.target.url,
+          }),
+        }
+      : {}),
+  });
+
+/*** Captures a runtime-immutable actor scope before any authorization boundary can await. */
+const snapshotActor = (actor: FlowSecurityActor): FlowSecurityActor => Object.freeze({ ...actor });
+
+/*** Compares every authorization-relevant operation field without relying on object identity. */
+const sameIdentity = (
+  left: FlowSecurityOperationIdentity,
+  right: FlowSecurityOperationIdentity,
+): boolean =>
+  left.actor.id === right.actor.id &&
+  left.actor.tenantId === right.actor.tenantId &&
+  left.actor.projectId === right.actor.projectId &&
+  left.actor.environment === right.actor.environment &&
+  left.capability === right.capability &&
+  left.idempotencyKey === right.idempotencyKey &&
+  left.operationId === right.operationId &&
+  sameStrings(left.secretRefs, right.secretRefs) &&
+  sameTarget(left.target, right.target);
+
+/*** Compares target authority exactly so approvals cannot move an operation to another host. */
+const sameTarget = (
+  left: FlowSecurityTarget | undefined,
+  right: FlowSecurityTarget | undefined,
+): boolean =>
+  left === undefined || right === undefined
+    ? left === right
+    : left.url === right.url && sameStrings(left.allowedHosts, right.allowedHosts);
+
+/*** Matches two ordered identity arrays exactly. */
+const sameStrings = (left: readonly string[], right: readonly string[]): boolean =>
+  JSON.stringify(left) === JSON.stringify(right);
+
+/*** Matches a grant only when all actor isolation dimensions are equal. */
+const isGranted = (
+  grants: readonly FlowSecurityGrant[],
+  actor: FlowSecurityActor,
+  capability: string,
+): boolean =>
+  grants.some(
+    (grant) =>
+      grant.actorId === actor.id &&
+      grant.capability === capability &&
+      grant.tenantId === actor.tenantId &&
+      grant.projectId === actor.projectId &&
+      grant.environment === actor.environment,
+  );
+/*** Converts a trusted actor boundary to the published secret-store scope. */
+const scopeOf = (actor: FlowSecurityActor) => ({
+  projectId: actor.projectId,
+  environment: actor.environment,
+});
+/*** Deduplicates secret references without changing their deterministic order. */
+const unique = (refs: readonly SecretRef[]): readonly SecretRef[] => [...new Set(refs)];
+/*** Audits a redacted decision before returning a stable denial. */
+const denyAsync = async (
+  audit: FlowSecurityAuditPort,
+  identity: FlowSecurityOperationIdentity,
+  targetHost: string | undefined,
+  reason: FlowSecurityDenialReason,
+): Promise<never> => {
+  await writeAuditAsync(audit, identity, targetHost, 'denied', reason);
+  throw new FlowSecurityError(reason, denialMessage(reason));
+};
+/*** Emits only identifiers and target host metadata to the audit edge. */
+const writeAuditAsync = (
+  audit: FlowSecurityAuditPort,
+  identity: FlowSecurityOperationIdentity,
+  targetHost: string | undefined,
+  decision: FlowSecurityAuditEvent['decision'],
+  reason: FlowSecurityAuditEvent['reason'],
+): Promise<void> =>
+  audit.writeAsync({
+    actorId: identity.actor.id,
+    capability: identity.capability,
+    decision,
+    operationId: identity.operationId,
+    reason,
+    secretRefs: identity.secretRefs,
+    ...(targetHost ? { targetHost } : {}),
+  });
+/*** Audits a credential-management decision without accepting its payload at the audit edge. */
+const writeCredentialAuditAsync = (
+  audit: FlowSecurityAuditPort,
+  actor: FlowSecurityActor,
+  ref: SecretRef,
+  capability: typeof CREATE_CAPABILITY | typeof REVOKE_CAPABILITY,
+): Promise<void> =>
+  audit.writeAsync({
+    actorId: actor.id,
+    capability,
+    decision: 'permitted',
+    operationId: ref,
+    reason: capability === CREATE_CAPABILITY ? 'credential_create' : 'credential_revoke',
+    secretRefs: [ref],
+  });
+/*** Audits and returns a stable denial for unauthorized credential management. */
+const denyCredentialAsync = async (
+  audit: FlowSecurityAuditPort,
+  actor: FlowSecurityActor,
+  ref: SecretRef,
+  capability: typeof CREATE_CAPABILITY | typeof REVOKE_CAPABILITY,
+): Promise<never> => {
+  await audit.writeAsync({
+    actorId: actor.id,
+    capability,
+    decision: 'denied',
+    operationId: ref,
+    reason: 'permission_denied',
+    secretRefs: [ref],
+  });
+  throw new FlowSecurityError(
+    'permission_denied',
+    'The actor is not permitted to perform this operation.',
+  );
+};
+/*** Maps policy reasons to public redaction-safe error text. */
+const denialMessage = (reason: FlowSecurityDenialReason): string => {
+  switch (reason) {
+    case 'approval_pending':
+      return 'The operation requires an approved Flow approval gate.';
+    case 'approval_rejected':
+      return 'The Flow approval gate rejected this operation.';
+    case 'idempotency_conflict':
+      return 'The idempotency key is already bound to another operation.';
+    case 'invalid_target':
+      return 'The external target is not permitted.';
+    case 'permission_denied':
+      return 'The actor is not permitted to perform this operation.';
+    case 'rate_limited':
+      return 'The operation is rate limited.';
+    case 'secret_unavailable':
+      return 'A required secret is unavailable.';
+  }
+  const impossible: never = reason;
+  return impossible;
+};