@siduri-x/api 1.0.0

package/src/context-mapper.ts

@@ -0,0 +1,331 @@
+import {
+  RequestContext,
+  AuthorizationRole,
+  Channel,
+  DiagnosticCode,
+  ContextError,
+  validateRequestContext,
+} from '@siduri-x/core';
+
+export interface ContextMapperOptions {
+  endpointPolicy?: 'public' | 'private' | 'operator' | 'direct';
+  defaultPublicAudience?: string;
+  defaultPrivateAudience?: string;
+  defaultOperatorAudience?: string;
+  allowAnonymousPublicChat?: boolean;
+}
+
+export interface MapRequestContextResult {
+  accepted: boolean;
+  context?: RequestContext;
+  diagnostics?: DiagnosticCode[];
+  error?: ContextError;
+}
+
+export function mapRequestContext(
+  input: any,
+  options: ContextMapperOptions = {}
+): MapRequestContextResult {
+  const diagnostics: DiagnosticCode[] = [];
+  const endpointPolicy = options.endpointPolicy || 'public';
+  const defaultPublicAudience = options.defaultPublicAudience || 'audience-public';
+
+  if (!input || typeof input !== 'object') {
+    return {
+      accepted: false,
+      error: {
+        code: 'MISSING_CONTEXT',
+        fields: ['request'],
+      },
+    };
+  }
+
+  // Check for legacy MASTER_PRIVATE in any audience field or request
+  const rawAudience =
+    input?.context?.conversation?.audienceId ??
+    input?.conversation?.audienceId ??
+    input?.audienceId ??
+    input?.audience;
+
+  if (rawAudience === 'MASTER_PRIVATE' || input?.scope === 'MASTER_PRIVATE') {
+    if (endpointPolicy === 'public' || input?.channel === 'public' || input?.context?.conversation?.channel === 'public') {
+      return {
+        accepted: false,
+        error: {
+          code: 'LEGACY_PERSONAL_AUDIENCE',
+          field: 'audienceId',
+          correlationId: input?.context?.conversation?.correlationId || input?.correlationId,
+        },
+      };
+    }
+  }
+
+  // 1. If incoming input already has a full neutral 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;
+
+    if (!companionId) {
+      return {
+        accepted: false,
+        error: {
+          code: 'MISSING_CONTEXT',
+          fields: ['companionId'],
+          correlationId,
+        },
+      };
+    }
+
+    // Role cannot select audience or subject
+    const rawRole = input.role || rawCtx.actor?.authorizationRole;
+    if (input.role && !rawCtx.conversation?.channel && !rawCtx.conversation?.audienceId) {
+      return {
+        accepted: false,
+        error: {
+          code: 'AMBIGUOUS_CONTEXT',
+          conflicts: ['role_does_not_select_audience', 'role_does_not_select_subject'],
+          correlationId,
+        },
+      };
+    }
+
+    const channel: Channel = rawCtx.conversation?.channel || (endpointPolicy as Channel);
+    let audienceId: string | undefined = rawCtx.conversation?.audienceId;
+
+    if (!audienceId) {
+      if (channel === 'public' || endpointPolicy === 'public') {
+        audienceId = defaultPublicAudience;
+        diagnostics.push('audience_defaulted_by_public_policy');
+      } else {
+        return {
+          accepted: false,
+          error: {
+            code: 'MISSING_CONTEXT',
+            fields: ['conversation.audienceId'],
+            correlationId,
+          },
+        };
+      }
+    }
+
+    if (!correlationId) {
+      return {
+        accepted: false,
+        error: {
+          code: 'MISSING_CONTEXT',
+          fields: ['conversation.correlationId'],
+        },
+      };
+    }
+
+    const actor = rawCtx.actor;
+    if (!actor || typeof actor !== 'object') {
+      return {
+        accepted: false,
+        error: {
+          code: 'MISSING_CONTEXT',
+          fields: ['actor'],
+          correlationId,
+        },
+      };
+    }
+
+    // Check required capabilities for private/operator/direct channels
+    const capabilities: string[] = Array.isArray(actor.capabilities) ? actor.capabilities : [];
+    if (channel === 'private' && !capabilities.includes('chat:private')) {
+      return {
+        accepted: false,
+        error: {
+          code: 'UNAUTHORIZED_CHANNEL_OR_CAPABILITY',
+          message: 'Private channel requires explicit chat:private capability',
+          fields: ['actor.capabilities'],
+          correlationId,
+        },
+      };
+    }
+    if (channel === 'operator' && !capabilities.includes('memory:inspect') && !capabilities.includes('operator:access')) {
+      return {
+        accepted: false,
+        error: {
+          code: 'UNAUTHORIZED_CHANNEL_OR_CAPABILITY',
+          message: 'Operator channel requires explicit operator capability',
+          fields: ['actor.capabilities'],
+          correlationId,
+        },
+      };
+    }
+
+    // Check subject policy
+    let subject = rawCtx.subject;
+    if (subject) {
+      if (subject.subjectId === 'primary_user' || subject === 'primary_user') {
+        // Global primary_user is rejected or quarantined
+        return {
+          accepted: false,
+          error: {
+            code: 'FORBIDDEN_CONTEXT',
+            message: 'Global primary_user subject is forbidden',
+            field: 'subject.subjectId',
+            correlationId,
+          },
+        };
+      }
+    }
+
+    const constructed: RequestContext = {
+      companionId,
+      actor: {
+        actorId: actor.actorId,
+        sessionId: actor.sessionId,
+        authorizationRole: actor.authorizationRole,
+        capabilities,
+        authenticated: Boolean(actor.authenticated),
+      },
+      conversation: {
+        channel,
+        audienceId,
+        isLive: rawCtx.conversation?.isLive,
+        correlationId,
+      },
+      subject,
+    };
+
+    const validated = validateRequestContext(constructed);
+    if (!validated.accepted) {
+      return validated;
+    }
+
+    return {
+      accepted: true,
+      context: validated.context,
+      diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+    };
+  }
+
+  // 2. Legacy compatibility envelope mapping
+  const companionId = input.companionId || input.id;
+  const correlationId = input.correlationId || input.conversation?.correlationId;
+
+  if (!companionId) {
+    return {
+      accepted: false,
+      error: {
+        code: 'MISSING_CONTEXT',
+        fields: ['companionId'],
+        correlationId,
+      },
+    };
+  }
+
+  if (companionId === 'default') {
+    diagnostics.push('companion_default_mapped_for_bootstrap');
+  }
+
+  // Map legacy role to authorizationRole
+  const legacyRole = input.role?.toString().toUpperCase();
+  let authRole: AuthorizationRole = 'viewer';
+  if (legacyRole === 'OWNER') {
+    authRole = 'administrator';
+    diagnostics.push('legacy_role_mapped_to_authorization');
+  } else if (legacyRole === 'OPERATOR') {
+    authRole = 'operator';
+    diagnostics.push('legacy_role_mapped_to_authorization');
+  } else if (legacyRole === 'VIEWER') {
+    authRole = 'viewer';
+    diagnostics.push('legacy_role_mapped_to_authorization');
+  } else if (input.role) {
+    return {
+      accepted: false,
+      error: {
+        code: 'INVALID_CONTEXT',
+        field: 'role',
+        correlationId,
+      },
+    };
+  }
+
+  // Check endpoint policy vs legacy request
+  if (endpointPolicy === 'private' || endpointPolicy === 'operator' || endpointPolicy === 'direct') {
+    // Missing explicit channel, audience, or capability on private/operator endpoint is an error
+    const fields: string[] = [];
+    if (!input.channel) fields.push('conversation.channel');
+    if (!input.audienceId) fields.push('conversation.audienceId');
+    if (!input.capabilities && !input.actor?.capabilities) fields.push('actor.capabilities');
+    if (!correlationId) fields.push('conversation.correlationId');
+
+    return {
+      accepted: false,
+      error: {
+        code: 'MISSING_CONTEXT',
+        fields: fields.length > 0 ? fields : ['conversation.audienceId', 'actor.capabilities'],
+        correlationId,
+      },
+    };
+  }
+
+  // Ambiguity check: if legacy input specifies role without correlationId or endpoint context for stateful op
+  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,
+      },
+    };
+  }
+
+  // Missing correlationId for stateful requests
+  const finalCorrelationId = correlationId || (input.generateCorrelationId ? `corr-${Date.now()}` : undefined);
+  if (!finalCorrelationId) {
+    return {
+      accepted: false,
+      error: {
+        code: 'MISSING_CONTEXT',
+        fields: ['conversation.correlationId'],
+      },
+    };
+  }
+
+  // Build anonymous public context
+  const actorId = input.actorId || input.actor?.actorId || 'anonymous-session-a';
+  const sessionId = input.sessionId || input.actor?.sessionId || 'session-a';
+  if (!input.actorId && !input.actor?.actorId) {
+    diagnostics.push('anonymous_session_generated');
+  }
+
+  const channel: Channel = 'public';
+  const audienceId = defaultPublicAudience;
+  diagnostics.push('audience_defaulted_by_public_policy');
+
+  const capabilities = authRole === 'administrator'
+    ? ['chat:public', 'admin:access']
+    : authRole === 'operator'
+    ? ['chat:public', 'operator:access']
+    : ['chat:public'];
+
+  const mappedContext: RequestContext = {
+    companionId,
+    actor: {
+      actorId,
+      sessionId,
+      authorizationRole: authRole,
+      capabilities,
+      authenticated: Boolean(input.authenticated),
+    },
+    conversation: {
+      channel,
+      audienceId,
+      correlationId: finalCorrelationId,
+    },
+    subject: undefined, // Anonymous public chat has no subject
+  };
+
+  return {
+    accepted: true,
+    context: mappedContext,
+    diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,129 @@
+import request from 'supertest';
+import { createApp } from './app';
+
+describe('API Boundary Context Validation (P2 Route Integration)', () => {
+  const fakeRuntime: any = {
+    handleUserMessage: jest.fn().mockResolvedValue({
+      response: { subtitle_en: 'Hello there' },
+      metadata: {},
+    }),
+  };
+
+  let app: any;
+  let runtimes: Map<string, any>;
+
+  beforeEach(() => {
+    runtimes = new Map([['companion-a', fakeRuntime]]);
+    const created = createApp(runtimes);
+    app = created.app;
+    fakeRuntime.handleUserMessage.mockClear();
+  });
+
+  test('accepts valid anonymous chat request and maps through API boundary', async () => {
+    const res = await request(app)
+      .post('/chat')
+      .send({
+        id: 'companion-a',
+        message: 'Hello neutral world',
+        history: [],
+      });
+
+    expect(res.status).toBe(200);
+    expect(fakeRuntime.handleUserMessage).toHaveBeenCalledWith(
+      'Hello neutral world',
+      'VIEWER',
+      []
+    );
+  });
+
+  test('accepts neutral context chat envelope at /chat route', async () => {
+    const res = await request(app)
+      .post('/chat')
+      .send({
+        companionId: 'companion-a',
+        context: {
+          actor: {
+            actorId: 'actor-a',
+            sessionId: 'session-a',
+            authorizationRole: 'viewer',
+            capabilities: ['chat:public'],
+            authenticated: false,
+          },
+          conversation: {
+            channel: 'public',
+            audienceId: 'audience-public',
+            correlationId: 'corr-route-1',
+          },
+        },
+        message: 'Hello structured context',
+        history: [],
+      });
+
+    expect(res.status).toBe(200);
+    expect(fakeRuntime.handleUserMessage).toHaveBeenCalledWith(
+      'Hello structured context',
+      'VIEWER',
+      []
+    );
+  });
+
+  test('rejects MASTER_PRIVATE in public request with 400 and structured error', async () => {
+    const res = await request(app)
+      .post('/chat')
+      .send({
+        companionId: 'companion-a',
+        context: {
+          actor: {
+            actorId: 'actor-a',
+            sessionId: 'session-a',
+            authorizationRole: 'viewer',
+            capabilities: ['chat:public'],
+            authenticated: false,
+          },
+          conversation: {
+            channel: 'public',
+            audienceId: 'MASTER_PRIVATE',
+            correlationId: 'corr-err-1',
+          },
+        },
+        message: 'Forbidden audience test',
+      });
+
+    expect(res.status).toBe(400);
+    expect(res.body.accepted).toBe(false);
+    expect(res.body.error.code).toBe('LEGACY_PERSONAL_AUDIENCE');
+    expect(fakeRuntime.handleUserMessage).not.toHaveBeenCalled();
+  });
+
+  test('rejects global primary_user subject with 400 and structured error', async () => {
+    const res = await request(app)
+      .post('/chat')
+      .send({
+        companionId: 'companion-a',
+        context: {
+          actor: {
+            actorId: 'actor-a',
+            sessionId: 'session-a',
+            authorizationRole: 'viewer',
+            capabilities: ['chat:public'],
+            authenticated: true,
+          },
+          conversation: {
+            channel: 'public',
+            audienceId: 'audience-public',
+            correlationId: 'corr-err-2',
+          },
+          subject: {
+            subjectId: 'primary_user',
+            kind: 'actor',
+          },
+        },
+        message: 'Forbidden primary user test',
+      });
+
+    expect(res.status).toBe(400);
+    expect(res.body.accepted).toBe(false);
+    expect(res.body.error.code).toBe('FORBIDDEN_CONTEXT');
+    expect(fakeRuntime.handleUserMessage).not.toHaveBeenCalled();
+  });
+});

package/src/index.ts

@@ -0,0 +1,161 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { Express } from 'express';
+import { createApp, AppInstance } from './app';
+import { SiduriRuntime } from './runtime';
+import { OpenAICompatibleBrain, OpenRouterBrain } from '@siduri-x/brain';
+import { PostgresMemoryOrgan } from '@siduri-x/memory';
+import { VoicevoxAdapter } from '@siduri-x/voice';
+import { EKnowledgeAdapter } from '@siduri-x/knowledge';
+import { OpenRouterVisionAdapter } from '@siduri-x/vision';
+import { ActiveSelfCompiler } from '@siduri-x/behavior';
+import { Live2DAdapter } from '@siduri-x/body';
+import { FixtureObservationOrgan } from '@siduri-x/observation';
+
+export { createApp, AppInstance };
+export * from './context-mapper';
+
+const runtimes = new Map<string, SiduriRuntime>();
+const instance: AppInstance = createApp(runtimes);
+export const app: Express = instance.app;
+export default app;
+
+function createBrain(config: any) {
+  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' });
+}
+
+function isDisabled(config: any): boolean {
+  return !config || config.provider === 'none';
+}
+
+function createVoice(config: any) {
+  return isDisabled(config)
+    ? undefined
+    : new VoicevoxAdapter({ baseUrl: process.env.VOICEVOX_URL || 'http://localhost:50021', speakerId: config.speakerId || 1 });
+}
+
+function createKnowledge(config: any) {
+  if (isDisabled(config)) return undefined;
+  if (!config?.packPath && !config?.registryUrl && !config?.baseUrl && !config?.hubUrl) {
+    return undefined;
+  }
+  return new EKnowledgeAdapter(config);
+}
+
+function createVision(config: any) {
+  return isDisabled(config)
+    ? undefined
+    : new OpenRouterVisionAdapter({ apiKey: process.env.OPENROUTER_API_KEY || '', model: config.model || 'gpt-4-vision' });
+}
+
+function createBehavior(config: any) {
+  return isDisabled(config) ? undefined : new ActiveSelfCompiler();
+}
+
+function createBody(config: any) {
+  return isDisabled(config)
+    ? undefined
+    : new Live2DAdapter(config);
+}
+
+const PORT = process.env.PORT || 3001;
+
+const defaultCompanionConfig = {
+  id: 'default',
+  name: 'Siduri',
+  brain: { provider: 'openrouter', model: 'gpt-4o-mini' },
+  voice: { provider: 'voicevox', speakerId: 1 },
+  memory: { provider: 'postgres' },
+  knowledge: {
+    provider: (process.env.SIDURI_KNOWLEDGE_PROVIDER as 'e-knowledge' | 'e-remote' | 'e-hub') || 'e-knowledge',
+    packPath: process.env.SIDURI_KNOWLEDGE_PACK || '',
+    registryUrl: process.env.SIDURI_KNOWLEDGE_REGISTRY_URL || '',
+    packId: process.env.SIDURI_KNOWLEDGE_PACK_ID || '',
+    timeoutMs: Number(process.env.SIDURI_KNOWLEDGE_TIMEOUT_MS || 5000),
+    preferredMode: (process.env.SIDURI_KNOWLEDGE_MODE as 'lexical' | 'semantic' | 'hybrid') || 'lexical',
+  },
+  behavior: { provider: 'active_self' },
+  body: {
+    provider: 'live2d',
+  },
+  vision: { provider: 'openrouter', model: 'gpt-4-vision' }
+};
+
+async function loadCompanionConfig() {
+  const configPath = process.env.SIDURI_CONFIG || path.resolve(process.cwd(), 'siduri.config.json');
+  let fileConfig: Record<string, any> = {};
+  try {
+    fileConfig = JSON.parse(await readFile(configPath, 'utf8')) as Record<string, any>;
+    console.log(`Loaded companion configuration from ${configPath}`);
+  } catch (error: any) {
+    if (error?.code !== 'ENOENT') throw new Error(`Unable to read ${configPath}: ${error.message}`);
+    console.log(`No ${configPath} found; using environment/default configuration.`);
+  }
+
+  const config: any = {
+    ...defaultCompanionConfig,
+    ...fileConfig,
+    id: fileConfig.id || defaultCompanionConfig.id,
+    brain: { ...defaultCompanionConfig.brain, ...fileConfig.brain },
+    voice: { ...defaultCompanionConfig.voice, ...fileConfig.voice },
+    memory: { ...defaultCompanionConfig.memory, ...fileConfig.memory },
+    knowledge: { ...defaultCompanionConfig.knowledge, ...fileConfig.knowledge },
+    behavior: { ...defaultCompanionConfig.behavior, ...fileConfig.behavior },
+    body: { ...defaultCompanionConfig.body, ...fileConfig.body },
+    vision: { ...defaultCompanionConfig.vision, ...fileConfig.vision },
+  };
+
+  if (process.env.SIDURI_KNOWLEDGE_PROVIDER) config.knowledge.provider = process.env.SIDURI_KNOWLEDGE_PROVIDER;
+  if (process.env.SIDURI_KNOWLEDGE_PACK) config.knowledge.packPath = process.env.SIDURI_KNOWLEDGE_PACK;
+  if (process.env.SIDURI_KNOWLEDGE_REGISTRY_URL) config.knowledge.registryUrl = process.env.SIDURI_KNOWLEDGE_REGISTRY_URL;
+  if (process.env.SIDURI_KNOWLEDGE_PACK_ID) config.knowledge.packId = process.env.SIDURI_KNOWLEDGE_PACK_ID;
+  if (process.env.SIDURI_KNOWLEDGE_MODE) config.knowledge.preferredMode = process.env.SIDURI_KNOWLEDGE_MODE;
+  return config;
+}
+
+async function bootDefaultCompanion() {
+  if (runtimes.has('default')) return;
+  console.log("Booting default companion...");
+  const config: any = await loadCompanionConfig();
+  
+  const brain = createBrain(config.brain);
+  const memory = new PostgresMemoryOrgan({ connectionString: process.env.DATABASE_URL || 'postgresql://postgres:postgres@localhost:5432/siduri' });
+  const voice = createVoice(config.voice);
+  const knowledge = createKnowledge(config.knowledge);
+  const vision = createVision(config.vision);
+  const observation = new FixtureObservationOrgan(
+    vision ?? { analyze: async () => JSON.stringify({ readings: [] }) },
+  );
+  instance.setObservationOrgan(observation);
+  const behavior = createBehavior(config.behavior);
+  const body = createBody(config.body);
+
+  await memory.runMigrations().catch(e => console.warn("Migrations warning:", e.message));
+
+  const runtime = new SiduriRuntime('default', config as any, { brain, memory, voice, knowledge, vision, behavior, body });
+  await runtime.initialize();
+
+  runtimes.set('default', runtime);
+  console.log("Default companion booted successfully.");
+}
+
+if (process.env.NODE_ENV !== 'test') {
+  bootDefaultCompanion().then(() => {
+    app.listen(PORT, () => {
+      console.log(`Siduri-Y API running on port ${PORT}`);
+    });
+  }).catch(e => {
+    console.error("Failed to boot default companion:", e);
+    process.exit(1);
+  });
+}