@siduri-x/api 2.0.1 → 2.0.3

package/src/boot.ts

@@ -0,0 +1,190 @@
+import { OpenAICompatibleBrain, OpenRouterBrain } from '@siduri-x/brain';
+import { SqliteMemoryStore } from '@siduri-x/memory';
+import { VoiceAdapter, VoiceConfig } from '@siduri-x/voice';
+import { UnifiedKnowledgeOrgan, UnifiedKnowledgeConfig } from '@siduri-x/knowledge';
+import { OpenRouterVisionAdapter, OpenRouterVisionConfig } from '@siduri-x/vision';
+import { ActiveSelfCompiler, SqliteSelfRepository } from '@siduri-x/self';
+import { Live2DAdapter, Live2DAdapterConfig } from '@siduri-x/body';
+import { FixtureObservationOrgan } from '@siduri-x/observation';
+import { DefaultHandsOrgan, DefaultHandsOrganConfig } from '@siduri-x/hands';
+import { DefaultEarOrgan, EarOrganConfig } from '@siduri-x/ear';
+import { DefaultMouthOrgan, DefaultMouthOrganConfig } from '@siduri-x/mouth';
+import { SiduriRuntime } from './runtime';
+
+export interface AppBrainConfig {
+  provider?: 'openrouter' | 'openai-compatible' | string;
+  model?: string;
+  apiKey?: string;
+  apiKeyEnv?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  [key: string]: unknown;
+}
+
+export interface AppBehaviorConfig {
+  provider?: 'active_self' | 'none' | string;
+  preset?: string;
+  [key: string]: unknown;
+}
+
+export interface AppBootCompanionConfig {
+  name: string;
+  id?: string;
+  brain?: AppBrainConfig;
+  voice?: VoiceConfig;
+  memory?: { provider?: string; connectionString?: string; maxConnections?: number; dbPath?: string; [key: string]: unknown };
+  knowledge?: UnifiedKnowledgeConfig;
+  vision?: OpenRouterVisionConfig;
+  behavior?: AppBehaviorConfig;
+  body?: Live2DAdapterConfig;
+  hands?: DefaultHandsOrganConfig;
+  ear?: EarOrganConfig;
+  mouth?: DefaultMouthOrganConfig;
+  self?: { dbPath?: string; [key: string]: unknown };
+  organs?: Record<string, any>;
+  [key: string]: unknown;
+}
+
+export interface BootCompanionOptions {
+  observationOrgan?: FixtureObservationOrgan;
+}
+
+export function isDisabled(config?: { provider?: string }): boolean {
+  return !config || config.provider === 'none';
+}
+
+export function createBrain(config?: AppBrainConfig) {
+  const provider = config?.provider || 'openrouter';
+  const defaultKeyEnv = provider === 'openai-compatible' ? 'OPENAI_COMPATIBLE_API_KEY' : 'OPENROUTER_API_KEY';
+  const apiKey = config?.apiKey || process.env[config?.apiKeyEnv || defaultKeyEnv] || '';
+  if (provider === 'openai-compatible') {
+    return new OpenAICompatibleBrain({
+      apiKey,
+      model: config?.model || 'local-model',
+      baseUrl: config?.baseUrl || 'http://127.0.0.1:1234/v1',
+    });
+  }
+  return new OpenRouterBrain({ apiKey, model: config?.model || 'gpt-4o-mini' });
+}
+
+export function createVoice(config?: VoiceConfig) {
+  return isDisabled(config)
+    ? undefined
+    : new VoiceAdapter({
+        provider: (config?.provider as any) || 'voicevox',
+        baseUrl: config?.baseUrl || process.env.VOICEVOX_URL || 'http://localhost:50021',
+        speakerId: config?.speakerId || 1,
+        ...config,
+      });
+}
+
+export function createKnowledge(config?: UnifiedKnowledgeConfig) {
+  if (isDisabled(config)) return undefined;
+  const dbPath = (config?.dbPath as string) || process.env.STORAGE_PATH || process.env.SQLITE_DB_PATH || 'siduri.sqlite';
+  return new UnifiedKnowledgeOrgan({
+    ...config,
+    dbPath,
+    lifeDatabase: config?.lifeDatabase ?? true,
+  });
+}
+
+export function createVision(config?: OpenRouterVisionConfig & { provider?: string }) {
+  return isDisabled(config)
+    ? undefined
+    : new OpenRouterVisionAdapter({
+        apiKey: config?.apiKey || process.env.OPENROUTER_API_KEY || '',
+        model: config?.model || 'gpt-4-vision',
+        ...config,
+      });
+}
+
+export function createBehavior(config?: AppBehaviorConfig) {
+  return isDisabled(config) ? undefined : new ActiveSelfCompiler();
+}
+
+export function createBody(config?: Live2DAdapterConfig & { provider?: string }) {
+  return isDisabled(config)
+    ? undefined
+    : new Live2DAdapter(config);
+}
+
+export function createHands(config?: DefaultHandsOrganConfig & { provider?: string }) {
+  return isDisabled(config)
+    ? new DefaultHandsOrgan()
+    : new DefaultHandsOrgan(config);
+}
+
+export function createEar(config?: EarOrganConfig & { provider?: string }) {
+  return isDisabled(config)
+    ? new DefaultEarOrgan()
+    : new DefaultEarOrgan(config);
+}
+
+export function createMouth(config?: DefaultMouthOrganConfig & { provider?: string }, voice?: any) {
+  return isDisabled(config)
+    ? new DefaultMouthOrgan({ voice })
+    : new DefaultMouthOrgan({ ...config, voice });
+}
+
+export function createMemory(config?: { provider?: string; connectionString?: string; maxConnections?: number; dbPath?: string }) {
+  if (isDisabled(config)) return undefined;
+  return new SqliteMemoryStore({ dbPath: config?.dbPath || process.env.STORAGE_PATH || process.env.SQLITE_DB_PATH || 'siduri.sqlite' });
+}
+
+export function createSelf(config?: { dbPath?: string }) {
+  return new SqliteSelfRepository({ dbPath: config?.dbPath || process.env.STORAGE_PATH || process.env.SQLITE_DB_PATH || 'siduri.sqlite' });
+}
+
+export function createObservation(vision?: any): FixtureObservationOrgan {
+  return new FixtureObservationOrgan(
+    vision ?? { analyze: async () => JSON.stringify({ readings: [] }) }
+  );
+}
+
+/**
+ * Canonical companion bootstrapper.
+ * Wires all 10 organs, runs memory migrations, and initializes the SiduriRuntime.
+ */
+export async function bootCompanion(
+  id: string,
+  config: AppBootCompanionConfig,
+  options?: BootCompanionOptions
+): Promise<SiduriRuntime> {
+  const organs = (config as any)?.organs || {};
+
+  const brain = createBrain(organs.brain || config?.brain);
+  const memory = createMemory(organs.memory || (config as any)?.memory);
+  const selfRepo = createSelf(organs.self || (config as any)?.self);
+  const voice = createVoice(organs.voice || config?.voice);
+  const knowledge = createKnowledge(organs.knowledge || config?.knowledge);
+  const vision = createVision(organs.vision || config?.vision);
+  const behavior = createBehavior(organs.behavior || config?.behavior);
+  const body = createBody(organs.body || config?.body);
+  const hands = createHands(organs.hands || config?.hands);
+  const ear = createEar(organs.ear || config?.ear);
+  const mouth = createMouth(organs.mouth || config?.mouth, voice);
+  const observation = options?.observationOrgan;
+
+  if (memory && typeof (memory as any).runMigrations === 'function') {
+    await (memory as any).runMigrations().catch((e: any) => console.warn("Migrations warning:", e.message));
+  }
+
+  const runtime = new SiduriRuntime(id, config as any, {
+    brain,
+    memory,
+    voice,
+    knowledge,
+    vision,
+    behavior,
+    body,
+    hands,
+    ear,
+    mouth,
+    observation,
+    self: selfRepo,
+    externalKnowledge: (knowledge as any)?.eAdapter ?? knowledge,
+  });
+
+  await runtime.initialize();
+  return runtime;
+}

package/src/context-mapper.test.ts

@@ -176,5 +176,144 @@ describe('API Request Context Mapper (Single-Owner, Single-Machine)', () => {
     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

@@ -20,8 +20,10 @@ export interface MapRequestContextResult {
 /**
  * Maps incoming HTTP requests to a canonical RequestContext.
  * In a single-owner, single-machine model:
- * - Security is enforced at the external boundary, not internally between roles.
+ * - 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,
@@ -43,7 +45,10 @@ export function mapRequestContext(
   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;
+    const correlationId =
+      rawCtx.conversation?.correlationId ||
+      input.correlationId ||
+      (input.generateCorrelationId ? `corr-${Date.now()}` : undefined);
 
     if (!companionId) {
       return {
@@ -81,18 +86,46 @@ export function mapRequestContext(
       };
     }
 
-    // Determine server-enforced authentication status
+    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 safeCapabilities = isAuthenticated
-      ? (Array.isArray(actor.capabilities) ? actor.capabilities : ['chat'])
-      : ['chat'];
+    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'];
 
-    const safeRole = isAuthenticated
-      ? actor.authorizationRole
-      : 'viewer';
+    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,
@@ -102,7 +135,7 @@ export function mapRequestContext(
         sessionId: actor.sessionId,
         capabilities: safeCapabilities,
         authenticated: isAuthenticated,
-        authorizationRole: safeRole,
+        authorizationRole,
       },
       conversation: {
         correlationId,
@@ -112,6 +145,7 @@ export function mapRequestContext(
       },
       source: input.source || rawCtx.source || (isAuthenticated ? 'local' : 'external'),
       subject: rawCtx.subject,
+      mode: rawCtx.mode || input.mode,
     };
 
     const validated = validateRequestContext(constructed);
@@ -167,20 +201,52 @@ export function mapRequestContext(
     };
   }
 
-  const actorId = input.actorId || input.actor?.actorId || 'local-user';
+  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 isAuthenticated = input.authenticated !== undefined ? Boolean(input.authenticated) : true;
-  const capabilities = isAuthenticated
-    ? (Array.isArray(input.capabilities)
-        ? input.capabilities
-        : Array.isArray(input.actor?.capabilities)
-        ? input.actor.capabilities
-        : ['chat', 'system'])
-    : ['chat'];
+  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,
@@ -189,7 +255,7 @@ export function mapRequestContext(
       sessionId,
       capabilities,
       authenticated: isAuthenticated,
-      authorizationRole: input.role ? (input.role.toLowerCase() === 'viewer' ? 'viewer' : 'administrator') : undefined,
+      authorizationRole,
     },
     conversation: {
       channel: input.channel || input.conversation?.channel || 'direct',
@@ -197,6 +263,7 @@ export function mapRequestContext(
     },
     source: input.source || (isAuthenticated ? 'local' : 'external'),
     subject: input.subject,
+    mode: input.mode || input.conversation?.mode,
   };
 
   const validated = validateRequestContext(mappedContext);

package/src/index.test.ts

@@ -127,7 +127,7 @@ describe('API Boundary Context Validation (P2 Route Integration)', () => {
   });
 
   test('handles barge-in interruption via POST /chat/interrupt', async () => {
-    fakeRuntime.interruptMouth = jest.fn();
+    fakeRuntime.mouth = { interrupt: jest.fn() };
 
     const res = await request(app)
       .post('/chat/interrupt')
@@ -138,11 +138,11 @@ describe('API Boundary Context Validation (P2 Route Integration)', () => {
 
     expect(res.status).toBe(200);
     expect(res.body.interrupted).toBe(true);
-    expect(fakeRuntime.interruptMouth).toHaveBeenCalledWith('user_stop');
+    expect(fakeRuntime.mouth.interrupt).toHaveBeenCalledWith('user_stop');
   });
 
   test('handles mouth interruption via POST /mouth/interrupt', async () => {
-    fakeRuntime.interruptMouth = jest.fn();
+    fakeRuntime.mouth = { interrupt: jest.fn() };
 
     const res = await request(app)
       .post('/mouth/interrupt')
@@ -153,6 +153,26 @@ describe('API Boundary Context Validation (P2 Route Integration)', () => {
 
     expect(res.status).toBe(200);
     expect(res.body.interrupted).toBe(true);
-    expect(fakeRuntime.interruptMouth).toHaveBeenCalledWith('user_barge_in');
+    expect(fakeRuntime.mouth.interrupt).toHaveBeenCalledWith('user_barge_in');
+  });
+
+  test('POST /chat passes explicit interaction mode (casual, teach, hybrid) to runtime', async () => {
+    const res = await request(app)
+      .post('/chat')
+      .send({
+        id: 'companion-a',
+        message: 'Casual banter',
+        mode: 'casual',
+      });
+
+    expect(res.status).toBe(200);
+    expect(fakeRuntime.handleUserMessage).toHaveBeenCalledWith(
+      'Casual banter',
+      expect.objectContaining({
+        companionId: 'companion-a',
+        mode: 'casual',
+      }),
+      []
+    );
   });
 });