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.
| 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. |
npm install requisition-ts@0.1.0Node 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.
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:
proposeruns the intake rules, derives the act hash and files a sanction request. A secondproposeof the same act finds the open request instead of filing another.awaitDecisionpolls 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.executesends the execute call and returns the signed decision,allowordeny. The bytes of the call are stored underkeybefore they are sent, and a retry with the samekeysends the same bytes.runnablesays whether an allow can still be acted on: its signedexec_not_afterhas not passed.claimrecords, 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, throwsFenceRefused.reportOutcomesends the caller's report of what happened and returns a short status:recorded,unsupported(the server has no outcome route) ornot 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.
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 8808The 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, anallowwhoseexec_not_afterhas 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.
Requisition's canonical encoding has no decimal numbers, so this package refuses one instead of guessing how it would be written:
checkArguments, whichproposeand the proxy run before anything is sent, throwsIntakeRefusal("float_refused", path)at the first float in the arguments, before every other intake check.pathnames the member, for exampleargs.amount.encodeandactHashthrowCanonicalRefusal("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.
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
recordis the four-field envelope (signature,key_id,signed_payload,receipt_hash) and thatreceipt_hashis the SHA-256 ofsigned_payload; - that
signed_payloadis strict JSON with ametadataobject; - the signature under the key rule (
signature:ok,invalidorunknown_key); - the co-signature rules of Requisition's evaluation environment for ML-DSA-87 (
pq:checked,absentorinvalid): a co-signature must cover the record's own bytes, be named by the record's signedcosignmember and verify under the key file, and a record that says it is co-signed and arrives without its co-signature fails asstripped; - with
expect, that the record binds the expected act (binding): the act type, the act hash recomputed fromargs, the hash label, the principal when given, and the display digest of a statement or a decision. A record with noact_hash_algmember 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.
npm ci
npm testThe 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.
- Authorization, not execution. A signed
allowshows 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.