@nkmc/gateway 0.1.0

package/src/federation/__tests__/peer-store.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { MemoryPeerStore } from "../peer-store.js";
+import type { PeerGateway, LendingRule } from "../types.js";
+
+function makePeer(overrides: Partial<PeerGateway> = {}): PeerGateway {
+  return {
+    id: "peer-1",
+    name: "Test Gateway",
+    url: "https://peer1.example.com",
+    sharedSecret: "secret-abc",
+    status: "active",
+    advertisedDomains: ["api.example.com"],
+    lastSeen: Date.now(),
+    createdAt: Date.now(),
+    ...overrides,
+  };
+}
+
+function makeRule(overrides: Partial<LendingRule> = {}): LendingRule {
+  return {
+    domain: "api.example.com",
+    allow: true,
+    peers: "*",
+    pricing: { mode: "free" },
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("MemoryPeerStore", () => {
+  let store: MemoryPeerStore;
+
+  beforeEach(() => {
+    store = new MemoryPeerStore();
+  });
+
+  // --- Peer CRUD ---
+
+  it("putPeer then getPeer returns the peer", async () => {
+    const peer = makePeer();
+    await store.putPeer(peer);
+    expect(await store.getPeer("peer-1")).toEqual(peer);
+  });
+
+  it("getPeer returns null for unknown id", async () => {
+    expect(await store.getPeer("nonexistent")).toBeNull();
+  });
+
+  it("deletePeer removes the peer", async () => {
+    await store.putPeer(makePeer());
+    await store.deletePeer("peer-1");
+    expect(await store.getPeer("peer-1")).toBeNull();
+  });
+
+  it("listPeers only returns active peers", async () => {
+    await store.putPeer(makePeer({ id: "a", status: "active", name: "A" }));
+    await store.putPeer(makePeer({ id: "b", status: "inactive", name: "B" }));
+    await store.putPeer(makePeer({ id: "c", status: "active", name: "C" }));
+
+    const list = await store.listPeers();
+    expect(list).toHaveLength(2);
+    expect(list.map((p) => p.id).sort()).toEqual(["a", "c"]);
+  });
+
+  it("updateLastSeen updates the timestamp", async () => {
+    await store.putPeer(makePeer({ lastSeen: 1000 }));
+    await store.updateLastSeen("peer-1", 9999);
+
+    const peer = await store.getPeer("peer-1");
+    expect(peer!.lastSeen).toBe(9999);
+  });
+
+  it("updateLastSeen is a no-op for unknown peer", async () => {
+    // should not throw
+    await store.updateLastSeen("nonexistent", Date.now());
+  });
+
+  // --- Lending Rule CRUD ---
+
+  it("putRule then getRule returns the rule", async () => {
+    const rule = makeRule();
+    await store.putRule(rule);
+    expect(await store.getRule("api.example.com")).toEqual(rule);
+  });
+
+  it("getRule returns null for unknown domain", async () => {
+    expect(await store.getRule("unknown.example.com")).toBeNull();
+  });
+
+  it("deleteRule removes the rule", async () => {
+    await store.putRule(makeRule());
+    await store.deleteRule("api.example.com");
+    expect(await store.getRule("api.example.com")).toBeNull();
+  });
+
+  it("listRules returns all rules", async () => {
+    await store.putRule(makeRule({ domain: "a.com" }));
+    await store.putRule(makeRule({ domain: "b.com" }));
+    await store.putRule(makeRule({ domain: "c.com" }));
+
+    const list = await store.listRules();
+    expect(list).toHaveLength(3);
+    expect(list.map((r) => r.domain).sort()).toEqual(["a.com", "b.com", "c.com"]);
+  });
+
+  it("putRule overwrites existing rule for same domain", async () => {
+    await store.putRule(makeRule({ domain: "x.com", allow: true }));
+    await store.putRule(makeRule({ domain: "x.com", allow: false }));
+
+    const rule = await store.getRule("x.com");
+    expect(rule!.allow).toBe(false);
+  });
+});

package/src/federation/d1-peer-store.ts

@@ -0,0 +1,164 @@
+import type { D1Database } from "../d1/types.js";
+import type { PeerGateway, LendingRule, PeerStore } from "./types.js";
+
+interface PeerRow {
+  id: string;
+  name: string;
+  url: string;
+  shared_secret: string;
+  status: string;
+  advertised_domains: string;
+  last_seen: number;
+  created_at: number;
+}
+
+interface LendingRuleRow {
+  domain: string;
+  allow: number;
+  peers: string;
+  pricing: string;
+  rate_limit: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+function rowToPeer(row: PeerRow): PeerGateway {
+  return {
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    sharedSecret: row.shared_secret,
+    status: row.status as PeerGateway["status"],
+    advertisedDomains: JSON.parse(row.advertised_domains),
+    lastSeen: row.last_seen,
+    createdAt: row.created_at,
+  };
+}
+
+function rowToRule(row: LendingRuleRow): LendingRule {
+  return {
+    domain: row.domain,
+    allow: row.allow === 1,
+    peers: JSON.parse(row.peers),
+    pricing: JSON.parse(row.pricing),
+    ...(row.rate_limit ? { rateLimit: JSON.parse(row.rate_limit) } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export class D1PeerStore implements PeerStore {
+  constructor(private db: D1Database) {}
+
+  async initSchema(): Promise<void> {
+    await this.db.exec(`
+CREATE TABLE IF NOT EXISTS peers (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  url TEXT NOT NULL,
+  shared_secret TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active',
+  advertised_domains TEXT NOT NULL DEFAULT '[]',
+  last_seen INTEGER NOT NULL,
+  created_at INTEGER NOT NULL
+)`);
+    await this.db.exec(`
+CREATE TABLE IF NOT EXISTS lending_rules (
+  domain TEXT PRIMARY KEY,
+  allow INTEGER NOT NULL DEFAULT 1,
+  peers TEXT NOT NULL DEFAULT '"*"',
+  pricing TEXT NOT NULL DEFAULT '{"mode":"free"}',
+  rate_limit TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+)`);
+  }
+
+  async getPeer(id: string): Promise<PeerGateway | null> {
+    const row = await this.db
+      .prepare("SELECT * FROM peers WHERE id = ?")
+      .bind(id)
+      .first<PeerRow>();
+    return row ? rowToPeer(row) : null;
+  }
+
+  async putPeer(peer: PeerGateway): Promise<void> {
+    await this.db
+      .prepare(
+        `INSERT OR REPLACE INTO peers (id, name, url, shared_secret, status, advertised_domains, last_seen, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .bind(
+        peer.id,
+        peer.name,
+        peer.url,
+        peer.sharedSecret,
+        peer.status,
+        JSON.stringify(peer.advertisedDomains),
+        peer.lastSeen,
+        peer.createdAt,
+      )
+      .run();
+  }
+
+  async deletePeer(id: string): Promise<void> {
+    await this.db
+      .prepare("DELETE FROM peers WHERE id = ?")
+      .bind(id)
+      .run();
+  }
+
+  async listPeers(): Promise<PeerGateway[]> {
+    const { results } = await this.db
+      .prepare("SELECT * FROM peers WHERE status = 'active'")
+      .all<PeerRow>();
+    return results.map(rowToPeer);
+  }
+
+  async updateLastSeen(id: string, timestamp: number): Promise<void> {
+    await this.db
+      .prepare("UPDATE peers SET last_seen = ? WHERE id = ?")
+      .bind(timestamp, id)
+      .run();
+  }
+
+  async getRule(domain: string): Promise<LendingRule | null> {
+    const row = await this.db
+      .prepare("SELECT * FROM lending_rules WHERE domain = ?")
+      .bind(domain)
+      .first<LendingRuleRow>();
+    return row ? rowToRule(row) : null;
+  }
+
+  async putRule(rule: LendingRule): Promise<void> {
+    await this.db
+      .prepare(
+        `INSERT OR REPLACE INTO lending_rules (domain, allow, peers, pricing, rate_limit, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .bind(
+        rule.domain,
+        rule.allow ? 1 : 0,
+        JSON.stringify(rule.peers),
+        JSON.stringify(rule.pricing),
+        rule.rateLimit ? JSON.stringify(rule.rateLimit) : null,
+        rule.createdAt,
+        rule.updatedAt,
+      )
+      .run();
+  }
+
+  async deleteRule(domain: string): Promise<void> {
+    await this.db
+      .prepare("DELETE FROM lending_rules WHERE domain = ?")
+      .bind(domain)
+      .run();
+  }
+
+  async listRules(): Promise<LendingRule[]> {
+    const { results } = await this.db
+      .prepare("SELECT * FROM lending_rules")
+      .all<LendingRuleRow>();
+    return results.map(rowToRule);
+  }
+}

package/src/federation/peer-backend.ts

@@ -0,0 +1,60 @@
+import type { FsBackend } from "@nkmc/agent-fs";
+import type { PeerClient, PeerExecResult } from "./peer-client.js";
+import type { PeerGateway } from "./types.js";
+
+/**
+ * An FsBackend that delegates filesystem operations to a peer gateway.
+ * Used when the local gateway doesn't have credentials for a domain
+ * but a federated peer does.
+ */
+export class PeerBackend implements FsBackend {
+  constructor(
+    private client: PeerClient,
+    private peer: PeerGateway,
+    private agentId: string,
+  ) {}
+
+  async list(path: string): Promise<string[]> {
+    const result = await this.execOnPeer(`ls ${path}`);
+    return (result.data as string[]) ?? [];
+  }
+
+  async read(path: string): Promise<unknown> {
+    const result = await this.execOnPeer(`cat ${path}`);
+    return result.data;
+  }
+
+  async write(path: string, data: unknown): Promise<{ id: string }> {
+    const result = await this.execOnPeer(
+      `write ${path} ${JSON.stringify(data)}`,
+    );
+    return (result.data as { id: string }) ?? { id: "" };
+  }
+
+  async remove(path: string): Promise<void> {
+    await this.execOnPeer(`rm ${path}`);
+  }
+
+  async search(path: string, pattern: string): Promise<unknown[]> {
+    const result = await this.execOnPeer(`grep ${pattern} ${path}`);
+    return (result.data as unknown[]) ?? [];
+  }
+
+  private async execOnPeer(command: string): Promise<PeerExecResult> {
+    const result = await this.client.exec(this.peer, {
+      command,
+      agentId: this.agentId,
+    });
+
+    if (!result.ok) {
+      if (result.paymentRequired) {
+        throw new Error(
+          `Payment required: ${result.paymentRequired.price} ${result.paymentRequired.currency}`,
+        );
+      }
+      throw new Error(result.error ?? "Peer execution failed");
+    }
+
+    return result;
+  }
+}

package/src/federation/peer-client.ts

@@ -0,0 +1,122 @@
+import type { PeerGateway } from "./types.js";
+
+export interface PeerQueryResult {
+  available: boolean;
+  pricing?: { mode: string; amount?: number };
+}
+
+export interface PeerExecResult {
+  ok: boolean;
+  data?: unknown;
+  error?: string;
+  paymentRequired?: {
+    price: number;
+    currency: string;
+    payTo: string;
+    network: string;
+  };
+}
+
+/**
+ * Client for communicating with peer gateways in the federation.
+ * Each method sends authenticated HTTP requests to the peer's URL.
+ */
+export class PeerClient {
+  constructor(private selfId: string) {}
+
+  /**
+   * Query a peer to check if it has credentials for a domain
+   * and its lending rules allow access.
+   */
+  async query(peer: PeerGateway, domain: string): Promise<PeerQueryResult> {
+    try {
+      const res = await fetch(`${peer.url}/federation/query`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Peer-Id": this.selfId,
+          Authorization: `Bearer ${peer.sharedSecret}`,
+        },
+        body: JSON.stringify({ domain }),
+      });
+
+      if (!res.ok) {
+        return { available: false };
+      }
+
+      const body = (await res.json()) as {
+        available: boolean;
+        pricing?: { mode: string; amount?: number };
+      };
+      return {
+        available: body.available,
+        ...(body.pricing ? { pricing: body.pricing } : {}),
+      };
+    } catch {
+      return { available: false };
+    }
+  }
+
+  /**
+   * Execute a command on a peer gateway on behalf of an agent.
+   * Handles 402 Payment Required responses with X-402-* headers.
+   */
+  async exec(
+    peer: PeerGateway,
+    request: { command: string; agentId: string },
+  ): Promise<PeerExecResult> {
+    try {
+      const res = await fetch(`${peer.url}/federation/exec`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Peer-Id": this.selfId,
+          Authorization: `Bearer ${peer.sharedSecret}`,
+        },
+        body: JSON.stringify(request),
+      });
+
+      if (res.status === 402) {
+        return {
+          ok: false,
+          paymentRequired: {
+            price: Number(res.headers.get("X-402-Price") ?? "0"),
+            currency: res.headers.get("X-402-Currency") ?? "USD",
+            payTo: res.headers.get("X-402-Pay-To") ?? "",
+            network: res.headers.get("X-402-Network") ?? "",
+          },
+        };
+      }
+
+      if (!res.ok) {
+        const body = (await res.json().catch(() => ({}))) as {
+          error?: string;
+        };
+        return { ok: false, error: body.error ?? `HTTP ${res.status}` };
+      }
+
+      const body = (await res.json()) as { data?: unknown };
+      return { ok: true, data: body.data };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  /**
+   * Announce our available domains to a peer gateway.
+   */
+  async announce(peer: PeerGateway, domains: string[]): Promise<void> {
+    await fetch(`${peer.url}/federation/announce`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Peer-Id": this.selfId,
+        Authorization: `Bearer ${peer.sharedSecret}`,
+      },
+      body: JSON.stringify({ domains }),
+    });
+  }
+}

package/src/federation/peer-store.ts

@@ -0,0 +1,45 @@
+import type { PeerGateway, LendingRule, PeerStore } from "./types.js";
+
+export class MemoryPeerStore implements PeerStore {
+  private peers = new Map<string, PeerGateway>();
+  private rules = new Map<string, LendingRule>();
+
+  async getPeer(id: string): Promise<PeerGateway | null> {
+    return this.peers.get(id) ?? null;
+  }
+
+  async putPeer(peer: PeerGateway): Promise<void> {
+    this.peers.set(peer.id, peer);
+  }
+
+  async deletePeer(id: string): Promise<void> {
+    this.peers.delete(id);
+  }
+
+  async listPeers(): Promise<PeerGateway[]> {
+    return Array.from(this.peers.values()).filter((p) => p.status === "active");
+  }
+
+  async updateLastSeen(id: string, timestamp: number): Promise<void> {
+    const peer = this.peers.get(id);
+    if (peer) {
+      peer.lastSeen = timestamp;
+    }
+  }
+
+  async getRule(domain: string): Promise<LendingRule | null> {
+    return this.rules.get(domain) ?? null;
+  }
+
+  async putRule(rule: LendingRule): Promise<void> {
+    this.rules.set(rule.domain, rule);
+  }
+
+  async deleteRule(domain: string): Promise<void> {
+    this.rules.delete(domain);
+  }
+
+  async listRules(): Promise<LendingRule[]> {
+    return Array.from(this.rules.values());
+  }
+}

package/src/federation/types.ts

@@ -0,0 +1,39 @@
+export interface PeerGateway {
+  id: string;
+  name: string;
+  url: string;
+  sharedSecret: string;
+  status: "active" | "inactive";
+  advertisedDomains: string[];
+  lastSeen: number;
+  createdAt: number;
+}
+
+export interface LendingRule {
+  domain: string;
+  allow: boolean;
+  peers: string[] | "*";
+  pricing: {
+    mode: "free" | "per-request" | "per-token";
+    amount?: number;
+  };
+  rateLimit?: {
+    requests: number;
+    window: "minute" | "hour" | "day";
+  };
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PeerStore {
+  getPeer(id: string): Promise<PeerGateway | null>;
+  putPeer(peer: PeerGateway): Promise<void>;
+  deletePeer(id: string): Promise<void>;
+  listPeers(): Promise<PeerGateway[]>;
+  updateLastSeen(id: string, timestamp: number): Promise<void>;
+
+  getRule(domain: string): Promise<LendingRule | null>;
+  putRule(rule: LendingRule): Promise<void>;
+  deleteRule(domain: string): Promise<void>;
+  listRules(): Promise<LendingRule[]>;
+}

package/src/http/app.ts

@@ -0,0 +1,152 @@
+import { Hono } from "hono";
+import { AgentFs } from "@nkmc/agent-fs";
+import type { JWK } from "jose";
+import type { RegistryStore } from "../registry/types.js";
+import type { D1Database } from "../d1/types.js";
+import type { CredentialVault } from "../credential/types.js";
+import { createRegistryResolver } from "../registry/resolver.js";
+import { Context7Backend } from "../registry/context7-backend.js";
+import { adminAuth } from "./middleware/admin-auth.js";
+import { publishOrAdminAuth } from "./middleware/publish-auth.js";
+import { agentAuth } from "./middleware/agent-auth.js";
+import { authRoutes } from "./routes/auth.js";
+import { registryRoutes } from "./routes/registry.js";
+import { domainRoutes } from "./routes/domains.js";
+import { credentialRoutes } from "./routes/credentials.js";
+import { byokRoutes } from "./routes/byok.js";
+import { fsRoutes } from "./routes/fs.js";
+import { proxyRoutes, type ExecResult } from "./routes/proxy.js";
+import { peerRoutes } from "./routes/peers.js";
+import { federationRoutes } from "./routes/federation.js";
+import type { PeerStore } from "../federation/types.js";
+import type { ToolRegistry } from "../proxy/tool-registry.js";
+import type { TunnelStore, TunnelProvider } from "../tunnel/types.js";
+import { tunnelRoutes } from "./routes/tunnels.js";
+
+export type Env = {
+  Variables: {
+    agent: { id: string; roles: string[] };
+  };
+};
+
+export interface GatewayOptions {
+  store: RegistryStore;
+  gatewayPrivateKey: JWK;
+  gatewayPublicKey: JWK;
+  adminToken: string;
+  db?: D1Database;
+  vault?: CredentialVault;
+  context7ApiKey?: string;
+  peerStore?: PeerStore;
+  proxy?: {
+    toolRegistry: ToolRegistry;
+    exec: (tool: string, args: string[], env: Record<string, string>) => Promise<ExecResult>;
+  };
+  tunnel?: {
+    store: TunnelStore;
+    provider: TunnelProvider;
+    domain: string;
+  };
+}
+
+export function createGateway(options: GatewayOptions): Hono<Env> {
+  const { store, gatewayPrivateKey, gatewayPublicKey, adminToken } = options;
+
+  const app = new Hono<Env>();
+
+  // Create registry resolver hooks for AgentFs
+  const { onMiss, listDomains, searchDomains, searchEndpoints } = createRegistryResolver(
+    options.vault
+      ? { store, vault: options.vault, gatewayPrivateKey }
+      : { store, gatewayPrivateKey },
+  );
+
+  // First-party mounts
+  const mounts: { path: string; backend: import("@nkmc/agent-fs").FsBackend }[] = [];
+
+  // Context7: built-in documentation query service
+  if (options.context7ApiKey) {
+    mounts.push({ path: "/context7", backend: new Context7Backend({ apiKey: options.context7ApiKey }) });
+  }
+
+  // Create AgentFs instance with registry hooks
+  const agentFs = new AgentFs({
+    mounts,
+    onMiss,
+    listDomains,
+    searchDomains,
+    searchEndpoints,
+  });
+
+  // Public: JWKS endpoint for developers to discover gateway public key
+  app.get("/.well-known/jwks.json", (c) => {
+    return c.json({ keys: [gatewayPublicKey] });
+  });
+
+  // Public: Auth token endpoint
+  app.route("/auth", authRoutes({ privateKey: gatewayPrivateKey }));
+
+  // Public: Domain claim / verify (only when db is provided)
+  if (options.db) {
+    app.route("/domains", domainRoutes({ db: options.db, gatewayPrivateKey }));
+  }
+
+  // Registry management (admin token or publish token)
+  app.use("/registry/*", publishOrAdminAuth(adminToken, gatewayPublicKey));
+  app.route("/registry", registryRoutes({ store }));
+
+  // Admin: Credential management (optional — only mounted when vault is provided)
+  if (options.vault) {
+    app.use("/credentials/*", adminAuth(adminToken));
+    app.route("/credentials", credentialRoutes({ vault: options.vault }));
+
+    // Agent: BYOK credential management (JWT protected)
+    app.use("/byok/*", agentAuth(gatewayPublicKey));
+    app.route("/byok", byokRoutes({ vault: options.vault }));
+  }
+
+  // Agent: FS and execute routes (JWT protected, middleware first)
+  app.use("/execute", agentAuth(gatewayPublicKey));
+  app.use("/fs/*", agentAuth(gatewayPublicKey));
+  app.route("/", fsRoutes({ agentFs }));
+
+  // Proxy routes (optional — only mounted when proxy config and vault are provided)
+  if (options.proxy && options.vault) {
+    app.use("/proxy/*", agentAuth(gatewayPublicKey));
+    app.route(
+      "/proxy",
+      proxyRoutes({
+        vault: options.vault,
+        toolRegistry: options.proxy.toolRegistry,
+        exec: options.proxy.exec,
+      }),
+    );
+  }
+
+  // Federation routes (optional — only mounted when peerStore and vault are provided)
+  if (options.peerStore && options.vault) {
+    app.use("/admin/federation/*", adminAuth(adminToken));
+    app.route("/admin/federation", peerRoutes({ peerStore: options.peerStore }));
+
+    app.route("/federation", federationRoutes({
+      peerStore: options.peerStore,
+      vault: options.vault,
+      agentFs,
+    }));
+  }
+
+  // Tunnel routes (optional — only mounted when tunnel config is provided)
+  if (options.tunnel) {
+    app.use("/tunnels/*", agentAuth(gatewayPublicKey));
+    app.route(
+      "/tunnels",
+      tunnelRoutes({
+        tunnelStore: options.tunnel.store,
+        tunnelProvider: options.tunnel.provider,
+        tunnelDomain: options.tunnel.domain,
+      }),
+    );
+  }
+
+  return app;
+}