Skip to content

About

TypeScript SDK and MCP proxy for Requisition's lab /v1 API (byte-compatible with requisition-aws).

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

requisition-ts

A TypeScript SDK and an MCP proxy for Requisition's /v1 API. The proxy forwards an agent's tool call when Requisition has signed an allow for that call's exact arguments and the proxy has checked that signature against a pinned key file; it forwards no other tool call. The SDK's gate reports the same two facts to your code (decision.allowed, decision.signatureChecked); your code decides what to run, and the SDK cannot stop it.

The package is a port of the Python package requisition-aws: the requests it sends and the hashes it derives are the same bytes, and the refusals it gives carry the same codes plus one of its own, integer_out_of_range (see "The float refusal"). The repository's tests hold it to vectors generated by the Python package (test/vectors/python/).

Every Requisition feature this package uses belongs to Requisition's evaluation environment: the /v1 API, the records it signs (Ed25519, with an ML-DSA-87 co-signature when one is configured) and the execute call that spends an approval once.

Licence: Apache License 2.0 (LICENSE, NOTICE). Third-party test files keep their own licences; they are listed in THIRD-PARTY.md and none of them is in the npm package.

The pieces

file what it is
src/index.ts The public surface. package.json exports this file and no other.
src/canonical.ts The canonical encoder (encode), the act hash (actHash: SHA-384 over the encoded arguments with act_type put inside, label sha384+canonical_payload.v3), the display digest, and the intake rules (checkArguments, ArgsSchema). Intake refuses before anything is sent, and never by truncating or rounding.
src/json.ts The strict JSON reader (parseStrict): RFC 8259, a duplicate member name refused, a nesting depth limit, and a number that is not a safe integer kept as its text (NumberLexeme), so 1.0 is never read as 1.
src/client.ts The HTTP client (Client): propose, read a request, execute, report an outcome, fetch the key file. Plain http is refused unless the host is loopback, or a private address that the caller allowed. The credential is sent in the Authorization header and is left out of the client's printed forms.
src/store.ts The relying party's store (Store): one SQLite file through node:sqlite, created with mode 600, every change in a transaction. It holds the open proposals, the exact bytes of each execute call, and the memory of every signed record already read.
src/gate.ts The flow (Gate): propose, awaitDecision, execute, claim, reportOutcome. Every answer from Requisition is checked against what was sent before it is used. A failed check throws, and the caller must not act.
src/keys.ts The pinned key file (KeyRegistry) and the key rule: a key's status, its validity window against the record's signed time, and the accepted signers, all checked before the signature.
src/pq.ts ML-DSA-87 verification, for the co-signatures of Requisition's evaluation environment, through @noble/post-quantum. The installed packages must hash to a pinned digest, or every verification throws.
src/verify.ts The offline check of one record (verifyRecord), described below.
src/registry.ts, src/catalog.ts The tool to act type registry (ToolRegistry) and the digest of a tool's definition. A tool that is not registered is denied.
src/mcp/ The MCP proxy (McpProxy), its stdio and Streamable HTTP servers (serveStdio, startHttp) and its upstream clients (StdioUpstream, HttpUpstream).
bin/requisition-mcp-proxy.ts The proxy's command.

Install

npm install requisition-ts@0.1.0

Node 22.18 or newer is required. The store uses node:sqlite, which Node provides. The package has two runtime dependencies, each pinned to an exact version: @noble/curves 2.4.0 and, for the ML-DSA-87 signatures of Requisition's evaluation environment, @noble/post-quantum 0.7.1.

The npm package carries the compiled JavaScript and its type declarations (dist/src/, dist/bin/), this page, LICENSE and NOTICE. It is an ES module. The sources, the tests and the test vectors are in the repository, not in the package.

The SDK

import { Client, Gate, KeyRegistry, Store, argumentsObject, idempotencyKey } from "requisition-ts";

const client = new Client({ baseUrl: "https://requisition.example", credential, principal });
const keys = KeyRegistry.fromFile("requisition-keys.json");    // the pinned key file
const store = new Store("relying-party.db");
const gate = new Gate(client, store, { approvalBaseUrl: "https://requisition.example", keys });

const args = argumentsObject("refund-agent", "session-1", "payments.refund_send",
  { amount_minor: 1250, currency: "USD", account: "acct-7781", reason: "duplicate charge" });

let sanction = await gate.propose("payments.refund_send", args);
console.log("approve at", sanction.approvalUrl);                // status is "pending"
sanction = await gate.awaitDecision(sanction, args, { deadlineMs: 10 * 60 * 1000 });

if (sanction.status === "sanctioned") {
  const key = idempotencyKey("my-service", "call-0001", sanction.actHash);
  const decision = await gate.execute(sanction, args, key);
  if (decision.allowed && decision.signatureChecked && gate.runnable(decision)) {
    gate.claim(decision, sanction, { tool: "payments_refund_send" });   // throws if already claimed
    const result = await sendRefund(args.args);                         // your own code: the effect
    await gate.reportOutcome(decision, true, result);
  }
}

What each step does:

  • propose runs the intake rules, derives the act hash and files a sanction request. A second propose of the same act finds the open request instead of filing another.
  • awaitDecision polls until the request is sanctioned or refused, or until the deadline, when it returns the pending answer. A sanctioned answer carries the signed statement; the gate checks that the statement names the request, the principal, the act type, the act hash and the display digest that were proposed, and that its signature verifies under the pinned key file.
  • execute sends the execute call and returns the signed decision, allow or deny. The bytes of the call are stored under key before they are sent, and a retry with the same key sends the same bytes.
  • runnable says whether an allow can still be acted on: its signed exec_not_after has not passed.
  • claim records, in the store and before it returns, that this approval is being acted on. A second claim of the same statement, or of another statement for the same approval, throws FenceRefused.
  • reportOutcome sends the caller's report of what happened and returns a short status: recorded, unsupported (the server has no outcome route) or not recorded: .... It does not throw: the effect has happened.

A Gate built without keys checks no signature, and decision.signatureChecked is then false. Give it a key file. With requirePq: true, a record of Requisition's evaluation environment without a valid ML-DSA-87 signature or co-signature is refused; this option needs a key file.

The MCP proxy

requisition-mcp-proxy stands between an MCP client and an MCP server. It holds every tools/call of a registered tool, proposes it to Requisition, and forwards it to the server when it holds a checked allow and has claimed it in its store.

requisition-mcp-proxy --config proxy.json --stdio
requisition-mcp-proxy --config proxy.json --http --port 8808

The configuration is a JSON file:

member meaning
requisition url, credential_file, principal, keys_file (required), approval_base_url; optional require_pq (true or false, default true), allow_classical_only (true or false, default false), accept_signers (the signer labels a key may carry: default ["kms"]; "any" lifts it), keys_max_age_seconds (a number above zero and at most 86400, default 300: the key file is read again at least that often), unix_socket (a path), allow_plaintext_private (true or false, default false).
store The path of the proxy's SQLite store.
seed, tools The seed file that describes the registered act types, and the map from tool name to act type.
agent, session, proxy_id Names put into the proposed arguments and into the proxy's idempotency keys.
upstream The MCP server: {command, args, env} for a child process, or {url} for Streamable HTTP.
caller_id The caller's name over stdio (default local).
http For --http: tokens_file (a JSON object from the SHA-256, in hex, of a bearer token to a caller name), and optional allowed_origins (a list of strings) and path.

Accepted values only. A switch takes the JSON booleans true or false; "true", "false", 1, 0, "" and null are refused. keys_max_age_seconds takes a JSON number above zero and at most 86400 (one day). When present, unix_socket must be a non-empty string and allowed_origins a list of non-empty strings. The tokens file must map 64 hex digits to a non-empty caller name, each digest once (the same digest in upper and lower case is refused). --host must be a host name or an IP literal; without it the proxy listens on 127.0.0.1. Any other value refuses to start (exit 78) and names the setting. A wrong value never falls back to the weaker setting.

How it answers a tools/call:

  • A tool that is not registered is denied, and nothing is forwarded.
  • While the request is pending, the answer is an error result that says awaiting approval, with the request id and the approval link. The tool did not run. The client calls again once it is approved.
  • A refused request, a signed deny, an allow whose exec_not_after has passed, a failed check and an unreachable Requisition or store all give an error result that says the tool did not run.
  • On a checked allow, the proxy claims the approval in its store and then forwards the call. From that moment no answer says that the tool did not run: if the server's answer is lost, the proxy says the outcome is unknown and that the call must not be repeated for this approval.
  • A repeated call (the same caller, JSON-RPC id and arguments) is answered from the stored result while the stored execute call is still valid, and with an error result after that. The tool does not run a second time.

tools/list shows the registered tools and leaves the others out. The Streamable HTTP server accepts POST, requires a bearer token that maps to a caller name, checks the Origin header against the allowed origins, and does not mint a session. Over stdio, standard output carries MCP messages and nothing else. The command exits 78 on a bad configuration and 70 on an internal error.

The float refusal

Requisition's canonical encoding has no decimal numbers, so this package refuses one instead of guessing how it would be written:

  • checkArguments, which propose and the proxy run before anything is sent, throws IntakeRefusal("float_refused", path) at the first float in the arguments, before every other intake check. path names the member, for example args.amount.
  • encode and actHash throw CanonicalRefusal("float_refused", path).
  • The proxy answers arguments refused before sending (float_refused at <path>); nothing was proposed.

What counts as a float: a number that is not an integer (12.5, NaN, the infinities), and, in JSON text read by parseStrict, any number written with a fraction or an exponent (1.0, 1e5). The reader keeps such a number as its text, so 1.0 in an MCP message is refused and is never turned into 1. JavaScript itself has one number type: a value written 1.0 in JavaScript source is the integer 1 by the time this package sees it.

An integer outside ±(2^53 − 1) is refused too. Given as a JavaScript number, the encoder refuses it integer_out_of_range. Written in JSON text read by parseStrict, it is kept as its text, as a float is, and the encoder refuses it float_refused. At intake it is refused malformed_member.

Send amounts as integers in a minor unit (amount_minor: 1250) or as strings.

Checking a record offline

verifyRecord (in src/verify.ts) checks one signed record against a pinned key file. It makes no network call.

import { KeyRegistry, verifyRecord } from "requisition-ts";

const keys = KeyRegistry.fromFile("requisition-keys.json");
const result = verifyRecord(
  { record, cosignature },                       // cosignature may be left out
  { keys, expect: { actType: "payments.refund_send", args, principal } },
);
if (!result.ok) console.error(result.failures);

It checks, and lists every failure in failures:

  • that record is the four-field envelope (signature, key_id, signed_payload, receipt_hash) and that receipt_hash is the SHA-256 of signed_payload;
  • that signed_payload is strict JSON with a metadata object;
  • the signature under the key rule (signature: ok, invalid or unknown_key);
  • the co-signature rules of Requisition's evaluation environment for ML-DSA-87 (pq: checked, absent or invalid): a co-signature must cover the record's own bytes, be named by the record's signed cosign member and verify under the key file, and a record that says it is co-signed and arrives without its co-signature fails as stripped;
  • with expect, that the record binds the expected act (binding): the act type, the act hash recomputed from args, the hash label, the principal when given, and the display digest of a statement or a decision. A record with no act_hash_alg member fails.

Options: requirePq: true fails a record of Requisition's evaluation environment that carries no checked ML-DSA-87 signature. Without it, the key file decides: when it holds an ML-DSA-87 key of the record's signer, a record of the evaluation environment without such a signature fails, unless allowClassicalOnly: true is given.

kind is the record's signed receipt_type. For an outcome record, outcomeNote says that the outcome was reported by the caller and is not proof that the effect happened. ok says that the checks above passed. It does not say that the record is an allow: verifyRecord does not read the verdict.

Tests

npm ci
npm test

The tests run the TypeScript sources directly with Node, against a local fake of the /v1 API. They need no network, no Requisition server and no other repository.

Limits, stated

  • Authorization, not execution. A signed allow shows that the act was authorized. It does not show that it ran. The outcome record is the caller's report.
  • The key file. A key file fetched from the server is served by the party whose signatures it checks. Pin the file you verify against.
  • The store. The store is one SQLite file on one host. The claim that an approval was acted on is as durable as that file, and a second host with its own store does not see it.
  • Interactive tools. A tool that asks for interactive input (input_required) is not supported by the proxy: the call is forwarded, its approval is used, and the answer is an error result.

About

TypeScript SDK and MCP proxy for Requisition's lab /v1 API (byte-compatible with requisition-aws).

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages