agentlock-shared 0.1.0

package/src/policy.ts

@@ -0,0 +1,186 @@
+import type {
+  PolicyRules,
+  AgentActionRequest,
+  PolicyEvaluationResult,
+  RiskLevel,
+  PolicyDecision,
+} from './types.js';
+import { redact } from './redact.js';
+
+const RISK_MAP: Record<string, RiskLevel> = {
+  read: 'low',
+  write: 'medium',
+  financial: 'high',
+  admin: 'critical',
+};
+
+export const DEFAULT_POLICY_RULES: PolicyRules = {
+  defaultMode: 'require_approval',
+  rules: [
+    { action_type: 'read', decision: 'ALLOW' },
+    { action_type: 'write', decision: 'REQUIRE_APPROVAL' },
+    { action_type: 'financial', decision: 'REQUIRE_APPROVAL' },
+    { action_type: 'admin', decision: 'BLOCK' },
+  ],
+  http: {
+    allowedDomains: [],
+    allowedMethods: ['GET', 'POST', 'PUT', 'DELETE'],
+    blockList: [],
+  },
+  limits: {
+    maxActionsPerHour: 100,
+  },
+};
+
+export function evaluatePolicy(
+  action: AgentActionRequest,
+  rules: PolicyRules
+): PolicyEvaluationResult {
+  const risk_level = RISK_MAP[action.action_type] ?? 'medium';
+
+  // Browser tools: browser.open always requires approval
+  if (action.tool.startsWith('browser.')) {
+    if (action.tool === 'browser.open') {
+      return {
+        decision: 'REQUIRE_APPROVAL',
+        risk_level: 'medium',
+        reason: 'Browser sessions always require approval to start',
+      };
+    }
+    // Other browser.* actions with a valid session are handled at the gateway
+    // level (auto-approved). If they reach the policy engine without a session,
+    // they should be blocked.
+    return {
+      decision: 'BLOCK',
+      risk_level: 'medium',
+      reason: 'Browser actions require an active session (use browser.open first)',
+    };
+  }
+
+  // MCP tools: list_tools is a read (low risk), call_tool defers to action_type rules
+  if (action.tool === 'mcp.list_tools') {
+    return {
+      decision: 'ALLOW',
+      risk_level: 'low',
+      reason: 'MCP tool discovery is read-only',
+    };
+  }
+
+  if (action.tool.split('.')[0] === 'http' && rules.http) {
+    const url = action.payload.url as string | undefined;
+    if (url) {
+      try {
+        const domain = new URL(url).hostname;
+        // Use exact match or proper subdomain match (preceded by a dot)
+        // to prevent "not-trusted.com" from matching allowlist entry "trusted.com"
+        const matchesDomain = (d: string, pattern: string) =>
+          d === pattern || d.endsWith('.' + pattern);
+        if (rules.http.blockList.some((b) => matchesDomain(domain, b))) {
+          return { decision: 'BLOCK', risk_level: 'critical', reason: `Domain ${domain} is in block list` };
+        }
+        if (rules.http.allowedDomains.length === 0) {
+          // No allowlist configured: safe default is REQUIRE_APPROVAL, not ALLOW.
+          // This prevents agents from exfiltrating data to arbitrary domains.
+          return {
+            decision: 'REQUIRE_APPROVAL',
+            risk_level,
+            reason: 'HTTP allowlist not configured — approval required for all HTTP calls',
+          };
+        }
+        if (!rules.http.allowedDomains.some((d) => matchesDomain(domain, d))) {
+          return { decision: 'BLOCK', risk_level, reason: `Domain ${domain} not in allowed list` };
+        }
+      } catch {
+        return { decision: 'BLOCK', risk_level: 'critical', reason: 'Invalid URL' };
+      }
+    }
+    const method = (action.payload.method as string | undefined)?.toUpperCase();
+    if (method && !rules.http.allowedMethods.includes(method)) {
+      return { decision: 'BLOCK', risk_level, reason: `HTTP method ${method} not allowed` };
+    }
+  }
+
+  if (
+    rules.limits?.maxCostPerAction !== undefined &&
+    action.cost_estimate !== undefined &&
+    action.cost_estimate > rules.limits.maxCostPerAction
+  ) {
+    return {
+      decision: 'BLOCK',
+      risk_level: 'high',
+      reason: `Cost estimate ${action.cost_estimate} exceeds limit ${rules.limits.maxCostPerAction}`,
+    };
+  }
+
+  // Most specific: tool-specific rule
+  let matched = rules.rules.find((r) => r.tool === action.tool);
+  // Then action-type rule
+  if (!matched) matched = rules.rules.find((r) => r.action_type === action.action_type);
+
+  if (matched) {
+    return {
+      decision: matched.decision,
+      risk_level,
+      reason: `Matched rule: ${matched.action_type ?? matched.tool}`,
+      matched_rule: matched,
+    };
+  }
+
+  const defaultDecision: PolicyDecision =
+    rules.defaultMode === 'allow' ? 'ALLOW' : rules.defaultMode === 'block' ? 'BLOCK' : 'REQUIRE_APPROVAL';
+
+  return { decision: defaultDecision, risk_level, reason: 'Default policy' };
+}
+
+export function buildActionPreview(action: AgentActionRequest): {
+  summary: string;
+  target?: string;
+  impact?: string;
+  cost_estimate?: number;
+} {
+  let summary = `${action.action_type.toUpperCase()} via ${action.tool}`;
+  let target: string | undefined;
+
+  if (action.tool.split('.')[0] === 'http') {
+    const url = action.payload.url as string | undefined;
+    const method = action.payload.method as string | undefined;
+    if (url) {
+      try {
+        target = new URL(url).hostname;
+      } catch {
+        target = url;
+      }
+      summary = `${method?.toUpperCase() ?? 'HTTP'} request to ${target}`;
+    }
+  } else if (action.tool === 'browser.open') {
+    const url = action.payload.url as string | undefined;
+    if (url) {
+      try {
+        target = new URL(url).hostname;
+      } catch {
+        target = url;
+      }
+      summary = `Open browser session to ${target}`;
+    } else {
+      summary = 'Open browser session';
+    }
+  } else if (action.tool === 'mcp.list_tools') {
+    const server = action.payload.server as string | undefined;
+    target = server;
+    summary = `List available tools on MCP server "${server ?? 'unknown'}"`;
+  } else if (action.tool === 'mcp.call_tool') {
+    const server = action.payload.server as string | undefined;
+    const method = action.payload.method as string | undefined;
+    target = server;
+    summary = `Call "${method ?? 'unknown'}" on MCP server "${server ?? 'unknown'}"`;
+  } else if (action.tool === 'demo') {
+    summary = `Write to demo table: ${JSON.stringify(redact(action.payload)).slice(0, 80)}`;
+  }
+
+  return {
+    summary,
+    target,
+    impact: action.action_type === 'write' ? 'Data will be modified' : undefined,
+    cost_estimate: action.cost_estimate,
+  };
+}

package/src/redact.ts

@@ -0,0 +1,114 @@
+// Exact-match field names (checked after lowercasing)
+const SECRET_FIELDS = new Set([
+  'authorization',
+  'api_key',
+  'apikey',
+  'api-key',
+  'token',
+  'secret',
+  'password',
+  'passwd',
+  'private_key',
+  'privatekey',
+  'access_token',
+  'refresh_token',
+  'client_secret',
+  'x-api-key',
+  'x-auth-token',
+  'credentials',
+  'bearer',
+  'session_token',
+  'session_key',
+  'cookie',
+  'set-cookie',
+  'aws_secret_access_key',
+  'aws_session_token',
+  'database_url',
+  'connection_string',
+  'private-key',
+  'master_key',
+  'encryption_key',
+  'signing_key',
+  'service_role_key',
+  'supabase_service_role_key',
+]);
+
+// Substring patterns: if the lowercased key contains any of these, redact
+const SECRET_SUBSTRINGS = [
+  'secret',
+  'password',
+  'passwd',
+  'token',
+  'api_key',
+  'apikey',
+  'private_key',
+  'privatekey',
+  'credential',
+  'authorization',
+  'auth_key',
+  'master_key',
+  'encryption_key',
+  'signing_key',
+  'connection_string',
+  'database_url',
+  'access_key',
+  'session_id',
+];
+
+const REDACTED = '[REDACTED]';
+
+// Value-based patterns to detect secrets regardless of field name
+const SECRET_VALUE_PATTERNS = [
+  /^(sk|pk|rk)_(live|test)_[a-zA-Z0-9]{10,}$/,  // Stripe keys
+  /^r[us]_[a-zA-Z0-9]{20,}$/,                      // Stripe restricted keys
+  /^ghp_[a-zA-Z0-9]{36}$/,                         // GitHub PATs
+  /^github_pat_[a-zA-Z0-9_]{20,}$/,                // GitHub fine-grained PATs
+  /^gho_[a-zA-Z0-9]{36}$/,                         // GitHub OAuth tokens
+  /^AKIA[A-Z0-9]{16}$/,                            // AWS access key IDs
+  /^eyJ[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]{20,}/,   // JWTs (eyJ prefix)
+  /^xox[bpras]-[a-zA-Z0-9-]{10,}$/,               // Slack tokens
+  /^Bearer\s+[a-zA-Z0-9._\-]{20,}$/,              // Bearer tokens
+  /^AIza[a-zA-Z0-9_-]{35}$/,                       // Google API keys
+  /^sk-[a-zA-Z0-9]{20,}$/,                         // OpenAI API keys
+  /^sk-ant-[a-zA-Z0-9_-]{20,}$/,                   // Anthropic API keys
+  /^SG\.[a-zA-Z0-9_-]{20,}$/,                      // SendGrid API keys
+  /^SK[a-f0-9]{32}$/,                              // Twilio API keys
+];
+
+function isSecretField(key: string): boolean {
+  const lower = key.toLowerCase();
+  if (SECRET_FIELDS.has(lower)) return true;
+  return SECRET_SUBSTRINGS.some((sub) => lower.includes(sub));
+}
+
+function isSecretValue(value: string): boolean {
+  return SECRET_VALUE_PATTERNS.some((pattern) => pattern.test(value));
+}
+
+export function redact(obj: unknown, depth = 0): unknown {
+  if (depth > 10) return obj;
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj === 'string') return isSecretValue(obj) ? REDACTED : obj;
+  if (typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map((item) => redact(item, depth + 1));
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    result[key] = isSecretField(key) ? REDACTED : redact(value, depth + 1);
+  }
+  return result;
+}
+
+export function redactHeaders(headers: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    result[key] = isSecretField(key) ? REDACTED : value;
+  }
+  return result;
+}
+
+export function sanitizeActionRequest(
+  request: Record<string, unknown>
+): Record<string, unknown> {
+  return redact(request) as Record<string, unknown>;
+}

package/src/schemas.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+
+/** Max payload size: 64KB when serialized */
+const MAX_PAYLOAD_SIZE = 65_536;
+
+export const AgentActionRequestSchema = z.object({
+  action_type: z.enum(['read', 'write', 'financial', 'admin']),
+  tool: z.string().min(1).max(100).regex(/^[a-zA-Z0-9._\-:]+$/, 'Tool name must be alphanumeric with dots, dashes, underscores, or colons'),
+  payload: z.record(z.unknown()).refine(
+    (val) => JSON.stringify(val).length <= MAX_PAYLOAD_SIZE,
+    { message: `Payload exceeds maximum size of ${MAX_PAYLOAD_SIZE} bytes` }
+  ),
+  idempotency_key: z.string().max(128).optional(),
+  cost_estimate: z.number().optional(),
+});
+
+export const RegisterAgentSchema = z.object({
+  name: z.string().min(1).max(100),
+  environment: z.enum(['development', 'staging', 'production']).default('production'),
+  public_key: z.string().min(40),
+  allowed_tools: z.array(z.string()).default([]),
+});
+
+export const PolicyRulesSchema = z.object({
+  defaultMode: z.enum(['allow', 'require_approval', 'block']),
+  rules: z.array(
+    z.object({
+      action_type: z.enum(['read', 'write', 'financial', 'admin']).optional(),
+      tool: z.string().optional(),
+      domain: z.string().optional(),
+      decision: z.enum(['ALLOW', 'REQUIRE_APPROVAL', 'BLOCK']),
+      require_two_approvals: z.boolean().optional(),
+    })
+  ),
+  http: z
+    .object({
+      allowedDomains: z.array(z.string()),
+      allowedMethods: z.array(z.string()),
+      blockList: z.array(z.string()),
+    })
+    .optional(),
+  limits: z
+    .object({
+      maxCostPerAction: z.number().optional(),
+      maxActionsPerHour: z.number().optional(),
+    })
+    .optional(),
+});
+
+export const ApproveRequestSchema = z.object({
+  action: z.enum(['approve', 'deny']),
+  reason: z.string().max(1000).optional(),
+});

package/src/signing.ts

@@ -0,0 +1,120 @@
+import nacl from 'tweetnacl';
+import { encodeBase64, decodeBase64, decodeUTF8 } from 'tweetnacl-util';
+
+export interface SignedHeaders {
+  'x-agent-id': string;
+  'x-timestamp': string;
+  'x-signature': string;
+  'x-nonce'?: string;
+}
+
+export interface KeyPair {
+  publicKey: string;
+  privateKey: string;
+}
+
+export function generateKeypair(): KeyPair {
+  const pair = nacl.sign.keyPair();
+  return {
+    publicKey: encodeBase64(pair.publicKey),
+    privateKey: encodeBase64(pair.secretKey),
+  };
+}
+
+/**
+ * Recursively stable-stringify: sorts object keys at every nesting level.
+ * This is critical for signature verification — every language SDK must produce
+ * the exact same canonical string for the same payload.
+ *
+ * Bug fixed: JSON.stringify(obj, replacerArray) only serializes keys named in the
+ * replacer at every nesting level, so nested objects would be serialized as {}.
+ */
+function stableStringify(val: unknown): string | undefined {
+  if (val === undefined) return undefined;
+  if (val === null) return 'null';
+  if (typeof val === 'number') {
+    // NaN, Infinity, -Infinity serialize to null per JSON spec
+    if (!Number.isFinite(val)) return 'null';
+    return JSON.stringify(val);
+  }
+  if (typeof val === 'boolean' || typeof val === 'string') return JSON.stringify(val);
+  if (Array.isArray(val)) {
+    return `[${val.map((v) => stableStringify(v) ?? 'null').join(',')}]`;
+  }
+  if (typeof val === 'object') {
+    const sorted = Object.keys(val as object).sort();
+    const pairs: string[] = [];
+    for (const k of sorted) {
+      const v = stableStringify((val as Record<string, unknown>)[k]);
+      if (v !== undefined) {
+        pairs.push(`${JSON.stringify(k)}:${v}`);
+      }
+    }
+    return `{${pairs.join(',')}}`;
+  }
+  return JSON.stringify(val);
+}
+
+export function canonicalStringify(obj: Record<string, unknown>): string {
+  return stableStringify(obj) ?? '{}';
+}
+
+export function signRequest(
+  body: Record<string, unknown>,
+  agentId: string,
+  privateKeyBase64: string
+): SignedHeaders {
+  const timestamp = Date.now().toString();
+  const nonce = encodeBase64(nacl.randomBytes(16));
+  const canonical = canonicalStringify(body);
+  const message = decodeUTF8(`${canonical}:${timestamp}:${nonce}`);
+
+  const privateKey = decodeBase64(privateKeyBase64);
+  const signature = nacl.sign.detached(message, privateKey);
+
+  return {
+    'x-agent-id': agentId,
+    'x-timestamp': timestamp,
+    'x-signature': encodeBase64(signature),
+    'x-nonce': nonce,
+  };
+}
+
+export function verifyRequest(
+  body: Record<string, unknown>,
+  headers: {
+    'x-agent-id'?: string;
+    'x-timestamp'?: string;
+    'x-signature'?: string;
+    'x-nonce'?: string;
+  },
+  publicKeyBase64: string,
+  maxSkewMs = 5 * 60 * 1000
+): { agentId: string; nonce: string } {
+  const agentId = headers['x-agent-id'];
+  const timestamp = headers['x-timestamp'];
+  const signatureB64 = headers['x-signature'];
+  const nonce = headers['x-nonce'];
+
+  if (!agentId || !timestamp || !signatureB64 || !nonce) {
+    throw new Error('Missing required signature headers');
+  }
+
+  const ts = parseInt(timestamp, 10);
+  const now = Date.now();
+  if (Math.abs(now - ts) > maxSkewMs) {
+    throw new Error(`Timestamp skew too large: ${Math.abs(now - ts)}ms`);
+  }
+
+  const canonical = canonicalStringify(body);
+  const message = decodeUTF8(`${canonical}:${timestamp}:${nonce}`);
+  const signature = decodeBase64(signatureB64);
+  const publicKey = decodeBase64(publicKeyBase64);
+
+  const valid = nacl.sign.detached.verify(message, signature, publicKey);
+  if (!valid) {
+    throw new Error('Invalid signature');
+  }
+
+  return { agentId, nonce };
+}

package/src/types.ts

@@ -0,0 +1,212 @@
+export type WorkspaceRole = 'owner' | 'admin' | 'approver' | 'member';
+export type AgentStatus = 'active' | 'revoked' | 'suspended';
+export type AgentEnvironment = 'development' | 'staging' | 'production';
+export type ApprovalStatus = 'PENDING' | 'NEEDS_SECOND_APPROVAL' | 'APPROVED' | 'DENIED' | 'EXPIRED' | 'CANCELLED';
+export type ExecutionStatus = 'PENDING' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'UNDONE';
+export type ActionType = 'read' | 'write' | 'financial' | 'admin';
+export type PolicyDecision = 'ALLOW' | 'REQUIRE_APPROVAL' | 'BLOCK';
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+
+export interface Workspace {
+  id: string;
+  name: string;
+  slug: string;
+  safe_mode: boolean;
+  safe_mode_enabled_at?: string;
+  safe_mode_enabled_by?: string;
+  timeline_enabled: boolean;
+  audit_log_enabled: boolean;
+  retention_days?: number | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface WorkspaceMember {
+  id: string;
+  workspace_id: string;
+  user_id: string;
+  role: WorkspaceRole;
+  created_at: string;
+}
+
+export interface Agent {
+  id: string;
+  workspace_id: string;
+  name: string;
+  environment: AgentEnvironment;
+  public_key: string;
+  allowed_tools: string[];
+  status: AgentStatus;
+  created_by?: string;
+  created_at: string;
+  updated_at: string;
+  last_seen_at?: string;
+}
+
+export interface ApiCredential {
+  id: string;
+  workspace_id: string;
+  name: string;
+  connector_type: string;
+  last_four?: string;
+  created_by?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface Policy {
+  id: string;
+  workspace_id: string;
+  name: string;
+  is_default: boolean;
+  rules: PolicyRules;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PolicyRules {
+  defaultMode: 'allow' | 'require_approval' | 'block';
+  rules: PolicyRule[];
+  http?: {
+    allowedDomains: string[];
+    allowedMethods: string[];
+    blockList: string[];
+  };
+  limits?: {
+    maxCostPerAction?: number;
+    maxActionsPerHour?: number;
+  };
+}
+
+export interface PolicyRule {
+  action_type?: ActionType;
+  tool?: string;
+  domain?: string;
+  decision: PolicyDecision;
+  require_two_approvals?: boolean;
+}
+
+export interface PolicyEvaluationResult {
+  decision: PolicyDecision;
+  risk_level: RiskLevel;
+  reason: string;
+  matched_rule?: PolicyRule;
+}
+
+export interface ApprovalRequest {
+  id: string;
+  workspace_id: string;
+  agent_id: string;
+  status: ApprovalStatus;
+  action_type: ActionType;
+  tool: string;
+  preview: ActionPreview;
+  risk_level: RiskLevel;
+  policy_decision: string;
+  policy_reason?: string;
+  expires_at: string;
+  requires_two_approvals: boolean;
+  approved_by?: string;
+  denied_by?: string;
+  decided_at?: string;
+  second_approved_by?: string;
+  second_decided_at?: string;
+  request_hash: string;
+  request_body: Record<string, unknown>;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ActionPreview {
+  summary: string;
+  target?: string;
+  impact?: string;
+  cost_estimate?: number;
+  raw_action?: Record<string, unknown>;
+}
+
+export interface ActionExecution {
+  id: string;
+  workspace_id: string;
+  approval_request_id?: string;
+  agent_id: string;
+  connector: string;
+  action_type: ActionType;
+  status: ExecutionStatus;
+  sanitized_request: Record<string, unknown>;
+  sanitized_response?: Record<string, unknown>;
+  undo_supported: boolean;
+  error_message?: string;
+  executed_at?: string;
+  completed_at?: string;
+  undone_at?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface AuditEvent {
+  id: string;
+  workspace_id: string;
+  event_type: string;
+  actor_id?: string;
+  actor_type: 'user' | 'agent' | 'system';
+  agent_id?: string;
+  resource_type?: string;
+  resource_id?: string;
+  metadata: Record<string, unknown>;
+  created_at: string;
+}
+
+export type BrowserSessionStatus = 'active' | 'closed' | 'expired';
+
+export type BrowserTool =
+  | 'browser.open'
+  | 'browser.click'
+  | 'browser.type'
+  | 'browser.fill_credentials'
+  | 'browser.navigate'
+  | 'browser.snapshot'
+  | 'browser.screenshot'
+  | 'browser.press_key'
+  | 'browser.select'
+  | 'browser.scroll'
+  | 'browser.close';
+
+export interface BrowserSession {
+  id: string;
+  workspace_id: string;
+  agent_id: string;
+  approval_request_id: string;
+  status: BrowserSessionStatus;
+  allowed_domains: string[];
+  action_count: number;
+  created_at: string;
+  last_activity_at: string;
+  expires_at: string;
+  closed_at?: string;
+}
+
+export interface BrowserActionResult {
+  session_id: string;
+  snapshot: string;
+  page_url: string;
+  page_title: string;
+  action_performed: string;
+  screenshot?: string;
+}
+
+export interface AgentActionRequest {
+  action_type: ActionType;
+  tool: string;
+  payload: Record<string, unknown>;
+  idempotency_key?: string;
+  cost_estimate?: number;
+}
+
+export interface GatewayRequestResult {
+  request_id: string;
+  decision: PolicyDecision;
+  status: ApprovalStatus | 'ALLOWED' | 'BLOCKED';
+  message?: string;
+  expires_at?: string;
+}