@animalabs/connectome-host 0.7.2 → 0.7.4

package/src/modules/identity-module.ts

@@ -0,0 +1,274 @@
+/**
+ * Agent identity — the agent's own archipelago-home principal (connectome
+ * docs/home-node.md §4).
+ *
+ * Two audiences, deliberately separated:
+ *
+ * HOST-FACING (this module's public methods): the deployment holds an
+ * ed25519 keypair in the data dir; `accessFor(audience)` exchanges a
+ * key-proof at the home node for a short-lived aid1 token, and
+ * `httpAuthFor(audience)` wraps it for HTTP. This is plumbing other host
+ * pieces call — the MCPL transport's per-dial credential provider, future
+ * HTTP helpers. Credentials live and die HERE.
+ *
+ * AGENT-FACING (utilities, via the `utils` meta-tool): deliberately small
+ * and deliberately boring — `status` ("who am I registered as, where is
+ * that recognized") and `accept_invite` ("register with an invitation code
+ * from your operator"). No tokens, keys, proofs, or signing in any
+ * agent-visible name, description, or result: the agent asks for access by
+ * name (`mcpl_deploy … access: "eidoverse"`); the host does the rest. This
+ * is both hygiene (credentials never enter model context, so they never
+ * enter chronicles, compression, or channels) and framing (an agent
+ * narrating credential mechanics reads as exfiltration to safety
+ * classifiers — so it simply never has them to narrate).
+ *
+ * Utilities-only module: enrollment is one-time; it costs no tool slots.
+ * Wire statements per the home-node spec (archipelago-home
+ * src/statements.ts is the source of truth — re-copy, don't fork).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign as cryptoSign,
+  type KeyObject,
+} from 'node:crypto';
+import type {
+  Module,
+  ModuleContext,
+  ToolCall,
+  ToolResult,
+  ToolDefinition,
+} from '@animalabs/agent-framework';
+
+export interface IdentityModuleConfig {
+  /** ed25519 PKCS#8 PEM, generated on first use, 0600. dataDir-anchored:
+   *  identity is per-deployment, not per-session. */
+  keyPath: string;
+  /** Home node domain (the trust anchor), e.g. `id.animalabs.ai`. */
+  home: string;
+  /** Audience assumed when none is named. */
+  defaultAudience?: string;
+  /** Injectable for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+/** Persisted beside the key after a successful registration. */
+interface IdentityRecord {
+  sub: string;
+  name: string;
+  home: string;
+  enrolledAt: string;
+}
+
+function ok(data: unknown): ToolResult {
+  return { success: true, data };
+}
+function fail(text: string): ToolResult {
+  return { success: false, error: text, isError: true };
+}
+
+export class IdentityModule implements Module {
+  readonly name = 'identity';
+  private readonly recordPath: string;
+
+  constructor(private readonly config: IdentityModuleConfig) {
+    this.recordPath = config.keyPath.replace(/\.pem$/, '') + '.json';
+  }
+
+  async start(_ctx: ModuleContext): Promise<void> {}
+  async stop(): Promise<void> {}
+
+  getTools(): ToolDefinition[] {
+    return []; // utilities-only, by design — see module header
+  }
+
+  getUtilities(): ToolDefinition[] {
+    return [
+      {
+        name: 'status',
+        description:
+          'Your registered identity: the name and id services know you by, and which ' +
+          'identity service vouches for it. Access to networked places (worlds etc.) is ' +
+          'managed by the host from this — you never handle credentials yourself.',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        name: 'accept_invite',
+        description:
+          'Register with the identity service using an invitation code from your operator. ' +
+          'One-time: it establishes the name services will know you by. After this, the ' +
+          'host handles access automatically (e.g. mcpl_deploy with an `access` name).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            invite: { type: 'string', description: 'Invitation code from your operator.' },
+            name: { type: 'string', description: 'The display name you want (must be unused).' },
+          },
+          required: ['invite', 'name'],
+        },
+      },
+    ];
+  }
+
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+    try {
+      switch (call.name) {
+        case 'status':
+          return this.status();
+        case 'accept_invite':
+          return await this.acceptInvite(call.input as { invite?: unknown; name?: unknown });
+        default:
+          return fail(`Unknown identity utility: ${call.name}`);
+      }
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async onProcess(): Promise<Record<string, never>> {
+    return {};
+  }
+
+  // ────────────────────────────────────────────────────────────────────────
+  // Host-facing API — credential plumbing. Nothing below ever reaches model
+  // context; callers (MCPL dial provider, HTTP helpers) consume the values
+  // outside the agent's view.
+  // ────────────────────────────────────────────────────────────────────────
+
+  /** True once this deployment holds a registered principal. */
+  isEnrolled(): boolean {
+    return this.record() !== null;
+  }
+
+  /** The registered principal id (`agent:<name>@<domain>`), if any. */
+  sub(): string | null {
+    return this.record()?.sub ?? null;
+  }
+
+  /**
+   * Exchange a key-proof for a fresh aid1 token for `audience`. Called per
+   * MCPL dial (connect + every reconnect) and by HTTP helpers — which is
+   * what lets audience tokens be short-lived. Throws with an actionable
+   * message when unregistered or refused.
+   */
+  async accessFor(audience?: string): Promise<string> {
+    const aud = audience ?? this.config.defaultAudience;
+    if (!aud) throw new Error('identity: no audience named and none configured');
+    if (!this.record()) {
+      throw new Error(
+        `identity: not registered with ${this.config.home} — the agent needs to accept an operator invite first (utils run identity--accept_invite)`,
+      );
+    }
+    const key = this.loadOrCreateKey();
+    const timestamp = new Date().toISOString();
+    const statement = `archipelago-token|v1|${this.config.home}|${aud}|${timestamp}`;
+    const proof = cryptoSign(null, Buffer.from(statement, 'utf8'), key.privateKey).toString('base64url');
+    const { status, json } = await this.post('/token', { id: key.id, audience: aud, timestamp, proof });
+    if (status !== 200 || typeof json.token !== 'string') {
+      throw new Error(`identity: ${this.config.home} refused access to "${aud}" (${status}): ${String(json.error ?? 'unknown')}`);
+    }
+    return json.token;
+  }
+
+  /** Authorization header for HTTP calls to an audience's API. */
+  async httpAuthFor(audience?: string): Promise<Record<string, string>> {
+    return { authorization: `Bearer ${await this.accessFor(audience)}` };
+  }
+
+  // ── key material ──
+
+  private loadOrCreateKey(): { privateKey: KeyObject; id: string } {
+    let privateKey: KeyObject;
+    if (existsSync(this.config.keyPath)) {
+      privateKey = createPrivateKey(readFileSync(this.config.keyPath, 'utf8'));
+    } else {
+      privateKey = generateKeyPairSync('ed25519').privateKey;
+      mkdirSync(dirname(this.config.keyPath), { recursive: true });
+      writeFileSync(this.config.keyPath, privateKey.export({ format: 'pem', type: 'pkcs8' }), { mode: 0o600 });
+    }
+    const spki = createPublicKey(privateKey).export({ format: 'der', type: 'spki' }) as Buffer;
+    return { privateKey, id: `ed25519:${spki.subarray(spki.length - 32).toString('base64url')}` };
+  }
+
+  private record(): IdentityRecord | null {
+    try {
+      return JSON.parse(readFileSync(this.recordPath, 'utf8')) as IdentityRecord;
+    } catch {
+      return null;
+    }
+  }
+
+  private saveRecord(rec: IdentityRecord): void {
+    writeFileSync(this.recordPath + '.tmp', JSON.stringify(rec, null, 2) + '\n');
+    renameSync(this.recordPath + '.tmp', this.recordPath);
+  }
+
+  private async post(path: string, body: unknown): Promise<{ status: number; json: Record<string, unknown> }> {
+    const f = this.config.fetchImpl ?? fetch;
+    const res = await f(`https://${this.config.home}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return { status: res.status, json: (await res.json().catch(() => ({}))) as Record<string, unknown> };
+  }
+
+  // ── agent-facing utilities ──
+
+  private status(): ToolResult {
+    // Key material is deliberately created lazily here too, so `status` is
+    // always safe to call — but none of it surfaces in the result.
+    this.loadOrCreateKey();
+    const rec = this.record();
+    return ok(
+      rec
+        ? {
+            registeredAs: rec.name,
+            id: rec.sub,
+            recognizedBy: rec.home,
+            since: rec.enrolledAt,
+            note: 'Access to services is handled by the host automatically (e.g. mcpl_deploy with an `access` name).',
+          }
+        : {
+            registeredAs: null,
+            note: `Not registered with ${this.config.home} yet — ask your operator for an invitation code, then use accept_invite.`,
+          },
+    );
+  }
+
+  private async acceptInvite(input: { invite?: unknown; name?: unknown }): Promise<ToolResult> {
+    if (typeof input.invite !== 'string' || typeof input.name !== 'string') {
+      return fail('accept_invite needs { invite, name }');
+    }
+    const existing = this.record();
+    if (existing) {
+      return fail(`Already registered as "${existing.name}" (${existing.sub}) — registration is one-time.`);
+    }
+    const key = this.loadOrCreateKey();
+    const timestamp = new Date().toISOString();
+    const statement = `archipelago-enroll|v1|${this.config.home}|${input.invite}|${timestamp}`;
+    const proof = cryptoSign(null, Buffer.from(statement, 'utf8'), key.privateKey).toString('base64url');
+    const { status, json } = await this.post('/enroll', {
+      invite: input.invite,
+      id: key.id,
+      name: input.name,
+      timestamp,
+      proof,
+    });
+    if (status !== 200 || typeof json.sub !== 'string') {
+      return fail(`Registration refused (${status}): ${String(json.error ?? 'unknown')}`);
+    }
+    this.saveRecord({ sub: json.sub, name: input.name, home: this.config.home, enrolledAt: timestamp });
+    // Note what is NOT returned: the first token the home node minted. The
+    // host fetches its own, fresh, per use — the agent never holds one.
+    return ok({
+      registeredAs: input.name,
+      id: json.sub,
+      recognizedBy: this.config.home,
+      note: 'Done — the host now handles access for you automatically.',
+    });
+  }
+}

package/src/modules/mcpl-admin-module.ts

@@ -51,6 +51,11 @@ export interface McplAdminModuleConfig {
   overlayPath?: string;
   /** Path to the human-owned server config file (read-only here). */
   configPath?: string;
+  /** Where these operations surface to the model: 'tools' (default — four
+   *  first-class slots, exactly the historical behavior) or 'utilities'
+   *  (behind the framework's single `utils` meta-tool: mcpl management is a
+   *  rare operation and needn't tax every inference with four schemas). */
+  surface?: 'tools' | 'utilities';
 }
 
 function ok(text: string): ToolResult {
@@ -69,10 +74,13 @@ export class McplAdminModule implements Module {
   private configPath: string;
   private timeZone: string;
 
+  private surface: 'tools' | 'utilities';
+
   constructor(config?: McplAdminModuleConfig) {
     this.overlayPath = config?.overlayPath ?? DEFAULT_AGENT_OVERLAY_PATH;
     this.configPath = config?.configPath ?? DEFAULT_CONFIG_PATH;
     this.timeZone = resolveTimeZone(config?.timeZone);
+    this.surface = config?.surface ?? 'tools';
   }
 
   /** Post-creation wiring (called from index.ts, mirrors ActivityModule.setFramework). */
@@ -80,6 +88,15 @@ export class McplAdminModule implements Module {
     this.framework = framework;
   }
 
+  /** Optional identity plumbing (index.ts wires it when the recipe enables
+   *  the identity module): lets deployed servers name an `access` grant that
+   *  the host turns into a per-dial credential provider. The agent names the
+   *  access; credentials never surface. */
+  private identity: { accessFor(audience?: string): Promise<string> } | null = null;
+  setIdentity(identity: { accessFor(audience?: string): Promise<string> } | null): void {
+    this.identity = identity;
+  }
+
   async start(_ctx: ModuleContext): Promise<void> {}
 
   async stop(): Promise<void> {
@@ -87,12 +104,23 @@ export class McplAdminModule implements Module {
   }
 
   getTools(): ToolDefinition[] {
+    return this.surface === 'tools' ? this.definitions() : [];
+  }
+
+  /** Same definitions, same handler — the surface flag only decides whether
+   *  they cost four slots or ride the `utils` meta-tool. */
+  getUtilities(): ToolDefinition[] {
+    return this.surface === 'utilities' ? this.definitions() : [];
+  }
+
+  private definitions(): ToolDefinition[] {
     return [
       {
         name: 'mcpl_list',
         description:
-          'List all MCPL servers: id, live connection status, tool count, command/url, ' +
-          'and where each is defined (recipe/file vs your own agent overlay).',
+          'List all MCPL servers: connection/retry state, whether policy was established, ' +
+          'the effective grant, masked/denied capability paths, host-command authority, ' +
+          'tool count, target, and config source.',
         inputSchema: { type: 'object', properties: {} },
       },
       {
@@ -111,7 +139,8 @@ export class McplAdminModule implements Module {
             args: { type: 'array', items: { type: 'string' }, description: 'Arguments for the command.' },
             env: { type: 'object', description: 'Environment variables for the spawned process.' },
             url: { type: 'string', description: 'WebSocket URL (websocket transport). Mutually exclusive with command.' },
-            token: { type: 'string', description: 'Bearer token for WebSocket auth.' },
+            token: { type: 'string', description: 'Bearer token for WebSocket auth (only when the operator hands you one — prefer `access`).' },
+            access: { type: 'string', description: 'Name of a host-managed access grant (e.g. "eidoverse"): the host attaches your standing credentials to the connection automatically. Nothing for you to obtain or handle.' },
             toolPrefix: { type: 'string', description: 'Tool namespace prefix. Default: mcpl--<id>.' },
             reconnect: { type: 'boolean', description: 'Auto-reconnect on transport failure (default false). Note: does NOT respawn a crashed child — use mcpl_restart for that.' },
             enabledFeatureSets: { type: 'array', items: { type: 'string' } },
@@ -199,7 +228,19 @@ export class McplAdminModule implements Module {
 
   private handleList(): ToolResult {
     const framework = this.requireFramework();
-    const live = framework.listMcplServers();
+    // These fields land in agent-framework 0.8's MCPL grant work. Keep them
+    // optional here so connectome-host remains truthful ("unknown") if it is
+    // temporarily run against an older framework package during rollout.
+    const live = framework.listMcplServers() as Array<
+      ReturnType<AgentFramework['listMcplServers']>[number] & {
+        retrying?: boolean;
+        policyEstablished?: boolean;
+        effectiveGrant?: string[];
+        maskedCapabilities?: string[];
+        deniedCapabilities?: string[];
+        allowHostCommands?: boolean;
+      }
+    >;
     const overlay = readAgentOverlay(this.overlayPath);
     const fileServers = readMcplServersFile(this.configPath);
 
@@ -209,8 +250,19 @@ export class McplAdminModule implements Module {
         ? 'agent-overlay'
         : s.id in fileServers ? 'file/recipe' : 'recipe';
       const target = s.command ?? s.url ?? '?';
+      const connectionState = s.connected ? 'CONNECTED' : s.retrying ? 'RETRYING' : 'DISCONNECTED';
+      const policyState = s.policyEstablished === undefined
+        ? 'unknown'
+        : s.policyEstablished ? 'established' : 'not-established';
+      const hostCommands = s.allowHostCommands === undefined
+        ? 'unknown'
+        : s.allowHostCommands ? 'allow' : 'deny';
       lines.push(
-        `${s.id}: ${s.connected ? 'CONNECTED' : 'DISCONNECTED'} — ${s.toolCount} tools, ` +
+        `${s.id}: ${connectionState} — policy=${policyState}, ` +
+        `grant=${formatCapabilityList(s.effectiveGrant)}, ` +
+        `masked=${formatCapabilityList(s.maskedCapabilities)}, ` +
+        `denied=${formatCapabilityList(s.deniedCapabilities)}, ` +
+        `hostCommands=${hostCommands}; ${s.toolCount} tools, ` +
         `prefix=${s.toolPrefix}, source=${source}, ${target}`,
       );
     }
@@ -251,6 +303,15 @@ export class McplAdminModule implements Module {
     if (Array.isArray(input.args)) entry.args = input.args.map(String);
     if (input.env && typeof input.env === 'object') entry.env = input.env as Record<string, string>;
     if (typeof input.token === 'string') entry.token = input.token;
+    if (typeof input.access === 'string' && input.access.trim()) {
+      if (!this.identity) {
+        return fail(
+          '`access` names a host-managed access grant, but this deployment has no identity ' +
+          'configured — ask your operator to enable it (recipe `identity`), or supply a `token`.',
+        );
+      }
+      entry.access = input.access.trim();
+    }
     if (typeof input.toolPrefix === 'string') entry.toolPrefix = input.toolPrefix;
     if (typeof input.reconnect === 'boolean') entry.reconnect = input.reconnect;
     if (Array.isArray(input.enabledFeatureSets)) entry.enabledFeatureSets = input.enabledFeatureSets.map(String);
@@ -266,6 +327,13 @@ export class McplAdminModule implements Module {
 
     const config = resolveOverlayEntry(id, entry, this.overlayPath) as unknown as McplServerConfig;
     config.env = { ...(config.env ?? {}), AGENT_TIMEZONE: this.timeZone };
+    if (entry.access && this.identity) {
+      const identity = this.identity;
+      const audience = entry.access;
+      // Fresh credential on every dial, resolved host-side; the overlay
+      // stores only the access NAME. See identity-module.ts header.
+      config.accessProvider = () => identity.accessFor(audience);
+    }
 
     const alreadyLoaded = framework.listMcplServers().some(s => s.id === id);
     try {
@@ -334,3 +402,8 @@ export class McplAdminModule implements Module {
     return ok(`Unloaded server "${id}" — its tools are gone from your toolset. ${persistNote}`);
   }
 }
+
+function formatCapabilityList(paths: string[] | undefined): string {
+  if (paths === undefined) return 'unknown';
+  return `[${paths.join(',')}]`;
+}

package/src/modules/observers-module.ts

@@ -37,6 +37,10 @@ import {
 export interface ObserversModuleConfig {
   /** Absolute path to the grant file (same one the webui watches). */
   path: string;
+  /** 'tools' (default) or 'utilities' — grant edits are rare; behind the
+   *  `utils` meta-tool they stop costing three schemas per inference. The
+   *  consent semantics are unchanged either way: the agent holds the pen. */
+  surface?: 'tools' | 'utilities';
 }
 
 export class ObserversModule implements Module {
@@ -48,6 +52,14 @@ export class ObserversModule implements Module {
   async stop(): Promise<void> {}
 
   getTools(): ToolDefinition[] {
+    return (this.config.surface ?? 'tools') === 'tools' ? this.definitions() : [];
+  }
+
+  getUtilities(): ToolDefinition[] {
+    return this.config.surface === 'utilities' ? this.definitions() : [];
+  }
+
+  private definitions(): ToolDefinition[] {
     return [
       {
         name: 'get',