@od-oneapp/ai-platform 0.1.0

package/src/governance/compliance/abac/policy-engine.ts

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview ABAC Policy Engine
+ * ABAC Policy Engine
+ * Implements Attribute-Based Access Control for HIPAA minimum necessary
+ */
+
+import type { ABACContext, ABACDecision, Action, Resource } from '../types';
+import type { ABACEvaluationResult, Policy, PolicyRegistry } from './types';
+
+/**
+ * Global policy registry
+ */
+const policyRegistry: PolicyRegistry = new Map();
+
+/**
+ * Register a policy
+ */
+export function registerPolicy(policy: Policy): void {
+  policyRegistry.set(policy.id, policy);
+}
+
+/**
+ * Unregister a policy
+ */
+export function unregisterPolicy(policyId: string): void {
+  policyRegistry.delete(policyId);
+}
+
+/**
+ * Get all registered policies
+ */
+export function getPolicies(): Policy[] {
+  return [...policyRegistry.values()].sort((a, b) => b.priority - a.priority);
+}
+
+/**
+ * Evaluate access decision using all registered policies
+ * Policies are evaluated in priority order (highest first)
+ * First DENY wins, otherwise all must ALLOW
+ */
+export async function evaluatePolicy(
+  context: ABACContext,
+  resource: Resource,
+  action: Action,
+): Promise<ABACEvaluationResult> {
+  const startTime = Date.now();
+  const policiesEvaluated: string[] = [];
+  const policies = getPolicies();
+
+  // Default deny if no policies
+  if (policies.length === 0) {
+    return {
+      decision: {
+        allowed: false,
+        reason: 'No policies configured',
+        policyId: 'default-deny',
+      },
+      policiesEvaluated: [],
+      evaluationTimeMs: Date.now() - startTime,
+    };
+  }
+
+  // Evaluate each policy
+  for (const policy of policies) {
+    policiesEvaluated.push(policy.id);
+
+    try {
+      const decision = await policy.evaluate(context, resource, action);
+
+      // First explicit DENY wins
+      if (!decision.allowed) {
+        return {
+          decision,
+          policiesEvaluated,
+          evaluationTimeMs: Date.now() - startTime,
+        };
+      }
+    } catch (error) {
+      // Policy evaluation error = DENY
+      return {
+        decision: {
+          allowed: false,
+          reason: `Policy evaluation error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          policyId: policy.id,
+        },
+        policiesEvaluated,
+        evaluationTimeMs: Date.now() - startTime,
+      };
+    }
+  }
+
+  // All policies allowed
+  return {
+    decision: {
+      allowed: true,
+      policyId: 'all-policies-allowed',
+    },
+    policiesEvaluated,
+    evaluationTimeMs: Date.now() - startTime,
+  };
+}
+
+/**
+ * Create ABAC context from request metadata
+ */
+export function createABACContext(
+  actorId: string,
+  roles: string[],
+  purpose: ABACContext['purpose'],
+  attributes: Record<string, unknown> = {},
+  environment: Partial<ABACContext['environment']> = {},
+): ABACContext {
+  return {
+    actor: {
+      id: actorId,
+      roles,
+      attributes,
+    },
+    environment: {
+      timestamp: new Date(),
+      ...environment,
+    },
+    purpose,
+  };
+}
+
+/**
+ * Helper: Check if actor has role
+ */
+export function hasRole(context: ABACContext, role: string): boolean {
+  return context.actor.roles.includes(role);
+}
+
+/**
+ * Helper: Check if actor has any of the roles
+ */
+export function hasAnyRole(context: ABACContext, roles: string[]): boolean {
+  return roles.some(role => context.actor.roles.includes(role));
+}
+
+/**
+ * Helper: Check if actor has all of the roles
+ */
+export function hasAllRoles(context: ABACContext, roles: string[]): boolean {
+  return roles.every(role => context.actor.roles.includes(role));
+}
+
+/**
+ * Helper: Check resource sensitivity level
+ */
+export function isResourceSensitive(resource: Resource): boolean {
+  return resource.sensitivity === 'confidential' || resource.sensitivity === 'restricted';
+}
+
+/**
+ * Helper: Create ALLOW decision
+ */
+export function allow(policyId: string, conditions?: string[]): ABACDecision {
+  return {
+    allowed: true,
+    policyId,
+    conditions,
+  };
+}
+
+/**
+ * Helper: Create DENY decision
+ */
+export function deny(policyId: string, reason: string): ABACDecision {
+  return {
+    allowed: false,
+    policyId,
+    reason,
+  };
+}

package/src/governance/compliance/abac/types.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview ABAC (Attribute-Based Access Control) type definitions
+ * ABAC (Attribute-Based Access Control) type definitions
+ */
+
+import type { ABACContext, ABACDecision, Action, Resource } from '../types';
+
+/**
+ * Policy evaluation function
+ */
+export type PolicyEvaluator = (
+  context: ABACContext,
+  resource: Resource,
+  action: Action,
+) => ABACDecision | Promise<ABACDecision>;
+
+/**
+ * Policy definition
+ */
+export type Policy = {
+  id: string;
+  name: string;
+  description: string;
+  priority: number; // Higher = evaluated first
+  evaluate: PolicyEvaluator;
+};
+
+/**
+ * Policy registry
+ */
+export type PolicyRegistry = Map<string, Policy>;
+
+/**
+ * ABAC evaluation result
+ */
+export type ABACEvaluationResult = {
+  decision: ABACDecision;
+  policiesEvaluated: string[];
+  evaluationTimeMs: number;
+};

package/src/governance/compliance/approval/compliance-approval-queue.ts

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview Compliance Approval Queue
+ * Human-in-the-Loop Approval Queue
+ * Manages approval workflow for high-risk tool executions
+ */
+
+import { logInfo } from '@repo/shared/logs';
+
+import type { ApprovalDecision, ApprovalRequest } from '../types';
+
+/**
+ * In-memory approval queue (for development)
+ * In production, use Redis or a database
+ */
+class ApprovalQueue {
+  private requests: Map<string, ApprovalRequest> = new Map();
+  private decisions: Map<string, ApprovalDecision> = new Map();
+  private callbacks: Map<string, (decision: ApprovalDecision) => void> = new Map();
+
+  /**
+   * Submit a tool execution for approval
+   */
+  async submitForApproval(
+    toolName: string,
+    args: Record<string, unknown>,
+    actor: string,
+    riskLevel: ApprovalRequest['riskLevel'],
+    timeoutMs: number = 300000, // 5 minutes default
+  ): Promise<ApprovalDecision> {
+    const request: ApprovalRequest = {
+      id: this.generateRequestId(),
+      toolName,
+      arguments: args,
+      actor,
+      timestamp: new Date(),
+      riskLevel,
+      status: 'pending',
+    };
+
+    this.requests.set(request.id, request);
+
+    // Log approval request
+    logInfo('[APPROVAL REQUIRED]', {
+      id: request.id,
+      tool: toolName,
+      actor,
+      riskLevel,
+    });
+
+    // Wait for approval with timeout
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        request.status = 'timeout';
+        this.requests.set(request.id, request);
+
+        const timeoutDecision: ApprovalDecision = {
+          requestId: request.id,
+          approved: false,
+          reviewer: 'system',
+          reason: `Approval request timed out after ${timeoutMs}ms`,
+          timestamp: new Date(),
+        };
+
+        this.decisions.set(request.id, timeoutDecision);
+        this.callbacks.delete(request.id);
+
+        reject(new Error(timeoutDecision.reason));
+      }, timeoutMs);
+
+      // Store callback for when approval is granted/denied
+      this.callbacks.set(request.id, decision => {
+        clearTimeout(timeoutId);
+        resolve(decision);
+      });
+    });
+  }
+
+  /**
+   * Approve a request
+   */
+  async approve(requestId: string, reviewer: string, reason?: string): Promise<void> {
+    const request = this.requests.get(requestId);
+
+    if (!request) {
+      throw new Error(`Approval request ${requestId} not found`);
+    }
+
+    if (request.status !== 'pending') {
+      throw new Error(`Request ${requestId} is ${request.status}, cannot approve`);
+    }
+
+    const decision: ApprovalDecision = {
+      requestId,
+      approved: true,
+      reviewer,
+      reason,
+      timestamp: new Date(),
+    };
+
+    request.status = 'approved';
+    this.requests.set(requestId, request);
+    this.decisions.set(requestId, decision);
+
+    // Notify callback
+    const callback = this.callbacks.get(requestId);
+    if (callback) {
+      callback(decision);
+      this.callbacks.delete(requestId);
+    }
+
+    logInfo('[APPROVAL GRANTED]', { requestId, reviewer });
+  }
+
+  /**
+   * Deny a request
+   */
+  async deny(requestId: string, reviewer: string, reason: string): Promise<void> {
+    const request = this.requests.get(requestId);
+
+    if (!request) {
+      throw new Error(`Approval request ${requestId} not found`);
+    }
+
+    if (request.status !== 'pending') {
+      throw new Error(`Request ${requestId} is ${request.status}, cannot deny`);
+    }
+
+    const decision: ApprovalDecision = {
+      requestId,
+      approved: false,
+      reviewer,
+      reason,
+      timestamp: new Date(),
+    };
+
+    request.status = 'denied';
+    this.requests.set(requestId, request);
+    this.decisions.set(requestId, decision);
+
+    // Notify callback
+    const callback = this.callbacks.get(requestId);
+    if (callback) {
+      callback(decision);
+      this.callbacks.delete(requestId);
+    }
+
+    logInfo('[APPROVAL DENIED]', { requestId, reviewer, reason });
+  }
+
+  /**
+   * Get all pending requests
+   */
+  getPendingRequests(): ApprovalRequest[] {
+    return [...this.requests.values()].filter(r => r.status === 'pending');
+  }
+
+  /**
+   * Get request by ID
+   */
+  getRequest(requestId: string): ApprovalRequest | undefined {
+    return this.requests.get(requestId);
+  }
+
+  /**
+   * Get decision by request ID
+   */
+  getDecision(requestId: string): ApprovalDecision | undefined {
+    return this.decisions.get(requestId);
+  }
+
+  /**
+   * Generate unique request ID
+   */
+  private generateRequestId(): string {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 15);
+    return `approval_${timestamp}_${random}`;
+  }
+
+  /**
+   * Clear all requests (for testing)
+   */
+  clear(): void {
+    this.requests.clear();
+    this.decisions.clear();
+    this.callbacks.clear();
+  }
+}
+
+/**
+ * Global approval queue instance
+ */
+let globalQueue: ApprovalQueue | null = null;
+
+/**
+ * Get or create global approval queue
+ */
+export function getApprovalQueue(): ApprovalQueue {
+  if (!globalQueue) {
+    globalQueue = new ApprovalQueue();
+  }
+  return globalQueue;
+}
+
+/**
+ * Set custom approval queue
+ */
+export function setApprovalQueue(queue: ApprovalQueue): void {
+  globalQueue = queue;
+}
+
+/**
+ * Create a new approval queue instance
+ */
+export function createApprovalQueue(): ApprovalQueue {
+  return new ApprovalQueue();
+}

package/src/governance/compliance/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Compliance module - ABAC, PHI detection, approval workflows
+ * Ported from oneapp-onstage production patterns
+ */
+
+// ABAC Policy Engine
+export * from './abac/policy-engine';
+export * from './abac/types';
+
+// PHI Detection & Redaction
+export * from './validators/phi-detector';
+export * from './validators/redaction-utils';
+export * from './validators/safe-harbor';
+
+// Approval Workflows (compliance-specific)
+export * from './approval/compliance-approval-queue';

package/src/governance/compliance/schemas.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Compliance schemas — risk levels and compliance signals.
+ *
+ * RiskLevel and ComplianceSignal are governance-domain concepts used across
+ * agents, tools, and policies for audit and compliance purposes.
+ *
+ * @module @od-oneapp/ai-platform/governance/compliance/schemas
+ */
+
+import { z } from 'zod';
+
+/** Valid risk level values. */
+export const riskLevels = ['low', 'medium', 'high'] as const;
+
+/** Risk level type ('low', 'medium', or 'high'). */
+export type RiskLevel = (typeof riskLevels)[number];
+
+/**
+ * Schema for compliance signals.
+ * Represents events emitted during agent execution for compliance and audit purposes.
+ * @example
+ * ```ts
+ * const signal = complianceSignalSchema.parse({
+ *   id: 'sig-1',
+ *   type: 'tool.executed',
+ *   message: 'auditLog executed',
+ *   runId: 'run-123',
+ *   timestamp: new Date().toISOString(),
+ * });
+ * ```
+ */
+export const complianceSignalSchema = z.object({
+  /** Unique signal identifier. */
+  id: z.string(),
+  /** Signal type indicating the event category. */
+  type: z.enum([
+    'guardrail.blocked',
+    'guardrail.sanitized',
+    'tool.awaiting-approval',
+    'tool.executed',
+    'tool.denied',
+    'loop.stopped',
+    // Governance Agent signals
+    'loop.started',
+    'loop.completed',
+    'loop.exhausted',
+    'loop.error',
+    'loop.timeout',
+    'loop.budget_exceeded',
+    'loop.approval_required',
+  ]),
+  /** Human-readable message describing the signal. */
+  message: z.string(),
+  /** Agent run associated with the signal. */
+  runId: z.string().describe('Agent run associated with the signal'),
+  /** Risk level classification. */
+  riskLevel: z
+    .union([z.literal('low'), z.literal('medium'), z.literal('high')])
+    .optional()
+    .describe('Risk level classification'),
+  /** Optional metadata for additional context. */
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  /** ISO timestamp for ordering in the UI. */
+  timestamp: z.string().describe('ISO timestamp for ordering in the UI'),
+});
+
+/** Compliance signal type. */
+export type ComplianceSignal = z.infer<typeof complianceSignalSchema>;

package/src/governance/compliance/types.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Compliance and ABAC types
+ * Centralized types for PHI detection, redaction, ABAC, and approvals.
+ */
+
+import type { AuditLogger } from '../types';
+import type { RiskLevel } from './schemas';
+
+/**
+ * HIPAA Safe Harbor PHI identifier types.
+ */
+export type PHIType =
+  | 'ssn'
+  | 'mrn'
+  | 'phone'
+  | 'fax'
+  | 'email'
+  | 'ip_address'
+  | 'url'
+  | 'date'
+  | 'name'
+  | 'geographic'
+  | 'account_number'
+  | 'license_number'
+  | 'vehicle_id'
+  | 'device_id'
+  | 'biometric'
+  | 'photo'
+  | 'other_unique_id';
+
+/**
+ * PHI detection result.
+ */
+export interface PHIDetection {
+  type: PHIType;
+  value: string;
+  start: number;
+  end: number;
+  confidence: number;
+}
+
+/**
+ * Redaction strategies for PHI.
+ */
+export type RedactionStrategy = 'MASK' | 'HASH' | 'TOKENIZE';
+
+/**
+ * ABAC action types.
+ * Extendable via custom string values.
+ */
+export type Action =
+  | 'read'
+  | 'write'
+  | 'delete'
+  | 'export'
+  | 'share'
+  | 'analyze'
+  | 'execute'
+  | 'admin'
+  | (string & {});
+
+/**
+ * ABAC resource definition.
+ */
+export interface Resource {
+  id: string;
+  type: string;
+  sensitivity: 'public' | 'internal' | 'confidential' | 'restricted';
+  ownerId?: string;
+  attributes?: Record<string, unknown>;
+}
+
+/**
+ * ABAC decision result.
+ */
+export interface ABACDecision {
+  allowed: boolean;
+  policyId: string;
+  reason?: string;
+  conditions?: string[];
+}
+
+/**
+ * ABAC context for policy evaluation.
+ */
+export interface ABACContext {
+  actor: {
+    id: string;
+    roles: string[];
+    attributes?: Record<string, unknown>;
+  };
+  environment: {
+    timestamp: Date;
+    ipAddress?: string;
+    userAgent?: string;
+    location?: string;
+  };
+  purpose:
+    | 'treatment'
+    | 'payment'
+    | 'healthcare_operations'
+    | 'research'
+    | 'public_health'
+    | 'quality_improvement'
+    | 'other';
+}
+
+/**
+ * Compliance configuration options.
+ */
+export interface ComplianceOptions {
+  enablePHIRedaction?: boolean;
+  enableABAC?: boolean;
+  policyVersion?: string;
+  auditLogger?: AuditLogger;
+  abacContext?: ABACContext;
+  redactionStrategy?: RedactionStrategy;
+  resource?: Resource;
+}
+
+/**
+ * Approval request for sensitive tool execution.
+ */
+export interface ApprovalRequest {
+  id: string;
+  toolName: string;
+  arguments: Record<string, unknown>;
+  actor: string;
+  timestamp: Date;
+  riskLevel: RiskLevel;
+  status: 'pending' | 'approved' | 'denied' | 'timeout';
+}
+
+/**
+ * Approval decision for a request.
+ */
+export interface ApprovalDecision {
+  requestId: string;
+  approved: boolean;
+  reviewer: string;
+  reason?: string;
+  timestamp: Date;
+}