@siduri-x/api 1.0.2 → 1.0.4

package/dist/index.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.app = exports.createApp = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const app_1 = require("./app");
+Object.defineProperty(exports, "createApp", { enumerable: true, get: function () { return app_1.createApp; } });
+const runtime_1 = require("./runtime");
+const brain_1 = require("@siduri-x/brain");
+const memory_1 = require("@siduri-x/memory");
+const voice_1 = require("@siduri-x/voice");
+const knowledge_1 = require("@siduri-x/knowledge");
+const vision_1 = require("@siduri-x/vision");
+const behavior_1 = require("@siduri-x/behavior");
+const body_1 = require("@siduri-x/body");
+const observation_1 = require("@siduri-x/observation");
+__exportStar(require("./context-mapper"), exports);
+const runtimes = new Map();
+const instance = (0, app_1.createApp)(runtimes);
+exports.app = instance.app;
+exports.default = exports.app;
+function createBrain(config) {
+    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 brain_1.OpenAICompatibleBrain({
+            apiKey,
+            model: config?.model || 'local-model',
+            baseUrl: config?.baseUrl || 'http://127.0.0.1:1234/v1',
+        });
+    }
+    return new brain_1.OpenRouterBrain({ apiKey, model: config?.model || 'gpt-4o-mini' });
+}
+function isDisabled(config) {
+    return !config || config.provider === 'none';
+}
+function createVoice(config) {
+    return isDisabled(config)
+        ? undefined
+        : new voice_1.VoiceAdapter({
+            provider: config?.provider || 'voicevox',
+            baseUrl: config?.baseUrl || process.env.VOICEVOX_URL || 'http://localhost:50021',
+            speakerId: config?.speakerId || 1,
+            ...config,
+        });
+}
+function createKnowledge(config) {
+    if (isDisabled(config))
+        return undefined;
+    if (!config?.packPath && !config?.registryUrl && !config?.baseUrl) {
+        return undefined;
+    }
+    return new knowledge_1.EKnowledgeAdapter(config || {});
+}
+function createVision(config) {
+    return isDisabled(config)
+        ? undefined
+        : new vision_1.OpenRouterVisionAdapter({
+            apiKey: config?.apiKey || process.env.OPENROUTER_API_KEY || '',
+            model: config?.model || 'gpt-4-vision',
+            ...config,
+        });
+}
+function createBehavior(config) {
+    return isDisabled(config) ? undefined : new behavior_1.ActiveSelfCompiler();
+}
+function createBody(config) {
+    return isDisabled(config)
+        ? undefined
+        : new body_1.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 || '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 || 'lexical',
+    },
+    behavior: { provider: 'active_self' },
+    body: {
+        provider: 'live2d',
+    },
+    vision: { provider: 'openrouter', model: 'gpt-4-vision' }
+};
+async function loadCompanionConfig() {
+    const configPath = process.env.SIDURI_CONFIG || node_path_1.default.resolve(process.cwd(), 'siduri.config.json');
+    let fileConfig = {};
+    try {
+        fileConfig = JSON.parse(await (0, promises_1.readFile)(configPath, 'utf8'));
+        console.log(`Loaded companion configuration from ${configPath}`);
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw new Error(`Unable to read ${configPath}: ${error.message}`);
+        console.log(`No ${configPath} found; using environment/default configuration.`);
+    }
+    const config = {
+        ...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 = await loadCompanionConfig();
+    const brain = createBrain(config.brain);
+    const memory = new memory_1.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 observation_1.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 runtime_1.SiduriRuntime('default', config, { 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(() => {
+        exports.app.listen(Number(PORT), '127.0.0.1', () => {
+            console.log(`Siduri-X API running on port ${PORT} (127.0.0.1)`);
+        });
+    }).catch(e => {
+        console.error("Failed to boot default companion:", e);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "@siduri-x/api",
-  "version": "1.0.2",
+  "version": "1.0.4",
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "dist/index.js",
   "dependencies": {
-    "@siduri-x/behavior": "1.0.5",
+    "@siduri-x/behavior": "1.0.6",
     "@siduri-x/body": "1.0.4",
-    "@siduri-x/brain": "1.0.4",
-    "@siduri-x/core": "1.0.5",
+    "@siduri-x/brain": "1.0.5",
+    "@siduri-x/core": "1.0.8",
     "@siduri-x/ear": "1.0.3",
     "@siduri-x/hands": "1.0.3",
     "@siduri-x/knowledge": "1.0.2",
-    "@siduri-x/memory": "1.0.4",
-    "@siduri-x/observation": "1.0.2",
+    "@siduri-x/memory": "1.0.6",
+    "@siduri-x/observation": "1.0.3",
     "@siduri-x/vision": "1.0.2",
     "@siduri-x/voice": "1.0.6",
     "@siduri-x/mouth": "1.0.0",

package/src/app.ts

@@ -13,7 +13,7 @@ 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 { attachIdentity, requireRole, Identity } from './auth';
+import { attachIdentity, requireAuth, Identity } from './auth';
 import { mapRequestContext } from './context-mapper';
 
 export interface AppBrainConfig {
@@ -130,7 +130,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
       : new DefaultMouthOrgan({ ...config, voice });
   }
 
-  app.post('/boot', requireRole(['OWNER']), async (req, res) => {
+  app.post('/boot', requireAuth, async (req, res) => {
     try {
       const { id, config } = req.body;
       if (runtimes.has(id)) {
@@ -204,39 +204,26 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
   app.get('/me', attachIdentity, (req, res) => {
     const identity = (req as any).identity as Identity;
     res.json({
-      actorId: identity.role === 'OWNER' ? 'owner-user' : 'anonymous-session',
-      role: identity.role,
-      authenticated: identity.role === 'OWNER',
+      actorId: identity.actorId || (identity.authenticated ? 'owner-user' : 'anonymous-session'),
+      role: identity.role || (identity.authenticated ? 'OWNER' : 'VIEWER'),
+      authenticated: Boolean(identity.authenticated),
     });
   });
-  app.put('/me', requireRole(['OWNER']), (req, res) => res.json({ success: true }));
+  app.put('/me', requireAuth, (req, res) => res.json({ success: true }));
 
   // CHAT (API context boundary validation)
   app.post('/chat', attachIdentity, async (req, res) => {
     const { id, message, history } = req.body;
     const identity = (req as any).identity as Identity;
 
-    // Single-owner companion model: /chat defaults to OWNER identity.
-    // Explicit non-owner role in request body or context (e.g. adversarial test suites) is respected.
-    const effectiveRole = req.body?.role === 'VIEWER' || req.body?.context?.actor?.authorizationRole === 'viewer'
-      ? 'VIEWER'
-      : (identity?.role === 'OPERATOR' ? 'OPERATOR' : 'OWNER');
-    const isOwner = effectiveRole === 'OWNER';
-
-    // Call context mapper at the API boundary
-    const mappingResult = mapRequestContext(
-      {
-        ...req.body,
-        id: id || req.body.companionId,
-        role: effectiveRole,
-        authenticated: isOwner,
-        generateCorrelationId: true,
-      },
-      {
-        endpointPolicy: 'public',
-        defaultPublicAudience: 'audience-public',
-      }
-    );
+    // Single-owner companion model: map request context directly
+    const mappingResult = mapRequestContext({
+      ...req.body,
+      id: id || req.body.companionId,
+      authenticated: identity?.authenticated ?? true,
+      source: identity?.source ?? 'local',
+      generateCorrelationId: true,
+    });
 
     if (!mappingResult.accepted) {
       return res.status(400).json({
@@ -269,24 +256,13 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     const { id, message, history } = req.body;
     const identity = (req as any).identity as Identity;
 
-    const effectiveRole = req.body?.role === 'VIEWER' || req.body?.context?.actor?.authorizationRole === 'viewer'
-      ? 'VIEWER'
-      : (identity?.role === 'OPERATOR' ? 'OPERATOR' : 'OWNER');
-    const isOwner = effectiveRole === 'OWNER';
-
-    const mappingResult = mapRequestContext(
-      {
-        ...req.body,
-        id: id || req.body.companionId,
-        role: effectiveRole,
-        authenticated: isOwner,
-        generateCorrelationId: true,
-      },
-      {
-        endpointPolicy: 'public',
-        defaultPublicAudience: 'audience-public',
-      }
-    );
+    const mappingResult = mapRequestContext({
+      ...req.body,
+      id: id || req.body.companionId,
+      authenticated: identity?.authenticated ?? true,
+      source: identity?.source ?? 'local',
+      generateCorrelationId: true,
+    });
 
     if (!mappingResult.accepted) {
       return res.status(400).json({
@@ -406,7 +382,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
   });
 
   // MEMORY GETTERS
-  app.get('/memory/proposals', requireRole(['OWNER', 'OPERATOR']), async (req, res) => {
+  app.get('/memory/proposals', requireAuth, async (req, res) => {
     const id = req.query.id as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -419,7 +395,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
-  app.get('/memory', requireRole(['OWNER', 'OPERATOR']), async (req, res) => {
+  app.get('/memory', requireAuth, async (req, res) => {
     const id = req.query.id as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -432,7 +408,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
-  app.get('/memory/claims', requireRole(['OWNER', 'OPERATOR']), async (req, res) => {
+  app.get('/memory/claims', requireAuth, async (req, res) => {
     const id = req.query.id as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -445,7 +421,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
-  app.get('/memory/behavioral', requireRole(['OWNER', 'OPERATOR']), async (req, res) => {
+  app.get('/memory/behavioral', requireAuth, async (req, res) => {
     const id = req.query.id as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -459,7 +435,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
   });
 
   // MEMORY MUTATIONS - PROPOSALS
-  app.post('/memory/proposals/update', requireRole(['OWNER', 'OPERATOR']), async (req, res) => {
+  app.post('/memory/proposals/update', requireAuth, async (req, res) => {
     const id = req.body.companionId as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -478,7 +454,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
-  app.post('/memory/proposals/approve', requireRole(['OWNER', 'OPERATOR']), async (req, res) => {
+  app.post('/memory/proposals/approve', requireAuth, async (req, res) => {
     const id = req.body.companionId as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -491,7 +467,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
-  app.post('/memory/proposals/reject', requireRole(['OWNER', 'OPERATOR']), async (req, res) => {
+  app.post('/memory/proposals/reject', requireAuth, async (req, res) => {
     const id = req.body.companionId as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -505,7 +481,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
   });
 
   // MEMORY MUTATIONS - BEHAVIORAL
-  app.post('/memory/behavioral/approve', requireRole(['OWNER']), async (req, res) => {
+  app.post('/memory/behavioral/approve', requireAuth, async (req, res) => {
     const id = req.body.companionId as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -518,7 +494,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
-  app.post('/memory/behavioral/reject', requireRole(['OWNER']), async (req, res) => {
+  app.post('/memory/behavioral/reject', requireAuth, async (req, res) => {
     const id = req.body.companionId as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -531,7 +507,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
-  app.post('/memory/behavioral/revoke', requireRole(['OWNER']), async (req, res) => {
+  app.post('/memory/behavioral/revoke', requireAuth, async (req, res) => {
     const id = req.body.companionId as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -544,7 +520,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
-  app.post('/memory/behavioral/disable', requireRole(['OWNER']), async (req, res) => {
+  app.post('/memory/behavioral/disable', requireAuth, async (req, res) => {
     const id = req.body.companionId as string || Array.from(runtimes.keys())[0];
     const runtime = runtimes.get(id);
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -559,7 +535,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
 
   const isDevMode = process.env.NODE_ENV !== 'production' || process.env.SIDURI_DEV_MODE === 'true';
   if (isDevMode) {
-    app.post('/dev/memory/reset', requireRole(['OWNER']), async (req, res) => {
+    app.post('/dev/memory/reset', requireAuth, async (req, res) => {
       const id = req.body.companionId as string || Array.from(runtimes.keys())[0];
       const runtime = runtimes.get(id);
       if (!runtime) return res.status(404).json({ error: "Companion not found" });
@@ -582,15 +558,12 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
         requestContext: {
           companionId,
           actor: {
-            actorId: 'operator-a',
-            sessionId: 'sess-op',
-            authorizationRole: 'operator',
-            capabilities: ['chat:public', 'memory:approve'],
+            actorId: 'local-user',
+            sessionId: 'sess-local',
+            capabilities: ['chat', 'memory:approve'],
             authenticated: true,
           },
           conversation: {
-            channel: 'public',
-            audienceId: 'audience-public',
             correlationId: req.body?.correlation_id || `corr-${Date.now()}`,
           },
         },
@@ -636,7 +609,6 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
         responseId,
         companionId,
         correlationId: correlationId || '',
-        audienceId: req.body?.audienceId,
       });
 
       if (!result.success) {

package/src/auth.test.ts

@@ -1,6 +1,6 @@
-import { resolveIdentity } from './auth';
+import { resolveIdentity, requireAuth } from './auth';
 
-describe('Auth Identity Resolution', () => {
+describe('Auth Identity Resolution (Single-Owner External Boundary)', () => {
   const originalEnv = process.env;
 
   beforeEach(() => {
@@ -12,46 +12,79 @@ describe('Auth Identity Resolution', () => {
     process.env = originalEnv;
   });
 
-  const mockReq = (token?: string) => ({
+  const mockReq = (token?: string, ip: string = '192.168.1.50') => ({
     headers: {
-      authorization: token ? `Bearer ${token}` : undefined
-    }
+      authorization: token ? `Bearer ${token}` : undefined,
+    },
+    ip,
+    socket: { remoteAddress: ip },
   } as any);
 
-  test('resolves explicit owner token', () => {
-    process.env.OWNER_TOKEN = 'owner-secret';
-    process.env.OPERATOR_TOKEN = 'operator-secret';
+  test('authenticates external request when token matches configured AUTH_TOKEN', () => {
+    process.env.AUTH_TOKEN = 'secret-auth-key';
     process.env.NODE_ENV = 'production';
 
-    const ownerId = resolveIdentity(mockReq('owner-secret'));
-    expect(ownerId.role).toBe('OWNER');
+    const identity = resolveIdentity(mockReq('secret-auth-key'));
+    expect(identity.authenticated).toBe(true);
+    expect(identity.source).toBe('external');
   });
 
-  test('resolves explicit operator token', () => {
+  test('authenticates external request when token matches legacy OWNER_TOKEN', () => {
     process.env.OWNER_TOKEN = 'owner-secret';
-    process.env.OPERATOR_TOKEN = 'operator-secret';
     process.env.NODE_ENV = 'production';
 
-    const opId = resolveIdentity(mockReq('operator-secret'));
-    expect(opId.role).toBe('OPERATOR');
+    const identity = resolveIdentity(mockReq('owner-secret'));
+    expect(identity.authenticated).toBe(true);
+    expect(identity.source).toBe('external');
   });
 
-  test('defaults to viewer when no token is present in production', () => {
+  test('rejects external request when token is missing in production with configured token', () => {
+    process.env.AUTH_TOKEN = 'secret-auth-key';
     process.env.NODE_ENV = 'production';
-    const viewerId = resolveIdentity(mockReq());
-    expect(viewerId.role).toBe('VIEWER');
+
+    const identity = resolveIdentity(mockReq());
+    expect(identity.authenticated).toBe(false);
   });
 
-  test('defaults to viewer for invalid token in production', () => {
+  test('rejects external request for invalid token in production', () => {
+    process.env.AUTH_TOKEN = 'secret-auth-key';
     process.env.NODE_ENV = 'production';
-    const invalidId = resolveIdentity(mockReq('invalid-token'));
-    expect(invalidId.role).toBe('VIEWER');
+
+    const identity = resolveIdentity(mockReq('invalid-token'));
+    expect(identity.authenticated).toBe(false);
   });
 
-  test('resolves development fallback role', () => {
+  test('authenticates local loopback request in development mode', () => {
     process.env.NODE_ENV = 'development';
     process.env.DEV_LOCAL_AUTH_ROLE = 'OWNER';
-    const devId = resolveIdentity(mockReq());
-    expect(devId.role).toBe('OWNER');
+    process.env.AUTH_TOKEN = 'secret-key';
+
+    const devIdentity = resolveIdentity(mockReq(undefined, '127.0.0.1'));
+    expect(devIdentity.authenticated).toBe(true);
+    expect(devIdentity.source).toBe('local');
+  });
+
+  test('requireAuth middleware accepts authenticated request and rejects unauthenticated with 401', () => {
+    process.env.AUTH_TOKEN = 'secret-key';
+    process.env.NODE_ENV = 'production';
+
+    const nextFn = jest.fn();
+    const resUnauthorized = {
+      status: jest.fn().mockReturnThis(),
+      json: jest.fn().mockReturnThis(),
+    } as any;
+
+    // Unauthorized call
+    requireAuth(mockReq('wrong-token'), resUnauthorized, nextFn);
+    expect(resUnauthorized.status).toHaveBeenCalledWith(401);
+    expect(nextFn).not.toHaveBeenCalled();
+
+    // Authorized call
+    const resAuthorized = {
+      status: jest.fn().mockReturnThis(),
+      json: jest.fn().mockReturnThis(),
+    } as any;
+    requireAuth(mockReq('secret-key'), resAuthorized, nextFn);
+    expect(nextFn).toHaveBeenCalled();
   });
 });

package/src/auth.ts

@@ -1,49 +1,101 @@
 import { Request, Response, NextFunction } from 'express';
 
-export type Role = 'OWNER' | 'OPERATOR' | 'VIEWER';
+export type Role = 'OWNER' | 'OPERATOR' | 'VIEWER' | 'user' | string;
 
 export interface Identity {
-  role: Role;
+  authenticated: boolean;
+  source: 'local' | 'external';
+  actorId?: string;
+  role?: Role;
+  [key: string]: unknown;
 }
 
+/**
+ * Checks whether an incoming request originates from the local machine loopback interface.
+ */
+export function isLocalRequest(req: Request): boolean {
+  const ip = req.ip || req.socket?.remoteAddress || '';
+  return (
+    ip === '127.0.0.1' ||
+    ip === '::1' ||
+    ip === '::ffff:127.0.0.1' ||
+    ip.endsWith('127.0.0.1') ||
+    ip === 'localhost'
+  );
+}
+
+/**
+ * Resolves request identity according to the single-owner external machine boundary security model.
+ * 
+ * - Security is enforced at the external machine boundary, NOT internally.
+ * - External network requests require a matching token (AUTH_TOKEN / OWNER_TOKEN).
+ * - There are no internal viewer/operator/owner role privileges inside the machine.
+ */
 export function resolveIdentity(req: Request): Identity {
-  const authHeader = req.headers.authorization;
+  const authHeader = req.headers?.authorization;
   const token = authHeader?.startsWith('Bearer ') ? authHeader.split(' ')[1] : undefined;
+  const ownerToken = process.env.AUTH_TOKEN || process.env.API_TOKEN || process.env.OWNER_TOKEN;
+  const operatorToken = process.env.OPERATOR_TOKEN;
+  const configuredToken = ownerToken || operatorToken;
+
+  const local = isLocalRequest(req);
 
   // 1. Explicit token matches
-  if (process.env.OWNER_TOKEN && token === process.env.OWNER_TOKEN) {
-    return { role: 'OWNER' };
+  if (ownerToken && token === ownerToken) {
+    return { authenticated: true, source: local ? 'local' : 'external', role: 'OWNER' };
   }
-  if (process.env.OPERATOR_TOKEN && token === process.env.OPERATOR_TOKEN) {
-    return { role: 'OPERATOR' };
+  if (operatorToken && token === operatorToken) {
+    return { authenticated: true, source: local ? 'local' : 'external', role: 'OPERATOR' };
   }
 
-  // 2. Development fallback
+  // 2. Dev local auth role fallback
   const isDev = process.env.NODE_ENV !== 'production';
   if (isDev && process.env.DEV_LOCAL_AUTH_ROLE) {
     const fallbackRole = process.env.DEV_LOCAL_AUTH_ROLE.toUpperCase() as Role;
-    if (['OWNER', 'OPERATOR', 'VIEWER'].includes(fallbackRole)) {
-      return { role: fallbackRole };
-    }
+    return {
+      authenticated: fallbackRole === 'OWNER' || fallbackRole === 'OPERATOR',
+      source: 'local',
+      role: fallbackRole,
+    };
+  }
+
+  // 3. Default unauthenticated / visitor
+  return { authenticated: false, source: local ? 'local' : 'external', role: 'VIEWER' };
+}
+
+/**
+ * External boundary authentication middleware.
+ * Verifies that requests crossing the external boundary are authorized.
+ */
+export function requireAuth(req: Request, res: Response, next: NextFunction) {
+  const identity = resolveIdentity(req);
+  (req as any).identity = identity;
+
+  if (!identity.authenticated) {
+    return res.status(401).json({ error: 'Unauthorized: missing or invalid authentication token' });
   }
+  next();
+}
 
-  // Default
-  return { role: 'VIEWER' };
+/**
+ * Attaches the resolved machine identity to the request.
+ */
+export function attachIdentity(req: Request, res: Response, next: NextFunction) {
+  (req as any).identity = resolveIdentity(req);
+  next();
 }
 
-export function requireRole(allowedRoles: Role[]) {
+/**
+ * Compatibility alias: in single-owner model, all authenticated callers have full access.
+ */
+export function requireRole(allowedRoles?: Role[]) {
   return (req: Request, res: Response, next: NextFunction) => {
     const identity = resolveIdentity(req);
     (req as any).identity = identity;
-    
-    if (!allowedRoles.includes(identity.role)) {
-      return res.status(403).json({ error: `Forbidden: requires one of ${allowedRoles.join(', ')}` });
+
+    if (!identity.authenticated) {
+      return res.status(403).json({ error: `Forbidden: requires one of ${(allowedRoles || []).join(', ')}` });
     }
     next();
   };
 }
-
-export function attachIdentity(req: Request, res: Response, next: NextFunction) {
-  (req as any).identity = resolveIdentity(req);
-  next();
-}