keymaker-cli 0.1.0

package/src/middleware.js

@@ -0,0 +1,66 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createBilling } from "./billing.js";
+import { findByKey, readKeys, writeKeys } from "./store.js";
+
+/**
+ * Drop-in auth middleware for the vendor's own API.
+ * Express-style (req, res, next) — also works with plain node:http
+ * (call without next; resolves true if the request may proceed).
+ *
+ * GET/HEAD/OPTIONS require the `read` or `write` scope; everything else requires `write`.
+ */
+export function keymakerAuth({ dir, rateLimitPerMinute = 60 } = {}) {
+  const hits = new Map();
+  const billingPromise = readFile(join(dir, "signup.config.json"), "utf8")
+    .then((raw) => createBilling(JSON.parse(raw).billing))
+    .catch(() => null);
+
+  return async function auth(req, res, next) {
+    const fail = (code, error) => {
+      if (res?.writeHead) {
+        res.writeHead(code, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error }));
+      }
+      return false;
+    };
+
+    const header = req.headers?.authorization ?? "";
+    const token = header.startsWith("Bearer ") ? header.slice(7) : null;
+    if (!token) return fail(401, "missing bearer token; see /auth.md to register");
+
+    const keys = await readKeys(dir);
+    const rec = findByKey(keys, token);
+    if (!rec) return fail(401, "unknown key; see /auth.md to register");
+    if (rec.revoked) return fail(401, "key revoked");
+    if (rec.expires_at && Date.parse(rec.expires_at) < Date.now()) {
+      return fail(401, "key expired; a human can make it permanent via /agent-auth/claim");
+    }
+
+    const mutating = !["GET", "HEAD", "OPTIONS"].includes(req.method);
+    if (mutating && !rec.scopes.includes("write")) return fail(403, "write scope required");
+    if (!mutating && !rec.scopes.includes("read") && !rec.scopes.includes("write")) {
+      return fail(403, "read scope required");
+    }
+
+    const now = Date.now();
+    const recent = (hits.get(rec.key_id) ?? []).filter((t) => t > now - 60_000);
+    if (recent.length >= rateLimitPerMinute) return fail(429, "rate limit exceeded");
+    recent.push(now);
+    hits.set(rec.key_id, recent);
+
+    rec.usage = (rec.usage ?? 0) + 1;
+    keys[rec.key_id] = rec;
+    await writeKeys(dir, keys);
+    billingPromise.then((b) => b?.onMeter(rec)).catch(() => {});
+
+    req.agent = {
+      key_id: rec.key_id,
+      client_name: rec.client_name,
+      scopes: rec.scopes,
+      status: rec.status,
+    };
+    if (typeof next === "function") next();
+    return true;
+  };
+}

package/src/parse.js

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import yaml from "js-yaml";
+
+export async function loadSpec(src) {
+  let text;
+  if (/^https?:\/\//.test(src)) {
+    const res = await fetch(src);
+    if (!res.ok) throw new Error(`Failed to fetch spec: HTTP ${res.status}`);
+    text = await res.text();
+  } else {
+    text = await readFile(src, "utf8");
+  }
+  const spec = yaml.load(text);
+  if (!spec || typeof spec !== "object" || (!spec.openapi && !spec.swagger)) {
+    throw new Error("Not an OpenAPI document (missing openapi/swagger field)");
+  }
+  return spec;
+}
+
+const MAX_DEPTH = 30;
+
+export function deref(spec, node, depth = 0) {
+  if (depth > MAX_DEPTH || node == null || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map((n) => deref(spec, n, depth + 1));
+  if (typeof node.$ref === "string" && node.$ref.startsWith("#/")) {
+    const target = node.$ref
+      .slice(2)
+      .split("/")
+      .reduce((acc, key) => acc?.[key.replaceAll("~1", "/").replaceAll("~0", "~")], spec);
+    if (!target) return { description: `Unresolved ref: ${node.$ref}` };
+    return deref(spec, target, depth + 1);
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(node)) out[k] = deref(spec, v, depth + 1);
+  return out;
+}

package/src/score.js

@@ -0,0 +1,60 @@
+export function scoreSpec(spec, ops, warnings) {
+  const totalOps = ops.length || 1;
+  const docWarn = warnings.filter((w) => w.includes("no summary or description")).length;
+  const paramWarn = warnings.filter((w) => w.includes("has no description")).length;
+  const totalParams = ops.reduce(
+    (n, o) => n + Object.values(o.paramLocs).filter((l) => l !== "body").length,
+    0
+  );
+
+  const parts = [];
+  parts.push({
+    name: "Operation docs",
+    got: Math.round((40 * (totalOps - docWarn)) / totalOps),
+    max: 40,
+    fix: docWarn ? `${docWarn} operation(s) missing summary/description` : null,
+  });
+  parts.push({
+    name: "Parameter docs",
+    got: totalParams ? Math.round((20 * Math.max(0, totalParams - paramWarn)) / totalParams) : 20,
+    max: 20,
+    fix: paramWarn ? `${paramWarn} parameter(s) undocumented` : null,
+  });
+  parts.push({
+    name: "API description",
+    got: spec.info?.description ? 10 : 0,
+    max: 10,
+    fix: spec.info?.description ? null : "add info.description",
+  });
+  const server = spec.servers?.[0]?.url ?? "";
+  const absolute = /^https?:\/\//.test(server);
+  parts.push({
+    name: "Absolute base URL",
+    got: absolute ? 10 : 0,
+    max: 10,
+    fix: absolute ? null : "servers[0].url should be an absolute https URL",
+  });
+  const schemes = Object.values(spec.components?.securitySchemes ?? {});
+  const schemesDescribed = schemes.length && schemes.every((s) => s.description);
+  parts.push({
+    name: "Documented auth",
+    got: schemes.length ? (schemesDescribed ? 10 : 5) : 0,
+    max: 10,
+    fix: !schemes.length
+      ? "declare components.securitySchemes"
+      : schemesDescribed
+        ? null
+        : "add descriptions to security schemes",
+  });
+  const tagged = ops.filter((o) => o.tags.length).length;
+  parts.push({
+    name: "Tagged operations",
+    got: Math.round((10 * tagged) / totalOps),
+    max: 10,
+    fix: tagged === totalOps ? null : "tag all operations for grouping",
+  });
+
+  const total = parts.reduce((n, p) => n + p.got, 0);
+  const grade = total >= 90 ? "A" : total >= 75 ? "B" : total >= 60 ? "C" : total >= 40 ? "D" : "F";
+  return { total, grade, parts };
+}

package/src/serve.js

@@ -0,0 +1,18 @@
+import { createServer } from "node:http";
+import { keymakerGateway } from "./gateway.js";
+
+export async function startSignupServer({ dir, port = 8787 }) {
+  const gateway = await keymakerGateway({ dir });
+  const server = createServer(async (req, res) => {
+    if (await gateway(req, res)) return;
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(
+      JSON.stringify({ error: "not found", hint: "GET /auth.md for agent registration instructions" })
+    );
+  });
+  await new Promise((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(port, resolve);
+  });
+  return server;
+}

package/src/store.js

@@ -0,0 +1,45 @@
+import { readFile, writeFile, rename } from "node:fs/promises";
+import { createHash, timingSafeEqual, randomBytes } from "node:crypto";
+import { join } from "node:path";
+
+/** API keys are stored only as SHA-256 hashes; the raw key is shown once at registration. */
+export function hashKey(token) {
+  return createHash("sha256").update(String(token)).digest("hex");
+}
+
+/** Timing-safe lookup of a key record by the presented bearer token. */
+export function findByKey(keys, token) {
+  if (!token) return null;
+  const presented = Buffer.from(hashKey(token), "hex");
+  for (const rec of Object.values(keys)) {
+    if (!rec.key_hash) continue;
+    const stored = Buffer.from(rec.key_hash, "hex");
+    if (stored.length === presented.length && timingSafeEqual(stored, presented)) return rec;
+  }
+  return null;
+}
+
+export async function readKeys(dir) {
+  try {
+    return JSON.parse(await readFile(join(dir, "keys.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// Writes are serialized per path and land via tmp-file + rename, so concurrent
+// requests in one process can't interleave a partial keys.json.
+const queues = new Map();
+export function writeKeys(dir, keys) {
+  const path = join(dir, "keys.json");
+  const prev = queues.get(path) ?? Promise.resolve();
+  const next = prev
+    .then(async () => {
+      const tmp = `${path}.${randomBytes(4).toString("hex")}.tmp`;
+      await writeFile(tmp, JSON.stringify(keys, null, 2));
+      await rename(tmp, path);
+    })
+    .catch(() => {});
+  queues.set(path, next);
+  return next;
+}