@xnetjs/cli 0.1.7 → 0.2.1

package/dist/cli.js

@@ -1230,20 +1230,337 @@ function registerDoctorCommand(program2) {
   });
 }
 
+// src/commands/enroll.ts
+import { getSigningPublicKeyFromPrivate as getSigningPublicKeyFromPrivate2 } from "@xnetjs/crypto";
+import { agentPassportId } from "@xnetjs/data";
+import { createDID as createDID2, mintAgentPassport } from "@xnetjs/identity";
+
+// src/utils/agent-passport-file.ts
+import { mkdir as mkdir2, readFile as readFile2, writeFile, chmod, readdir } from "fs/promises";
+import { homedir } from "os";
+import { join as join6 } from "path";
+function agentPassportDir() {
+  return process.env.XNET_AGENT_DIR ?? join6(homedir(), ".xnet", "agents");
+}
+var passportPath = (name) => {
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    throw new Error(`Invalid agent name: ${name} (use letters, digits, - and _)`);
+  }
+  return join6(agentPassportDir(), `${name}.json`);
+};
+async function saveAgentPassportFile(file) {
+  const dir = agentPassportDir();
+  await mkdir2(dir, { recursive: true, mode: 448 });
+  const path = passportPath(file.name);
+  await writeFile(path, JSON.stringify(file, null, 2) + "\n", { mode: 384 });
+  await chmod(path, 384);
+  return path;
+}
+async function loadAgentPassportFile(name) {
+  try {
+    const raw = await readFile2(passportPath(name), "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+async function listAgentPassportNames() {
+  try {
+    const entries = await readdir(agentPassportDir());
+    return entries.filter((e) => e.endsWith(".json")).map((e) => e.slice(0, -5));
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+function bytesToHex(bytes) {
+  return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function hexToBytes2(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  return new Uint8Array(Buffer.from(clean, "hex"));
+}
+
+// src/commands/enroll.ts
+var AGENT_PASSPORT_SCHEMA_IRI = "xnet://xnet.fyi/AgentPassport@1.0.0";
+var RUNTIMES = ["openclaw", "hermes", "claude-code", "other"];
+var openClawStdioSnippet = (name) => JSON.stringify(
+  {
+    mcp: {
+      servers: {
+        xnet: {
+          command: "xnet",
+          args: ["mcp", "serve", "--agent", name],
+          transport: "stdio"
+        }
+      }
+    }
+  },
+  null,
+  2
+);
+var hermesStdioSnippet = (name) => JSON.stringify(
+  {
+    mcpServers: {
+      xnet: { command: "xnet", args: ["mcp", "serve", "--agent", name] }
+    }
+  },
+  null,
+  2
+);
+async function runEnroll(name, options) {
+  const keyHex = options.key ?? process.env.XNET_SIGNING_KEY;
+  if (!keyHex) {
+    throw new Error(
+      "Operator signing key required: pass --key <hex> or set $XNET_SIGNING_KEY (an ephemeral operator would break the trust chain)"
+    );
+  }
+  if (options.space.length === 0) {
+    throw new Error("At least one --space <id> is required (passports are always scoped)");
+  }
+  const operatorKey = hexToBytes2(keyHex);
+  const operatorDID = createDID2(getSigningPublicKeyFromPrivate2(operatorKey));
+  const capabilities = options.space.flatMap(
+    (space) => options.can.map((can) => ({ with: `xnet://space/${space}`, can }))
+  );
+  const grant = mintAgentPassport({
+    operatorDID,
+    operatorKey,
+    capabilities,
+    ttlSeconds: options.ttlDays * 24 * 3600
+  });
+  const passport = {
+    name,
+    runtime: options.runtime,
+    agentDID: grant.agentDID,
+    operatorDID,
+    agentKeyHex: bytesToHex(grant.agentKey),
+    ucan: grant.ucan,
+    expiresAt: grant.expiresAt,
+    capabilities,
+    createdAt: Date.now()
+  };
+  const path = await saveAgentPassportFile(passport);
+  let nodeCreated = false;
+  if (options.node) {
+    try {
+      const backend = await createRemoteAgentBackend(
+        options.apiUrl ? { apiUrl: options.apiUrl } : {}
+      );
+      await backend.store.create({
+        id: agentPassportId(grant.agentDID),
+        schemaId: AGENT_PASSPORT_SCHEMA_IRI,
+        properties: {
+          ...options.auditSpace ? { space: options.auditSpace } : {},
+          agentDID: grant.agentDID,
+          operatorDID,
+          displayName: name,
+          runtime: options.runtime,
+          ucan: grant.ucan,
+          expiresAt: grant.expiresAt,
+          status: "active"
+        }
+      });
+      nodeCreated = true;
+    } catch {
+    }
+  }
+  return {
+    passport,
+    path,
+    nodeCreated,
+    snippets: { openclaw: openClawStdioSnippet(name), hermes: hermesStdioSnippet(name) }
+  };
+}
+function registerAgentEnrollCommand(program2) {
+  const agent = program2.command("agent").description("Enroll and manage external agent passports (exploration 0337)");
+  agent.command("enroll <name>").description("Mint a scoped Agent Passport (own DID + operator-delegated UCAN)").option("--runtime <runtime>", `Agent runtime: ${RUNTIMES.join("|")}`, "other").option("--space <id...>", "Space ids the agent may write (repeatable)", []).option("--can <action...>", "Delegated actions", ["node/create", "node/update"]).option("--ttl-days <n>", "Passport lifetime in days (rotate weekly)", parseFloatOption, 7).option("--key <hex>", "Operator Ed25519 signing key (hex); falls back to $XNET_SIGNING_KEY").option("--audit-space <id>", "Space to home the AgentPassport node in").option("--api-url <url>", "xNet local API URL (default http://127.0.0.1:31415)").option("--no-node", "Skip recording the AgentPassport node in the workspace").action(async (name, options) => {
+    if (!RUNTIMES.includes(options.runtime)) {
+      throw new Error(`Unknown runtime: ${options.runtime} (use ${RUNTIMES.join("|")})`);
+    }
+    const result = await runEnroll(name, options);
+    console.log(`Agent passport minted: ${result.passport.agentDID}`);
+    console.log(`  runtime:  ${result.passport.runtime}`);
+    console.log(`  expires:  ${new Date(result.passport.expiresAt).toISOString()}`);
+    console.log(`  saved:    ${result.path} (0600 \u2014 contains the agent's private key)`);
+    console.log(
+      `  workspace node: ${result.nodeCreated ? "recorded" : "skipped (API unreachable or --no-node)"}`
+    );
+    console.log("\nCapabilities:");
+    for (const cap of result.passport.capabilities) {
+      console.log(`  ${cap.can}  ${cap.with}`);
+    }
+    console.log("\nOpenClaw (~/.openclaw/openclaw.json):\n" + result.snippets.openclaw);
+    console.log("\nHermes Agent:\n" + result.snippets.hermes);
+    console.log(
+      `
+Hub: add the operator DID to trustedDids so self-issued tokens are rejected:
+  trustedDids: ["${result.passport.operatorDID}"]`
+    );
+  });
+  agent.command("list").description("List enrolled agent passports").action(async () => {
+    const names = await listAgentPassportNames();
+    if (names.length === 0) {
+      console.log("No agent passports enrolled (xnet agent enroll <name> --space <id>)");
+      return;
+    }
+    for (const name of names) console.log(name);
+  });
+}
+function parseFloatOption(value) {
+  const parsed = Number.parseFloat(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`Invalid number: ${value}`);
+  return parsed;
+}
+
 // src/commands/mcp.ts
 import {
   createMCPServer,
   createMcpHttpServer
 } from "@xnetjs/plugins/node";
+
+// src/utils/agent-local.ts
+import { getSigningPublicKeyFromPrivate as getSigningPublicKeyFromPrivate3 } from "@xnetjs/crypto";
+import { SQLiteNodeStorageAdapter as SQLiteNodeStorageAdapter2, builtInSchemas } from "@xnetjs/data";
+import { createDID as createDID3 } from "@xnetjs/identity";
+import { createXNetClient as createXNetClient2 } from "@xnetjs/runtime";
+var toNodeData = (node) => ({
+  id: node.id,
+  schemaId: node.schemaId,
+  properties: node.properties,
+  deleted: node.deleted ?? false,
+  createdAt: node.createdAt ?? 0,
+  updatedAt: node.updatedAt ?? 0
+});
+async function resolveStorage2(db) {
+  if (db) {
+    const { createElectronSQLiteAdapter } = await import("@xnetjs/sqlite/electron");
+    const adapter2 = await createElectronSQLiteAdapter({
+      path: db,
+      busyTimeout: 5e3,
+      foreignKeys: true,
+      walMode: true
+    });
+    return new SQLiteNodeStorageAdapter2(adapter2);
+  }
+  const { createMemorySQLiteAdapter } = await import("@xnetjs/sqlite/memory");
+  const adapter = await createMemorySQLiteAdapter();
+  return new SQLiteNodeStorageAdapter2(adapter);
+}
+function builtInSchemaRegistry() {
+  const iris = Object.keys(builtInSchemas).filter((iri) => iri.includes("@"));
+  return {
+    getAllIRIs: () => iris,
+    get: async (iri) => {
+      const loader = builtInSchemas[iri];
+      if (!loader) return null;
+      const schema = await loader();
+      return {
+        iri,
+        name: schema.schema.name,
+        properties: schema.schema.properties
+      };
+    }
+  };
+}
+async function createLocalAgentBackend(options) {
+  const agentDID = createDID3(getSigningPublicKeyFromPrivate3(options.agentKey));
+  const nodeStorage = await resolveStorage2(options.db);
+  const client = await createXNetClient2({
+    nodeStorage,
+    authorDID: agentDID,
+    signingKey: options.agentKey
+  });
+  const store = {
+    get: async (id) => {
+      const node = await client.store.get(id);
+      return node ? toNodeData(node) : null;
+    },
+    list: async (opts) => {
+      const nodes = await client.store.list({
+        ...opts?.schemaId ? { schemaId: opts.schemaId } : {},
+        ...opts?.limit !== void 0 ? { limit: opts.limit } : {},
+        ...opts?.offset !== void 0 ? { offset: opts.offset } : {}
+      });
+      return nodes.map(toNodeData);
+    },
+    create: async (opts) => {
+      const node = await client.store.create({
+        ...opts.id ? { id: opts.id } : {},
+        schemaId: opts.schemaId,
+        properties: opts.properties
+      });
+      return toNodeData(node);
+    },
+    update: async (id, opts) => {
+      const node = await client.store.update(id, { properties: opts.properties });
+      return toNodeData(node);
+    },
+    delete: async (id) => {
+      await client.store.delete(id);
+    },
+    subscribe: (listener) => client.store.subscribe((event) => {
+      listener({ change: { type: event.change.type }, node: null, isRemote: false });
+    })
+  };
+  return { store, schemas: builtInSchemaRegistry(), client, agentDID };
+}
+
+// src/commands/mcp.ts
 var defaultBackendFactory = (options) => createRemoteAgentBackend(options);
-function buildMcpServer(backend) {
-  return createMCPServer({ store: backend.store, schemas: backend.schemas });
+function buildMcpServer(backend, agent) {
+  return createMCPServer({
+    store: backend.store,
+    schemas: backend.schemas,
+    ...agent ? {
+      agentAudit: {
+        agentDID: agent.passport.agentDID,
+        sessionKey: `${agent.passport.runtime}:${agent.passport.name}`,
+        channel: "other",
+        ...agent.auditSpaceId ? { spaceId: agent.auditSpaceId } : {}
+      }
+    } : {}
+  });
 }
 async function startMcpServe(backendFactory, options) {
-  const backend = await backendFactory({
-    ...options.apiUrl ? { apiUrl: options.apiUrl } : {}
-  });
-  const server = buildMcpServer(backend);
+  let agent;
+  let backend;
+  if (options.agent) {
+    const passport = await loadAgentPassportFile(options.agent);
+    if (!passport) {
+      throw new Error(
+        `No passport for agent "${options.agent}" (run: xnet agent enroll ${options.agent} --space <id>)`
+      );
+    }
+    if (passport.expiresAt <= Date.now()) {
+      throw new Error(
+        `Passport for "${options.agent}" expired ${new Date(passport.expiresAt).toISOString()} \u2014 re-enroll to rotate`
+      );
+    }
+    agent = {
+      passport,
+      ...options.auditSpace ? { auditSpaceId: options.auditSpace } : {}
+    };
+    if (options.db) {
+      backend = await createLocalAgentBackend({
+        db: options.db,
+        agentKey: hexToBytes2(passport.agentKeyHex)
+      });
+    } else {
+      console.error(
+        "warning: --agent without --db serves over the local API; writes are signed by the app identity, not the agent DID"
+      );
+      backend = await backendFactory({
+        ...options.apiUrl ? { apiUrl: options.apiUrl } : {}
+      });
+    }
+  } else {
+    backend = await backendFactory({
+      ...options.apiUrl ? { apiUrl: options.apiUrl } : {}
+    });
+  }
+  const server = buildMcpServer(backend, agent);
   if (options.http) {
     const http = createMcpHttpServer({
       server,
@@ -1285,7 +1602,7 @@ function registerMcpCommand(program2, backendFactory = defaultBackendFactory) {
   mcp.command("serve").description("Start an MCP server (stdio by default; --http for browser/OpenClaw clients)").option("--http", "Serve over hardened loopback HTTP instead of stdio").option("--host <host>", "Loopback host for --http (default 127.0.0.1)").option("--port <n>", "Port for --http (default 31416)", parseIntOption3).option(
     "--allow-origin <origin...>",
     "Browser origins permitted for --http (e.g. https://user.github.io)"
-  ).option("--pairing-token <token>", "Shared secret for --http (generated if omitted)").option("--api-url <url>", "xNet local API URL (default http://127.0.0.1:31415)").action(async (options) => {
+  ).option("--pairing-token <token>", "Shared secret for --http (generated if omitted)").option("--api-url <url>", "xNet local API URL (default http://127.0.0.1:31415)").option("--agent <name>", "Serve as an enrolled agent passport (exploration 0337)").option("--db <path>", "With --agent: agent-signed local SQLite store").option("--audit-space <id>", "With --agent: Space to home audit records in").action(async (options) => {
     const handle = await startMcpServe(backendFactory, options);
     if (handle.mode === "http" && handle.http) {
       console.error(`xNet MCP server listening on ${handle.http.url}${handle.http.path}`);
@@ -1760,6 +2077,7 @@ registerMigrateCommand(program);
 registerSchemaCommand(program);
 registerDoctorCommand(program);
 registerAgentCommands(program);
+registerAgentEnrollCommand(program);
 registerMcpCommand(program);
 registerBridgeCommand(program);
 registerCodeCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/cli",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "xNet CLI - Schema migrations, diagnostics, and development tools",
   "license": "MIT",
   "repository": {
@@ -31,15 +31,15 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
-    "@xnetjs/core": "2.0.0",
-    "@xnetjs/crypto": "2.0.0",
-    "@xnetjs/data": "2.0.0",
+    "@xnetjs/core": "2.2.0",
+    "@xnetjs/crypto": "2.2.0",
+    "@xnetjs/data": "2.2.0",
     "@xnetjs/devkit": "1.0.0",
-    "@xnetjs/identity": "2.0.0",
-    "@xnetjs/plugins": "2.0.0",
-    "@xnetjs/runtime": "0.5.0",
-    "@xnetjs/sqlite": "2.0.0",
-    "@xnetjs/sync": "2.0.0"
+    "@xnetjs/identity": "2.2.0",
+    "@xnetjs/plugins": "2.2.0",
+    "@xnetjs/runtime": "0.5.2",
+    "@xnetjs/sqlite": "2.2.0",
+    "@xnetjs/sync": "2.2.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",