@sidurijs/api 1.0.0

package/src/context-mapper.test.ts

@@ -0,0 +1,319 @@
+import { mapRequestContext } from './context-mapper';
+
+describe('API Request Context Mapper (Single-Owner, Single-Machine)', () => {
+  test('Local chat request maps to valid RequestContext with local user defaults', () => {
+    const input = {
+      companionId: 'companion-a',
+      message: 'Hello world',
+      correlationId: 'corr-local-1',
+    };
+
+    const result = mapRequestContext(input);
+
+    expect(result.accepted).toBe(true);
+    expect(result.context?.companionId).toBe('companion-a');
+    expect(result.context?.actor.actorId).toBe('local-user');
+    expect(result.context?.actor.authenticated).toBe(true);
+    expect(result.context?.conversation.correlationId).toBe('corr-local-1');
+    expect(result.context?.source).toBe('local');
+    expect(result.context?.subject).toBeUndefined();
+  });
+
+  test('Accepts structured context envelope', () => {
+    const input = {
+      companionId: 'companion-a',
+      context: {
+        actor: {
+          actorId: 'user-main',
+          sessionId: 'session-main',
+          authenticated: true,
+          capabilities: ['chat', 'system'],
+        },
+        conversation: {
+          correlationId: 'corr-structured-1',
+        },
+      },
+      message: 'Hello structured context',
+    };
+
+    const result = mapRequestContext(input);
+    expect(result.accepted).toBe(true);
+    expect(result.context?.actor.actorId).toBe('user-main');
+    expect(result.context?.conversation.correlationId).toBe('corr-structured-1');
+  });
+
+  test('Rejects global primary_user subject', () => {
+    const input = {
+      companionId: 'companion-a',
+      context: {
+        actor: {
+          actorId: 'user-a',
+          sessionId: 'session-a',
+        },
+        conversation: {
+          correlationId: 'corr-primary-user',
+        },
+        subject: {
+          subjectId: 'primary_user',
+          kind: 'actor',
+        },
+      },
+    };
+
+    const result = mapRequestContext(input);
+    expect(result.accepted).toBe(false);
+    expect(result.error?.code).toBe('FORBIDDEN_CONTEXT');
+    expect(result.error?.field).toBe('subject.subjectId');
+  });
+
+  test('Rejects missing actor on structured context', () => {
+    const input = {
+      companionId: 'companion-a',
+      context: {
+        actor: {
+          actorId: '',
+          sessionId: 'session-a',
+        },
+        conversation: {
+          correlationId: 'corr-teach-no-actor',
+        },
+      },
+    };
+
+    const result = mapRequestContext(input);
+    expect(result.accepted).toBe(false);
+    expect(result.error?.code).toBe('MISSING_CONTEXT');
+    expect(result.error?.fields).toContain('actor.actorId');
+  });
+
+  test('Two companion IDs with same actor remain isolated under context mapper', () => {
+    const actor = {
+      actorId: 'user-a',
+      sessionId: 'session-a',
+      authenticated: true,
+    };
+    const conv = {
+      correlationId: 'corr-iso-1',
+    };
+
+    const reqA = { companionId: 'companion-a', context: { actor, conversation: conv } };
+    const reqB = { companionId: 'companion-b', context: { actor, conversation: conv } };
+
+    const resA = mapRequestContext(reqA);
+    const resB = mapRequestContext(reqB);
+
+    expect(resA.accepted).toBe(true);
+    expect(resB.accepted).toBe(true);
+    expect(resA.context?.companionId).toBe('companion-a');
+    expect(resB.context?.companionId).toBe('companion-b');
+  });
+
+  test('Rejects missing companionId', () => {
+    const input = {
+      message: 'No companion id',
+      correlationId: 'corr-no-comp',
+    };
+
+    const result = mapRequestContext(input);
+    expect(result.accepted).toBe(false);
+    expect(result.error?.code).toBe('MISSING_CONTEXT');
+    expect(result.error?.fields).toContain('companionId');
+  });
+
+  test('Rejects missing correlation ID when generateCorrelationId is not set', () => {
+    const input = {
+      companionId: 'companion-a',
+      context: {
+        actor: {
+          actorId: 'user-a',
+          sessionId: 'session-a',
+        },
+        conversation: {
+          correlationId: '',
+        },
+      },
+    };
+
+    const result = mapRequestContext(input);
+    expect(result.accepted).toBe(false);
+    expect(result.error?.code).toBe('MISSING_CONTEXT');
+    expect(result.error?.fields).toContain('conversation.correlationId');
+  });
+
+  test('Generates correlationId when generateCorrelationId option is true', () => {
+    const input = {
+      companionId: 'companion-a',
+      generateCorrelationId: true,
+    };
+
+    const result = mapRequestContext(input);
+    expect(result.accepted).toBe(true);
+    expect(result.context?.conversation.correlationId).toMatch(/^corr-/);
+  });
+
+  test('Overrides forged client actor authentication and caps capabilities on unauthenticated requests', () => {
+    const forgedInput = {
+      companionId: 'companion-a',
+      authenticated: false, // Server detected unauthenticated request
+      source: 'external',
+      context: {
+        actor: {
+          actorId: 'attacker',
+          sessionId: 'session-att',
+          authenticated: true, // Forged
+          capabilities: ['system:exec', 'bash', 'chat'], // Forged elevated capabilities
+          authorizationRole: 'OWNER', // Forged role
+        },
+        conversation: {
+          correlationId: 'corr-forged-1',
+        },
+      },
+    };
+
+    const result = mapRequestContext(forgedInput);
+    expect(result.accepted).toBe(true);
+    expect(result.context?.actor.authenticated).toBe(false);
+    expect(result.context?.actor.capabilities).toEqual(['chat']);
+    expect(result.context?.actor.authorizationRole).toBe('viewer');
+    expect(result.context?.source).toBe('external');
+    expect(result.diagnostics).toContain('role_escalation_attempt_suppressed');
+    expect(result.diagnostics).toContain('capability_escalation_attempt_suppressed');
+  });
+
+  test('Prevents attenuated caller from escalating to administrator role or forging elevated capabilities', () => {
+    const attenuatedPayload = {
+      companionId: 'companion-a',
+      authenticated: true,
+      role: 'VIEWER',
+      source: 'external',
+      context: {
+        actor: {
+          actorId: 'visitor-bob',
+          sessionId: 'session-vis-1',
+          authorizationRole: 'administrator', // Forged owner/admin role
+          capabilities: ['chat', 'system', 'root:manage', 'action:execute'], // Forged system/root capabilities
+        },
+        conversation: {
+          correlationId: 'corr-att-escalate',
+        },
+      },
+    };
+
+    const result = mapRequestContext(attenuatedPayload);
+    expect(result.accepted).toBe(true);
+    expect(result.context?.actor.authenticated).toBe(true);
+    expect(result.context?.actor.authorizationRole).toBe('viewer');
+    expect(result.context?.actor.capabilities).toEqual(['chat']);
+    expect(result.diagnostics).toContain('role_escalation_attempt_suppressed');
+    expect(result.diagnostics).toContain('capability_escalation_attempt_suppressed');
+  });
+
+  test('Strips unknown capabilities for authenticated owner while preserving canonical companion capabilities', () => {
+    const ownerPayload = {
+      companionId: 'companion-a',
+      authenticated: true,
+      source: 'local',
+      context: {
+        actor: {
+          actorId: 'owner-user',
+          sessionId: 'session-owner-1',
+          capabilities: ['chat', 'system', 'root:unauthorized', 'arbitrary:hack'],
+        },
+        conversation: {
+          correlationId: 'corr-owner-caps',
+        },
+      },
+    };
+
+    const result = mapRequestContext(ownerPayload);
+    expect(result.accepted).toBe(true);
+    expect(result.context?.actor.authorizationRole).toBe('administrator');
+    expect(result.context?.actor.capabilities).toEqual(['chat', 'system']);
+    expect(result.diagnostics).toContain('capability_escalation_attempt_suppressed');
+  });
+
+  test('Flat envelope: suppresses role and capability escalation when serverRole is VIEWER', () => {
+    const viewerPayload = {
+      companionId: 'companion-a',
+      authenticated: false,
+      serverRole: 'VIEWER',
+      role: 'OWNER', // Forged in flat envelope
+      capabilities: ['chat', 'system', 'action:execute'],
+      generateCorrelationId: true,
+    };
+
+    const result = mapRequestContext(viewerPayload);
+    expect(result.accepted).toBe(true);
+    expect(result.context?.actor.authorizationRole).toBe('viewer');
+    expect(result.context?.actor.capabilities).toEqual(['chat']);
+    expect(result.diagnostics).toContain('role_escalation_attempt_suppressed');
+  });
+
+  test('Authenticated owner receives canonical administrator role and capabilities, and can safely attenuate to viewer', () => {
+    const ownerPayload = {
+      companionId: 'companion-a',
+      authenticated: true,
+      serverRole: 'OWNER',
+      generateCorrelationId: true,
+    };
+
+    const ownerResult = mapRequestContext(ownerPayload);
+    expect(ownerResult.accepted).toBe(true);
+    expect(ownerResult.context?.actor.authorizationRole).toBe('administrator');
+    expect(ownerResult.context?.actor.capabilities).toEqual([
+      'chat',
+      'memory:approve',
+      'action:execute',
+      'system',
+    ]);
+
+    // Attenuation to viewer
+    const attenuatedPayload = {
+      ...ownerPayload,
+      role: 'VIEWER',
+    };
+    const attenuatedResult = mapRequestContext(attenuatedPayload);
+    expect(attenuatedResult.accepted).toBe(true);
+    expect(attenuatedResult.context?.actor.authorizationRole).toBe('viewer');
+    expect(attenuatedResult.diagnostics).not.toContain('role_escalation_attempt_suppressed');
+  });
+
+  describe('Mode Mapping (Casual, Teach, Hybrid)', () => {
+    test('maps explicit mode parameter to RequestContext', () => {
+      const casualResult = mapRequestContext({
+        companionId: 'comp-1',
+        mode: 'casual',
+        generateCorrelationId: true,
+      });
+      expect(casualResult.accepted).toBe(true);
+      expect(casualResult.context?.mode).toBe('casual');
+
+      const teachResult = mapRequestContext({
+        companionId: 'comp-1',
+        mode: 'teach',
+        generateCorrelationId: true,
+      });
+      expect(teachResult.accepted).toBe(true);
+      expect(teachResult.context?.mode).toBe('teach');
+
+      const hybridResult = mapRequestContext({
+        companionId: 'comp-1',
+        mode: 'hybrid',
+        generateCorrelationId: true,
+      });
+      expect(hybridResult.accepted).toBe(true);
+      expect(hybridResult.context?.mode).toBe('hybrid');
+    });
+
+    test('rejects invalid interaction mode', () => {
+      const invalidResult = mapRequestContext({
+        companionId: 'comp-1',
+        mode: 'super_turbo',
+        generateCorrelationId: true,
+      });
+      expect(invalidResult.accepted).toBe(false);
+      expect(invalidResult.error?.code).toBe('INVALID_CONTEXT');
+      expect(invalidResult.error?.field).toBe('mode');
+    });
+  });
+});

package/src/context-mapper.ts

@@ -0,0 +1,279 @@
+import {
+  RequestContext,
+  DiagnosticCode,
+  ContextError,
+  validateRequestContext,
+} from '@sidurijs/core';
+
+export interface ContextMapperOptions {
+  endpointPolicy?: 'public' | 'private' | 'operator' | 'direct' | string;
+  allowAnonymousPublicChat?: boolean;
+}
+
+export interface MapRequestContextResult {
+  accepted: boolean;
+  context?: RequestContext;
+  diagnostics?: DiagnosticCode[];
+  error?: ContextError;
+}
+
+/**
+ * Maps incoming HTTP requests to a canonical RequestContext.
+ * In a single-owner, single-machine model:
+ * - Security is enforced at the external machine boundary, NOT internally between roles.
+ * - No internal audience or viewer/operator/owner role hierarchies.
+ * - Authenticated callers are the single owner with full companion access.
+ * - Unauthenticated callers are bounded to public chat.
+ */
+export function mapRequestContext(
+  input: any,
+  options: ContextMapperOptions = {}
+): MapRequestContextResult {
+  const diagnostics: DiagnosticCode[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return {
+      accepted: false,
+      error: {
+        code: 'MISSING_CONTEXT',
+        fields: ['request'],
+      },
+    };
+  }
+
+  // 1. If incoming input already has a context structure
+  if (input.context && typeof input.context === 'object') {
+    const rawCtx = input.context;
+    const companionId = input.companionId || rawCtx.companionId || input.id;
+    const correlationId =
+      rawCtx.conversation?.correlationId ||
+      input.correlationId ||
+      (input.generateCorrelationId ? `corr-${Date.now()}` : undefined);
+
+    if (!companionId) {
+      return {
+        accepted: false,
+        error: {
+          code: 'MISSING_CONTEXT',
+          fields: ['companionId'],
+          correlationId,
+        },
+      };
+    }
+
+    const actor = rawCtx.actor;
+    if (!actor || typeof actor !== 'object') {
+      return {
+        accepted: false,
+        error: {
+          code: 'MISSING_CONTEXT',
+          fields: ['actor'],
+          correlationId,
+        },
+      };
+    }
+
+    // Reject invalid primary_user subject
+    if (rawCtx.subject && (rawCtx.subject.subjectId === 'primary_user' || rawCtx.subject === 'primary_user')) {
+      return {
+        accepted: false,
+        error: {
+          code: 'FORBIDDEN_CONTEXT',
+          message: 'Global primary_user subject is forbidden',
+          field: 'subject.subjectId',
+          correlationId,
+        },
+      };
+    }
+
+    const isViewerRequested =
+      (typeof input.role === 'string' && input.role.toLowerCase() === 'viewer') ||
+      (typeof input.serverRole === 'string' && input.serverRole.toLowerCase() === 'viewer') ||
+      (typeof actor.authorizationRole === 'string' && actor.authorizationRole.toLowerCase() === 'viewer') ||
+      (typeof (actor as any).role === 'string' && (actor as any).role.toLowerCase() === 'viewer');
+
+    // Determine server-enforced authentication status at the machine boundary
+    const isAuthenticated = input.authenticated !== undefined
+      ? Boolean(input.authenticated)
+      : (actor.authenticated !== undefined ? Boolean(actor.authenticated) : true);
+
+    const isViewer = !isAuthenticated || isViewerRequested;
+
+    const CANONICAL_CAPABILITIES = new Set(['chat', 'memory:approve', 'action:execute', 'system']);
+    const DEFAULT_OWNER_CAPABILITIES = ['chat', 'memory:approve', 'action:execute', 'system'];
+
+    let safeCapabilities: string[];
+    let authorizationRole: string;
+
+    if (isViewer) {
+      safeCapabilities = ['chat'];
+      authorizationRole = 'viewer';
+      if (Array.isArray(actor.capabilities) && actor.capabilities.some((c: string) => c !== 'chat' && c !== 'chat:public')) {
+        diagnostics.push('capability_escalation_attempt_suppressed');
+      }
+      if (actor.authorizationRole && actor.authorizationRole.toLowerCase() !== 'viewer') {
+        diagnostics.push('role_escalation_attempt_suppressed');
+      }
+    } else {
+      authorizationRole = 'administrator';
+      if (Array.isArray(actor.capabilities) && actor.capabilities.length > 0) {
+        const filtered = actor.capabilities.filter((c: string) => CANONICAL_CAPABILITIES.has(c));
+        if (filtered.length < actor.capabilities.length) {
+          diagnostics.push('capability_escalation_attempt_suppressed');
+        }
+        safeCapabilities = filtered.length > 0 ? filtered : [...DEFAULT_OWNER_CAPABILITIES];
+      } else {
+        safeCapabilities = [...DEFAULT_OWNER_CAPABILITIES];
+      }
+    }
+
+    const constructed: RequestContext = {
+      companionId,
+      actor: {
+        ...actor,
+        actorId: actor.actorId,
+        sessionId: actor.sessionId,
+        capabilities: safeCapabilities,
+        authenticated: isAuthenticated,
+        authorizationRole,
+      },
+      conversation: {
+        correlationId,
+        channel: rawCtx.conversation?.channel || input.channel || 'direct',
+        isLive: rawCtx.conversation?.isLive,
+        ...rawCtx.conversation,
+      },
+      source: input.source || rawCtx.source || (isAuthenticated ? 'local' : 'external'),
+      subject: rawCtx.subject,
+      mode: rawCtx.mode || input.mode,
+    };
+
+    const validated = validateRequestContext(constructed);
+    if (!validated.accepted) {
+      return validated;
+    }
+
+    return {
+      accepted: true,
+      context: validated.context,
+      diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+    };
+  }
+
+  // 2. Synthesize clean RequestContext from request envelope
+  const companionId = input.companionId || input.id;
+  const correlationId = input.correlationId || input.conversation?.correlationId || (input.generateCorrelationId ? `corr-${Date.now()}` : undefined);
+
+  if (!companionId) {
+    return {
+      accepted: false,
+      error: {
+        code: 'MISSING_CONTEXT',
+        fields: ['companionId'],
+        correlationId,
+      },
+    };
+  }
+
+  if (companionId === 'default') {
+    diagnostics.push('companion_default_mapped_for_bootstrap');
+  }
+
+  if (!correlationId) {
+    return {
+      accepted: false,
+      error: {
+        code: 'MISSING_CONTEXT',
+        fields: ['conversation.correlationId'],
+      },
+    };
+  }
+
+  if (input.subject === 'primary_user' || input.subjectId === 'primary_user') {
+    return {
+      accepted: false,
+      error: {
+        code: 'FORBIDDEN_CONTEXT',
+        message: 'Global primary_user subject is forbidden',
+        field: 'subject',
+        correlationId,
+      },
+    };
+  }
+
+  const isViewerRequested =
+    (typeof input.role === 'string' && input.role.toLowerCase() === 'viewer') ||
+    (typeof input.serverRole === 'string' && input.serverRole.toLowerCase() === 'viewer');
+
+  const isAuthenticated = input.authenticated !== undefined ? Boolean(input.authenticated) : true;
+  const isViewer = !isAuthenticated || isViewerRequested;
+
+  const actorId = input.actorId || input.actor?.actorId || (isAuthenticated && !isViewer ? 'local-user' : 'anonymous-session');
+  const sessionId = input.sessionId || input.actor?.sessionId || `session-${Date.now()}`;
+  if (!input.actorId && !input.actor?.actorId) {
+    diagnostics.push('anonymous_session_generated');
+  }
+
+  const CANONICAL_CAPABILITIES = new Set(['chat', 'memory:approve', 'action:execute', 'system']);
+  const DEFAULT_OWNER_CAPABILITIES = ['chat', 'memory:approve', 'action:execute', 'system'];
+
+  const rawCaps = Array.isArray(input.capabilities)
+    ? input.capabilities
+    : Array.isArray(input.actor?.capabilities)
+    ? input.actor.capabilities
+    : undefined;
+
+  let capabilities: string[];
+  let authorizationRole: string;
+
+  if (isViewer) {
+    capabilities = ['chat'];
+    authorizationRole = 'viewer';
+    if (rawCaps && rawCaps.some((c: string) => c !== 'chat' && c !== 'chat:public')) {
+      diagnostics.push('capability_escalation_attempt_suppressed');
+    }
+    if (input.role && input.role.toLowerCase() !== 'viewer') {
+      diagnostics.push('role_escalation_attempt_suppressed');
+    }
+  } else {
+    authorizationRole = 'administrator';
+    if (rawCaps && rawCaps.length > 0) {
+      const filtered = rawCaps.filter((c: string) => CANONICAL_CAPABILITIES.has(c));
+      if (filtered.length < rawCaps.length) {
+        diagnostics.push('capability_escalation_attempt_suppressed');
+      }
+      capabilities = filtered.length > 0 ? filtered : [...DEFAULT_OWNER_CAPABILITIES];
+    } else {
+      capabilities = [...DEFAULT_OWNER_CAPABILITIES];
+    }
+  }
+
+  const mappedContext: RequestContext = {
+    companionId,
+    actor: {
+      actorId,
+      sessionId,
+      capabilities,
+      authenticated: isAuthenticated,
+      authorizationRole,
+    },
+    conversation: {
+      channel: input.channel || input.conversation?.channel || 'direct',
+      correlationId,
+    },
+    source: input.source || (isAuthenticated ? 'local' : 'external'),
+    subject: input.subject,
+    mode: input.mode || input.conversation?.mode,
+  };
+
+  const validated = validateRequestContext(mappedContext);
+  if (!validated.accepted) {
+    return validated;
+  }
+
+  return {
+    accepted: true,
+    context: validated.context,
+    diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+  };
+}

package/src/cors.ts

@@ -0,0 +1,44 @@
+import cors from 'cors';
+
+export function getAllowedOrigins(): Set<string> {
+  const allowed = new Set<string>([
+    'http://localhost:3000',
+    'http://127.0.0.1:3000',
+    'http://localhost:3001',
+    'http://127.0.0.1:3001',
+  ]);
+
+  if (process.env.PORT) {
+    allowed.add(`http://localhost:${process.env.PORT}`);
+    allowed.add(`http://127.0.0.1:${process.env.PORT}`);
+  }
+
+  const envOrigins = process.env.ALLOWED_ORIGINS;
+  if (envOrigins) {
+    for (const origin of envOrigins.split(',')) {
+      const trimmed = origin.trim();
+      if (trimmed) {
+        allowed.add(trimmed);
+      }
+    }
+  }
+
+  return allowed;
+}
+
+export function createCorsOptions(): cors.CorsOptions {
+  return {
+    origin: (origin, callback) => {
+      // Allow non-browser requests with no origin header (e.g., native tools, curl)
+      if (!origin) {
+        return callback(null, true);
+      }
+      const allowedOrigins = getAllowedOrigins();
+      if (allowedOrigins.has(origin)) {
+        return callback(null, true);
+      }
+      return callback(null, false);
+    },
+    credentials: true,
+  };
+}