keymaker-cli 0.1.0

package/src/extract.js

@@ -0,0 +1,99 @@
+import { deref } from "./parse.js";
+
+const METHODS = ["get", "post", "put", "patch", "delete"];
+
+export function extractOperations(spec, { include, exclude } = {}) {
+  const ops = [];
+  const warnings = [];
+  for (const [path, rawPathItem] of Object.entries(spec.paths ?? {})) {
+    const pathItem = rawPathItem ?? {};
+    const sharedParams = deref(spec, pathItem.parameters) ?? [];
+    for (const method of METHODS) {
+      if (!pathItem[method]) continue;
+      const op = deref(spec, pathItem[method]);
+      const name = (op.operationId || `${method}_${path}`)
+        .replace(/[^a-zA-Z0-9_-]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 64);
+      if (include?.length && !include.some((p) => name.toLowerCase().includes(p.toLowerCase()))) continue;
+      if (exclude?.length && exclude.some((p) => name.toLowerCase().includes(p.toLowerCase()))) continue;
+
+      const properties = {};
+      const required = new Set();
+      const paramLocs = {};
+      for (const p of [...sharedParams, ...(op.parameters ?? [])]) {
+        if (!p?.name) continue;
+        // Swagger 2.0: the whole request body arrives as a single in:"body" parameter
+        if (p.in === "body") {
+          const schema = p.schema ?? {};
+          if (schema.type === "object" && schema.properties) {
+            for (const [k, v] of Object.entries(schema.properties)) {
+              if (properties[k]) continue;
+              properties[k] = v;
+              paramLocs[k] = "body";
+              if ((schema.required ?? []).includes(k)) required.add(k);
+            }
+          } else {
+            properties.body = schema;
+            paramLocs.body = "body";
+            if (p.required) required.add("body");
+          }
+          continue;
+        }
+        // Swagger 2.0 formData fields are body fields for our purposes
+        if (p.in === "formData") {
+          properties[p.name] = { type: p.type ?? "string", ...(p.description ? { description: p.description } : {}) };
+          paramLocs[p.name] = "body";
+          if (p.required) required.add(p.name);
+          continue;
+        }
+        properties[p.name] = {
+          ...(p.schema ?? { type: "string" }),
+          ...(p.description || p.schema?.description
+            ? { description: p.description ?? p.schema.description }
+            : {}),
+        };
+        if (p.required || p.in === "path") required.add(p.name);
+        paramLocs[p.name] = p.in;
+        if (!p.description && !p.schema?.description) {
+          warnings.push(`${name}: parameter "${p.name}" has no description`);
+        }
+      }
+
+      const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+      if (bodySchema) {
+        if (bodySchema.type === "object" && bodySchema.properties) {
+          for (const [k, v] of Object.entries(bodySchema.properties)) {
+            if (properties[k]) continue;
+            properties[k] = v;
+            paramLocs[k] = "body";
+            if ((bodySchema.required ?? []).includes(k)) required.add(k);
+          }
+        } else {
+          properties.body = bodySchema;
+          paramLocs.body = "body";
+        }
+      }
+
+      const description = [op.summary, op.description].filter(Boolean).join(" — ");
+      if (!description) {
+        warnings.push(`${name}: no summary or description — agents pick tools by docs; write one`);
+      }
+
+      ops.push({
+        name,
+        description: description || `${method.toUpperCase()} ${path}`,
+        method: method.toUpperCase(),
+        path,
+        paramLocs,
+        inputSchema: {
+          type: "object",
+          properties,
+          ...(required.size ? { required: [...required] } : {}),
+        },
+        tags: op.tags ?? [],
+      });
+    }
+  }
+  return { ops, warnings };
+}

package/src/gateway.js

@@ -0,0 +1,246 @@
+import { readFile } from "node:fs/promises";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { join } from "node:path";
+import { verifyAttestation } from "./attest.js";
+import { handleMcpRequest } from "./mcp-http.js";
+import { createBilling } from "./billing.js";
+import { hashKey, findByKey, readKeys, writeKeys } from "./store.js";
+
+function readJson(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => (data += chunk));
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve({});
+      }
+    });
+  });
+}
+
+const GATEWAY_PATHS = new Set(["/auth.md", "/.well-known/auth.md", "/llms.txt", "/mcp"]);
+
+/**
+ * Mountable agent gateway: serves /auth.md, /.well-known/auth.md, /llms.txt,
+ * /agent-auth*, and /mcp from inside any node HTTP app.
+ *
+ * const gateway = await keymakerGateway({ dir: "./agent-ready" });
+ * // plain node:  if (await gateway(req, res)) return;
+ * // express:     app.use(gateway.express());
+ *
+ * Returns true if the request was handled.
+ */
+export async function keymakerGateway({ dir }) {
+  let config = {};
+  try {
+    config = JSON.parse(await readFile(join(dir, "signup.config.json"), "utf8"));
+  } catch {}
+  let mcpMeta = null;
+  try {
+    mcpMeta = JSON.parse(await readFile(join(dir, "tools.json"), "utf8"));
+  } catch {}
+  const billing = createBilling(config.billing);
+
+  const registrationLimit = config.registrations_per_minute_per_ip ?? 10;
+  const verifyLimit = config.verifies_per_minute_per_key ?? 120;
+  const regHits = new Map();
+  const verifyHits = new Map();
+  const allow = (map, id, limit) => {
+    const now = Date.now();
+    const recent = (map.get(id) ?? []).filter((t) => t > now - 60_000);
+    if (recent.length >= limit) return false;
+    recent.push(now);
+    map.set(id, recent);
+    return true;
+  };
+
+  // keys.json on disk is the source of truth — the vendor's API process
+  // (keymakerAuth middleware) reads and writes it too. Raw keys are never
+  // stored; records hold a SHA-256 hash plus a display prefix.
+  const load = () => readKeys(dir);
+  const save = (keys) => writeKeys(dir, keys);
+  const safeEqual = (a, b) => {
+    const ba = Buffer.from(String(a ?? ""));
+    const bb = Buffer.from(String(b ?? ""));
+    return ba.length === bb.length && timingSafeEqual(ba, bb);
+  };
+
+  const handler = async (req, res) => {
+    const url = new URL(req.url, "http://localhost");
+    const p = url.pathname;
+    if (!GATEWAY_PATHS.has(p) && !p.startsWith("/agent-auth")) return false;
+
+    const send = (code, body, type = "application/json") => {
+      res.writeHead(code, { "content-type": type });
+      res.end(type === "application/json" ? JSON.stringify(body, null, 2) : body);
+    };
+    try {
+      if (req.method === "GET" && (p === "/auth.md" || p === "/.well-known/auth.md")) {
+        send(200, await readFile(join(dir, "auth.md"), "utf8"), "text/markdown");
+        return true;
+      }
+      if (req.method === "GET" && p === "/llms.txt") {
+        send(200, await readFile(join(dir, "llms.txt"), "utf8"), "text/plain");
+        return true;
+      }
+      if (req.method === "POST" && p === "/agent-auth") {
+        if (!allow(regHits, req.socket.remoteAddress ?? "?", registrationLimit)) {
+          send(429, { error: "registration rate limit exceeded; retry in a minute" });
+          return true;
+        }
+        const body = await readJson(req);
+        let attResult = null;
+        if (body.attestation) attResult = await verifyAttestation(body.attestation, config);
+        const verified = Boolean(attResult?.verified);
+        const keys = await load();
+        const keyId = `key_${randomBytes(6).toString("hex")}`;
+        const apiKey = `ak_${randomBytes(24).toString("hex")}`;
+        const record = {
+          key_id: keyId,
+          key_hash: hashKey(apiKey),
+          key_prefix: apiKey.slice(0, 10),
+          client_name: String(body.client_name ?? "unnamed-agent").slice(0, 100),
+          scopes: Array.isArray(body.scopes) && body.scopes.length ? body.scopes.map(String) : ["read"],
+          status: verified ? "agent_verified" : "unclaimed",
+          attestation_mode: attResult?.mode ?? null,
+          created_at: new Date().toISOString(),
+          expires_at: verified ? null : new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+          claim_token: verified ? null : `ct_${randomBytes(12).toString("hex")}`,
+          usage: 0,
+        };
+        if (billing) {
+          try {
+            const b = await billing.onRegister(record, body);
+            if (b?.customer_id) record.billing_customer_id = b.customer_id;
+          } catch {}
+        }
+        keys[keyId] = record;
+        await save(keys);
+        const { claim_token, key_hash, ...pub } = record;
+        send(201, {
+          ...pub,
+          api_key: apiKey,
+          key_storage: "hashed — this is the only time the full key is shown",
+          ...(claim_token ? { claim_token, claim_endpoint: "/agent-auth/claim" } : {}),
+          ...(attResult && !attResult.verified ? { attestation_error: attResult.reason } : {}),
+        });
+        return true;
+      }
+      if (req.method === "POST" && p === "/agent-auth/claim") {
+        const { claim_token } = await readJson(req);
+        const keys = await load();
+        const rec = Object.values(keys).find((k) => k.claim_token && k.claim_token === claim_token);
+        if (!rec) {
+          send(404, { error: "unknown claim token" });
+          return true;
+        }
+        rec.status = "claimed";
+        rec.expires_at = null;
+        rec.claim_token = null;
+        await save(keys);
+        send(200, { key_id: rec.key_id, status: rec.status });
+        return true;
+      }
+      if (req.method === "POST" && p === "/agent-auth/verify") {
+        const { api_key } = await readJson(req);
+        if (!allow(verifyHits, String(api_key ?? "?"), verifyLimit)) {
+          send(429, { error: "verify rate limit exceeded" });
+          return true;
+        }
+        const keys = await load();
+        const rec = findByKey(keys, api_key);
+        const expired = rec?.expires_at && Date.parse(rec.expires_at) < Date.now();
+        if (!rec || expired || rec.revoked) {
+          send(401, { valid: false });
+          return true;
+        }
+        rec.usage += 1;
+        await save(keys);
+        billing?.onMeter(rec).catch(() => {});
+        send(200, {
+          valid: true,
+          key_id: rec.key_id,
+          scopes: rec.scopes,
+          status: rec.status,
+          usage: rec.usage,
+        });
+        return true;
+      }
+      if (req.method === "GET" && p === "/agent-auth/keys") {
+        send(
+          200,
+          Object.values(await load()).map(({ key_hash, claim_token, ...rest }) => rest)
+        );
+        return true;
+      }
+      if (req.method === "POST" && p === "/agent-auth/revoke") {
+        if (!config.admin_token || !safeEqual(req.headers["x-admin-token"], config.admin_token)) {
+          send(401, { error: "admin token required (x-admin-token header)" });
+          return true;
+        }
+        const { key_id } = await readJson(req);
+        const keys = await load();
+        if (!keys[key_id]) {
+          send(404, { error: "unknown key_id" });
+          return true;
+        }
+        keys[key_id].revoked = true;
+        await save(keys);
+        send(200, { key_id, revoked: true });
+        return true;
+      }
+      if (p === "/mcp") {
+        if (!mcpMeta) {
+          send(501, { error: "no tools.json in this directory; re-run keymaker generate" });
+          return true;
+        }
+        if (req.method !== "POST") {
+          send(405, { error: "POST only (stateless MCP)" });
+          return true;
+        }
+        const header = req.headers.authorization ?? "";
+        const token = header.startsWith("Bearer ") ? header.slice(7) : null;
+        const keys = await load();
+        const rec = findByKey(keys, token);
+        const expired = rec?.expires_at && Date.parse(rec.expires_at) < Date.now();
+        if (!rec || expired || rec.revoked) {
+          send(401, { error: "valid bearer key required; register via POST /agent-auth (see /auth.md)" });
+          return true;
+        }
+        const body = await readJson(req);
+        await handleMcpRequest(req, res, body, {
+          meta: mcpMeta,
+          // api_key: the presented raw token — records only store its hash, and
+          // the proxy needs it to forward the agent's identity upstream.
+          agent: { ...rec, api_key: token },
+          meter: async () => {
+            const fresh = await load();
+            if (fresh[rec.key_id]) {
+              fresh[rec.key_id].usage += 1;
+              await save(fresh);
+              billing?.onMeter(fresh[rec.key_id]).catch(() => {});
+            }
+          },
+        });
+        return true;
+      }
+      send(404, { error: "not found", hint: "GET /auth.md for agent registration instructions" });
+      return true;
+    } catch (err) {
+      send(500, { error: String(err?.message ?? err) });
+      return true;
+    }
+  };
+
+  handler.express = () => (req, res, next) => {
+    handler(req, res)
+      .then((handled) => {
+        if (!handled) next();
+      })
+      .catch(next);
+  };
+
+  return handler;
+}

package/src/gen-authmd.js

@@ -0,0 +1,63 @@
+export function renderAuthMd({ spec, serviceUrl }) {
+  const title = spec.info?.title ?? "API";
+  return `# Agent registration — ${title}
+
+> Machine-readable instructions for AI agents to register and obtain scoped API keys with no human in the loop. Generated by keymaker. Pattern-compatible with auth.md (https://workos.com/auth-md); served at /auth.md and /.well-known/auth.md.
+
+## Register
+
+\`\`\`
+POST ${serviceUrl}/agent-auth
+Content-Type: application/json
+
+{
+  "client_name": "<your agent's name>",
+  "scopes": ["read"],
+  "attestation": "<optional: ID-JAG token from your agent platform>"
+}
+\`\`\`
+
+Response \`201\`:
+
+\`\`\`json
+{
+  "key_id": "key_…",
+  "api_key": "ak_…",
+  "status": "unclaimed | agent_verified",
+  "scopes": ["read"],
+  "expires_at": "<ISO timestamp or null>",
+  "claim_token": "ct_…",
+  "claim_url": "…"
+}
+\`\`\`
+
+- **With a valid platform attestation** the key is issued as \`agent_verified\` and does not expire.
+- **Without one** the key is temporary (60 minutes) — enough to try the API — and becomes permanent when a human claims it:
+
+\`\`\`
+POST ${serviceUrl}/agent-auth/claim
+{ "claim_token": "ct_…" }
+\`\`\`
+
+Use the key as \`Authorization: Bearer ak_…\` on every API request.
+
+## Scopes
+
+- \`read\` — non-mutating endpoints (GET)
+- \`write\` — mutating endpoints (POST/PUT/PATCH/DELETE)
+
+## For the API's backend (verification + metering)
+
+\`\`\`
+POST ${serviceUrl}/agent-auth/verify
+{ "api_key": "ak_…" }
+\`\`\`
+
+Returns \`{ "valid": true, "scopes": […], "status": "…", "usage": <request count> }\` and increments the usage meter. \`401\` if unknown or expired.
+
+## Discovering this API
+
+- [llms.txt](${serviceUrl}/llms.txt) — agent-readable API overview
+- MCP server available (stdio): ask the vendor for connection details, or run the generated \`mcp-server.mjs\`
+`;
+}

package/src/gen-llms.js

@@ -0,0 +1,41 @@
+export function renderLlmsTxt({ spec, ops, baseUrl, serviceUrl }) {
+  const title = spec.info?.title ?? "API";
+  const lines = [`# ${title}`, ""];
+  if (spec.info?.description) {
+    lines.push(`> ${spec.info.description.trim().split("\n")[0]}`, "");
+  }
+  lines.push(`Base URL: ${baseUrl}`, "");
+
+  const schemes = Object.entries(spec.components?.securitySchemes ?? {});
+  if (schemes.length) {
+    lines.push("## Authentication", "");
+    for (const [name, s] of schemes) {
+      lines.push(
+        `- ${name}: ${s.type}${s.scheme ? ` (${s.scheme})` : ""}${s.description ? ` — ${s.description}` : ""}`
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## Agent signup",
+    "",
+    `- [auth.md](${serviceUrl}/auth.md): Agents can register and obtain a scoped API key programmatically — no human required. POST ${serviceUrl}/agent-auth`,
+    ""
+  );
+
+  const byTag = new Map();
+  for (const op of ops) {
+    const tag = op.tags[0] ?? "Endpoints";
+    if (!byTag.has(tag)) byTag.set(tag, []);
+    byTag.get(tag).push(op);
+  }
+  for (const [tag, list] of byTag) {
+    lines.push(`## ${tag}`, "");
+    for (const op of list) {
+      lines.push(`- ${op.method} ${op.path} (${op.name}): ${op.description}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}

package/src/gen-mcp.js

@@ -0,0 +1,82 @@
+export function toTools(ops) {
+  return ops.map(({ name, description, method, path, paramLocs, inputSchema }) => ({
+    name,
+    description,
+    method,
+    path,
+    paramLocs,
+    inputSchema,
+  }));
+}
+
+export function renderMcpServer({ title, version, baseUrl, ops }) {
+  const tools = toTools(ops);
+
+  return `#!/usr/bin/env node
+// Generated by keymaker — MCP server for ${title}
+// Run: node mcp-server.mjs   (stdio transport; point any MCP client at it)
+// Env: API_BASE_URL (default ${baseUrl}), API_KEY (sent as Bearer token)
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const BASE_URL = (process.env.API_BASE_URL ?? ${JSON.stringify(baseUrl)}).replace(/\\/$/, "");
+const API_KEY = process.env.API_KEY ?? "";
+
+const TOOLS = ${JSON.stringify(tools, null, 2)};
+
+const server = new Server(
+  { name: ${JSON.stringify(`${title} (agent-ready)`)}, version: ${JSON.stringify(version)} },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const tool = TOOLS.find((t) => t.name === request.params.name);
+  if (!tool) {
+    return { content: [{ type: "text", text: \`Unknown tool: \${request.params.name}\` }], isError: true };
+  }
+  const args = request.params.arguments ?? {};
+  let path = tool.path;
+  const query = new URLSearchParams();
+  const headers = { "content-type": "application/json" };
+  if (API_KEY) headers.authorization = \`Bearer \${API_KEY}\`;
+  const body = {};
+  let hasBody = false;
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null) continue;
+    const loc = tool.paramLocs[key];
+    if (loc === "path") path = path.replace(\`{\${key}}\`, encodeURIComponent(String(value)));
+    else if (loc === "query") query.set(key, String(value));
+    else if (loc === "header") headers[key.toLowerCase()] = String(value);
+    else {
+      if (key === "body" && typeof value === "object") Object.assign(body, value);
+      else body[key] = value;
+      hasBody = true;
+    }
+  }
+  const url = \`\${BASE_URL}\${path}\${[...query].length ? \`?\${query}\` : ""}\`;
+  try {
+    const res = await fetch(url, {
+      method: tool.method,
+      headers,
+      ...(hasBody ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    return {
+      content: [{ type: "text", text: \`HTTP \${res.status} \${tool.method} \${url}\\n\${text.slice(0, 20000)}\` }],
+      isError: res.status >= 400,
+    };
+  } catch (err) {
+    return { content: [{ type: "text", text: \`Request failed: \${err.message}\` }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(\`[keymaker] MCP server ready — \${TOOLS.length} tools proxying \${BASE_URL}\`);
+`;
+}

package/src/index.js

@@ -0,0 +1,10 @@
+export { startSignupServer } from "./serve.js";
+export { keymakerGateway } from "./gateway.js";
+export { keymakerAuth } from "./middleware.js";
+export { createBilling } from "./billing.js";
+export { verifyAttestation } from "./attest.js";
+export { loadSpec, deref } from "./parse.js";
+export { hashKey, findByKey, readKeys, writeKeys } from "./store.js";
+export { extractOperations } from "./extract.js";
+export { scoreSpec } from "./score.js";
+export { checkSite } from "./doctor.js";

package/src/mcp-http.js

@@ -0,0 +1,85 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const READ_METHODS = new Set(["GET", "HEAD"]);
+
+function allowedTools(tools, scopes) {
+  const canWrite = scopes.includes("write");
+  const canRead = canWrite || scopes.includes("read");
+  return tools.filter((t) => (READ_METHODS.has(t.method) ? canRead : canWrite));
+}
+
+async function proxyCall(tool, args, baseUrl, agentKey) {
+  let path = tool.path;
+  const query = new URLSearchParams();
+  // Forward the agent's own key upstream so the vendor's API (e.g. keymakerAuth
+  // middleware) sees the same identity that authenticated at /mcp.
+  const headers = { "content-type": "application/json", authorization: `Bearer ${agentKey}` };
+  const body = {};
+  let hasBody = false;
+  for (const [key, value] of Object.entries(args ?? {})) {
+    if (value === undefined || value === null) continue;
+    const loc = tool.paramLocs[key];
+    if (loc === "path") path = path.replace(`{${key}}`, encodeURIComponent(String(value)));
+    else if (loc === "query") query.set(key, String(value));
+    else if (loc === "header") headers[key.toLowerCase()] = String(value);
+    else {
+      if (key === "body" && typeof value === "object") Object.assign(body, value);
+      else body[key] = value;
+      hasBody = true;
+    }
+  }
+  const url = `${baseUrl}${path}${[...query].length ? `?${query}` : ""}`;
+  const res = await fetch(url, {
+    method: tool.method,
+    headers,
+    ...(hasBody ? { body: JSON.stringify(body) } : {}),
+  });
+  const text = await res.text();
+  return {
+    content: [{ type: "text", text: `HTTP ${res.status} ${tool.method} ${url}\n${text.slice(0, 20000)}` }],
+    isError: res.status >= 400,
+  };
+}
+
+/**
+ * Handle one HTTP request to /mcp (stateless Streamable HTTP).
+ * `agent` is the authenticated key record; tool visibility and calls are
+ * scope-filtered, and `meter()` is invoked on every successful tool call.
+ */
+export async function handleMcpRequest(req, res, body, { meta, agent, meter }) {
+  const visible = allowedTools(meta.tools, agent.scopes);
+  const server = new Server(
+    { name: `${meta.title} (agent-ready)`, version: meta.version ?? "0.0.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: visible.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = visible.find((t) => t.name === request.params.name);
+    if (!tool) {
+      return {
+        content: [{ type: "text", text: `Unknown tool or insufficient scope: ${request.params.name}` }],
+        isError: true,
+      };
+    }
+    const result = await proxyCall(tool, request.params.arguments, meta.baseUrl, agent.api_key);
+    // When the upstream API is keymaker-protected, its middleware already meters
+    // this key; meter at the gateway only for hosted-only setups that opt in.
+    if (!result.isError && meta.meter_at_gateway) await meter();
+    return result;
+  });
+
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true,
+  });
+  res.on("close", () => {
+    transport.close();
+    server.close();
+  });
+  await server.connect(transport);
+  await transport.handleRequest(req, res, body);
+}