@nkmc/gateway 0.1.0

package/src/registry/memory-store.ts

@@ -0,0 +1,101 @@
+import type { RegistryStore, SearchResult, ServiceRecord, ServiceSummary, VersionSummary } from "./types.js";
+
+export class MemoryRegistryStore implements RegistryStore {
+  // key = "domain@version"
+  private records = new Map<string, ServiceRecord>();
+
+  private key(domain: string, version: string): string {
+    return `${domain}@${version}`;
+  }
+
+  async get(domain: string): Promise<ServiceRecord | null> {
+    for (const record of this.records.values()) {
+      if (record.domain === domain && record.isDefault) return record;
+    }
+    return null;
+  }
+
+  async getVersion(domain: string, version: string): Promise<ServiceRecord | null> {
+    return this.records.get(this.key(domain, version)) ?? null;
+  }
+
+  async listVersions(domain: string): Promise<VersionSummary[]> {
+    const versions: VersionSummary[] = [];
+    for (const record of this.records.values()) {
+      if (record.domain === domain) {
+        versions.push({
+          version: record.version,
+          status: record.status,
+          isDefault: record.isDefault,
+          createdAt: record.createdAt,
+          updatedAt: record.updatedAt,
+        });
+      }
+    }
+    return versions.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async put(domain: string, record: ServiceRecord): Promise<void> {
+    this.records.set(this.key(domain, record.version), record);
+  }
+
+  async delete(domain: string): Promise<void> {
+    const keysToDelete: string[] = [];
+    for (const [key, record] of this.records.entries()) {
+      if (record.domain === domain) keysToDelete.push(key);
+    }
+    for (const key of keysToDelete) {
+      this.records.delete(key);
+    }
+  }
+
+  async list(): Promise<ServiceSummary[]> {
+    const results: ServiceSummary[] = [];
+    for (const record of this.records.values()) {
+      if (record.isDefault) results.push(toSummary(record));
+    }
+    return results;
+  }
+
+  async search(query: string): Promise<SearchResult[]> {
+    const q = query.toLowerCase();
+    const results: SearchResult[] = [];
+
+    for (const record of this.records.values()) {
+      if (!record.isDefault) continue;
+
+      const nameMatch =
+        record.name.toLowerCase().includes(q) ||
+        record.description.toLowerCase().includes(q);
+
+      const matched = record.endpoints.filter(
+        (e) =>
+          e.description.toLowerCase().includes(q) ||
+          e.method.toLowerCase().includes(q) ||
+          e.path.toLowerCase().includes(q),
+      );
+
+      if (nameMatch || matched.length > 0) {
+        results.push({
+          ...toSummary(record),
+          matchedEndpoints: matched.map((e) => ({
+            method: e.method,
+            path: e.path,
+            description: e.description,
+          })),
+        });
+      }
+    }
+
+    return results;
+  }
+}
+
+function toSummary(record: ServiceRecord): ServiceSummary {
+  return {
+    domain: record.domain,
+    name: record.name,
+    description: record.description,
+    isFirstParty: record.isFirstParty,
+  };
+}

package/src/registry/openapi-compiler.ts

@@ -0,0 +1,284 @@
+import YAML from "yaml";
+import type { ServiceRecord, EndpointRecord, EndpointPricing, EndpointParam, SchemaProperty } from "./types.js";
+import type { HttpResource } from "@nkmc/agent-fs";
+
+export interface CompileOptions {
+  domain: string;
+  version?: string;
+  isFirstParty?: boolean;
+}
+
+export interface CompileResult {
+  record: ServiceRecord;
+  resources: HttpResource[];
+  skillMd: string;
+}
+
+/** Extract basePath from OpenAPI servers[0].url (e.g. "/client/v4" from "https://api.cloudflare.com/client/v4") */
+export function extractBasePath(spec: any): string {
+  const servers = spec.servers;
+  if (!Array.isArray(servers) || servers.length === 0) return "";
+  const serverUrl = servers[0]?.url;
+  if (!serverUrl || typeof serverUrl !== "string") return "";
+  try {
+    // Handle relative URLs
+    if (serverUrl.startsWith("/")) {
+      return serverUrl.replace(/\/+$/, "");
+    }
+    const parsed = new URL(serverUrl);
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    return pathname || "";
+  } catch {
+    return "";
+  }
+}
+
+/** Resolve a $ref pointer like "#/components/schemas/Pet" */
+function resolveRef(spec: any, ref: string): any {
+  if (!ref.startsWith("#/")) return undefined;
+  const parts = ref.slice(2).split("/");
+  let current = spec;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/** Resolve a schema, following $ref if present (one level only) */
+function resolveSchema(spec: any, schema: any): any {
+  if (!schema) return undefined;
+  if (schema.$ref) return resolveRef(spec, schema.$ref);
+  return schema;
+}
+
+/** Extract top-level properties from a JSON Schema object */
+function extractProperties(spec: any, schema: any): SchemaProperty[] {
+  const resolved = resolveSchema(spec, schema);
+  if (!resolved || resolved.type !== "object" || !resolved.properties) return [];
+  const requiredSet = new Set<string>(resolved.required ?? []);
+  const props: SchemaProperty[] = [];
+  for (const [name, prop] of Object.entries(resolved.properties as Record<string, any>)) {
+    const p = resolveSchema(spec, prop) ?? prop;
+    props.push({
+      name,
+      type: p.type ?? (p.enum ? "enum" : "unknown"),
+      required: requiredSet.has(name),
+      ...(p.description ? { description: p.description } : {}),
+    });
+  }
+  return props;
+}
+
+/** Extract parameters from an OpenAPI operation */
+function extractParams(spec: any, operation: any): EndpointParam[] | undefined {
+  const params = operation.parameters;
+  if (!Array.isArray(params) || params.length === 0) return undefined;
+  const result: EndpointParam[] = [];
+  for (const raw of params) {
+    const p = resolveSchema(spec, raw) ?? raw;
+    if (!p.name || !p.in) continue;
+    if (!["path", "query", "header"].includes(p.in)) continue;
+    const schema = resolveSchema(spec, p.schema) ?? p.schema;
+    result.push({
+      name: p.name,
+      in: p.in as "path" | "query" | "header",
+      required: !!p.required,
+      type: schema?.type ?? "string",
+      ...(p.description ? { description: p.description } : {}),
+    });
+  }
+  return result.length > 0 ? result : undefined;
+}
+
+/** Extract requestBody from an OpenAPI operation */
+function extractRequestBody(spec: any, operation: any): EndpointRecord["requestBody"] {
+  const body = resolveSchema(spec, operation.requestBody);
+  if (!body?.content) return undefined;
+  const jsonContent = body.content["application/json"];
+  if (!jsonContent?.schema) return undefined;
+  const properties = extractProperties(spec, jsonContent.schema);
+  if (properties.length === 0) return undefined;
+  return {
+    contentType: "application/json",
+    required: !!body.required,
+    properties,
+  };
+}
+
+/** Extract 2xx responses from an OpenAPI operation */
+function extractResponses(spec: any, operation: any): EndpointRecord["responses"] {
+  const responses = operation.responses;
+  if (!responses || typeof responses !== "object") return undefined;
+  const result: NonNullable<EndpointRecord["responses"]> = [];
+  for (const [code, raw] of Object.entries(responses as Record<string, any>)) {
+    const status = parseInt(code, 10);
+    if (isNaN(status) || status < 200 || status >= 300) continue;
+    const resp = resolveSchema(spec, raw) ?? raw;
+    const jsonContent = resp?.content?.["application/json"];
+    const properties = jsonContent?.schema ? extractProperties(spec, jsonContent.schema) : undefined;
+    result.push({
+      status,
+      description: resp?.description ?? "",
+      ...(properties && properties.length > 0 ? { properties } : {}),
+    });
+  }
+  return result.length > 0 ? result : undefined;
+}
+
+// Compile an OpenAPI spec (parsed JSON object) into a ServiceRecord + HttpResources
+export function compileOpenApiSpec(spec: any, options: CompileOptions): CompileResult {
+  const info = spec.info ?? {};
+  const name = info.title ?? options.domain;
+  const description = info.description ?? "";
+  const version = options.version ?? info.version ?? "1.0";
+  const basePath = extractBasePath(spec);
+
+  const endpoints: EndpointRecord[] = [];
+  const resources: HttpResource[] = [];
+  const resourcePaths = new Map<string, HttpResource>();
+
+  // Extract endpoints from paths
+  const paths = spec.paths ?? {};
+  for (const [path, methods] of Object.entries(paths)) {
+    if (typeof methods !== "object" || methods === null) continue;
+    for (const [method, op] of Object.entries(methods as Record<string, any>)) {
+      if (!["get", "post", "put", "patch", "delete"].includes(method)) continue;
+      const operation = op as any;
+      const parameters = extractParams(spec, operation);
+      const requestBody = extractRequestBody(spec, operation);
+      const responses = extractResponses(spec, operation);
+      endpoints.push({
+        method: method.toUpperCase(),
+        path,
+        description: operation.summary ?? operation.operationId ?? `${method.toUpperCase()} ${path}`,
+        ...(parameters ? { parameters } : {}),
+        ...(requestBody ? { requestBody } : {}),
+        ...(responses ? { responses } : {}),
+      });
+    }
+
+    // Infer resources from path patterns like /resources or /resources/{id}
+    const segments = path.split("/").filter(Boolean);
+    if (segments.length >= 1) {
+      const resourceName = segments[0];
+      if (!resourcePaths.has(resourceName) && !resourceName.startsWith("{")) {
+        resourcePaths.set(resourceName, {
+          name: resourceName,
+          apiPath: `/${resourceName}`,
+        });
+      }
+    }
+  }
+
+  for (const r of resourcePaths.values()) {
+    resources.push(r);
+  }
+
+  // Generate skill.md
+  const skillMd = generateSkillMd(name, version, description, endpoints, resources);
+
+  const now = Date.now();
+  const record: ServiceRecord = {
+    domain: options.domain,
+    name,
+    description,
+    version,
+    roles: ["agent"],
+    skillMd,
+    endpoints,
+    isFirstParty: options.isFirstParty ?? false,
+    createdAt: now,
+    updatedAt: now,
+    status: "active",
+    isDefault: true,
+    source: { type: "openapi", ...(basePath ? { basePath } : {}) },
+  };
+
+  return { record, resources, skillMd };
+}
+
+// Fetch a remote OpenAPI spec and compile
+export async function fetchAndCompile(
+  specUrl: string,
+  options: CompileOptions,
+  fetchFn: typeof globalThis.fetch = globalThis.fetch.bind(globalThis),
+): Promise<CompileResult> {
+  const resp = await fetchFn(specUrl);
+  if (!resp.ok) throw new Error(`Failed to fetch spec: ${resp.status} ${resp.statusText}`);
+  const text = await resp.text();
+  const spec = parseSpec(specUrl, resp.headers.get("content-type") ?? "", text);
+  const result = compileOpenApiSpec(spec, options);
+  const basePath = result.record.source?.basePath;
+  result.record.source = { type: "openapi", url: specUrl, ...(basePath ? { basePath } : {}) };
+  return result;
+}
+
+/** Detect format from content-type or URL extension and parse accordingly */
+function parseSpec(url: string, contentType: string, text: string): any {
+  const isJson =
+    contentType.includes("json") ||
+    url.endsWith(".json") ||
+    text.trimStart().startsWith("{");
+  if (isJson) return JSON.parse(text);
+  return YAML.parse(text);
+}
+
+function propsTable(props: SchemaProperty[]): string {
+  let t = "| name | type | required |\n|------|------|----------|\n";
+  for (const p of props) {
+    t += `| ${p.name} | ${p.type} | ${p.required ? "*" : ""} |\n`;
+  }
+  return t;
+}
+
+function generateSkillMd(
+  name: string,
+  version: string,
+  description: string,
+  endpoints: EndpointRecord[],
+  resources: HttpResource[],
+): string {
+  let md = `---\nname: "${name}"\ngateway: nkmc\nversion: "${version}"\nroles: [agent]\n---\n\n`;
+  md += `# ${name}\n\n${description}\n\n`;
+  if (resources.length > 0) {
+    md += `## Schema\n\n`;
+    for (const r of resources) {
+      md += `### ${r.name} (public)\n\n`;
+    }
+  }
+  if (endpoints.length > 0) {
+    md += `## API\n\n`;
+    for (const ep of endpoints) {
+      md += `### ${ep.description}\n\n`;
+      md += `\`${ep.method} ${ep.path}\`\n\n`;
+
+      if (ep.parameters && ep.parameters.length > 0) {
+        md += "**Parameters:**\n\n";
+        md += "| name | in | type | required |\n|------|-----|------|----------|\n";
+        for (const p of ep.parameters) {
+          md += `| ${p.name} | ${p.in} | ${p.type} | ${p.required ? "*" : ""} |\n`;
+        }
+        md += "\n";
+      }
+
+      if (ep.requestBody) {
+        const req = ep.requestBody;
+        md += `**Body** (${req.contentType}${req.required ? ", required" : ""}):\n\n`;
+        md += propsTable(req.properties);
+        md += "\n";
+      }
+
+      if (ep.responses && ep.responses.length > 0) {
+        for (const r of ep.responses) {
+          md += `**Response ${r.status}**${r.description ? `: ${r.description}` : ""}\n\n`;
+          if (r.properties && r.properties.length > 0) {
+            md += propsTable(r.properties);
+            md += "\n";
+          }
+        }
+      }
+    }
+  }
+  return md;
+}

package/src/registry/resolver.ts

@@ -0,0 +1,196 @@
+import { HttpBackend, RpcBackend, JsonRpcTransport } from "@nkmc/agent-fs";
+import type { AgentContext, Mount, FsBackend, HttpAuth } from "@nkmc/agent-fs";
+import type { JWK } from "jose";
+import { signJwt } from "@nkmc/core";
+import type { EndpointRecord, RegistryStore, SearchResult } from "./types.js";
+import { skillToHttpConfig, skillToRpcConfig } from "./skill-to-config.js";
+import { VirtualFileBackend } from "./virtual-files.js";
+import type { PeerGateway } from "../federation/types.js";
+import type { PeerClient } from "../federation/peer-client.js";
+import { PeerBackend } from "../federation/peer-backend.js";
+
+export interface RegistryResolverHooks {
+  onMiss: (path: string, addMount: (mount: Mount) => void, agent?: AgentContext) => Promise<boolean>;
+  listDomains: () => Promise<string[]>;
+  searchDomains: (query: string) => Promise<SearchResult[]>;
+  searchEndpoints: (domain: string, query: string) => Promise<Pick<EndpointRecord, "method" | "path" | "description">[]>;
+}
+
+export interface RegistryResolverOptions {
+  store: RegistryStore;
+  vault?: {
+    get(domain: string, developerId?: string): Promise<{ auth: HttpAuth } | null>;
+  };
+  gatewayPrivateKey?: JWK;
+  wrapVirtualFiles?: boolean;
+  peerStore?: { listPeers(): Promise<PeerGateway[]> };
+  peerClient?: PeerClient;
+}
+
+export function createRegistryResolver(
+  storeOrOptions: RegistryStore | RegistryResolverOptions,
+): RegistryResolverHooks {
+  const options: RegistryResolverOptions =
+    "get" in storeOrOptions && "put" in storeOrOptions
+      ? { store: storeOrOptions }
+      : storeOrOptions;
+  const { store, vault, gatewayPrivateKey } = options;
+
+  // cache key = "domain@version" or "domain"
+  const loaded = new Set<string>();
+
+  async function tryPeerFallback(
+    domain: string,
+    version: string | null,
+    addMount: (mount: Mount) => void,
+    agent?: AgentContext,
+  ): Promise<boolean> {
+    if (!options.peerClient || !options.peerStore) return false;
+
+    const peers = await options.peerStore.listPeers();
+    for (const peer of peers) {
+      // Skip peers whose advertised domains don't include this domain
+      if (peer.advertisedDomains.length > 0 && !peer.advertisedDomains.includes(domain)) {
+        continue;
+      }
+      const result = await options.peerClient.query(peer, domain);
+      if (result.available) {
+        const peerBackend = new PeerBackend(options.peerClient, peer, agent?.id ?? "anonymous");
+        const mountPath = version ? `/${domain}@${version}` : `/${domain}`;
+        addMount({ path: mountPath, backend: peerBackend });
+        return true;
+      }
+    }
+    return false;
+  }
+
+  async function onMiss(
+    path: string,
+    addMount: (mount: Mount) => void,
+    agent?: AgentContext,
+  ): Promise<boolean> {
+    const { domain, version } = extractDomainPath(path);
+    if (!domain) return false;
+
+    const cacheKey = version ? `${domain}@${version}` : domain;
+
+    // Fetch record first — we need it to determine auth mode
+    const record = version
+      ? await store.getVersion(domain, version)
+      : await store.get(domain);
+
+    // No local record → try peer gateways before giving up
+    if (!record) {
+      return tryPeerFallback(domain, version, addMount, agent);
+    }
+
+    const isNkmcJwt = record.authMode === "nkmc-jwt";
+
+    // For non-nkmc-jwt, use cache; nkmc-jwt needs fresh JWT per request
+    if (!isNkmcJwt && loaded.has(cacheKey)) return false;
+
+    // Reject sunset services
+    if (record.status === "sunset") return false;
+
+    // Resolve auth credentials
+    let auth: HttpAuth | undefined;
+    if (isNkmcJwt && gatewayPrivateKey && agent) {
+      const token = await signJwt(gatewayPrivateKey, {
+        sub: agent.id,
+        roles: agent.roles,
+        svc: domain,
+      }, { expiresIn: "5m" });
+      auth = { type: "bearer", token };
+    } else if (vault) {
+      const cred = await vault.get(domain, agent?.id);
+      if (cred) {
+        auth = cred.auth;
+      }
+    }
+
+    // Local record exists but no credential resolved (and not nkmc-jwt) → try peers
+    if (!auth && !isNkmcJwt) {
+      const peerMounted = await tryPeerFallback(domain, version, addMount, agent);
+      if (peerMounted) return true;
+    }
+
+    // Create backend based on source type
+    let backend: FsBackend;
+    if (record.source?.type === "jsonrpc" && record.source.rpc) {
+      const { resources } = skillToRpcConfig(record.source.rpc);
+      const headers: Record<string, string> = {};
+      if (auth) {
+        if (auth.type === "bearer") {
+          headers["Authorization"] = `${(auth as any).prefix ?? "Bearer"} ${auth.token}`;
+        } else if (auth.type === "api-key") {
+          headers[auth.header] = auth.key;
+        }
+      }
+      const transport = new JsonRpcTransport({ url: record.source.rpc.rpcUrl, headers });
+      backend = new RpcBackend({ transport, resources });
+    } else {
+      const config = skillToHttpConfig(record);
+      config.auth = auth;
+      backend = new HttpBackend(config);
+    }
+
+    let finalBackend: FsBackend = backend;
+    if (options.wrapVirtualFiles !== false) {
+      finalBackend = new VirtualFileBackend({ inner: backend, domain, store: options.store });
+    }
+
+    const mountPath = version ? `/${domain}@${version}` : `/${domain}`;
+    addMount({ path: mountPath, backend: finalBackend });
+
+    // Only cache non-nkmc-jwt mounts
+    if (!isNkmcJwt) {
+      loaded.add(cacheKey);
+    }
+    return true;
+  }
+
+  async function listDomains(): Promise<string[]> {
+    const summaries = await store.list();
+    return summaries.map((s) => s.domain);
+  }
+
+  async function searchDomains(query: string): Promise<SearchResult[]> {
+    return store.search(query);
+  }
+
+  async function searchEndpoints(
+    domain: string,
+    query: string,
+  ): Promise<Pick<EndpointRecord, "method" | "path" | "description">[]> {
+    const record = await store.get(domain);
+    if (!record) return [];
+    const q = query.toLowerCase();
+    return record.endpoints
+      .filter(
+        (e) =>
+          e.description.toLowerCase().includes(q) ||
+          e.method.toLowerCase().includes(q) ||
+          e.path.toLowerCase().includes(q),
+      )
+      .map((e) => ({ method: e.method, path: e.path, description: e.description }));
+  }
+
+  return { onMiss, listDomains, searchDomains, searchEndpoints };
+}
+
+export function extractDomainPath(path: string): { domain: string | null; version: string | null } {
+  const segments = path.split("/").filter(Boolean);
+  if (segments.length === 0) return { domain: null, version: null };
+
+  const first = segments[0];
+  // Parse @version: "api.cloudflare.com@v5" → { domain: "api.cloudflare.com", version: "v5" }
+  const atIndex = first.indexOf("@");
+  if (atIndex > 0) {
+    return {
+      domain: first.slice(0, atIndex),
+      version: first.slice(atIndex + 1),
+    };
+  }
+
+  return { domain: first, version: null };
+}