@nkmc/gateway 0.1.0

package/src/http/routes/registry.ts

@@ -0,0 +1,222 @@
+import { Hono } from "hono";
+import type { RegistryStore, EndpointRecord, SourceConfig } from "../../registry/types.js";
+import { parseSkillMd } from "../../registry/skill-parser.js";
+import { fetchAndCompile } from "../../registry/openapi-compiler.js";
+import type { Env } from "../app.js";
+import type { PublishAuthContext } from "../middleware/publish-auth.js";
+
+/** Well-known paths to probe for OpenAPI specs */
+const OPENAPI_PATHS = [
+  "/openapi.json",
+  "/openapi.yaml",
+  "/swagger.json",
+  "/swagger.yaml",
+  "/docs/openapi.json",
+  "/api-docs",
+  "/api/openapi.json",
+  "/.well-known/openapi.json",
+  "/.well-known/openapi.yaml",
+];
+
+export interface RegistryRouteOptions {
+  store: RegistryStore;
+}
+
+export function registryRoutes(options: RegistryRouteOptions) {
+  const { store } = options;
+  const app = new Hono<Env>();
+
+  // Register a service (body = skill.md content)
+  app.post("/services", async (c) => {
+    const domain = c.req.query("domain");
+    if (!domain) {
+      return c.json({ error: "Missing ?domain= query parameter" }, 400);
+    }
+
+    // Publish token scope check: token must match the target domain
+    const auth = c.get("publishAuth" as never) as PublishAuthContext | undefined;
+    if (auth?.type === "publish" && auth.domain !== domain) {
+      return c.json(
+        { error: `Token is scoped to "${auth.domain}", cannot register "${domain}"` },
+        403,
+      );
+    }
+
+    const contentType = c.req.header("Content-Type") ?? "";
+    let skillMd: string;
+
+    if (contentType.includes("text/markdown") || contentType.includes("text/plain")) {
+      skillMd = await c.req.text();
+    } else {
+      // Try JSON body with skillMd field (and optional pre-compiled endpoints)
+      const body = await c.req.json<{ skillMd: string; endpoints?: EndpointRecord[]; source?: SourceConfig }>().catch(() => null);
+      if (!body?.skillMd) {
+        return c.json({ error: "Body must be skill.md text or JSON with skillMd field" }, 400);
+      }
+      skillMd = body.skillMd;
+      // If pre-compiled endpoints are provided, use them after parsing
+      if (Array.isArray(body.endpoints) && body.endpoints.length > 0) {
+        if (!skillMd.trim()) {
+          return c.json({ error: "Empty skill.md content" }, 400);
+        }
+        const isFirstParty = c.req.query("first_party") === "true";
+        const authMode = c.req.query("auth_mode");
+        const record = parseSkillMd(domain, skillMd, { isFirstParty });
+        record.endpoints = body.endpoints;
+        if (body.source) {
+          record.source = body.source;
+        }
+        if (authMode === "nkmc-jwt") {
+          record.authMode = "nkmc-jwt";
+        }
+        await store.put(domain, record);
+        return c.json({ ok: true, domain, name: record.name }, 201);
+      }
+    }
+
+    if (!skillMd.trim()) {
+      return c.json({ error: "Empty skill.md content" }, 400);
+    }
+
+    const isFirstParty = c.req.query("first_party") === "true";
+    const authMode = c.req.query("auth_mode");
+    const record = parseSkillMd(domain, skillMd, { isFirstParty });
+    if (authMode === "nkmc-jwt") {
+      record.authMode = "nkmc-jwt";
+    }
+    await store.put(domain, record);
+
+    return c.json({ ok: true, domain, name: record.name }, 201);
+  });
+
+  // Discover: auto-detect OpenAPI spec from a running service URL and register
+  app.post("/services/discover", async (c) => {
+    const body = await c.req.json<{ url: string; domain?: string; specUrl?: string }>().catch(() => null);
+    if (!body?.url) {
+      return c.json({ error: "Missing 'url' field (base URL of the service)" }, 400);
+    }
+
+    const baseUrl = body.url.replace(/\/+$/, "");
+
+    // Derive domain from URL if not provided
+    let domain: string;
+    try {
+      domain = body.domain ?? new URL(baseUrl).hostname;
+    } catch {
+      return c.json({ error: "Invalid URL" }, 400);
+    }
+
+    // Publish token scope check
+    const auth = c.get("publishAuth" as never) as PublishAuthContext | undefined;
+    if (auth?.type === "publish" && auth.domain !== domain) {
+      return c.json(
+        { error: `Token is scoped to "${auth.domain}", cannot register "${domain}"` },
+        403,
+      );
+    }
+
+    // If specUrl is provided, use it directly
+    if (body.specUrl) {
+      try {
+        const result = await fetchAndCompile(body.specUrl, { domain });
+        await store.put(domain, result.record);
+        return c.json({
+          ok: true,
+          domain,
+          name: result.record.name,
+          endpoints: result.record.endpoints.length,
+          source: body.specUrl,
+        }, 201);
+      } catch (err) {
+        return c.json({ error: `Failed to compile spec: ${err instanceof Error ? err.message : err}` }, 400);
+      }
+    }
+
+    // Auto-discover: probe well-known paths
+    for (const path of OPENAPI_PATHS) {
+      const specUrl = `${baseUrl}${path}`;
+      try {
+        const resp = await fetch(specUrl, { method: "GET", headers: { Accept: "application/json, application/yaml" } });
+        if (!resp.ok) continue;
+
+        const text = await resp.text();
+        if (!text.trim() || text.length < 20) continue;
+
+        // Try to compile — if it fails, try next path
+        try {
+          const result = await fetchAndCompile(specUrl, { domain });
+          await store.put(domain, result.record);
+          return c.json({
+            ok: true,
+            domain,
+            name: result.record.name,
+            endpoints: result.record.endpoints.length,
+            source: specUrl,
+          }, 201);
+        } catch {
+          continue;
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    return c.json({
+      error: "Could not find OpenAPI spec",
+      probed: OPENAPI_PATHS.map((p) => `${baseUrl}${p}`),
+      hint: "Use --spec-url to provide the spec location directly",
+    }, 404);
+  });
+
+  // List all services
+  app.get("/services", async (c) => {
+    const query = c.req.query("q");
+    if (query) {
+      const results = await store.search(query);
+      return c.json(results);
+    }
+    const list = await store.list();
+    return c.json(list);
+  });
+
+  // Get service details
+  app.get("/services/:domain", async (c) => {
+    const domain = c.req.param("domain");
+    const record = await store.get(domain);
+    if (!record) {
+      return c.json({ error: "Service not found" }, 404);
+    }
+    return c.json(record);
+  });
+
+  // List versions of a service
+  app.get("/services/:domain/versions", async (c) => {
+    const domain = c.req.param("domain");
+    const versions = await store.listVersions(domain);
+    return c.json({ domain, versions });
+  });
+
+  // Get specific version of a service
+  app.get("/services/:domain/versions/:version", async (c) => {
+    const domain = c.req.param("domain");
+    const version = c.req.param("version");
+    const record = await store.getVersion(domain, version);
+    if (!record) {
+      return c.json({ error: "Version not found" }, 404);
+    }
+    return c.json(record);
+  });
+
+  // Delete a service
+  app.delete("/services/:domain", async (c) => {
+    const domain = c.req.param("domain");
+    const existing = await store.get(domain);
+    if (!existing) {
+      return c.json({ error: "Service not found" }, 404);
+    }
+    await store.delete(domain);
+    return c.json({ ok: true, domain });
+  });
+
+  return app;
+}

package/src/http/routes/tunnels.ts

@@ -0,0 +1,124 @@
+import { Hono } from "hono";
+import type { Env } from "../app.js";
+import type { TunnelStore, TunnelProvider } from "../../tunnel/types.js";
+import { nanoid } from "nanoid";
+
+export interface TunnelRouteOptions {
+  tunnelStore: TunnelStore;
+  tunnelProvider: TunnelProvider;
+  tunnelDomain: string; // e.g. "tunnel.example.com"
+}
+
+export function tunnelRoutes(options: TunnelRouteOptions) {
+  const { tunnelStore, tunnelProvider, tunnelDomain } = options;
+  const app = new Hono<Env>();
+
+  // POST /tunnels/create — create a tunnel for the authenticated agent
+  app.post("/create", async (c) => {
+    const agent = c.get("agent");
+    const body = await c.req.json<{
+      advertisedDomains?: string[];
+      gatewayName?: string;
+    }>().catch(() => ({} as { advertisedDomains?: string[]; gatewayName?: string }));
+
+    // Check if agent already has a tunnel
+    const existing = await tunnelStore.getByAgent(agent.id);
+    if (existing && existing.status === "active") {
+      return c.json({
+        tunnelId: existing.id,
+        publicUrl: existing.publicUrl,
+        message: "Tunnel already exists",
+      });
+    }
+
+    const id = nanoid(12);
+    const hostname = `${id}.${tunnelDomain}`;
+    const publicUrl = `https://${hostname}`;
+
+    // Create via Cloudflare API
+    const { tunnelId, tunnelToken } = await tunnelProvider.create(
+      `nkmc-${agent.id}-${id}`,
+      hostname,
+    );
+
+    const now = Date.now();
+
+    // Store record
+    await tunnelStore.put({
+      id,
+      agentId: agent.id,
+      tunnelId,
+      publicUrl,
+      status: "active",
+      createdAt: now,
+      advertisedDomains: body.advertisedDomains ?? [],
+      gatewayName: body.gatewayName,
+      lastSeen: now,
+    });
+
+    return c.json({ tunnelId: id, tunnelToken, publicUrl }, 201);
+  });
+
+  // DELETE /tunnels/:id — delete a tunnel
+  app.delete("/:id", async (c) => {
+    const id = c.req.param("id");
+    const agent = c.get("agent");
+
+    const record = await tunnelStore.get(id);
+    if (!record) return c.json({ error: "Tunnel not found" }, 404);
+    if (record.agentId !== agent.id)
+      return c.json({ error: "Not your tunnel" }, 403);
+
+    await tunnelProvider.delete(record.tunnelId);
+    await tunnelStore.delete(id);
+
+    return c.json({ ok: true });
+  });
+
+  // GET /tunnels — list agent's tunnels
+  app.get("/", async (c) => {
+    const agent = c.get("agent");
+    const all = await tunnelStore.list();
+    const mine = all.filter((t) => t.agentId === agent.id);
+    return c.json({ tunnels: mine });
+  });
+
+  // GET /tunnels/discover — list all online gateways (public info only)
+  // Optional: ?domain=api.openai.com — filter by advertised domain
+  app.get("/discover", async (c) => {
+    const domain = c.req.query("domain");
+    const all = await tunnelStore.list();
+
+    let results = all.filter((t) => t.status === "active");
+    if (domain) {
+      results = results.filter((t) => t.advertisedDomains.includes(domain));
+    }
+
+    // Return public info only — no tunnelToken, no internal IDs
+    return c.json({
+      gateways: results.map((t) => ({
+        id: t.id,
+        name: t.gatewayName ?? `gateway-${t.id}`,
+        publicUrl: t.publicUrl,
+        advertisedDomains: t.advertisedDomains,
+      })),
+    });
+  });
+
+  // POST /tunnels/heartbeat — update advertised domains and confirm online
+  app.post("/heartbeat", async (c) => {
+    const agent = c.get("agent");
+    const body = await c.req.json<{ advertisedDomains?: string[] }>();
+
+    const record = await tunnelStore.getByAgent(agent.id);
+    if (!record) return c.json({ error: "No active tunnel" }, 404);
+
+    record.advertisedDomains = body.advertisedDomains ?? record.advertisedDomains;
+    record.lastSeen = Date.now();
+    await tunnelStore.put(record);
+
+    return c.json({ ok: true });
+  });
+
+  return app;
+}

package/src/http.ts

@@ -0,0 +1,9 @@
+export { createGateway, type GatewayOptions, type Env } from "./http/app.js";
+export { adminAuth } from "./http/middleware/admin-auth.js";
+export { publishOrAdminAuth, type PublishAuthContext } from "./http/middleware/publish-auth.js";
+export { agentAuth } from "./http/middleware/agent-auth.js";
+export { authRoutes, type AuthRouteOptions } from "./http/routes/auth.js";
+export { registryRoutes, type RegistryRouteOptions } from "./http/routes/registry.js";
+export { domainRoutes, type DomainRouteOptions } from "./http/routes/domains.js";
+export { fsRoutes, type FsRouteOptions } from "./http/routes/fs.js";
+export { tunnelRoutes, type TunnelRouteOptions } from "./http/routes/tunnels.js";

package/src/index.ts

@@ -0,0 +1,63 @@
+export const VERSION = "0.1.0";
+
+export type {
+  EndpointSummary,
+  EndpointRecord,
+  EndpointPricing,
+  EndpointAnnotations,
+  ServiceRecord,
+  SearchResult,
+  ServiceSummary,
+  ServiceStatus,
+  VersionSummary,
+  SourceConfig,
+  RegistryStore,
+} from "./registry/types.js";
+
+export { MemoryRegistryStore } from "./registry/memory-store.js";
+export { D1RegistryStore } from "./registry/d1-store.js";
+export { parseSkillMd, parsePricingAnnotation, type ParseOptions } from "./registry/skill-parser.js";
+export { skillToHttpConfig } from "./registry/skill-to-config.js";
+export {
+  createRegistryResolver,
+  extractDomainPath,
+  type RegistryResolverHooks,
+  type RegistryResolverOptions,
+} from "./registry/resolver.js";
+
+export type { MeterRecord, MeterQuery, MeterStore } from "./metering/types.js";
+export { MemoryMeterStore } from "./metering/memory-store.js";
+export { D1MeterStore } from "./metering/d1-store.js";
+export { lookupPricing, checkAccess, meter } from "./metering/pricing-guard.js";
+export { VirtualFileBackend } from "./registry/virtual-files.js";
+
+export type { StoredCredential, CredentialVault } from "./credential/types.js";
+export { MemoryCredentialVault } from "./credential/memory-vault.js";
+export { D1CredentialVault } from "./credential/d1-vault.js";
+export { credentialRoutes } from "./http/routes/credentials.js";
+
+export { queryDnsTxt } from "./http/lib/dns.js";
+export { Context7Client, type Context7Options, type LibrarySearchResult } from "./registry/context7.js";
+export { Context7Backend, type Context7BackendOptions } from "./registry/context7-backend.js";
+
+export {
+  OnboardPipeline,
+  discoverFromApisGuru,
+  type PipelineOptions,
+  type ApisGuruOptions,
+  type ManifestEntry,
+  type ManifestAuth,
+  type OnboardResult,
+  type OnboardReport,
+} from "./onboard/index.js";
+
+export type { D1Database, D1PreparedStatement, D1Result, D1RunResult } from "./d1/types.js";
+export { createSqliteD1 } from "./d1/sqlite-adapter.js";
+
+export type { PeerGateway, LendingRule, PeerStore } from "./federation/types.js";
+export { D1PeerStore } from "./federation/d1-peer-store.js";
+
+export type { TunnelRecord, TunnelStore, TunnelProvider } from "./tunnel/types.js";
+export { MemoryTunnelStore } from "./tunnel/memory-store.js";
+export { CloudflareTunnelProvider } from "./tunnel/cloudflare-provider.js";
+export { tunnelRoutes, type TunnelRouteOptions } from "./http/routes/tunnels.js";

package/src/metering/d1-store.ts

@@ -0,0 +1,123 @@
+import type { D1Database } from "../d1/types.js";
+import type { MeterRecord, MeterQuery, MeterStore } from "./types.js";
+
+const CREATE_METER_RECORDS = `
+CREATE TABLE IF NOT EXISTS meter_records (
+  id TEXT PRIMARY KEY,
+  timestamp INTEGER NOT NULL,
+  domain TEXT NOT NULL,
+  version TEXT NOT NULL,
+  endpoint TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  developer_id TEXT,
+  cost REAL NOT NULL,
+  currency TEXT NOT NULL DEFAULT 'USDC'
+)`;
+
+const CREATE_METER_INDEX_DOMAIN = `
+CREATE INDEX IF NOT EXISTS idx_meter_domain ON meter_records(domain, timestamp)`;
+
+const CREATE_METER_INDEX_AGENT = `
+CREATE INDEX IF NOT EXISTS idx_meter_agent ON meter_records(agent_id, timestamp)`;
+
+interface MeterRow {
+  id: string;
+  timestamp: number;
+  domain: string;
+  version: string;
+  endpoint: string;
+  agent_id: string;
+  developer_id: string | null;
+  cost: number;
+  currency: string;
+}
+
+export class D1MeterStore implements MeterStore {
+  constructor(private db: D1Database) {}
+
+  async initSchema(): Promise<void> {
+    await this.db.exec(CREATE_METER_RECORDS);
+    await this.db.exec(CREATE_METER_INDEX_DOMAIN);
+    await this.db.exec(CREATE_METER_INDEX_AGENT);
+  }
+
+  async record(entry: MeterRecord): Promise<void> {
+    await this.db
+      .prepare(
+        `INSERT INTO meter_records (id, timestamp, domain, version, endpoint, agent_id, developer_id, cost, currency)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .bind(
+        entry.id,
+        entry.timestamp,
+        entry.domain,
+        entry.version,
+        entry.endpoint,
+        entry.agentId,
+        entry.developerId ?? null,
+        entry.cost,
+        entry.currency,
+      )
+      .run();
+  }
+
+  async query(filter: MeterQuery): Promise<MeterRecord[]> {
+    const { sql, bindings } = this.buildQuery("SELECT *", filter);
+    const { results } = await this.db.prepare(sql).bind(...bindings).all<MeterRow>();
+    return results.map(rowToRecord);
+  }
+
+  async sum(filter: MeterQuery): Promise<{ total: number; currency: string }> {
+    const { sql, bindings } = this.buildQuery("SELECT COALESCE(SUM(cost), 0) as total, COALESCE(MIN(currency), 'USDC') as currency", filter);
+    const row = await this.db.prepare(sql).bind(...bindings).first<{ total: number; currency: string }>();
+    return { total: row?.total ?? 0, currency: row?.currency ?? "USDC" };
+  }
+
+  private buildQuery(select: string, filter: MeterQuery): { sql: string; bindings: unknown[] } {
+    const conditions: string[] = [];
+    const bindings: unknown[] = [];
+
+    if (filter.domain) {
+      conditions.push("domain = ?");
+      bindings.push(filter.domain);
+    }
+    if (filter.agentId) {
+      conditions.push("agent_id = ?");
+      bindings.push(filter.agentId);
+    }
+    if (filter.developerId) {
+      conditions.push("developer_id = ?");
+      bindings.push(filter.developerId);
+    }
+    if (filter.from) {
+      conditions.push("timestamp >= ?");
+      bindings.push(filter.from);
+    }
+    if (filter.to) {
+      conditions.push("timestamp <= ?");
+      bindings.push(filter.to);
+    }
+
+    let sql = `${select} FROM meter_records`;
+    if (conditions.length > 0) {
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+    }
+    sql += " ORDER BY timestamp DESC";
+
+    return { sql, bindings };
+  }
+}
+
+function rowToRecord(row: MeterRow): MeterRecord {
+  return {
+    id: row.id,
+    timestamp: row.timestamp,
+    domain: row.domain,
+    version: row.version,
+    endpoint: row.endpoint,
+    agentId: row.agent_id,
+    ...(row.developer_id ? { developerId: row.developer_id } : {}),
+    cost: row.cost,
+    currency: row.currency,
+  };
+}

package/src/metering/memory-store.ts

@@ -0,0 +1,29 @@
+import type { MeterRecord, MeterQuery, MeterStore } from "./types.js";
+
+export class MemoryMeterStore implements MeterStore {
+  private records: MeterRecord[] = [];
+
+  async record(entry: MeterRecord): Promise<void> {
+    this.records.push(entry);
+  }
+
+  async query(filter: MeterQuery): Promise<MeterRecord[]> {
+    return this.records.filter((r) => this.matches(r, filter));
+  }
+
+  async sum(filter: MeterQuery): Promise<{ total: number; currency: string }> {
+    const matched = this.records.filter((r) => this.matches(r, filter));
+    const total = matched.reduce((acc, r) => acc + r.cost, 0);
+    const currency = matched[0]?.currency ?? "USDC";
+    return { total, currency };
+  }
+
+  private matches(record: MeterRecord, filter: MeterQuery): boolean {
+    if (filter.domain && record.domain !== filter.domain) return false;
+    if (filter.agentId && record.agentId !== filter.agentId) return false;
+    if (filter.developerId && record.developerId !== filter.developerId) return false;
+    if (filter.from && record.timestamp < filter.from) return false;
+    if (filter.to && record.timestamp > filter.to) return false;
+    return true;
+  }
+}

package/src/metering/pricing-guard.ts

@@ -0,0 +1,68 @@
+import type { EndpointPricing, ServiceRecord } from "../registry/types.js";
+import type { MeterStore, MeterRecord } from "./types.js";
+
+export function lookupPricing(
+  record: ServiceRecord,
+  method: string,
+  path: string,
+): EndpointPricing | null {
+  // Find matching endpoint with pricing
+  for (const ep of record.endpoints) {
+    if (ep.method.toUpperCase() !== method.toUpperCase()) continue;
+    if (matchPath(ep.path, path)) {
+      return ep.pricing ?? null;
+    }
+  }
+  return null;
+}
+
+export function checkAccess(record: ServiceRecord): { allowed: boolean; reason?: string } {
+  if (record.status === "sunset") {
+    return { allowed: false, reason: "Service has been sunset" };
+  }
+  if (record.sunsetDate && record.sunsetDate < Date.now()) {
+    return { allowed: false, reason: "Service sunset date has passed" };
+  }
+  return { allowed: true };
+}
+
+export async function meter(
+  store: MeterStore,
+  opts: {
+    domain: string;
+    version: string;
+    endpoint: string;
+    agentId: string;
+    developerId?: string;
+    pricing: EndpointPricing;
+  },
+): Promise<MeterRecord> {
+  const entry: MeterRecord = {
+    id: `m_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: Date.now(),
+    domain: opts.domain,
+    version: opts.version,
+    endpoint: opts.endpoint,
+    agentId: opts.agentId,
+    developerId: opts.developerId,
+    cost: opts.pricing.cost,
+    currency: opts.pricing.currency,
+  };
+  await store.record(entry);
+  return entry;
+}
+
+function matchPath(pattern: string, actual: string): boolean {
+  // Support :param pattern matching
+  const patternParts = pattern.split("/").filter(Boolean);
+  const actualParts = actual.split("/").filter(Boolean);
+
+  if (patternParts.length !== actualParts.length) return false;
+
+  for (let i = 0; i < patternParts.length; i++) {
+    if (patternParts[i].startsWith(":")) continue; // wildcard
+    if (patternParts[i] !== actualParts[i]) return false;
+  }
+
+  return true;
+}

package/src/metering/types.ts

@@ -0,0 +1,25 @@
+export interface MeterRecord {
+  id: string;
+  timestamp: number;
+  domain: string;
+  version: string;
+  endpoint: string;
+  agentId: string;
+  developerId?: string;
+  cost: number;
+  currency: string;
+}
+
+export interface MeterQuery {
+  domain?: string;
+  agentId?: string;
+  developerId?: string;
+  from?: number;
+  to?: number;
+}
+
+export interface MeterStore {
+  record(entry: MeterRecord): Promise<void>;
+  query(filter: MeterQuery): Promise<MeterRecord[]>;
+  sum(filter: MeterQuery): Promise<{ total: number; currency: string }>;
+}