@paystage/mcp 0.3.3 → 0.3.5-canary.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -3
- package/dist/server.d.ts +3 -2
- package/dist/server.js +10 -198
- package/dist/tools.d.ts +37 -0
- package/dist/tools.js +352 -0
- package/dist/verify-cli.d.ts +1 -1
- package/dist/verify-cli.js +54 -4
- package/dist/verify.d.ts +40 -1
- package/dist/verify.js +128 -5
- package/package.json +12 -8
- package/server.json +9 -3
package/README.md
CHANGED
|
@@ -7,6 +7,35 @@ PayStage umbrella MCP server: payment preflight, auth watch, HIP-3 trade preflig
|
|
|
7
7
|
|
|
8
8
|
Published on npm as **`@paystage/mcp`** — see the [npm page](https://www.npmjs.com/package/@paystage/mcp) for the current version rather than a number here that can go stale.
|
|
9
9
|
|
|
10
|
+
|
|
11
|
+
## What a valid receipt means
|
|
12
|
+
|
|
13
|
+
`paystage-verify` returning exit 0 means **the key it verified against signed this receipt
|
|
14
|
+
and it has not been altered**. That is all it means — and which key that was matters:
|
|
15
|
+
|
|
16
|
+
- `key_source: "published"` → PayStage's published key: the issuer signed it.
|
|
17
|
+
- `key_source: "supplied"` (you passed `--key` or `--key-url`) → **the key you named signed
|
|
18
|
+
it**, which is a weaker claim and not evidence about PayStage at all. Exit 0 on that path
|
|
19
|
+
says nothing more than that the holder of that key produced the receipt.
|
|
20
|
+
|
|
21
|
+
It does **not** mean the payment happened — settlement is a separate on-chain event. It does
|
|
22
|
+
not mean the verdict was correct — a receipt records a decision, not the soundness of the
|
|
23
|
+
policy behind it. And it does not identify the caller; no caller identity is bound into the
|
|
24
|
+
payload, by design.
|
|
25
|
+
|
|
26
|
+
Two narrower points a careful reader should know:
|
|
27
|
+
|
|
28
|
+
- **`key_source` tells you where the verifying key came from**: `published` (PayStage's
|
|
29
|
+
endpoint) or `supplied` (someone passed `--key`). A receipt verified against a supplied key
|
|
30
|
+
proves only that the holder of *that* key signed it.
|
|
31
|
+
- **A receipt with `signed: false` is still useful**: the request and policy digests are
|
|
32
|
+
checkable, so "over these inputs" survives even when provenance does not.
|
|
33
|
+
- **`--max-age` is your policy, not the issuer's.** Nothing in the signed payload says how
|
|
34
|
+
long a verdict is meant to hold, so a freshness bound is set by the verifier. If "this
|
|
35
|
+
verdict is good for 24 hours" ever becomes the issuer's promise it has to be signed, and
|
|
36
|
+
that is a format change.
|
|
37
|
+
|
|
38
|
+
|
|
10
39
|
## Install
|
|
11
40
|
|
|
12
41
|
```sh
|
|
@@ -30,7 +59,7 @@ The package exposes a `stdio` MCP server (bin: `paystage-mcp`).
|
|
|
30
59
|
"mcpServers": {
|
|
31
60
|
"paystage": {
|
|
32
61
|
"command": "npx",
|
|
33
|
-
"args": ["-y", "@paystage/mcp"],
|
|
62
|
+
"args": ["-y", "-p", "@paystage/mcp", "paystage-mcp"],
|
|
34
63
|
"env": {
|
|
35
64
|
"PAYSTAGE_POLICY_PATH": "./policy.json"
|
|
36
65
|
}
|
|
@@ -78,7 +107,7 @@ this tool.
|
|
|
78
107
|
|
|
79
108
|
| Package | Version | Purpose |
|
|
80
109
|
| --- | --- | --- |
|
|
81
|
-
| `@paystage/mcp` | Umbrella server (
|
|
110
|
+
| `@paystage/mcp` | Umbrella server (9 tools) |
|
|
82
111
|
| `@paystage/preflight` | x402 payment preflight |
|
|
83
112
|
| `@paystage/auth-watch` | Outstanding-auth tools |
|
|
84
113
|
| `@paystage/trade-preflight` | HIP-3 / trade.xyz trade preflight |
|
|
@@ -102,7 +131,9 @@ Exit codes are distinct on purpose:
|
|
|
102
131
|
| 0 | signature matches the payload |
|
|
103
132
|
| 1 | **invalid** — altered, or signed by a different key |
|
|
104
133
|
| 2 | unsigned — a record of the decision, with no proof of who made it |
|
|
105
|
-
| 3 | unverifiable — the key could not be fetched, so nothing can be checked |
|
|
134
|
+
| 3 | unverifiable — the key could not be fetched, or an input file could not be read, so nothing can be checked |
|
|
135
|
+
| 4 | inputs-mismatch — the receipt is genuine but does not cover the `--request`/`--policy` you supplied |
|
|
136
|
+
| 5 | stale — the receipt is genuine but older than `--max-age` allows |
|
|
106
137
|
|
|
107
138
|
"Invalid" and "could not check" are different facts and must not collapse into one
|
|
108
139
|
failure. `--key <file>` verifies against a local JWK for point-in-time checks.
|
|
@@ -139,3 +170,21 @@ Full table: [SECURITY.md](../../SECURITY.md).
|
|
|
139
170
|
## License
|
|
140
171
|
|
|
141
172
|
MIT
|
|
173
|
+
|
|
174
|
+
## Tools
|
|
175
|
+
|
|
176
|
+
Every one is read-only. None of them signs, holds a key, or moves money — the agent stays the only
|
|
177
|
+
signer, which is the entire product.
|
|
178
|
+
|
|
179
|
+
| tool | what it answers |
|
|
180
|
+
|---|---|
|
|
181
|
+
| `evaluate_mcp_payment` | should this x402 payment be signed? → `pay` · `review` · `do_not_pay` |
|
|
182
|
+
| `evaluate_batch` | the same question for several payments at once, one verdict each |
|
|
183
|
+
| `list_outstanding_auths` | which ERC-20 / Permit2 / EIP-3009 authorisations are still outstanding |
|
|
184
|
+
| `evaluate_outstanding_auths` | which of those need attention before the next payment |
|
|
185
|
+
| `evaluate_hip3_trade` | should this HIP-3 / trade.xyz order be placed? → `allow` · `review` · `do_not_trade` |
|
|
186
|
+
| `evaluate_velocity` | is this spend a burst, a spike, or a runaway cadence |
|
|
187
|
+
| `verify_receipt` | is this receipt really ours, checked against the published key |
|
|
188
|
+
| `decode_payment_required` | what does this base64 402 header actually say |
|
|
189
|
+
| `validate_policy` | is this policy document valid, and if not why |
|
|
190
|
+
|
package/dist/server.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { McpServer } from "@modelcontextprotocol/server";
|
|
2
|
-
|
|
3
|
-
export
|
|
2
|
+
import { TOOL_NAMES, type ToolName } from "./tools.js";
|
|
3
|
+
export { TOOL_NAMES };
|
|
4
|
+
export type { ToolName };
|
|
4
5
|
export declare function createServer(): McpServer;
|
|
5
6
|
export declare function getToolNames(): string[];
|
|
6
7
|
export declare function startServer(): Promise<void>;
|
package/dist/server.js
CHANGED
|
@@ -1,212 +1,24 @@
|
|
|
1
1
|
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
|
|
2
2
|
import { createRequire } from "node:module";
|
|
3
|
+
import { McpServer } from "@modelcontextprotocol/server";
|
|
4
|
+
import { loadPolicy, parsePolicy } from "@paystage/policy";
|
|
5
|
+
import { registerAllTools, SERVER_CAPABILITIES, TOOL_NAMES } from "./tools.js";
|
|
3
6
|
/**
|
|
4
|
-
* Report the real package version. This was hardcoded as "0.3.0" and stayed there two
|
|
5
|
-
*
|
|
7
|
+
* Report the real package version. This was hardcoded as "0.3.0" and stayed there two releases,
|
|
8
|
+
* so every client logging serverInfo was told the wrong version.
|
|
6
9
|
*/
|
|
7
10
|
const SERVER_VERSION = createRequire(import.meta.url)("../package.json").version;
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
import { loadPolicy, parsePolicy } from "@paystage/policy";
|
|
11
|
-
import { evaluatePayment, normalizePaymentRequired } from "@paystage/preflight";
|
|
12
|
-
import { listOutstandingAuths, evaluateOutstandingAuths, createRpcClient, resolveRpcUrl, } from "@paystage/auth-watch";
|
|
13
|
-
import { evaluateTrade, parseTradePolicy, fetchMetaAndAssetCtxs, } from "@paystage/trade-preflight";
|
|
14
|
-
import { evaluateVelocity, serializeVelocityResult, EvaluateVelocityInputSchema, } from "@paystage/velocity";
|
|
15
|
-
export const TOOL_NAMES = [
|
|
16
|
-
"evaluate_mcp_payment",
|
|
17
|
-
"list_outstanding_auths",
|
|
18
|
-
"evaluate_outstanding_auths",
|
|
19
|
-
"evaluate_hip3_trade",
|
|
20
|
-
"evaluate_velocity",
|
|
21
|
-
];
|
|
22
|
-
const DEFAULT_NETWORK = "base";
|
|
11
|
+
export { TOOL_NAMES };
|
|
12
|
+
/** The stdio transport resolves a policy from a path; the Worker never can. */
|
|
23
13
|
async function resolvePolicy(input) {
|
|
24
|
-
if (input.policy !== undefined)
|
|
14
|
+
if (input.policy !== undefined)
|
|
25
15
|
return parsePolicy(input.policy);
|
|
26
|
-
}
|
|
27
16
|
const path = input.policy_path ?? process.env.PAYSTAGE_POLICY_PATH ?? "./policy.json";
|
|
28
17
|
return await loadPolicy(path);
|
|
29
18
|
}
|
|
30
|
-
function tokensForNetwork(policy, network) {
|
|
31
|
-
const tokens = policy.tokens;
|
|
32
|
-
return tokens?.[network] ?? [];
|
|
33
|
-
}
|
|
34
|
-
function spendersForPolicy(policy) {
|
|
35
|
-
const spenders = policy.spenders;
|
|
36
|
-
return spenders ?? [];
|
|
37
|
-
}
|
|
38
|
-
const authWatchShape = {
|
|
39
|
-
wallet: z.string(),
|
|
40
|
-
network: z.string().optional(),
|
|
41
|
-
tokens: z.array(z.string()).optional(),
|
|
42
|
-
spenders: z.array(z.string()).optional(),
|
|
43
|
-
policy_path: z.string().optional(),
|
|
44
|
-
policy: z.unknown().optional(),
|
|
45
|
-
eip3009_nonces: z.array(z.string()).optional(),
|
|
46
|
-
rpc_url: z.string().optional(),
|
|
47
|
-
};
|
|
48
|
-
const tradeProposalShape = z.object({
|
|
49
|
-
dex: z.string(),
|
|
50
|
-
asset: z.string(),
|
|
51
|
-
side: z.enum(["buy", "sell"]),
|
|
52
|
-
size: z.string(),
|
|
53
|
-
leverage: z.number().optional(),
|
|
54
|
-
order_type: z.enum(["limit", "market"]).optional(),
|
|
55
|
-
limit_px: z.string().optional(),
|
|
56
|
-
});
|
|
57
|
-
function registerAllTools(server) {
|
|
58
|
-
server.registerTool("evaluate_mcp_payment", {
|
|
59
|
-
description: "Evaluate an x402 PaymentRequired payload against a PayStage spending policy before paying",
|
|
60
|
-
inputSchema: z.object({
|
|
61
|
-
payment_required: z.unknown(),
|
|
62
|
-
policy_path: z.string().optional(),
|
|
63
|
-
policy: z.unknown().optional(),
|
|
64
|
-
}),
|
|
65
|
-
}, async (input) => {
|
|
66
|
-
try {
|
|
67
|
-
const policy = await resolvePolicy(input);
|
|
68
|
-
const pr = normalizePaymentRequired(input.payment_required);
|
|
69
|
-
const result = evaluatePayment(pr, policy);
|
|
70
|
-
return {
|
|
71
|
-
content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
|
|
72
|
-
};
|
|
73
|
-
}
|
|
74
|
-
catch (error) {
|
|
75
|
-
const message = error instanceof Error ? error.message : String(error);
|
|
76
|
-
return {
|
|
77
|
-
isError: true,
|
|
78
|
-
content: [{ type: "text", text: `Error: ${message}` }],
|
|
79
|
-
};
|
|
80
|
-
}
|
|
81
|
-
});
|
|
82
|
-
server.registerTool("list_outstanding_auths", {
|
|
83
|
-
description: "List outstanding token authorizations for a wallet",
|
|
84
|
-
inputSchema: z.object(authWatchShape),
|
|
85
|
-
}, async (args) => {
|
|
86
|
-
const policy = await resolvePolicy(args);
|
|
87
|
-
const network = args.network ?? DEFAULT_NETWORK;
|
|
88
|
-
const tokens = args.tokens ?? tokensForNetwork(policy, network);
|
|
89
|
-
const spenders = args.spenders ?? spendersForPolicy(policy);
|
|
90
|
-
const rpcUrl = args.rpc_url ?? resolveRpcUrl(network);
|
|
91
|
-
const rpc = createRpcClient(rpcUrl);
|
|
92
|
-
const items = await listOutstandingAuths({
|
|
93
|
-
wallet: args.wallet,
|
|
94
|
-
network,
|
|
95
|
-
tokens,
|
|
96
|
-
spenders,
|
|
97
|
-
rpc,
|
|
98
|
-
eip3009Nonces: args.eip3009_nonces,
|
|
99
|
-
});
|
|
100
|
-
const serialized = items.map((i) => ({
|
|
101
|
-
...i,
|
|
102
|
-
amount: i.amount.toString(),
|
|
103
|
-
}));
|
|
104
|
-
return {
|
|
105
|
-
content: [
|
|
106
|
-
{
|
|
107
|
-
type: "text",
|
|
108
|
-
text: JSON.stringify({ items: serialized }, null, 2),
|
|
109
|
-
},
|
|
110
|
-
],
|
|
111
|
-
};
|
|
112
|
-
});
|
|
113
|
-
server.registerTool("evaluate_outstanding_auths", {
|
|
114
|
-
description: "List and evaluate outstanding token authorizations against a policy",
|
|
115
|
-
inputSchema: z.object(authWatchShape),
|
|
116
|
-
}, async (args) => {
|
|
117
|
-
const policy = await resolvePolicy(args);
|
|
118
|
-
const network = args.network ?? DEFAULT_NETWORK;
|
|
119
|
-
const tokens = args.tokens ?? tokensForNetwork(policy, network);
|
|
120
|
-
const spenders = args.spenders ?? spendersForPolicy(policy);
|
|
121
|
-
const rpcUrl = args.rpc_url ?? resolveRpcUrl(network);
|
|
122
|
-
const rpc = createRpcClient(rpcUrl);
|
|
123
|
-
const items = await listOutstandingAuths({
|
|
124
|
-
wallet: args.wallet,
|
|
125
|
-
network,
|
|
126
|
-
tokens,
|
|
127
|
-
spenders,
|
|
128
|
-
rpc,
|
|
129
|
-
eip3009Nonces: args.eip3009_nonces,
|
|
130
|
-
});
|
|
131
|
-
const results = evaluateOutstandingAuths(items, policy);
|
|
132
|
-
const serialized = results.map((r) => ({
|
|
133
|
-
item: { ...r.item, amount: r.item.amount.toString() },
|
|
134
|
-
flags: r.flags,
|
|
135
|
-
summary: r.summary,
|
|
136
|
-
}));
|
|
137
|
-
return {
|
|
138
|
-
content: [
|
|
139
|
-
{
|
|
140
|
-
type: "text",
|
|
141
|
-
text: JSON.stringify({ results: serialized }, null, 2),
|
|
142
|
-
},
|
|
143
|
-
],
|
|
144
|
-
};
|
|
145
|
-
});
|
|
146
|
-
server.registerTool("evaluate_hip3_trade", {
|
|
147
|
-
description: "Evaluate a Hyperliquid HIP-3 (trade.xyz) order against a TradePolicy before an agent trades. Returns decision allow | review | do_not_trade.",
|
|
148
|
-
inputSchema: z.object({
|
|
149
|
-
proposal: tradeProposalShape,
|
|
150
|
-
policy: z.unknown().optional(),
|
|
151
|
-
policy_path: z.string().optional(),
|
|
152
|
-
snapshot: z.unknown().optional(),
|
|
153
|
-
}),
|
|
154
|
-
}, async (args) => {
|
|
155
|
-
try {
|
|
156
|
-
const policy = parseTradePolicy(args.policy);
|
|
157
|
-
const snapshot = args.snapshot !== undefined
|
|
158
|
-
? args.snapshot
|
|
159
|
-
: await fetchMetaAndAssetCtxs(args.proposal.dex || "xyz");
|
|
160
|
-
const result = evaluateTrade(args.proposal, snapshot, policy);
|
|
161
|
-
return {
|
|
162
|
-
content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
|
|
163
|
-
};
|
|
164
|
-
}
|
|
165
|
-
catch (error) {
|
|
166
|
-
const message = error instanceof Error ? error.message : String(error);
|
|
167
|
-
return {
|
|
168
|
-
isError: true,
|
|
169
|
-
content: [{ type: "text", text: `Error: ${message}` }],
|
|
170
|
-
};
|
|
171
|
-
}
|
|
172
|
-
});
|
|
173
|
-
server.registerTool("evaluate_velocity", {
|
|
174
|
-
description: "Rolling-window rate and spend-pattern check for a proposed payment against recent action history and a policy.velocity config",
|
|
175
|
-
inputSchema: z.object({
|
|
176
|
-
history: EvaluateVelocityInputSchema.shape.history,
|
|
177
|
-
proposed: EvaluateVelocityInputSchema.shape.proposed,
|
|
178
|
-
policy: z.unknown().optional(),
|
|
179
|
-
policy_path: z.string().optional(),
|
|
180
|
-
now_ms: z.number().int().nonnegative().optional(),
|
|
181
|
-
}),
|
|
182
|
-
}, async (input) => {
|
|
183
|
-
try {
|
|
184
|
-
const parsed = EvaluateVelocityInputSchema.parse(input);
|
|
185
|
-
const result = await evaluateVelocity(parsed);
|
|
186
|
-
return {
|
|
187
|
-
content: [
|
|
188
|
-
{
|
|
189
|
-
type: "text",
|
|
190
|
-
text: JSON.stringify(serializeVelocityResult(result), null, 2),
|
|
191
|
-
},
|
|
192
|
-
],
|
|
193
|
-
};
|
|
194
|
-
}
|
|
195
|
-
catch (error) {
|
|
196
|
-
const message = error instanceof Error ? error.message : String(error);
|
|
197
|
-
return {
|
|
198
|
-
isError: true,
|
|
199
|
-
content: [{ type: "text", text: `Error: ${message}` }],
|
|
200
|
-
};
|
|
201
|
-
}
|
|
202
|
-
});
|
|
203
|
-
}
|
|
204
19
|
export function createServer() {
|
|
205
|
-
const server = new McpServer({
|
|
206
|
-
|
|
207
|
-
version: SERVER_VERSION,
|
|
208
|
-
});
|
|
209
|
-
registerAllTools(server);
|
|
20
|
+
const server = new McpServer({ name: "paystage", version: SERVER_VERSION }, { capabilities: SERVER_CAPABILITIES });
|
|
21
|
+
registerAllTools(server, { resolvePolicy, version: SERVER_VERSION });
|
|
210
22
|
return server;
|
|
211
23
|
}
|
|
212
24
|
export function getToolNames() {
|
package/dist/tools.d.ts
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { McpServer, type ServerCapabilities } from "@modelcontextprotocol/server";
|
|
2
|
+
import type { Policy } from "@paystage/policy";
|
|
3
|
+
export declare const TOOL_NAMES: readonly ["evaluate_mcp_payment", "list_outstanding_auths", "evaluate_outstanding_auths", "evaluate_hip3_trade", "evaluate_velocity", "verify_receipt", "decode_payment_required", "validate_policy", "evaluate_batch"];
|
|
4
|
+
export type ToolName = (typeof TOOL_NAMES)[number];
|
|
5
|
+
/**
|
|
6
|
+
* The server exposes tools only, but it must answer `resources/list` and `prompts/list` with an
|
|
7
|
+
* empty result rather than `-32601 Method not found`: Anthropic's and Cursor's MCP checks treat a
|
|
8
|
+
* declared-but-unimplemented capability as a bug, and a client that probes either list gets a hard
|
|
9
|
+
* error instead of "none". Declaring the capabilities is what makes the SDK serve the empty lists
|
|
10
|
+
* (see `ServerOptions.capabilities`); no resource or prompt is registered.
|
|
11
|
+
*
|
|
12
|
+
* Shared by the stdio server and the hosted Worker so both surfaces answer the same way.
|
|
13
|
+
*/
|
|
14
|
+
export declare const SERVER_CAPABILITIES: ServerCapabilities;
|
|
15
|
+
export interface ToolDeps {
|
|
16
|
+
/**
|
|
17
|
+
* Resolve a policy from a tool call. The stdio server reads a file; the hosted Worker has no
|
|
18
|
+
* filesystem, so it refuses `policy_path` and requires an inline policy.
|
|
19
|
+
*/
|
|
20
|
+
resolvePolicy: (input: {
|
|
21
|
+
policy?: unknown;
|
|
22
|
+
policy_path?: string;
|
|
23
|
+
}) => Promise<Policy>;
|
|
24
|
+
/** Reported in `serverInfo`; the Worker and the package version them separately. */
|
|
25
|
+
version: string;
|
|
26
|
+
/**
|
|
27
|
+
* The published key, when the host already holds it.
|
|
28
|
+
*
|
|
29
|
+
* A Worker that serves `verify_receipt` cannot fetch its own `/v1/public/receipt-key.json`: the
|
|
30
|
+
* subrequest to its own origin came back 522/523, so a genuine signed receipt reported
|
|
31
|
+
* `unverifiable` on the live endpoint while the same check passed locally. Passing the key in
|
|
32
|
+
* removes the network from the one path that is supposed to be an independent check.
|
|
33
|
+
*/
|
|
34
|
+
resolveReceiptKey?: () => Promise<Record<string, unknown> | null>;
|
|
35
|
+
}
|
|
36
|
+
export declare function registerAllTools(server: McpServer, deps: ToolDeps): void;
|
|
37
|
+
//# sourceMappingURL=tools.d.ts.map
|
package/dist/tools.js
ADDED
|
@@ -0,0 +1,352 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { parsePolicy } from "@paystage/policy";
|
|
3
|
+
import { evaluatePayment, normalizePaymentRequired } from "@paystage/preflight";
|
|
4
|
+
import { verifyReceipt } from "./verify.js";
|
|
5
|
+
import { listOutstandingAuths, evaluateOutstandingAuths, createRpcClient, resolveRpcUrl, } from "@paystage/auth-watch";
|
|
6
|
+
import { evaluateTrade, parseTradePolicy, fetchMetaAndAssetCtxs, } from "@paystage/trade-preflight";
|
|
7
|
+
import { evaluateVelocity, serializeVelocityResult, EvaluateVelocityInputSchema, } from "@paystage/velocity";
|
|
8
|
+
export const TOOL_NAMES = [
|
|
9
|
+
"evaluate_mcp_payment",
|
|
10
|
+
"list_outstanding_auths",
|
|
11
|
+
"evaluate_outstanding_auths",
|
|
12
|
+
"evaluate_hip3_trade",
|
|
13
|
+
"evaluate_velocity",
|
|
14
|
+
"verify_receipt",
|
|
15
|
+
"decode_payment_required",
|
|
16
|
+
"validate_policy",
|
|
17
|
+
"evaluate_batch",
|
|
18
|
+
];
|
|
19
|
+
const DEFAULT_NETWORK = "base";
|
|
20
|
+
/**
|
|
21
|
+
* The server exposes tools only, but it must answer `resources/list` and `prompts/list` with an
|
|
22
|
+
* empty result rather than `-32601 Method not found`: Anthropic's and Cursor's MCP checks treat a
|
|
23
|
+
* declared-but-unimplemented capability as a bug, and a client that probes either list gets a hard
|
|
24
|
+
* error instead of "none". Declaring the capabilities is what makes the SDK serve the empty lists
|
|
25
|
+
* (see `ServerOptions.capabilities`); no resource or prompt is registered.
|
|
26
|
+
*
|
|
27
|
+
* Shared by the stdio server and the hosted Worker so both surfaces answer the same way.
|
|
28
|
+
*/
|
|
29
|
+
export const SERVER_CAPABILITIES = { resources: {}, prompts: {} };
|
|
30
|
+
function tokensForNetwork(policy, network) {
|
|
31
|
+
const tokens = policy.tokens;
|
|
32
|
+
return tokens?.[network] ?? [];
|
|
33
|
+
}
|
|
34
|
+
function spendersForPolicy(policy) {
|
|
35
|
+
const spenders = policy.spenders;
|
|
36
|
+
return spenders ?? [];
|
|
37
|
+
}
|
|
38
|
+
const authWatchShape = {
|
|
39
|
+
wallet: z.string(),
|
|
40
|
+
network: z.string().optional(),
|
|
41
|
+
tokens: z.array(z.string()).optional(),
|
|
42
|
+
spenders: z.array(z.string()).optional(),
|
|
43
|
+
policy_path: z.string().optional(),
|
|
44
|
+
policy: z.unknown().optional(),
|
|
45
|
+
eip3009_nonces: z.array(z.string()).optional(),
|
|
46
|
+
rpc_url: z.string().optional(),
|
|
47
|
+
};
|
|
48
|
+
const tradeProposalShape = z.object({
|
|
49
|
+
dex: z.string(),
|
|
50
|
+
asset: z.string(),
|
|
51
|
+
side: z.enum(["buy", "sell"]),
|
|
52
|
+
size: z.string(),
|
|
53
|
+
leverage: z.number().optional(),
|
|
54
|
+
order_type: z.enum(["limit", "market"]).optional(),
|
|
55
|
+
limit_px: z.string().optional(),
|
|
56
|
+
});
|
|
57
|
+
export function registerAllTools(server, deps) {
|
|
58
|
+
server.registerTool("evaluate_mcp_payment", {
|
|
59
|
+
description: "Evaluate an x402 PaymentRequired payload against a PayStage spending policy before paying",
|
|
60
|
+
annotations: {
|
|
61
|
+
title: "Evaluate an x402 payment (read-only, never signs)",
|
|
62
|
+
readOnlyHint: true,
|
|
63
|
+
destructiveHint: false,
|
|
64
|
+
openWorldHint: false,
|
|
65
|
+
},
|
|
66
|
+
inputSchema: z.object({
|
|
67
|
+
payment_required: z.unknown(),
|
|
68
|
+
policy_path: z.string().optional(),
|
|
69
|
+
policy: z.unknown().optional(),
|
|
70
|
+
agent_id: z
|
|
71
|
+
.string()
|
|
72
|
+
.optional()
|
|
73
|
+
.describe("Which agent is asking. Required to reach per-agent budgets in policy.agents."),
|
|
74
|
+
}),
|
|
75
|
+
}, async (input) => {
|
|
76
|
+
try {
|
|
77
|
+
const policy = await deps.resolvePolicy(input);
|
|
78
|
+
const pr = normalizePaymentRequired(input.payment_required);
|
|
79
|
+
const result = evaluatePayment(pr, policy, input.agent_id !== undefined ? { agentId: input.agent_id } : {});
|
|
80
|
+
return {
|
|
81
|
+
content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
catch (error) {
|
|
85
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
86
|
+
return {
|
|
87
|
+
isError: true,
|
|
88
|
+
content: [{ type: "text", text: `Error: ${message}` }],
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
});
|
|
92
|
+
server.registerTool("list_outstanding_auths", {
|
|
93
|
+
description: "List outstanding token authorizations for a wallet",
|
|
94
|
+
annotations: {
|
|
95
|
+
title: "List outstanding token authorizations (read-only, never signs)",
|
|
96
|
+
readOnlyHint: true,
|
|
97
|
+
destructiveHint: false,
|
|
98
|
+
openWorldHint: true,
|
|
99
|
+
},
|
|
100
|
+
inputSchema: z.object(authWatchShape),
|
|
101
|
+
}, async (args) => {
|
|
102
|
+
const policy = await deps.resolvePolicy(args);
|
|
103
|
+
const network = args.network ?? DEFAULT_NETWORK;
|
|
104
|
+
const tokens = args.tokens ?? tokensForNetwork(policy, network);
|
|
105
|
+
const spenders = args.spenders ?? spendersForPolicy(policy);
|
|
106
|
+
const rpcUrl = args.rpc_url ?? resolveRpcUrl(network);
|
|
107
|
+
const rpc = createRpcClient(rpcUrl);
|
|
108
|
+
const items = await listOutstandingAuths({
|
|
109
|
+
wallet: args.wallet,
|
|
110
|
+
network,
|
|
111
|
+
tokens,
|
|
112
|
+
spenders,
|
|
113
|
+
rpc,
|
|
114
|
+
eip3009Nonces: args.eip3009_nonces,
|
|
115
|
+
});
|
|
116
|
+
const serialized = items.map((i) => ({
|
|
117
|
+
...i,
|
|
118
|
+
amount: i.amount.toString(),
|
|
119
|
+
}));
|
|
120
|
+
return {
|
|
121
|
+
content: [
|
|
122
|
+
{
|
|
123
|
+
type: "text",
|
|
124
|
+
text: JSON.stringify({ items: serialized }, null, 2),
|
|
125
|
+
},
|
|
126
|
+
],
|
|
127
|
+
};
|
|
128
|
+
});
|
|
129
|
+
server.registerTool("evaluate_outstanding_auths", {
|
|
130
|
+
description: "List and evaluate outstanding token authorizations against a policy",
|
|
131
|
+
annotations: {
|
|
132
|
+
title: "Evaluate outstanding token authorizations (read-only, never signs)",
|
|
133
|
+
readOnlyHint: true,
|
|
134
|
+
destructiveHint: false,
|
|
135
|
+
openWorldHint: true,
|
|
136
|
+
},
|
|
137
|
+
inputSchema: z.object(authWatchShape),
|
|
138
|
+
}, async (args) => {
|
|
139
|
+
const policy = await deps.resolvePolicy(args);
|
|
140
|
+
const network = args.network ?? DEFAULT_NETWORK;
|
|
141
|
+
const tokens = args.tokens ?? tokensForNetwork(policy, network);
|
|
142
|
+
const spenders = args.spenders ?? spendersForPolicy(policy);
|
|
143
|
+
const rpcUrl = args.rpc_url ?? resolveRpcUrl(network);
|
|
144
|
+
const rpc = createRpcClient(rpcUrl);
|
|
145
|
+
const items = await listOutstandingAuths({
|
|
146
|
+
wallet: args.wallet,
|
|
147
|
+
network,
|
|
148
|
+
tokens,
|
|
149
|
+
spenders,
|
|
150
|
+
rpc,
|
|
151
|
+
eip3009Nonces: args.eip3009_nonces,
|
|
152
|
+
});
|
|
153
|
+
const results = evaluateOutstandingAuths(items, policy);
|
|
154
|
+
const serialized = results.map((r) => ({
|
|
155
|
+
item: { ...r.item, amount: r.item.amount.toString() },
|
|
156
|
+
flags: r.flags,
|
|
157
|
+
summary: r.summary,
|
|
158
|
+
}));
|
|
159
|
+
return {
|
|
160
|
+
content: [
|
|
161
|
+
{
|
|
162
|
+
type: "text",
|
|
163
|
+
text: JSON.stringify({ results: serialized }, null, 2),
|
|
164
|
+
},
|
|
165
|
+
],
|
|
166
|
+
};
|
|
167
|
+
});
|
|
168
|
+
server.registerTool("evaluate_hip3_trade", {
|
|
169
|
+
description: "Evaluate a Hyperliquid HIP-3 (trade.xyz) order against a TradePolicy before an agent trades. Returns decision allow | review | do_not_trade.",
|
|
170
|
+
annotations: {
|
|
171
|
+
title: "Evaluate a HIP-3 trade (read-only, never signs)",
|
|
172
|
+
readOnlyHint: true,
|
|
173
|
+
destructiveHint: false,
|
|
174
|
+
openWorldHint: true,
|
|
175
|
+
},
|
|
176
|
+
inputSchema: z.object({
|
|
177
|
+
proposal: tradeProposalShape,
|
|
178
|
+
policy: z.unknown().optional(),
|
|
179
|
+
policy_path: z.string().optional(),
|
|
180
|
+
snapshot: z.unknown().optional(),
|
|
181
|
+
}),
|
|
182
|
+
}, async (args) => {
|
|
183
|
+
try {
|
|
184
|
+
const policy = parseTradePolicy(args.policy);
|
|
185
|
+
const snapshot = args.snapshot !== undefined
|
|
186
|
+
? args.snapshot
|
|
187
|
+
: await fetchMetaAndAssetCtxs(args.proposal.dex || "xyz");
|
|
188
|
+
const result = evaluateTrade(args.proposal, snapshot, policy);
|
|
189
|
+
return {
|
|
190
|
+
content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
catch (error) {
|
|
194
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
195
|
+
return {
|
|
196
|
+
isError: true,
|
|
197
|
+
content: [{ type: "text", text: `Error: ${message}` }],
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
});
|
|
201
|
+
server.registerTool("evaluate_velocity", {
|
|
202
|
+
description: "Rolling-window rate and spend-pattern check for a proposed payment against recent action history and a policy.velocity config",
|
|
203
|
+
annotations: {
|
|
204
|
+
title: "Evaluate payment velocity (read-only, never signs)",
|
|
205
|
+
readOnlyHint: true,
|
|
206
|
+
destructiveHint: false,
|
|
207
|
+
openWorldHint: false,
|
|
208
|
+
},
|
|
209
|
+
inputSchema: z.object({
|
|
210
|
+
history: EvaluateVelocityInputSchema.shape.history,
|
|
211
|
+
proposed: EvaluateVelocityInputSchema.shape.proposed,
|
|
212
|
+
policy: z.unknown().optional(),
|
|
213
|
+
policy_path: z.string().optional(),
|
|
214
|
+
now_ms: z.number().int().nonnegative().optional(),
|
|
215
|
+
}),
|
|
216
|
+
}, async (input) => {
|
|
217
|
+
try {
|
|
218
|
+
const parsed = EvaluateVelocityInputSchema.parse(input);
|
|
219
|
+
const result = await evaluateVelocity(parsed);
|
|
220
|
+
return {
|
|
221
|
+
content: [
|
|
222
|
+
{
|
|
223
|
+
type: "text",
|
|
224
|
+
text: JSON.stringify(serializeVelocityResult(result), null, 2),
|
|
225
|
+
},
|
|
226
|
+
],
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
catch (error) {
|
|
230
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
231
|
+
return {
|
|
232
|
+
isError: true,
|
|
233
|
+
content: [{ type: "text", text: `Error: ${message}` }],
|
|
234
|
+
};
|
|
235
|
+
}
|
|
236
|
+
});
|
|
237
|
+
// ---------------------------------------------------------------------------------------------
|
|
238
|
+
// Four more tools, added 2026-11-14. Each one reuses code that already shipped as a library or a
|
|
239
|
+
// CLI call: nothing here is new logic, it is the same evaluation reachable from an agent.
|
|
240
|
+
// ---------------------------------------------------------------------------------------------
|
|
241
|
+
server.registerTool("verify_receipt", {
|
|
242
|
+
description: "Verify a PayStage receipt against the published signing key. Returns the verdict it attests to, or why it cannot be trusted.",
|
|
243
|
+
annotations: {
|
|
244
|
+
title: "Verify a receipt against the published key (read-only, never signs)",
|
|
245
|
+
readOnlyHint: true,
|
|
246
|
+
destructiveHint: false,
|
|
247
|
+
openWorldHint: true,
|
|
248
|
+
},
|
|
249
|
+
inputSchema: z.object({
|
|
250
|
+
receipt: z.unknown().describe("The receipt object as issued"),
|
|
251
|
+
key_url: z.string().url().optional().describe("Override the published key location"),
|
|
252
|
+
}),
|
|
253
|
+
}, async ({ receipt, key_url }) => {
|
|
254
|
+
try {
|
|
255
|
+
// Prefer a key the host already holds; an explicit key_url still wins, so a caller can check
|
|
256
|
+
// a receipt from a different deployment against that deployment's published key.
|
|
257
|
+
const injected = key_url === undefined && deps.resolveReceiptKey
|
|
258
|
+
? await deps.resolveReceiptKey()
|
|
259
|
+
: null;
|
|
260
|
+
const verdict = await verifyReceipt(receipt, key_url ? { keyUrl: key_url } : injected ? { jwk: injected } : {});
|
|
261
|
+
return { content: [{ type: "text", text: JSON.stringify(verdict, null, 2) }] };
|
|
262
|
+
}
|
|
263
|
+
catch (error) {
|
|
264
|
+
return {
|
|
265
|
+
isError: true,
|
|
266
|
+
content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
|
|
267
|
+
};
|
|
268
|
+
}
|
|
269
|
+
});
|
|
270
|
+
server.registerTool("decode_payment_required", {
|
|
271
|
+
description: "Decode a base64 `payment-required` header from a 402 response into the JSON challenge, so an agent can inspect it before deciding anything.",
|
|
272
|
+
annotations: {
|
|
273
|
+
title: "Decode a payment-required header (read-only, never signs)",
|
|
274
|
+
readOnlyHint: true,
|
|
275
|
+
destructiveHint: false,
|
|
276
|
+
openWorldHint: false,
|
|
277
|
+
},
|
|
278
|
+
inputSchema: z.object({
|
|
279
|
+
header: z.string().min(1).describe("The raw base64 value of the payment-required header"),
|
|
280
|
+
}),
|
|
281
|
+
}, async ({ header }) => {
|
|
282
|
+
// Inline rather than importing @paystage/x402-guard: this is four lines and a dependency for
|
|
283
|
+
// four lines is a supply-chain cost paid by every user of the umbrella.
|
|
284
|
+
let decoded;
|
|
285
|
+
try {
|
|
286
|
+
decoded = typeof atob === "function" ? atob(header) : Buffer.from(header, "base64").toString("utf8");
|
|
287
|
+
}
|
|
288
|
+
catch {
|
|
289
|
+
return { isError: true, content: [{ type: "text", text: "Error: header is not valid base64" }] };
|
|
290
|
+
}
|
|
291
|
+
let parsed;
|
|
292
|
+
try {
|
|
293
|
+
parsed = JSON.parse(decoded);
|
|
294
|
+
}
|
|
295
|
+
catch {
|
|
296
|
+
return { isError: true, content: [{ type: "text", text: "Error: decoded header is not JSON" }] };
|
|
297
|
+
}
|
|
298
|
+
return { content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }] };
|
|
299
|
+
});
|
|
300
|
+
server.registerTool("validate_policy", {
|
|
301
|
+
description: "Check a policy document without evaluating a payment. Returns the exact validation error when it is wrong, which is the question behind most support requests.",
|
|
302
|
+
annotations: {
|
|
303
|
+
title: "Validate a spending policy (read-only, never signs)",
|
|
304
|
+
readOnlyHint: true,
|
|
305
|
+
destructiveHint: false,
|
|
306
|
+
openWorldHint: false,
|
|
307
|
+
},
|
|
308
|
+
inputSchema: z.object({ policy: z.unknown() }),
|
|
309
|
+
}, async ({ policy }) => {
|
|
310
|
+
try {
|
|
311
|
+
const parsed = parsePolicy(policy);
|
|
312
|
+
return {
|
|
313
|
+
content: [{ type: "text", text: JSON.stringify({ valid: true, version: parsed.version ?? null }, null, 2) }],
|
|
314
|
+
};
|
|
315
|
+
}
|
|
316
|
+
catch (error) {
|
|
317
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
318
|
+
return {
|
|
319
|
+
content: [{ type: "text", text: JSON.stringify({ valid: false, error: message }, null, 2) }],
|
|
320
|
+
};
|
|
321
|
+
}
|
|
322
|
+
});
|
|
323
|
+
server.registerTool("evaluate_batch", {
|
|
324
|
+
description: "Evaluate several payment challenges against one policy in a single call. Returns one verdict per input, in order, so an agent settling a batch decides once per payment and can stop at the first refusal.",
|
|
325
|
+
annotations: {
|
|
326
|
+
title: "Evaluate a batch of x402 payments (read-only, never signs)",
|
|
327
|
+
readOnlyHint: true,
|
|
328
|
+
destructiveHint: false,
|
|
329
|
+
openWorldHint: false,
|
|
330
|
+
},
|
|
331
|
+
inputSchema: z.object({
|
|
332
|
+
payments: z.array(z.unknown()).min(1).max(50),
|
|
333
|
+
policy: z.unknown(),
|
|
334
|
+
}),
|
|
335
|
+
}, async ({ payments, policy }) => {
|
|
336
|
+
const parsedPolicy = parsePolicy(policy);
|
|
337
|
+
const results = payments.map((payment) => {
|
|
338
|
+
try {
|
|
339
|
+
const normalised = normalizePaymentRequired(payment);
|
|
340
|
+
return evaluatePayment(normalised, parsedPolicy);
|
|
341
|
+
}
|
|
342
|
+
catch (error) {
|
|
343
|
+
return {
|
|
344
|
+
decision: "do_not_pay",
|
|
345
|
+
reasons: [`could not evaluate: ${error instanceof Error ? error.message : String(error)}`],
|
|
346
|
+
};
|
|
347
|
+
}
|
|
348
|
+
});
|
|
349
|
+
return { content: [{ type: "text", text: JSON.stringify({ results }, null, 2) }] };
|
|
350
|
+
});
|
|
351
|
+
}
|
|
352
|
+
//# sourceMappingURL=tools.js.map
|
package/dist/verify-cli.d.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* `paystage-verify <file|->` — check a PayStage receipt without trusting PayStage.
|
|
4
4
|
*
|
|
5
5
|
* Fetches the published key, verifies the signature over the canonical payload, and
|
|
6
|
-
* prints one of
|
|
6
|
+
* prints one of five verdicts. Exit codes are listed below and in --help.
|
|
7
7
|
* 3 unverifiable (could not check). Distinct codes so a script can tell "forged" from
|
|
8
8
|
* "no key published yet" — collapsing those into one failure would overstate what we
|
|
9
9
|
* know.
|
package/dist/verify-cli.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* `paystage-verify <file|->` — check a PayStage receipt without trusting PayStage.
|
|
4
4
|
*
|
|
5
5
|
* Fetches the published key, verifies the signature over the canonical payload, and
|
|
6
|
-
* prints one of
|
|
6
|
+
* prints one of five verdicts. Exit codes are listed below and in --help.
|
|
7
7
|
* 3 unverifiable (could not check). Distinct codes so a script can tell "forged" from
|
|
8
8
|
* "no key published yet" — collapsing those into one failure would overstate what we
|
|
9
9
|
* know.
|
|
@@ -12,9 +12,15 @@ import { readFile } from "node:fs/promises";
|
|
|
12
12
|
import { DEFAULT_KEY_URL, verifyReceipt } from "./verify.js";
|
|
13
13
|
const EXIT = {
|
|
14
14
|
"signed-and-valid": 0,
|
|
15
|
-
unsigned: 2,
|
|
16
15
|
invalid: 1,
|
|
16
|
+
unsigned: 2,
|
|
17
17
|
unverifiable: 3,
|
|
18
|
+
// New and deliberately distinct: "the receipt is genuine but does not cover the inputs
|
|
19
|
+
// you gave me" is not "this receipt is forged". A script needs to tell those apart.
|
|
20
|
+
"inputs-mismatch": 4,
|
|
21
|
+
// Genuine and coverable, but older than the bound the caller set. A third fact again:
|
|
22
|
+
// "forged" (1), "could not check" (3), and "true but expired" (5).
|
|
23
|
+
stale: 5,
|
|
18
24
|
};
|
|
19
25
|
function usage() {
|
|
20
26
|
return [
|
|
@@ -28,8 +34,14 @@ function usage() {
|
|
|
28
34
|
" --key <path> verify against a local JWK instead of the published one",
|
|
29
35
|
" --key-url <u> override the published key endpoint",
|
|
30
36
|
" --json machine-readable output",
|
|
37
|
+
" --request <f> check the receipt covers this request JSON",
|
|
38
|
+
" --policy <f> check the receipt covers this policy JSON",
|
|
39
|
+
" --max-age <s> reject a receipt older than this many seconds",
|
|
31
40
|
"",
|
|
32
|
-
"Exit codes:
|
|
41
|
+
"Exit codes:",
|
|
42
|
+
" 0 valid · 1 invalid · 2 unsigned · 3 unverifiable · 4 inputs-mismatch · 5 stale",
|
|
43
|
+
" 4 means the receipt is genuine but does not cover the inputs you supplied",
|
|
44
|
+
" 5 means the receipt is genuine but older than --max-age allows",
|
|
33
45
|
].join("\n");
|
|
34
46
|
}
|
|
35
47
|
async function readStdin() {
|
|
@@ -48,14 +60,26 @@ async function main(argv) {
|
|
|
48
60
|
let keyPath;
|
|
49
61
|
let keyUrl;
|
|
50
62
|
let asJson = false;
|
|
63
|
+
let requestPath;
|
|
64
|
+
let policyPath;
|
|
65
|
+
let maxAgeRaw;
|
|
66
|
+
// One chain. The first version had standalone `if`s for the new flags followed by an
|
|
67
|
+
// `else if` chain, so `--json` matched the first test and then fell through to the
|
|
68
|
+
// positional branch — the flag was read as the receipt path.
|
|
51
69
|
for (let i = 0; i < args.length; i += 1) {
|
|
52
70
|
const arg = args[i];
|
|
53
71
|
if (arg === "--json")
|
|
54
72
|
asJson = true;
|
|
73
|
+
else if (arg === "--request")
|
|
74
|
+
requestPath = args[++i];
|
|
75
|
+
else if (arg === "--policy")
|
|
76
|
+
policyPath = args[++i];
|
|
55
77
|
else if (arg === "--key")
|
|
56
78
|
keyPath = args[++i];
|
|
57
79
|
else if (arg === "--key-url")
|
|
58
80
|
keyUrl = args[++i];
|
|
81
|
+
else if (arg === "--max-age")
|
|
82
|
+
maxAgeRaw = args[++i];
|
|
59
83
|
else if (arg !== undefined)
|
|
60
84
|
source = arg;
|
|
61
85
|
}
|
|
@@ -91,9 +115,35 @@ async function main(argv) {
|
|
|
91
115
|
}
|
|
92
116
|
if (keyUrl !== undefined)
|
|
93
117
|
options.keyUrl = keyUrl;
|
|
118
|
+
// --request / --policy turn the stated digests into a checked claim. An unreadable file
|
|
119
|
+
// is "could not check" (exit 3), never a pass and never a forgery verdict.
|
|
120
|
+
const readJson = async (p) => {
|
|
121
|
+
try {
|
|
122
|
+
return JSON.parse(await readFile(p, "utf8"));
|
|
123
|
+
}
|
|
124
|
+
catch (error) {
|
|
125
|
+
process.stdout.write(`UNVERIFIABLE — could not read ${p}: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
126
|
+
process.exit(3);
|
|
127
|
+
}
|
|
128
|
+
};
|
|
129
|
+
if (requestPath !== undefined)
|
|
130
|
+
options.expectedRequest = await readJson(requestPath);
|
|
131
|
+
if (policyPath !== undefined)
|
|
132
|
+
options.expectedPolicy = await readJson(policyPath);
|
|
133
|
+
if (maxAgeRaw !== undefined) {
|
|
134
|
+
const seconds = Number(maxAgeRaw);
|
|
135
|
+
if (!Number.isFinite(seconds) || seconds < 0) {
|
|
136
|
+
process.stderr.write(`paystage-verify: --max-age needs a number of seconds, got ${JSON.stringify(maxAgeRaw)}\n`);
|
|
137
|
+
return 3;
|
|
138
|
+
}
|
|
139
|
+
options.maxAgeSeconds = seconds;
|
|
140
|
+
}
|
|
94
141
|
const verdict = await verifyReceipt(receipt, options);
|
|
95
142
|
if (asJson) {
|
|
96
|
-
|
|
143
|
+
// `key_source` says published-or-supplied; this says WHICH. A machine consumer that
|
|
144
|
+
// cannot tell those apart can be handed a forged receipt and a matching key.
|
|
145
|
+
const source = keyPath !== undefined ? `file:${keyPath}` : (keyUrl ?? DEFAULT_KEY_URL);
|
|
146
|
+
process.stdout.write(`${JSON.stringify({ ...verdict, key_source_detail: source })}\n`);
|
|
97
147
|
}
|
|
98
148
|
else if (verdict.ok) {
|
|
99
149
|
process.stdout.write([
|
package/dist/verify.d.ts
CHANGED
|
@@ -24,7 +24,6 @@ export interface JwkLike {
|
|
|
24
24
|
}
|
|
25
25
|
export declare const RECEIPT_ALG = "ECDSA-P256-SHA256";
|
|
26
26
|
export declare const DEFAULT_KEY_URL = "https://api.paystage.xyz/v1/public/receipt-key.json";
|
|
27
|
-
/** JSON with recursively sorted keys and no insignificant whitespace. */
|
|
28
27
|
export declare function canonicalize(value: unknown): string;
|
|
29
28
|
export interface ReceiptLike {
|
|
30
29
|
signed?: boolean;
|
|
@@ -51,20 +50,60 @@ export declare function receiptPayload(receipt: ReceiptLike): Record<string, unk
|
|
|
51
50
|
export interface VerifyOptions {
|
|
52
51
|
/** Published JWK. Fetched from DEFAULT_KEY_URL when omitted. */
|
|
53
52
|
jwk?: JwkLike;
|
|
53
|
+
/**
|
|
54
|
+
* Inputs to check the receipt against. When supplied, the receipt's stated digests are
|
|
55
|
+
* recomputed over these values instead of being taken on trust — which is the difference
|
|
56
|
+
* between a receipt as a record and a receipt as evidence.
|
|
57
|
+
*/
|
|
58
|
+
expectedRequest?: unknown;
|
|
59
|
+
expectedPolicy?: unknown;
|
|
60
|
+
/**
|
|
61
|
+
* Reject a receipt older than this many seconds. A bound set by the *verifier*, not the
|
|
62
|
+
* issuer: nothing in the signed payload says how long a verdict is meant to hold, and
|
|
63
|
+
* inventing that would be a format change (`v: 2`). Boundary is inclusive — a receipt
|
|
64
|
+
* exactly at the limit is still fresh.
|
|
65
|
+
*/
|
|
66
|
+
maxAgeSeconds?: number;
|
|
67
|
+
/** Injectable clock, so freshness tests do not depend on wall time. */
|
|
68
|
+
now?: Date;
|
|
54
69
|
/** Override for tests and for point-in-time checks. */
|
|
55
70
|
keyUrl?: string;
|
|
56
71
|
fetchImpl?: typeof fetch;
|
|
57
72
|
}
|
|
73
|
+
/**
|
|
74
|
+
* Where the verifying key came from. A machine consumer must be able to tell "verified
|
|
75
|
+
* against PayStage's published key" from "verified against a key someone handed me" — the
|
|
76
|
+
* human output said this all along, and `--json` did not, which is the difference between a
|
|
77
|
+
* receipt and a receipt-shaped claim.
|
|
78
|
+
*/
|
|
79
|
+
export type KeySource = "published" | "supplied";
|
|
58
80
|
export type VerifyVerdict = {
|
|
81
|
+
ok: false;
|
|
82
|
+
status: "stale";
|
|
83
|
+
reason: string;
|
|
84
|
+
/** Age in seconds, and the bound that was exceeded. */
|
|
85
|
+
age_seconds: number;
|
|
86
|
+
max_age_seconds: number;
|
|
87
|
+
} | {
|
|
88
|
+
ok: false;
|
|
89
|
+
status: "inputs-mismatch";
|
|
90
|
+
reason: string;
|
|
91
|
+
/** Which digest disagreed: "request", "policy", or both. */
|
|
92
|
+
mismatched: Array<"request" | "policy">;
|
|
93
|
+
} | {
|
|
59
94
|
ok: true;
|
|
60
95
|
status: "signed-and-valid";
|
|
61
96
|
verdict?: string;
|
|
62
97
|
issued_at?: string;
|
|
63
98
|
key_id?: string;
|
|
99
|
+
key_source: KeySource;
|
|
64
100
|
} | {
|
|
65
101
|
ok: false;
|
|
66
102
|
status: "unsigned";
|
|
67
103
|
reason: string;
|
|
104
|
+
/** Present only when --request/--policy were supplied: does the receipt cover them? */
|
|
105
|
+
inputs?: "match" | "mismatch";
|
|
106
|
+
mismatched?: Array<"request" | "policy">;
|
|
68
107
|
} | {
|
|
69
108
|
ok: false;
|
|
70
109
|
status: "invalid";
|
package/dist/verify.js
CHANGED
|
@@ -14,10 +14,38 @@
|
|
|
14
14
|
* is DER. Getting this wrong produces the same failure mode, so it is pinned to
|
|
15
15
|
* `ieee-p1363` explicitly.
|
|
16
16
|
*/
|
|
17
|
-
|
|
17
|
+
// globalThis.crypto exists in Workers and in Node 18+. Importing `webcrypto` from node:crypto
|
|
18
|
+
// works in Node and breaks the Worker bundle, which is the difference that matters here.
|
|
19
|
+
const webcrypto = globalThis.crypto;
|
|
20
|
+
/** The receipt format version this verifier understands. Kept local on purpose: a verifier
|
|
21
|
+
* must not silently follow the issuer's constant upward — it validates what it knows. */
|
|
22
|
+
const RECEIPT_VERSION = 1;
|
|
18
23
|
export const RECEIPT_ALG = "ECDSA-P256-SHA256";
|
|
19
24
|
export const DEFAULT_KEY_URL = "https://api.paystage.xyz/v1/public/receipt-key.json";
|
|
20
25
|
/** JSON with recursively sorted keys and no insignificant whitespace. */
|
|
26
|
+
/**
|
|
27
|
+
* How far ahead of the verifier's clock an `issued_at` may be before it is refused.
|
|
28
|
+
*
|
|
29
|
+
* A future-dated receipt is not "fresh" — it is a receipt that could not have been issued
|
|
30
|
+
* yet, and without this check `age > maxAge` is never true for it, so it never expires.
|
|
31
|
+
* Five minutes covers honest clock skew between two machines.
|
|
32
|
+
*/
|
|
33
|
+
const MAX_CLOCK_SKEW_SECONDS = 300;
|
|
34
|
+
/** Age in seconds, or null when `issued_at` is not a timestamp. */
|
|
35
|
+
function ageSeconds(issuedAt, now) {
|
|
36
|
+
if (typeof issuedAt !== "string")
|
|
37
|
+
return null;
|
|
38
|
+
const then = Date.parse(issuedAt);
|
|
39
|
+
if (Number.isNaN(then))
|
|
40
|
+
return null;
|
|
41
|
+
return ((now ?? new Date()).getTime() - then) / 1000;
|
|
42
|
+
}
|
|
43
|
+
/** SHA-256 over the canonical form, lowercase hex — same rule the issuer used. */
|
|
44
|
+
async function sha256Hex(value) {
|
|
45
|
+
const bytes = new TextEncoder().encode(canonicalize(value));
|
|
46
|
+
const digest = await webcrypto.subtle.digest("SHA-256", bytes);
|
|
47
|
+
return Buffer.from(new Uint8Array(digest)).toString("hex");
|
|
48
|
+
}
|
|
21
49
|
export function canonicalize(value) {
|
|
22
50
|
if (value === null || typeof value !== "object")
|
|
23
51
|
return JSON.stringify(value) ?? "null";
|
|
@@ -51,11 +79,48 @@ export async function verifyReceipt(receipt, options = {}) {
|
|
|
51
79
|
if (receipt === null || typeof receipt !== "object") {
|
|
52
80
|
return { ok: false, status: "invalid", reason: "receipt is not an object" };
|
|
53
81
|
}
|
|
82
|
+
// A receipt from a future format version may mean something this code does not check.
|
|
83
|
+
// Validating it would assert more than we know.
|
|
84
|
+
if (receipt.v !== undefined && receipt.v !== RECEIPT_VERSION) {
|
|
85
|
+
return {
|
|
86
|
+
ok: false,
|
|
87
|
+
status: "invalid",
|
|
88
|
+
reason: `unsupported receipt version ${String(receipt.v)} (this verifier understands ${RECEIPT_VERSION})`,
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
// The verdict is what a caller acts on, so an unknown value is a refusal, not a pass.
|
|
92
|
+
const verdictValue = receipt.verdict?.decision;
|
|
93
|
+
if (verdictValue !== undefined && !["pay", "review", "do_not_pay"].includes(verdictValue)) {
|
|
94
|
+
return {
|
|
95
|
+
ok: false,
|
|
96
|
+
status: "invalid",
|
|
97
|
+
reason: `unknown verdict ${JSON.stringify(verdictValue)} — expected pay, review or do_not_pay`,
|
|
98
|
+
};
|
|
99
|
+
}
|
|
54
100
|
if (receipt.signed !== true) {
|
|
101
|
+
// No signature means the digest is the only evidence there is, so the recompute still
|
|
102
|
+
// runs. The status stays `unsigned` (exit 2): an unsigned receipt cannot be forged, so
|
|
103
|
+
// a mismatch here is not a forgery verdict.
|
|
104
|
+
const mismatchedUnsigned = [];
|
|
105
|
+
const checkUnsigned = async (expected, claimed, which) => {
|
|
106
|
+
if (expected === undefined)
|
|
107
|
+
return;
|
|
108
|
+
if (typeof claimed !== "string") {
|
|
109
|
+
mismatchedUnsigned.push(which);
|
|
110
|
+
return;
|
|
111
|
+
}
|
|
112
|
+
if ((await sha256Hex(expected)) !== claimed)
|
|
113
|
+
mismatchedUnsigned.push(which);
|
|
114
|
+
};
|
|
115
|
+
await checkUnsigned(options.expectedRequest, receipt.request_sha256, "request");
|
|
116
|
+
await checkUnsigned(options.expectedPolicy, receipt.policy_sha256, "policy");
|
|
55
117
|
return {
|
|
56
118
|
ok: false,
|
|
57
119
|
status: "unsigned",
|
|
58
120
|
reason: "receipt carries no signature — it is still useful as a record of what was decided, but it cannot prove who decided it",
|
|
121
|
+
...(options.expectedRequest === undefined && options.expectedPolicy === undefined
|
|
122
|
+
? {}
|
|
123
|
+
: { inputs: mismatchedUnsigned.length === 0 ? "match" : "mismatch", mismatched: mismatchedUnsigned }),
|
|
59
124
|
};
|
|
60
125
|
}
|
|
61
126
|
if (typeof receipt.signature !== "string" || receipt.signature.length === 0) {
|
|
@@ -91,11 +156,15 @@ export async function verifyReceipt(receipt, options = {}) {
|
|
|
91
156
|
};
|
|
92
157
|
}
|
|
93
158
|
}
|
|
94
|
-
const data =
|
|
95
|
-
const
|
|
159
|
+
const data = new TextEncoder().encode(canonicalize(receiptPayload(receipt)));
|
|
160
|
+
const signatureBuffer = base64UrlToBuffer(receipt.signature);
|
|
161
|
+
const signature = new Uint8Array(signatureBuffer.buffer, signatureBuffer.byteOffset, signatureBuffer.byteLength);
|
|
96
162
|
try {
|
|
97
|
-
|
|
98
|
-
|
|
163
|
+
// Web Crypto rather than node:crypto: identical verification, but it also runs in a Worker,
|
|
164
|
+
// which is what lets the hosted endpoint expose `verify_receipt` at all. The JWK already names
|
|
165
|
+
// the curve and hash, so the import is the whole setup.
|
|
166
|
+
const publicKey = await webcrypto.subtle.importKey("jwk", jwk, { name: "ECDSA", namedCurve: String(jwk.crv ?? "P-256") }, false, ["verify"]);
|
|
167
|
+
const valid = await webcrypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, publicKey, signature, data);
|
|
99
168
|
if (!valid) {
|
|
100
169
|
return {
|
|
101
170
|
ok: false,
|
|
@@ -103,12 +172,66 @@ export async function verifyReceipt(receipt, options = {}) {
|
|
|
103
172
|
reason: "signature does not match the payload — the receipt was altered or was signed by a different key",
|
|
104
173
|
};
|
|
105
174
|
}
|
|
175
|
+
// Only now, with the signature proven, is it worth asking whether the receipt covers
|
|
176
|
+
// the inputs the caller has in hand. Doing this earlier would let a forgery masquerade
|
|
177
|
+
// as a mismatch, which is a less serious verdict than it deserves.
|
|
178
|
+
const mismatched = [];
|
|
179
|
+
const checkDigest = async (expected, claimed, which) => {
|
|
180
|
+
if (expected === undefined)
|
|
181
|
+
return;
|
|
182
|
+
if (typeof claimed !== "string") {
|
|
183
|
+
mismatched.push(which);
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
const actual = await sha256Hex(expected);
|
|
187
|
+
if (actual !== claimed)
|
|
188
|
+
mismatched.push(which);
|
|
189
|
+
};
|
|
190
|
+
await checkDigest(options.expectedRequest, receipt.request_sha256, "request");
|
|
191
|
+
await checkDigest(options.expectedPolicy, receipt.policy_sha256, "policy");
|
|
192
|
+
if (mismatched.length > 0) {
|
|
193
|
+
return {
|
|
194
|
+
ok: false,
|
|
195
|
+
status: "inputs-mismatch",
|
|
196
|
+
reason: `signature is valid but the receipt does not cover the supplied ${mismatched.join(" and ")} input`,
|
|
197
|
+
mismatched,
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
if (options.maxAgeSeconds !== undefined) {
|
|
201
|
+
const age = ageSeconds(receipt.issued_at, options.now);
|
|
202
|
+
if (age === null) {
|
|
203
|
+
// Garbage here is inside the signature: the issuer signed it, so it is the receipt
|
|
204
|
+
// that is invalid, not the verifier's input.
|
|
205
|
+
return {
|
|
206
|
+
ok: false,
|
|
207
|
+
status: "invalid",
|
|
208
|
+
reason: `issued_at is not a parseable timestamp: ${JSON.stringify(receipt.issued_at)}`,
|
|
209
|
+
};
|
|
210
|
+
}
|
|
211
|
+
if (age < -MAX_CLOCK_SKEW_SECONDS) {
|
|
212
|
+
return {
|
|
213
|
+
ok: false,
|
|
214
|
+
status: "invalid",
|
|
215
|
+
reason: `issued_at is ${Math.round(-age)}s in the future, beyond any plausible clock skew — this receipt could not have been issued yet`,
|
|
216
|
+
};
|
|
217
|
+
}
|
|
218
|
+
if (age > options.maxAgeSeconds) {
|
|
219
|
+
return {
|
|
220
|
+
ok: false,
|
|
221
|
+
status: "stale",
|
|
222
|
+
reason: `receipt is ${Math.round(age)}s old, older than the ${options.maxAgeSeconds}s bound`,
|
|
223
|
+
age_seconds: age,
|
|
224
|
+
max_age_seconds: options.maxAgeSeconds,
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
}
|
|
106
228
|
return {
|
|
107
229
|
ok: true,
|
|
108
230
|
status: "signed-and-valid",
|
|
109
231
|
verdict: receipt.verdict?.decision,
|
|
110
232
|
issued_at: receipt.issued_at,
|
|
111
233
|
key_id: receipt.key_id,
|
|
234
|
+
key_source: options.jwk !== undefined || options.keyUrl !== undefined ? "supplied" : "published",
|
|
112
235
|
};
|
|
113
236
|
}
|
|
114
237
|
catch (error) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paystage/mcp",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.5-canary.22",
|
|
4
4
|
"description": "PayStage umbrella MCP: payment preflight, auth watch, HIP-3 trade preflight, and velocity rate/spend-pattern checks",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -11,7 +11,11 @@
|
|
|
11
11
|
"types": "./dist/index.d.ts",
|
|
12
12
|
"import": "./dist/index.js"
|
|
13
13
|
},
|
|
14
|
-
"./package.json": "./package.json"
|
|
14
|
+
"./package.json": "./package.json",
|
|
15
|
+
"./tools": {
|
|
16
|
+
"types": "./dist/tools.d.ts",
|
|
17
|
+
"import": "./dist/tools.js"
|
|
18
|
+
}
|
|
15
19
|
},
|
|
16
20
|
"bin": {
|
|
17
21
|
"paystage-mcp": "dist/cli.js",
|
|
@@ -22,7 +26,7 @@
|
|
|
22
26
|
"server.json",
|
|
23
27
|
"!dist/**/*.map"
|
|
24
28
|
],
|
|
25
|
-
"mcpName": "
|
|
29
|
+
"mcpName": "io.github.base-buzz/mcp",
|
|
26
30
|
"engines": {
|
|
27
31
|
"node": ">=20"
|
|
28
32
|
},
|
|
@@ -50,11 +54,11 @@
|
|
|
50
54
|
},
|
|
51
55
|
"dependencies": {
|
|
52
56
|
"@modelcontextprotocol/server": "^2.4.0",
|
|
53
|
-
"@paystage/auth-watch": "0.2.
|
|
54
|
-
"@paystage/policy": "0.2.1",
|
|
55
|
-
"@paystage/preflight": "0.2.
|
|
56
|
-
"@paystage/trade-preflight": "0.2.
|
|
57
|
-
"@paystage/velocity": "0.2.
|
|
57
|
+
"@paystage/auth-watch": "0.2.1-canary.22",
|
|
58
|
+
"@paystage/policy": "0.2.1-canary.22",
|
|
59
|
+
"@paystage/preflight": "0.2.3-canary.22",
|
|
60
|
+
"@paystage/trade-preflight": "0.2.1-canary.22",
|
|
61
|
+
"@paystage/velocity": "0.2.1-canary.22",
|
|
58
62
|
"zod": "^4.6.7"
|
|
59
63
|
},
|
|
60
64
|
"devDependencies": {
|
package/server.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
-
"name": "
|
|
3
|
+
"name": "io.github.base-buzz/mcp",
|
|
4
4
|
"title": "PayStage",
|
|
5
5
|
"description": "Umbrella MCP: payment preflight, auth watch, HIP-3 trade preflight, velocity checks",
|
|
6
|
-
"version": "0.3.
|
|
6
|
+
"version": "0.3.5",
|
|
7
7
|
"websiteUrl": "https://paystage.xyz",
|
|
8
8
|
"repository": {
|
|
9
9
|
"url": "https://github.com/base-buzz/paystage",
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
"registryType": "npm",
|
|
16
16
|
"registryBaseUrl": "https://registry.npmjs.org",
|
|
17
17
|
"identifier": "@paystage/mcp",
|
|
18
|
-
"version": "0.3.
|
|
18
|
+
"version": "0.3.5",
|
|
19
19
|
"transport": {
|
|
20
20
|
"type": "stdio"
|
|
21
21
|
},
|
|
@@ -32,5 +32,11 @@
|
|
|
32
32
|
}
|
|
33
33
|
]
|
|
34
34
|
}
|
|
35
|
+
],
|
|
36
|
+
"remotes": [
|
|
37
|
+
{
|
|
38
|
+
"type": "streamable-http",
|
|
39
|
+
"url": "https://api.paystage.xyz/mcp"
|
|
40
|
+
}
|
|
35
41
|
]
|
|
36
42
|
}
|