@keyflint/wrap 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KeyFlint Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @keyflint/wrap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sell access to an existing stdio MCP server without touching its code. `keyflint-wrap` starts your
+server, relays JSON-RPC in both directions, and gates every `tools/call`:
+
+1. Offline Ed25519 license check (`keyflint-verify`), including features, node and domain locks.
+2. For metered tools, `POST /api/v1/quota/deduct` on your KeyFlint gateway.
+3. If the server answers with a JSON-RPC error or `isError: true`, the credits are refunded.
+
+Refused calls never reach your server; the client gets the standard KeyFlint errors
+(`-32060` license, `-32061` feature, `-32062` quota, `-32063` gateway). `initialize`, `tools/list`
+and every other message pass through untouched.
+
+```bash
+export KEYFLINT_LICENSE="LIC-..."          # the buyer's key
+export KEYFLINT_PUBLIC_KEYS="k1=<hex>"     # your issuer public key(s)
+export KEYFLINT_URL="https://licenses.example.com"   # needed for metered tools
+
+npx @keyflint/wrap --credits 0 --tool summarize=5 -- python server.py
+```
+
+| Option | Meaning |
+|---|---|
+| `--credits N` | Credits per call for tools without `--tool` (default `1` when `KEYFLINT_URL` is set, else `0`). `0` means license check only. |
+| `--tool NAME=N` | Credits for one tool. Repeatable. |
+| `--free A,B` | Tools that skip KeyFlint entirely. |
+| `--features A,B` | Features the license must include. |
+| `--offline-grace N` | Calls (0-5) allowed while the gateway is unreachable; their debits are replayed later and never refunded. |
+| `--event-type TYPE` | `event_type` sent to the gateway (default `mcp:<tool>`). |
+
+Environment variables are the same as `keyflint-verify` (`KEYFLINT_LICENSE`, `KEYFLINT_PUBLIC_KEYS`,
+`KEYFLINT_URL`, `KEYFLINT_CHECKOUT_URL`, `KEYFLINT_MACHINE_ID`, `KEYFLINT_DOMAIN`).
+
+## Claude Desktop (.mcpb)
+
+[`examples/mcpb-template`](../../examples/mcpb-template) packages a server behind the wrapper as an
+MCP Bundle. The buyer pastes the license key once at install time; it is declared `sensitive`, so the
+host masks it and stores it securely, then passes it to the wrapper as `KEYFLINT_LICENSE`.
+
+## Limits
+
+- stdio transport only (newline-delimited JSON-RPC). For HTTP servers use `keyflint-verify/mcp` in code.
+- A gated `tools/call` is forwarded after its check, so it can reach the server after messages the
+  client sent later. JSON-RPC does not order requests, and MCP clients do not rely on it.
+- JSON-RPC batches (removed in MCP 2025-06-18) may not contain `tools/call`; such entries are refused.
+- The wrapper protects honest buyers' keys and quota, not a server the buyer can edit: anyone with
+  the server's source can run it without the wrapper. Keep paid logic behind the gateway or on your
+  own host if that matters.
+
+MIT licensed.

package/bin/keyflint-wrap.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { parseArgs, wrap, UsageError } from "../src/wrap.js";
+
+const USAGE = `Usage: keyflint-wrap [options] -- <command> [args...]
+
+Gates every tools/call of a stdio MCP server with a KeyFlint license.
+
+Options:
+  --credits N         credits per tool call (default 1 with KEYFLINT_URL, else 0 = license check only)
+  --tool NAME=N       credits for one tool (repeatable; 0 = license check only)
+  --free A,B          tools that skip KeyFlint entirely
+  --features A,B      features the license must include
+  --offline-grace N   calls allowed while the gateway is unreachable (0-5, default 0)
+  --event-type TYPE   event_type sent to the gateway (default mcp:<tool>)
+
+Environment: KEYFLINT_LICENSE, KEYFLINT_PUBLIC_KEYS, KEYFLINT_URL, KEYFLINT_CHECKOUT_URL,
+KEYFLINT_MACHINE_ID, KEYFLINT_DOMAIN (same as keyflint-verify).
+`;
+
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+  process.stderr.write(USAGE);
+  process.exit(argv.length === 0 ? 2 : 0);
+}
+let opts;
+try {
+  opts = parseArgs(argv);
+} catch (e) {
+  if (!(e instanceof UsageError)) throw e;
+  process.stderr.write(`keyflint-wrap: ${e.message}\n\n${USAGE}`);
+  process.exit(2);
+}
+const code = await wrap(opts, { forwardSignals: true });
+// stdin may still be open when the server exits on its own; flush and leave with its code.
+process.stdout.write("", () => process.exit(code));

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@keyflint/wrap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Put KeyFlint license checks and credit metering in front of any stdio MCP server, with no code changes.",
+  "license": "MIT",
+  "author": "ArceeDev",
+  "homepage": "https://keyflint.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArceeDev/keyflint.git",
+    "directory": "sdks/js-wrap"
+  },
+  "bugs": {
+    "url": "https://github.com/ArceeDev/keyflint/issues"
+  },
+  "type": "module",
+  "main": "./src/wrap.js",
+  "exports": {
+    ".": "./src/wrap.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "keyflint-wrap": "bin/keyflint-wrap.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.4"
+  },
+  "keywords": [
+    "keyflint",
+    "license",
+    "licensing",
+    "mcp",
+    "model-context-protocol",
+    "metering",
+    "proxy"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "keyflint-verify": "^1.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/wrap.js

@@ -0,0 +1,206 @@
+/**
+ * @keyflint/wrap — puts KeyFlint license checks and credit metering in front of any stdio MCP server.
+ *
+ *   npx @keyflint/wrap --tool summarize=5 -- python server.py
+ *
+ * The wrapper spawns the server, relays newline-delimited JSON-RPC in both directions, and gates
+ * every `tools/call` request: offline license check, then POST /api/v1/quota/deduct for metered
+ * tools. Failures are answered by the wrapper with the KeyFlint JSON-RPC errors (-32060..-32063)
+ * and never reach the server. Calls the server answers with an error (or `isError: true`) are
+ * refunded. Every other message passes through untouched.
+ */
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { createKeyFlint, KeyFlintMcpError } from "keyflint-verify/mcp";
+
+const INTERNAL_ERROR = -32603;
+
+/** Parses argv (without node and script) into wrapper options and the server command. */
+export function parseArgs(argv, env = process.env) {
+  const sep = argv.indexOf("--");
+  if (sep === -1 || sep === argv.length - 1) throw new UsageError("missing server command after --");
+  const flags = argv.slice(0, sep);
+  const opts = {
+    command: argv[sep + 1],
+    args: argv.slice(sep + 2),
+    defaultCredits: undefined,
+    tools: new Map(),
+    free: new Set(),
+    features: [],
+    offlineGraceCalls: 0,
+    eventType: undefined,
+  };
+  const value = (i, name) => {
+    if (i + 1 >= flags.length) throw new UsageError(`${name} needs a value`);
+    return flags[i + 1];
+  };
+  for (let i = 0; i < flags.length; i++) {
+    const f = flags[i];
+    if (f === "--credits") opts.defaultCredits = credits(value(i++, f), f);
+    else if (f === "--tool") {
+      const raw = value(i++, f);
+      const eq = raw.lastIndexOf("=");
+      if (eq <= 0) throw new UsageError(`--tool expects name=credits, got "${raw}"`);
+      opts.tools.set(raw.slice(0, eq), credits(raw.slice(eq + 1), f));
+    } else if (f === "--free") for (const t of list(value(i++, f))) opts.free.add(t);
+    else if (f === "--features") opts.features.push(...list(value(i++, f)));
+    else if (f === "--offline-grace") {
+      opts.offlineGraceCalls = credits(value(i++, f), f);
+      if (opts.offlineGraceCalls > 5) throw new UsageError("--offline-grace is capped at 5");
+    }
+    else if (f === "--event-type") opts.eventType = value(i++, f);
+    else throw new UsageError(`unknown option ${f}`);
+  }
+  // Without a gateway nothing can be deducted, so the default is a license-only check.
+  if (opts.defaultCredits === undefined) opts.defaultCredits = gatewayConfigured(env) ? 1 : 0;
+  return opts;
+}
+
+export class UsageError extends Error {}
+
+function credits(raw, flag) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) throw new UsageError(`${flag}: "${raw}" is not a non-negative integer`);
+  return n;
+}
+
+function list(raw) {
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+function gatewayConfigured(env) {
+  return Boolean((env.KEYFLINT_URL ?? env.KEYFORGE_URL ?? "").trim());
+}
+
+/**
+ * Starts the server and relays messages. Resolves with the server's exit code.
+ * `io` lets tests swap stdin/stdout; `kf` lets tests inject a configured KeyFlint instance.
+ */
+export function wrap(opts, io = {}) {
+  const input = io.stdin ?? process.stdin;
+  const output = io.stdout ?? process.stdout;
+  const kf = io.kf ?? createKeyFlint();
+  const child = spawn(opts.command, opts.args, {
+    stdio: ["pipe", "pipe", "inherit"],
+    env: io.env ?? process.env,
+    shell: false,
+  });
+
+  const waiting = new Map(); // JSON-RPC id (as JSON) -> resolve(response)
+  const gates = new Map(); // tool name -> gated forwarder
+  let childGone = false;
+  if (io.forwardSignals) {
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, () => child.kill(sig));
+  }
+
+  const send = (msg) => output.write(JSON.stringify(msg) + "\n");
+  const toChild = (line) => {
+    if (!childGone) child.stdin.write(line + "\n");
+  };
+
+  function gateFor(name) {
+    let gate = gates.get(name);
+    if (gate) return gate;
+    const forward = async (msg) => {
+      const response = await new Promise((resolve, reject) => {
+        if (childGone) return reject(new Error("MCP server exited"));
+        waiting.set(JSON.stringify(msg.id), resolve);
+        toChild(JSON.stringify(msg));
+      });
+      // Refund (metered) when the server reports a failure; the response is relayed as-is.
+      return { isError: Boolean(response.error || response.result?.isError === true), response };
+    };
+    const n = opts.tools.get(name) ?? opts.defaultCredits;
+    if (n === 0) gate = kf.requireLicense(forward, { features: opts.features });
+    else {
+      const m = { features: opts.features, offlineGraceCalls: opts.offlineGraceCalls };
+      m.eventType = opts.eventType ?? `mcp:${name}`;
+      gate = kf.metered(n, forward, m);
+    }
+    gates.set(name, gate);
+    return gate;
+  }
+
+  async function handleToolCall(msg) {
+    const name = typeof msg.params?.name === "string" ? msg.params.name : "";
+    if (opts.free.has(name)) return toChild(JSON.stringify(msg));
+    try {
+      const { response } = await gateFor(name)(msg);
+      output.write(response.__raw + "\n");
+    } catch (e) {
+      if (e instanceof KeyFlintMcpError || (e && typeof e.code === "number" && e.data)) {
+        send({ jsonrpc: "2.0", id: msg.id, error: { code: e.code, message: e.message, data: e.data } });
+      } else {
+        send({ jsonrpc: "2.0", id: msg.id, error: { code: INTERNAL_ERROR, message: String(e?.message ?? e) } });
+      }
+    }
+  }
+
+  // client -> server
+  const fromClient = createInterface({ input, crlfDelay: Infinity });
+  fromClient.on("line", (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return toChild(line); // not ours to judge; the server answers parse errors
+    }
+    if (Array.isArray(msg)) {
+      // JSON-RPC batches (dropped in MCP 2025-06-18): never let a tools/call through ungated.
+      const calls = msg.filter(isToolCall);
+      const rest = msg.filter((m) => !isToolCall(m));
+      if (calls.length) {
+        send(calls.map((m) => ({ jsonrpc: "2.0", id: m.id, error: { code: INTERNAL_ERROR, message: "keyflint-wrap: batched tools/call is not supported" } })));
+      }
+      if (rest.length) toChild(JSON.stringify(rest));
+      return;
+    }
+    if (isToolCall(msg)) handleToolCall(msg);
+    else toChild(line);
+  });
+  fromClient.on("close", () => {
+    if (!childGone) child.stdin.end();
+  });
+
+  // server -> client
+  const fromServer = createInterface({ input: child.stdout, crlfDelay: Infinity });
+  fromServer.on("line", (line) => {
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return output.write(line + "\n");
+    }
+    const key = msg && !Array.isArray(msg) && "id" in msg && !("method" in msg) ? JSON.stringify(msg.id) : undefined;
+    const resolve = key !== undefined ? waiting.get(key) : undefined;
+    if (resolve) {
+      waiting.delete(key);
+      Object.defineProperty(msg, "__raw", { value: line, enumerable: false });
+      resolve(msg);
+    } else output.write(line + "\n");
+  });
+
+  return new Promise((resolve) => {
+    const finish = (code) => {
+      if (childGone) return;
+      childGone = true;
+      for (const [id, done] of waiting) {
+        const msg = { jsonrpc: "2.0", id: JSON.parse(id), error: { code: INTERNAL_ERROR, message: "MCP server exited" } };
+        done(Object.defineProperty(msg, "__raw", { value: JSON.stringify(msg) }));
+      }
+      waiting.clear();
+      resolve(code);
+    };
+    child.on("error", (e) => {
+      process.stderr.write(`keyflint-wrap: cannot start ${opts.command}: ${e.message}\n`);
+      finish(127);
+    });
+    child.on("exit", (code, signal) => finish(code ?? (signal ? 128 : 1)));
+  });
+}
+
+function isToolCall(m) {
+  return m && typeof m === "object" && m.method === "tools/call" && "id" in m;
+}