Stop a payment in a Claude Agent SDK program

import type {
  HookCallback,
  HookJSONOutput,
  PostToolUseHookInput,
  PreToolUseHookInput,
} from "@anthropic-ai/claude-agent-sdk";

const base =
  process.env.VULSIGHT_BASE_URL ?? "https://vulsight-guard.vercel.app";
const headers = {
  authorization: `Bearer ${process.env.VULSIGHT_API_KEY}`,
  "content-type": "application/json",
  "x-vulsight-channel": "api",
};
const sessionId = crypto.randomUUID();
// The hash of the last page sent for checking from each origin. A payment
// sends its seller's, so it inherits that page's result.
const lastSent = new Map<string, string>();
type PendingRead = { origin: string; text: string; sending?: Promise<void> };
const pending = new Set<PendingRead>();
let reads = 0;
// A payment sent to a person keeps its decision id, so the retry after the
// approval reads that decision instead of opening a second hold. Every new
// read clears held (see sendWhatItRead), so the key needs no page hash.
const held = new Map<string, string>();
type Decision = {
  id: string;
  status: string;
  rules: { result: string; sentence?: string }[];
};
// The x402 method fields a seller's 402 may name, at its top level or in its
// extra object.
type Method = { assetTransferMethod?: string; paymentFlow?: string };
type Quote = Method & {
  extra?: Method;
  x402Version?: number;
  observed402PayTo?: string;
};
// No permission decision, so your own permission rules and prompts still run.
const noDecision: HookJSONOutput = {};
const deny = (permissionDecisionReason: string): HookJSONOutput => ({
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "deny",
    permissionDecisionReason,
  },
});

export const checkPayment: HookCallback = async (input) => {
  const signal = AbortSignal.timeout(110_000);
  const before = reads;
  const { tool_input } = input as PreToolUseHookInput;
  const { payTo, amountAtomic, asset, network, scheme, resourceUrl } =
    tool_input as Record<string, string>;
  // The 402's method fields, when your payment tool takes them: at the top
  // level, or inside the 402's extra object passed as it is. The guard
  // checks both. Left out, they read as the defaults.
  const {
    assetTransferMethod,
    paymentFlow,
    extra,
    x402Version,
    observed402PayTo,
  } = tool_input as Quote;
  if (x402Version !== 2 || !observed402PayTo) {
    return deny(
      "The payment tool must pass the seller's x402 v2 version and " +
        "original 402 payee. Do not pay without them; send the payment " +
        "through the proxy URL instead.",
    );
  }
  // The seller's origin: the payment cites the last page sent from it.
  const seller = URL.canParse(resourceUrl)
    ? new URL(resourceUrl).origin
    : undefined;
  const payment = JSON.stringify([
    network, payTo, amountAtomic, asset, scheme,
    assetTransferMethod, paymentFlow,
    extra?.assetTransferMethod, extra?.paymentFlow,
    x402Version, observed402PayTo, resourceUrl,
  ]);
  // Taken out before any await, so two attempts at once cannot both read
  // one approval.
  const heldId = held.get(payment);
  held.delete(payment);
  let decision: Decision;
  try {
    await Promise.all(
      [...pending].map(async (read) => {
        await read.sending;
        if (pending.has(read)) await sendRead(read, signal);
      }),
    );
    signal.throwIfAborted();
    if (pending.size) {
      return deny(
        "VulSight Guard could not check a page the agent read. Retry this " +
          "payment. If it still fails, check the API key and service " +
          "connection. Do not pay.",
      );
    }
    if (reads !== before) {
      return deny(
        "A new page was read during this check. Retry the payment to " +
          "include it. Do not pay.",
      );
    }
    const answer = heldId
      ? await fetch(`${base}/api/v1/decisions/${heldId}`, {
          headers,
          signal,
        })
      : await fetch(`${base}/api/v1/decisions`, {
          method: "POST",
          headers,
          body: JSON.stringify({
            kind: "x402_payment",
            payTo, amountAtomic, asset, network, scheme,
            assetTransferMethod, paymentFlow, extra,
            x402Version, observed402PayTo, resourceUrl, sessionId,
            contextSha256: seller && lastSent.get(seller),
          }),
          signal,
        });
    const body = await answer.json();
    if (!answer.ok) {
      // A guard that is busy or down keeps the hold for the next attempt; a
      // refused read drops it.
      if (
        heldId &&
        reads === before &&
        (answer.status >= 500 || answer.status === 429)
      ) {
        held.set(payment, heldId);
      }
      return deny(
        `VulSight Guard did not decide. ${body.error.message} Do not pay.`,
      );
    }
    if (
      !body ||
      typeof body.id !== "string" ||
      !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(body.id) ||
      ![
        "allowed", "denied", "review_pending",
        "review_approved", "review_denied", "review_expired",
      ].includes(body.status) ||
      !Array.isArray(body.rules) ||
      !body.rules.every(
        (rule: unknown) =>
          typeof rule === "object" && rule !== null &&
          "result" in rule && typeof rule.result === "string" &&
          ["pass", "review", "deny", "info"].includes(rule.result) &&
          (!("sentence" in rule) || typeof rule.sentence === "string"),
      )
    ) {
      if (heldId && reads === before) held.set(payment, heldId);
      return deny(
        "VulSight Guard returned an invalid decision. Retry the payment. " +
          "Do not pay.",
      );
    }
    decision = body;
  } catch {
    if (heldId && reads === before) held.set(payment, heldId);
    return deny("VulSight Guard did not answer. Do not pay.");
  }
  if (reads !== before) {
    return deny(
      "A new page was read during this check. Retry the payment to " +
        "include it. Do not pay.",
    );
  }
  if (decision.status === "review_pending") {
    held.set(payment, decision.id);
    return deny(
      `Held for a person. Approve or deny it on Review, decision ` +
        `${decision.id}, then try the same payment again.`,
    );
  }
  if (
    decision.status === "allowed" ||
    decision.status === "review_approved"
  ) {
    return noDecision;
  }
  if (decision.status === "review_denied") {
    return deny("A reviewer denied this payment. Do not pay.");
  }
  if (decision.status === "review_expired") {
    return deny("The review expired before anyone answered. Do not pay.");
  }
  const denied = decision.rules.filter((r) => r.result === "deny");
  return deny(
    denied.map((r) => r.sentence).join(" ").trim() ||
      "VulSight Guard denied this payment. Check its decision before " +
        "trying again. Do not pay.",
  );
};

// guard.ts, continued: shared state comes from the block above.
function sendRead(read: PendingRead, signal: AbortSignal): Promise<void> {
  if (read.sending) return read.sending;
  read.sending = (async () => {
    try {
      const answer = await fetch(`${base}/api/v1/context`, {
        method: "POST",
        headers,
        // The guard takes a label of at most 200 characters, and a hostname
        // can run to 253.
        body: JSON.stringify({
          sessionId,
          origin: read.origin.slice(0, 200),
          text: read.text,
        }),
        signal,
      });
      if (!answer.ok) throw new Error(`HTTP ${answer.status}`);
      const receipt = await answer.json();
      if (
        typeof receipt.sha256 !== "string" ||
        !/^[a-f0-9]{64}$/.test(receipt.sha256) ||
        !["pass", "restrict", "unavailable"].includes(receipt.route)
      ) {
        throw new Error("Invalid check receipt");
      }
      lastSent.set(read.origin, receipt.sha256);
      pending.delete(read);
    } catch {
      console.error(
        `VulSight Guard could not check ${read.origin}. Payments stay ` +
          "blocked until a retry succeeds, so retry the payment.",
      );
    } finally {
      read.sending = undefined;
    }
  })();
  return read.sending;
}

export const sendWhatItRead: HookCallback = async (input) => {
  const { tool_name, tool_input, tool_response } =
    input as PostToolUseHookInput;
  const page =
    typeof tool_response === "string"
      ? tool_response
      : JSON.stringify(tool_response);
  if (!page) return {};
  // The first 64 KiB, whole characters, each NUL as the replacement
  // character (the guard refuses a NUL), as the shipped clients send it.
  const bytes = new TextEncoder()
    .encode(page.replaceAll("\u0000", "\uFFFD"))
    .subarray(0, 65_536);
  const text = new TextDecoder("utf-8", { ignoreBOM: true })
    .decode(bytes, { stream: true });
  // A page fetched by URL is sent under its origin, anything else under the
  // tool's name, as the Claude Code hook sends them.
  const url = (tool_input as { url?: unknown } | undefined)?.url;
  const origin =
    typeof url === "string" &&
    URL.canParse(url) &&
    /^https?:$/.test(new URL(url).protocol)
      ? new URL(url).origin
      : tool_name;
  const read: PendingRead = { origin, text };
  pending.add(read);
  reads += 1;
  held.clear();
  await sendRead(read, AbortSignal.timeout(110_000));
  return {};
};

import { createInterface } from "node:readline/promises";
import { query } from "@anthropic-ai/claude-agent-sdk";
import { checkPayment, sendWhatItRead } from "./guard";

// One prompt at a time: tool calls can run in parallel, and two prompts
// open on one terminal would both take the same typed answer.
let asking = Promise.resolve();
async function ask(toolName: string, input: Record<string, unknown>) {
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  try {
    return await rl.question(
      `Allow ${toolName} ${JSON.stringify(input)}? (y/n) `,
    );
  } finally {
    rl.close();
  }
}

// Name the tools your agent pays with in both matchers.
for await (const message of query({
  prompt:
    "Buy the dataset at https://vulsight-guard.vercel.app/merchant/dataset.",
  options: {
    // Asks a person before each tool call the guard hook has not refused.
    // To approve the pay tools with no prompt instead, replace this with
    // allowedTools: ["pay_x402", "mcp__wallet__pay"].
    canUseTool: async (toolName, input) => {
      const turn = asking.then(() => ask(toolName, input));
      asking = turn.then(
        () => {},
        () => {},
      );
      const answer = await turn;
      return answer.trim() === "y"
        ? { behavior: "allow", updatedInput: input }
        : { behavior: "deny", message: "The user declined this tool call." };
    },
    hooks: {
      PreToolUse: [
        {
          matcher: "pay_x402|mcp__wallet__pay",
          hooks: [checkPayment],
          timeout: 120,
        },
      ],
      PostToolUse: [
        {
          matcher: "pay_x402|mcp__wallet__pay|WebFetch|mcp__browser__.*",
          hooks: [sendWhatItRead],
          timeout: 120,
        },
      ],
    },
  },
})) {
  console.log(message);
}