@ankhorage/flow 0.0.0-stage → 0.4.1

package/src/features/security/domain/validateFlowSecurityTarget.ts

@@ -0,0 +1,73 @@
+import type { FlowSecurityTarget } from '../../../types/security.js';
+import { FlowSecurityError } from '../FlowSecurityError.js';
+
+/*** Validates target syntax before the host transport verifies every resolved network peer. */
+export const validateFlowSecurityTarget = (
+  target: FlowSecurityTarget | undefined,
+): string | undefined => {
+  if (!target) return undefined;
+  let url: URL;
+  try {
+    url = new URL(target.url);
+  } catch {
+    throw new FlowSecurityError('invalid_target', 'External targets must be absolute HTTPS URLs.');
+  }
+  const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (
+    url.protocol !== 'https:' ||
+    url.username ||
+    url.password ||
+    url.hash ||
+    !uniqueStrings(target.allowedHosts) ||
+    !target.allowedHosts.includes(host) ||
+    isUnsafeLiteralHost(host)
+  )
+    throw new FlowSecurityError(
+      'invalid_target',
+      'External targets must use an explicitly allowlisted public HTTPS host.',
+    );
+  return host;
+};
+
+/*** Rejects normalized loopback, local, private, and special-use IP literals before transport access. */
+const isUnsafeLiteralHost = (host: string): boolean =>
+  host === 'localhost' || host.endsWith('.localhost') || isUnsafeIpv4(host) || isUnsafeIpv6(host);
+
+/*** Identifies IPv4 ranges that must never be an outbound target. */
+const isUnsafeIpv4 = (host: string): boolean => {
+  const parts = host.split('.').map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+    return false;
+  const [first, second] = parts as [number, number, number, number];
+  return (
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    first >= 224 ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168)
+  );
+};
+
+/*** Identifies IPv6 loopback, unspecified, unique-local, link-local, and mapped literal forms. */
+const isUnsafeIpv6 = (host: string): boolean => {
+  const normalized = host.toLowerCase();
+  return (
+    normalized === '::' ||
+    normalized === '::1' ||
+    normalized.startsWith('fc') ||
+    normalized.startsWith('fd') ||
+    normalized.startsWith('fe8') ||
+    normalized.startsWith('fe9') ||
+    normalized.startsWith('fea') ||
+    normalized.startsWith('feb') ||
+    normalized.startsWith('::ffff:')
+  );
+};
+
+/*** Checks unique non-empty authority strings. */
+const uniqueStrings = (values: readonly string[]): boolean =>
+  values.length > 0 &&
+  values.every((value) => value.length > 0) &&
+  new Set(values).size === values.length;

package/src/index.ts

@@ -0,0 +1,35 @@
+/*** Headless graph compilation and deterministic single-process execution. */
+export { executeFlowAsync } from './features/execution/application/executeFlowAsync.js';
+export { compileFlowGraph } from './features/execution/domain/compileFlowGraph.js';
+export { createDefaultNodeRegistry } from './features/execution/domain/createDefaultNodeRegistry.js';
+export { createFlowSecurityPort } from './features/security/application/createFlowSecurityPort.js';
+export { FlowSecurityError } from './features/security/FlowSecurityError.js';
+export type {
+  FlowClock,
+  FlowCompiledGraph,
+  FlowExecutionResult,
+  FlowNodeOperation,
+  FlowNodeOperationResult,
+  FlowNodeRegistry,
+  FlowRunRequest,
+} from './types/execution.js';
+export type {
+  FlowApprovalStorePort,
+  FlowOperationStorePort,
+  FlowOutboundTransportPort,
+  FlowRateLimitPort,
+  FlowResolvedSecrets,
+  FlowSecretCreateInput,
+  FlowSecretMetadata,
+  FlowSecretRevokeInput,
+  FlowSecurityActor,
+  FlowSecurityApproval,
+  FlowSecurityAuditEvent,
+  FlowSecurityAuditPort,
+  FlowSecurityGrant,
+  FlowSecurityOperation,
+  FlowSecurityOperationIdentity,
+  FlowSecurityPermit,
+  FlowSecurityPort,
+  FlowSecurityTarget,
+} from './types/security.js';

package/src/mcp.ts

@@ -0,0 +1,11 @@
+/*** Optional, allowlist-only MCP tool discovery and invocation integration. */
+export { createMcpToolRegistry } from './features/mcp/createMcpToolRegistry.js';
+export type {
+  McpProviderDefinition,
+  McpToolInvocation,
+  McpToolMetadata,
+  McpToolPermission,
+  McpToolRegistry,
+  McpToolResult,
+  McpTrustedStdioProvider,
+} from './types/mcp.js';

package/src/social.ts

@@ -0,0 +1,6 @@
+/***
+ * Reserved public subpath for future social-provider adapters.
+ *
+ * This bootstrap intentionally provides no social execution, configuration, or dependencies.
+ */
+export {};

package/src/types/execution.ts

@@ -0,0 +1,41 @@
+import type { DataSchemaRegistry } from '@ankhorage/contracts/data';
+import type {
+  FlowDataRef,
+  FlowDefinition,
+  FlowEdge,
+  FlowNode,
+  FlowNodeConfig,
+  FlowPortId,
+  FlowRunSnapshot,
+} from '@ankhorage/contracts/flow';
+
+export interface FlowClock {
+  readonly now: () => Date;
+}
+export interface FlowNodeOperationResult {
+  readonly output?: Readonly<Record<FlowPortId, FlowDataRef>>;
+}
+export interface FlowNodeOperation {
+  readonly executeAsync: (input: {
+    readonly config: FlowNodeConfig | undefined;
+    readonly input: Readonly<Record<FlowPortId, FlowDataRef>>;
+    readonly node: FlowNode;
+    readonly signal: AbortSignal;
+  }) => Promise<FlowNodeOperationResult>;
+}
+export type FlowNodeRegistry = Readonly<Record<string, FlowNodeOperation>>;
+export interface FlowCompiledGraph {
+  readonly definition: FlowDefinition;
+  readonly edgesBySourceNodeId: Readonly<Record<string, readonly FlowEdge[]>>;
+  readonly topologicalNodeIds: readonly string[];
+}
+export interface FlowRunRequest {
+  readonly input?: Readonly<Record<FlowPortId, FlowDataRef>>;
+  readonly runId: string;
+  readonly schemaRegistry?: DataSchemaRegistry;
+  readonly signal?: AbortSignal;
+  readonly triggerId: string;
+}
+export interface FlowExecutionResult {
+  readonly run: FlowRunSnapshot;
+}

package/src/types/mcp.ts

@@ -0,0 +1,70 @@
+import type { SecretRef } from '@ankhorage/contracts/secrets';
+
+import type { FlowSecurityActor } from './security.js';
+
+/** Public configuration and results for the optional MCP integration. */
+export interface McpToolPermission {
+  readonly name: string;
+  readonly grantedScopes: readonly string[];
+}
+
+export type McpProviderDefinition =
+  | {
+      readonly id: string;
+      readonly transport: 'remote';
+      readonly endpoint: string;
+      readonly allowedHosts: readonly string[];
+      readonly allowedTools: readonly McpToolPermission[];
+      readonly grantedScopes: readonly string[];
+      readonly timeoutMs?: number;
+    }
+  | {
+      readonly id: string;
+      readonly transport: 'stdio';
+      readonly allowedTools: readonly McpToolPermission[];
+      readonly grantedScopes: readonly string[];
+      readonly timeoutMs?: number;
+    };
+
+/** Host-owned command configuration. It is deliberately separate from workflow provider data. */
+export interface McpTrustedStdioProvider {
+  readonly command: string;
+  readonly args?: readonly string[];
+}
+
+export interface McpToolMetadata {
+  readonly providerId: string;
+  readonly name: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly schemaFingerprint: string;
+  readonly scopes: readonly string[];
+  readonly readOnly: boolean;
+}
+
+export interface McpToolInvocation {
+  readonly providerId: string;
+  readonly toolName: string;
+  readonly schemaFingerprint: string;
+  readonly arguments: Readonly<Record<string, unknown>>;
+  readonly scopes: readonly string[];
+  readonly security: {
+    readonly actor: FlowSecurityActor;
+    readonly idempotencyKey: string;
+    readonly operationId: string;
+    readonly secretRefs?: readonly SecretRef[];
+  };
+  readonly signal?: AbortSignal;
+}
+
+export interface McpToolResult {
+  readonly content: readonly unknown[];
+  readonly structuredContent?: Readonly<Record<string, unknown>>;
+  readonly isError: boolean;
+}
+
+export interface McpToolRegistry {
+  discoverAsync(signal?: AbortSignal): Promise<readonly McpToolMetadata[]>;
+  invokeAsync(invocation: McpToolInvocation): Promise<McpToolResult>;
+}

package/src/types/security.ts

@@ -0,0 +1,148 @@
+import type { SecretMetadata, SecretPayload, SecretRef } from '@ankhorage/contracts/secrets';
+
+/** Trusted execution identity supplied by the host authentication boundary. */
+export interface FlowSecurityActor {
+  readonly id: string;
+  readonly tenantId: string;
+  readonly projectId: string;
+  readonly environment: string;
+}
+
+/** An exact capability grant; omitted dimensions never imply access. */
+export interface FlowSecurityGrant {
+  readonly actorId: string;
+  readonly capability: string;
+  readonly tenantId: string;
+  readonly projectId: string;
+  readonly environment: string;
+}
+
+/** A protected external operation presented to the security boundary. */
+export interface FlowSecurityOperation {
+  readonly actor: FlowSecurityActor;
+  readonly capability: string;
+  readonly idempotencyKey: string;
+  readonly operationId: string;
+  readonly secretRefs?: readonly SecretRef[];
+  readonly target?: FlowSecurityTarget;
+}
+
+/** An outbound destination and its exact host authority. */
+export interface FlowSecurityTarget {
+  readonly allowedHosts: readonly string[];
+  readonly url: string;
+}
+
+/** The complete immutable identity that grants, claims, and consumes one operation. */
+export interface FlowSecurityOperationIdentity {
+  readonly actor: FlowSecurityActor;
+  readonly capability: string;
+  readonly idempotencyKey: string;
+  readonly operationId: string;
+  readonly secretRefs: readonly SecretRef[];
+  readonly target?: FlowSecurityTarget;
+}
+
+/** A durable human decision bound to exactly one complete operation identity. */
+export interface FlowSecurityApproval {
+  readonly operation: FlowSecurityOperationIdentity;
+  readonly status: 'approved' | 'pending' | 'rejected';
+}
+
+/** Host-owned persistence boundary for approval-gate state. */
+export interface FlowApprovalStorePort {
+  getAsync(operation: FlowSecurityOperationIdentity): Promise<FlowSecurityApproval | undefined>;
+}
+
+/**
+ * Host-owned durable exactly-once boundary. Every transition must be atomic across workers and
+ * restarts. `releaseAsync` may only release an unconsumed claim for this exact identity.
+ */
+export interface FlowOperationStorePort {
+  claimAsync(operation: FlowSecurityOperationIdentity): Promise<boolean>;
+  consumeAsync(operation: FlowSecurityOperationIdentity): Promise<boolean>;
+  releaseAsync(operation: FlowSecurityOperationIdentity): Promise<void>;
+}
+
+/**
+ * Host-owned network boundary that verifies every actual peer before opening a connection.
+ * It must enforce the supplied host allowlist, resolve immediately before every connection,
+ * reject private or special-use resolved addresses, and reapply that policy to redirects.
+ */
+export interface FlowOutboundTransportPort {
+  fetchAsync(input: {
+    readonly allowedHosts: readonly string[];
+    readonly init?: RequestInit;
+    readonly url: string;
+  }): Promise<Response>;
+}
+
+/** Host-owned rate limiter. A denied acquisition must have no external side effect. */
+export interface FlowRateLimitPort {
+  acquireAsync(input: {
+    readonly actor: FlowSecurityActor;
+    readonly capability: string;
+    readonly operationId: string;
+  }): Promise<boolean>;
+}
+
+/** Redaction-safe audit edge. Secret values and payloads are intentionally absent. */
+export interface FlowSecurityAuditPort {
+  writeAsync(event: FlowSecurityAuditEvent): Promise<void>;
+}
+
+/** Immutable audit metadata for one permit or denial. */
+export interface FlowSecurityAuditEvent {
+  readonly actorId: string;
+  readonly capability: string;
+  readonly decision: 'denied' | 'permitted';
+  readonly operationId: string;
+  readonly reason:
+    | 'approval_pending'
+    | 'approval_rejected'
+    | 'credential_create'
+    | 'credential_revoke'
+    | 'idempotency_conflict'
+    | 'invalid_target'
+    | 'permission_denied'
+    | 'rate_limited'
+    | 'secret_unavailable';
+  readonly secretRefs: readonly SecretRef[];
+  readonly targetHost?: string;
+}
+
+/** Metadata-only credential view safe for administrative or graph-facing callers. */
+export type FlowSecretMetadata = SecretMetadata;
+export type FlowResolvedSecrets = Readonly<Record<SecretRef, Readonly<Record<string, string>>>>;
+
+/** Protected server-side credential creation input. Its scope is always derived from the actor. */
+export interface FlowSecretCreateInput {
+  readonly actor: FlowSecurityActor;
+  readonly kind: string;
+  readonly payload: SecretPayload;
+  readonly provider?: string;
+  readonly ref: SecretRef;
+}
+
+/** Protected server-side credential revocation input. Its scope is always derived from the actor. */
+export interface FlowSecretRevokeInput {
+  readonly actor: FlowSecurityActor;
+  readonly ref: SecretRef;
+}
+
+/** One-use authorization result. Raw secrets stay private to the returned server closure. */
+export interface FlowSecurityPermit {
+  readonly operation: FlowSecurityOperationIdentity;
+  executeAsync<T>(operation: (secrets: FlowResolvedSecrets) => Promise<T>): Promise<T>;
+}
+
+/** Public server-side boundary consumed by provider, AI, MCP, and social adapters. */
+export interface FlowSecurityPort {
+  authorizeAsync(operation: FlowSecurityOperation): Promise<FlowSecurityPermit>;
+  createSecretAsync(input: FlowSecretCreateInput): Promise<FlowSecretMetadata>;
+  getSecretMetadataAsync(input: {
+    readonly actor: FlowSecurityActor;
+    readonly ref: SecretRef;
+  }): Promise<FlowSecretMetadata>;
+  revokeSecretAsync(input: FlowSecretRevokeInput): Promise<void>;
+}