@prereason/mcp 0.3.2 → 0.5.0

package/lib/claim.js

@@ -0,0 +1,233 @@
+/**
+ * The claim flow, from the bridge's side.
+ *
+ * With no key configured the bridge asks PreReason for access on the person's
+ * behalf: it creates a claim, prints one link to stderr, and polls until the
+ * person has approved it in a browser. The first poll after approval returns
+ * the key once; the bridge saves it and attaches it to the running transport.
+ * Meanwhile the free tools keep working, and any AUTH_REQUIRED tool result is
+ * prefixed with the approve link so the model can relay it, because a person
+ * inside Claude Desktop never sees this process's stderr.
+ *
+ * Everything that touches the network or the clock is injectable
+ * (fetchImpl, sleep, now) so the flow is tested without a server.
+ */
+
+import { writeCredentials } from './credentials.js';
+
+export const DEFAULT_POLL_INTERVAL_MS = 5000;
+/** Consecutive network failures before the flow gives up for this process. */
+export const MAX_CONSECUTIVE_ERRORS = 10;
+
+/** The claims endpoint on the same origin as the MCP endpoint (so PREREASON_URL overrides both). */
+export function claimEndpoint(mcpUrl) {
+  return new URL('/api/agent/claims', mcpUrl).toString();
+}
+
+function parseRetryAfter(headers, fallbackMs) {
+  const raw = headers && typeof headers.get === 'function' ? headers.get('retry-after') : null;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : fallbackMs;
+}
+
+async function readJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * POST a claim. Resolves { ok: true, claim } or { ok: false, status, retryAfterMs, message }.
+ */
+export async function createClaim({ mcpUrl, clientName, purpose, requestHeaders = {}, fetchImpl = fetch }) {
+  const res = await fetchImpl(claimEndpoint(mcpUrl), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json', ...requestHeaders },
+    body: JSON.stringify({ client_name: clientName, purpose }),
+  });
+  const body = await readJson(res);
+  if (res.status === 201 && body && typeof body.claim_code === 'string' && typeof body.claim_token === 'string') {
+    return { ok: true, claim: body };
+  }
+  return {
+    ok: false,
+    status: res.status,
+    retryAfterMs: parseRetryAfter(res.headers, 60_000),
+    message: (body && body.message) || `claim request answered ${res.status}`,
+  };
+}
+
+/**
+ * Poll one claim until it settles. Outcomes:
+ *   approved   -> { outcome, apiKey, key, account, how_to_use }
+ *   delivered  -> the key was collected by another poll of the same token
+ *   denied, expired, not_found, gave_up
+ */
+export async function pollUntilSettled({ claim, requestHeaders = {}, fetchImpl = fetch, sleep = defaultSleep, now = () => Date.now(), onPending = () => {} }) {
+  let expiresAt = Date.parse(claim.expires_at);
+  const intervalMs = Math.max(1000, (claim.poll?.interval_seconds ?? 5) * 1000);
+  const pollUrl = claim.poll?.url ?? `${claimEndpoint(claim.approve_url)}/${claim.claim_code}`;
+  let consecutiveErrors = 0;
+
+  while (true) {
+    if (Number.isFinite(expiresAt) && now() >= expiresAt) return { outcome: 'expired' };
+
+    let res;
+    try {
+      res = await fetchImpl(pollUrl, {
+        headers: { accept: 'application/json', authorization: `Bearer ${claim.claim_token}`, ...requestHeaders },
+      });
+    } catch {
+      if (++consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) return { outcome: 'gave_up' };
+      await sleep(intervalMs);
+      continue;
+    }
+    consecutiveErrors = 0;
+
+    if (res.status === 404) return { outcome: 'not_found' };
+    if (res.status === 429) {
+      await sleep(parseRetryAfter(res.headers, intervalMs));
+      continue;
+    }
+    if (res.status !== 200) {
+      if (++consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) return { outcome: 'gave_up' };
+      await sleep(intervalMs);
+      continue;
+    }
+
+    const body = await readJson(res);
+    switch (body.status) {
+      case 'pending': {
+        // The approval page can extend the claim; honour the server's clock.
+        const fresh = Date.parse(body.expires_at);
+        if (Number.isFinite(fresh)) expiresAt = fresh;
+        onPending(body);
+        await sleep(Math.max(1000, (body.poll_interval ?? intervalMs / 1000) * 1000));
+        continue;
+      }
+      case 'approved': {
+        if (typeof body.api_key === 'string') {
+          return { outcome: 'approved', apiKey: body.api_key, key: body.key, account: body.account, how_to_use: body.how_to_use };
+        }
+        // KEY_ISSUE_FAILED: the approval stands, the mint is retried on the next poll.
+        await sleep(Math.max(1000, (body.retry_after ?? 5) * 1000));
+        continue;
+      }
+      case 'delivered':
+        return { outcome: 'delivered' };
+      case 'denied':
+        return { outcome: 'denied' };
+      case 'expired':
+        return { outcome: 'expired' };
+      default:
+        if (++consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) return { outcome: 'gave_up' };
+        await sleep(intervalMs);
+    }
+  }
+}
+
+/** The one line a person is meant to read. */
+export function approvalLine(claim) {
+  return `PreReason: no API key found. Open ${claim.approve_url} to approve access (link expires in 15 min).`;
+}
+
+/**
+ * While a claim is pending, put the approve link in front of any AUTH_REQUIRED
+ * tool result so the model relays it. Leaves every other message untouched.
+ */
+export function decorateAuthRequired(message, approveUrl) {
+  if (!approveUrl || !message || typeof message !== 'object') return message;
+  const result = message.result;
+  if (!result || result.isError !== true || !Array.isArray(result.content)) return message;
+  const first = result.content[0];
+  if (!first || first.type !== 'text' || typeof first.text !== 'string') return message;
+  let payload;
+  try {
+    payload = JSON.parse(first.text);
+  } catch {
+    return message;
+  }
+  if (!payload || payload.error !== 'AUTH_REQUIRED') return message;
+  const prefix = `Approve at ${approveUrl} (the human who owns this agent must open it and click Approve; the key arrives here on its own afterwards). `;
+  return {
+    ...message,
+    result: {
+      ...result,
+      content: [{ ...first, text: prefix + first.text }, ...result.content.slice(1)],
+    },
+  };
+}
+
+/**
+ * The whole flow: create, announce, poll, save, attach. `state.approveUrl` is
+ * set while the claim is pending so the message decorator can read it.
+ * Resolves the poll outcome (or a create failure) and never throws.
+ */
+export async function runClaimFlow({
+  mcpUrl,
+  headers,
+  clientName,
+  purpose,
+  credentialsFile,
+  requestHeaders = {},
+  fetchImpl = fetch,
+  sleep = defaultSleep,
+  now = () => Date.now(),
+  log = (line) => process.stderr.write(`${line}\n`),
+  state = {},
+}) {
+  let created;
+  try {
+    created = await createClaim({ mcpUrl, clientName, purpose, requestHeaders, fetchImpl });
+  } catch (error) {
+    log(`PreReason: could not reach ${claimEndpoint(mcpUrl)} to request access (${error?.message ?? 'network error'}). Free tools still work; set PREREASON_API_KEY to skip this step.`);
+    return { outcome: 'create_failed' };
+  }
+  if (!created.ok) {
+    const wait = Math.ceil(created.retryAfterMs / 60_000);
+    log(`PreReason: access request refused (${created.status}: ${created.message}). Try again in about ${wait} minute${wait === 1 ? '' : 's'}, or set PREREASON_API_KEY. Free tools still work.`);
+    return { outcome: 'create_refused', status: created.status };
+  }
+
+  const claim = created.claim;
+  state.approveUrl = claim.approve_url;
+  state.claimCode = claim.claim_code;
+  log(approvalLine(claim));
+
+  const settled = await pollUntilSettled({ claim, requestHeaders, fetchImpl, sleep, now });
+  state.approveUrl = null;
+
+  if (settled.outcome === 'approved') {
+    try {
+      writeCredentials(credentialsFile, {
+        apiKey: settled.apiKey,
+        claimCode: claim.claim_code,
+        clientName,
+        keyName: settled.key?.name ?? null,
+        now: new Date(now()),
+      });
+      headers.Authorization = `Bearer ${settled.apiKey}`;
+      log(`PreReason: access approved. Key "${settled.key?.name ?? 'Agent key'}" saved to ${credentialsFile}; get_context and get_metric work from the next call.`);
+    } catch (error) {
+      headers.Authorization = `Bearer ${settled.apiKey}`;
+      log(`PreReason: access approved and attached for this session, but the key could not be saved to ${credentialsFile} (${error?.message ?? 'write failed'}). Set PREREASON_API_KEY to keep it.`);
+    }
+    return settled;
+  }
+
+  const why = {
+    expired: 'the link expired before it was approved',
+    denied: 'the request was denied',
+    delivered: 'the key was collected elsewhere',
+    not_found: 'the claim is no longer known to the server',
+    gave_up: 'the server could not be reached',
+  }[settled.outcome] ?? settled.outcome;
+  log(`PreReason: access was not granted (${why}). Restart the bridge to ask again, or set PREREASON_API_KEY. Free tools still work.`);
+  return settled;
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/credentials.js

@@ -0,0 +1,152 @@
+/**
+ * Where the bridge's API key comes from, and where a claimed key is kept.
+ *
+ * Precedence, highest first:
+ *   1. PREREASON_API_KEY in the environment (the documented config path)
+ *   2. an Authorization or X-API-Key value passed with --header
+ *   3. the credentials file, written by the claim flow (~/.prereason/credentials.json,
+ *      or PREREASON_CREDENTIALS_FILE, or --credentials-file)
+ *
+ * The file holds the key and a little provenance (which claim, which client
+ * name, when). It never holds a claim token: a token is a fifteen minute
+ * secret for one poll loop and dies with the process. On POSIX the directory
+ * is 0700 and the file 0600. On Windows chmod is a no-op (the mode bits do
+ * not exist), so the file relies on the profile directory's own permissions,
+ * which is what every other credential store in %USERPROFILE% does.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const KEY_PATTERN = /^pr_(?:live|test)_[A-Za-z0-9_-]{16,}$/;
+export const CREDENTIALS_VERSION = 1;
+
+/** The credentials file path: the flag, then the env override, then the default under the home directory. */
+export function credentialsPath({ env = process.env, home = homedir(), flag = null } = {}) {
+  if (flag) return flag;
+  if (env.PREREASON_CREDENTIALS_FILE) return env.PREREASON_CREDENTIALS_FILE;
+  return join(home, '.prereason', 'credentials.json');
+}
+
+/**
+ * Parse the CLI arguments the bridge understands.
+ *   --header Key:Value   (repeatable)
+ *   --credentials-file <path>
+ *   --login  --logout  --help/-h  --version/-v
+ *   <url>    a bare argument overrides the endpoint
+ */
+export function parseArgs(argv) {
+  const out = { headers: {}, url: null, credentialsFile: null, login: false, logout: false, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--header' && argv[i + 1] !== undefined) {
+      const value = argv[++i];
+      const colon = value.indexOf(':');
+      if (colon > 0) out.headers[value.slice(0, colon).trim()] = value.slice(colon + 1).trim();
+    } else if (arg === '--credentials-file' && argv[i + 1] !== undefined) {
+      out.credentialsFile = argv[++i];
+    } else if (arg === '--login') {
+      out.login = true;
+    } else if (arg === '--logout') {
+      out.logout = true;
+    } else if (arg === '--help' || arg === '-h') {
+      out.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      out.version = true;
+    } else if (!arg.startsWith('-')) {
+      out.url = arg;
+    }
+  }
+  return out;
+}
+
+/** The API key carried by a --header value, if any. Accepts Authorization: Bearer and X-API-Key, any case. */
+export function keyFromHeaders(headers) {
+  for (const [name, value] of Object.entries(headers || {})) {
+    const lower = name.toLowerCase();
+    if (lower === 'authorization') {
+      const m = /^Bearer\s+(\S+)$/i.exec(String(value).trim());
+      if (m && KEY_PATTERN.test(m[1])) return m[1];
+    } else if (lower === 'x-api-key') {
+      const v = String(value).trim();
+      if (KEY_PATTERN.test(v)) return v;
+    }
+  }
+  return null;
+}
+
+/** Read the credentials file. Anything that is not a well formed key reads as null. */
+export function readCredentials(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed.api_key !== 'string' || !KEY_PATTERN.test(parsed.api_key)) return null;
+    return {
+      apiKey: parsed.api_key,
+      savedAt: typeof parsed.saved_at === 'string' ? parsed.saved_at : null,
+      claimCode: typeof parsed.claim_code === 'string' ? parsed.claim_code : null,
+      clientName: typeof parsed.client_name === 'string' ? parsed.client_name : null,
+      keyName: typeof parsed.key_name === 'string' ? parsed.key_name : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the credentials file atomically (temp file, then rename) with the
+ * tightest modes the platform offers. Only these fields are ever written.
+ */
+export function writeCredentials(path, { apiKey, claimCode = null, clientName = null, keyName = null, now = new Date() }) {
+  if (!KEY_PATTERN.test(apiKey)) throw new Error('refusing to save something that is not a PreReason API key');
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  tighten(dir, 0o700);
+  const body = JSON.stringify(
+    {
+      version: CREDENTIALS_VERSION,
+      api_key: apiKey,
+      saved_at: now.toISOString(),
+      claim_code: claimCode,
+      client_name: clientName,
+      key_name: keyName,
+    },
+    null,
+    2
+  );
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, body + '\n', { mode: 0o600 });
+  tighten(tmp, 0o600);
+  renameSync(tmp, path);
+  tighten(path, 0o600);
+}
+
+export function deleteCredentials(path) {
+  if (!existsSync(path)) return false;
+  unlinkSync(path);
+  return true;
+}
+
+function tighten(target, mode) {
+  if (process.platform === 'win32') return; // no mode bits to set
+  try {
+    chmodSync(target, mode);
+  } catch {
+    // a filesystem that refuses chmod (some mounts) still gets the file; nothing else to do
+  }
+}
+
+/**
+ * Which key the bridge should use, and where it came from.
+ * Returns { key, source } with source one of 'env', 'header', 'file', or null.
+ */
+export function resolveApiKey({ env = process.env, headers = {}, credentialsFile }) {
+  const fromEnv = env.PREREASON_API_KEY;
+  if (fromEnv && KEY_PATTERN.test(fromEnv.trim())) return { key: fromEnv.trim(), source: 'env' };
+  const fromHeader = keyFromHeaders(headers);
+  if (fromHeader) return { key: fromHeader, source: 'header' };
+  const stored = credentialsFile ? readCredentials(credentialsFile) : null;
+  if (stored) return { key: stored.apiKey, source: 'file' };
+  return { key: null, source: null };
+}

package/lib/jsonrpc.js

@@ -0,0 +1,60 @@
+/**
+ * The smallest shape check that keeps garbage out of the relay.
+ *
+ * The bridge forwards JSON-RPC frames between a stdio host and PreReason's
+ * HTTP endpoint without reading them, so it has no reason to validate methods
+ * or params, and no reason to carry a schema library to do it. It only has to
+ * be sure that what it forwards is a JSON-RPC object: a host that receives a
+ * bare string or a number on stdout treats the stream as corrupt and drops the
+ * connection, which is the one failure the relay must not cause itself.
+ */
+
+/** A single JSON-RPC 2.0 frame: an object, not an array, tagged "2.0". */
+export function isJsonRpcMessage(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) && value.jsonrpc === '2.0';
+}
+
+/**
+ * Throws on anything that is not one JSON-RPC message.
+ *
+ * Used on the stdio side, which is framed one message per line and has never
+ * carried a batch.
+ */
+export function assertJsonRpcMessage(value) {
+  if (!isJsonRpcMessage(value)) {
+    throw new Error('not a JSON-RPC 2.0 message');
+  }
+  return value;
+}
+
+/**
+ * Throws on anything that is not a JSON-RPC message or an array of them.
+ *
+ * Used on the HTTP side. Batching left the MCP spec in 2025-06-18, but a
+ * server is still free to answer with an array and the relay should pass it
+ * on rather than decide the stream is broken.
+ */
+export function assertJsonRpcPayload(value) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      throw new Error('empty JSON-RPC batch');
+    }
+    for (const entry of value) {
+      if (!isJsonRpcMessage(entry)) {
+        throw new Error('batch entry is not a JSON-RPC 2.0 message');
+      }
+    }
+    return value;
+  }
+  return assertJsonRpcMessage(value);
+}
+
+/**
+ * True when the frame expects an answer, which is what decides whether a POST
+ * reads a response body or just releases the connection. A notification has a
+ * method and no id; a response has an id and no method.
+ */
+export function expectsResponse(message) {
+  const frames = Array.isArray(message) ? message : [message];
+  return frames.some((frame) => typeof frame === 'object' && frame !== null && 'method' in frame && 'id' in frame && frame.id !== undefined);
+}

package/lib/sse.js

@@ -0,0 +1,170 @@
+/**
+ * A Server-Sent Events decoder, sized for this bridge.
+ *
+ * PreReason's own endpoint answers POST with application/json and 405s a GET,
+ * so nothing here runs against api.prereason.com today. It exists because
+ * PREREASON_URL can point the bridge at any Streamable HTTP server, and the
+ * transport half of that spec is allowed to answer a POST with an event
+ * stream. Keeping the decoder costs forty lines and keeps the bridge honest
+ * against a server that does.
+ *
+ * The field rules are the WHATWG ones, and the buffering rules follow
+ * eventsource-parser, which is what the MCP SDK used before this file
+ * replaced it:
+ *
+ *   a blank line dispatches, and only if data was collected
+ *   data lines join with a newline, and one trailing newline is dropped
+ *   one space after the colon is part of the separator, not the value
+ *   a line with no colon is a field with an empty value
+ *   an id holding a NUL is discarded, and id does not survive a dispatch
+ *   a line starting with a colon is a comment, which is how servers keep alive
+ */
+
+/** Split text into complete lines plus the tail that has not ended yet. */
+function splitLines(chunk) {
+  const lines = [];
+  let index = 0;
+
+  while (index < chunk.length) {
+    const cr = chunk.indexOf('\r', index);
+    const lf = chunk.indexOf('\n', index);
+    let end = -1;
+
+    if (cr !== -1 && lf !== -1) {
+      end = Math.min(cr, lf);
+    } else if (cr !== -1) {
+      // A lone carriage return at the very end may be the first half of a
+      // CRLF that the next chunk completes, so hold the line back.
+      end = cr === chunk.length - 1 ? -1 : cr;
+    } else if (lf !== -1) {
+      end = lf;
+    }
+
+    if (end === -1) {
+      return [lines, chunk.slice(index)];
+    }
+
+    lines.push(chunk.slice(index, end));
+    index = end + 1;
+    if (chunk[index - 1] === '\r' && chunk[index] === '\n') {
+      index += 1;
+    }
+  }
+
+  return [lines, ''];
+}
+
+export class SseDecoder {
+  #incomplete = '';
+  #data = '';
+  #eventType = '';
+  #id;
+  #onRetry;
+
+  constructor({ onRetry } = {}) {
+    this.#onRetry = onRetry;
+  }
+
+  /**
+   * Feed one decoded text chunk and get back the events that completed inside
+   * it. A chunk may end mid line, so the tail is carried to the next call.
+   */
+  push(text) {
+    const [lines, incomplete] = splitLines(this.#incomplete + text);
+    this.#incomplete = incomplete;
+
+    const events = [];
+    for (const line of lines) {
+      const event = this.#readLine(line);
+      if (event) {
+        events.push(event);
+      }
+    }
+    return events;
+  }
+
+  #readLine(line) {
+    if (line === '') {
+      return this.#dispatch();
+    }
+    if (line.startsWith(':')) {
+      return null;
+    }
+
+    const separator = line.indexOf(':');
+    if (separator === -1) {
+      this.#setField(line, '');
+      return null;
+    }
+
+    const offset = line[separator + 1] === ' ' ? 2 : 1;
+    this.#setField(line.slice(0, separator), line.slice(separator + offset));
+    return null;
+  }
+
+  #setField(field, value) {
+    if (field === 'data') {
+      this.#data += `${value}\n`;
+    } else if (field === 'event') {
+      this.#eventType = value;
+    } else if (field === 'id') {
+      this.#id = value.includes('\u0000') ? undefined : value;
+    } else if (field === 'retry' && /^\d+$/.test(value)) {
+      this.#onRetry?.(Number.parseInt(value, 10));
+    }
+    // Any other field is ignored, which is what the spec asks for.
+  }
+
+  #dispatch() {
+    const data = this.#data;
+    const event = this.#eventType;
+    const id = this.#id;
+
+    this.#data = '';
+    this.#eventType = '';
+    this.#id = undefined;
+
+    if (data.length === 0) {
+      return null;
+    }
+    return {
+      id,
+      event: event || undefined,
+      data: data.endsWith('\n') ? data.slice(0, -1) : data,
+    };
+  }
+}
+
+/**
+ * Read an event stream body to the end, handing each event to onEvent.
+ *
+ * Takes the reader rather than the stream so the caller keeps the handle it
+ * needs to cancel, and decodes with TextDecoder rather than piping through a
+ * TextDecoderStream, because a multi byte character may straddle two chunks
+ * and { stream: true } is what carries the partial one across.
+ */
+export async function readEventStream(body, { onEvent, onRetry } = {}) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const sse = new SseDecoder({ onRetry });
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) {
+        break;
+      }
+      for (const event of sse.push(decoder.decode(value, { stream: true }))) {
+        onEvent?.(event);
+      }
+    }
+    // Flush any half decoded character. An event the server never terminated
+    // with a blank line is dropped on purpose: its data is a truncated frame,
+    // and forwarding half a JSON-RPC message is worse than losing it.
+    for (const event of sse.push(decoder.decode())) {
+      onEvent?.(event);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}