@paystage/mcp 0.3.3 → 0.3.5

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 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
  }
@@ -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.
@@ -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 four verdicts. Exit codes: 0 valid, 1 invalid, 2 unsigned,
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.
@@ -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 four verdicts. Exit codes: 0 valid, 1 invalid, 2 unsigned,
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: 0 valid · 1 invalid · 2 unsigned · 3 unverifiable",
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
- process.stdout.write(`${JSON.stringify(verdict)}\n`);
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,36 @@
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
- import { createPublicKey, verify as nodeVerify } from "node:crypto";
17
+ import { createPublicKey, verify as nodeVerify, webcrypto } from "node:crypto";
18
+ /** The receipt format version this verifier understands. Kept local on purpose: a verifier
19
+ * must not silently follow the issuer's constant upward — it validates what it knows. */
20
+ const RECEIPT_VERSION = 1;
18
21
  export const RECEIPT_ALG = "ECDSA-P256-SHA256";
19
22
  export const DEFAULT_KEY_URL = "https://api.paystage.xyz/v1/public/receipt-key.json";
20
23
  /** JSON with recursively sorted keys and no insignificant whitespace. */
24
+ /**
25
+ * How far ahead of the verifier's clock an `issued_at` may be before it is refused.
26
+ *
27
+ * A future-dated receipt is not "fresh" — it is a receipt that could not have been issued
28
+ * yet, and without this check `age > maxAge` is never true for it, so it never expires.
29
+ * Five minutes covers honest clock skew between two machines.
30
+ */
31
+ const MAX_CLOCK_SKEW_SECONDS = 300;
32
+ /** Age in seconds, or null when `issued_at` is not a timestamp. */
33
+ function ageSeconds(issuedAt, now) {
34
+ if (typeof issuedAt !== "string")
35
+ return null;
36
+ const then = Date.parse(issuedAt);
37
+ if (Number.isNaN(then))
38
+ return null;
39
+ return ((now ?? new Date()).getTime() - then) / 1000;
40
+ }
41
+ /** SHA-256 over the canonical form, lowercase hex — same rule the issuer used. */
42
+ async function sha256Hex(value) {
43
+ const bytes = new TextEncoder().encode(canonicalize(value));
44
+ const digest = await webcrypto.subtle.digest("SHA-256", bytes);
45
+ return Buffer.from(new Uint8Array(digest)).toString("hex");
46
+ }
21
47
  export function canonicalize(value) {
22
48
  if (value === null || typeof value !== "object")
23
49
  return JSON.stringify(value) ?? "null";
@@ -51,11 +77,48 @@ export async function verifyReceipt(receipt, options = {}) {
51
77
  if (receipt === null || typeof receipt !== "object") {
52
78
  return { ok: false, status: "invalid", reason: "receipt is not an object" };
53
79
  }
80
+ // A receipt from a future format version may mean something this code does not check.
81
+ // Validating it would assert more than we know.
82
+ if (receipt.v !== undefined && receipt.v !== RECEIPT_VERSION) {
83
+ return {
84
+ ok: false,
85
+ status: "invalid",
86
+ reason: `unsupported receipt version ${String(receipt.v)} (this verifier understands ${RECEIPT_VERSION})`,
87
+ };
88
+ }
89
+ // The verdict is what a caller acts on, so an unknown value is a refusal, not a pass.
90
+ const verdictValue = receipt.verdict?.decision;
91
+ if (verdictValue !== undefined && !["pay", "review", "do_not_pay"].includes(verdictValue)) {
92
+ return {
93
+ ok: false,
94
+ status: "invalid",
95
+ reason: `unknown verdict ${JSON.stringify(verdictValue)} — expected pay, review or do_not_pay`,
96
+ };
97
+ }
54
98
  if (receipt.signed !== true) {
99
+ // No signature means the digest is the only evidence there is, so the recompute still
100
+ // runs. The status stays `unsigned` (exit 2): an unsigned receipt cannot be forged, so
101
+ // a mismatch here is not a forgery verdict.
102
+ const mismatchedUnsigned = [];
103
+ const checkUnsigned = async (expected, claimed, which) => {
104
+ if (expected === undefined)
105
+ return;
106
+ if (typeof claimed !== "string") {
107
+ mismatchedUnsigned.push(which);
108
+ return;
109
+ }
110
+ if ((await sha256Hex(expected)) !== claimed)
111
+ mismatchedUnsigned.push(which);
112
+ };
113
+ await checkUnsigned(options.expectedRequest, receipt.request_sha256, "request");
114
+ await checkUnsigned(options.expectedPolicy, receipt.policy_sha256, "policy");
55
115
  return {
56
116
  ok: false,
57
117
  status: "unsigned",
58
118
  reason: "receipt carries no signature — it is still useful as a record of what was decided, but it cannot prove who decided it",
119
+ ...(options.expectedRequest === undefined && options.expectedPolicy === undefined
120
+ ? {}
121
+ : { inputs: mismatchedUnsigned.length === 0 ? "match" : "mismatch", mismatched: mismatchedUnsigned }),
59
122
  };
60
123
  }
61
124
  if (typeof receipt.signature !== "string" || receipt.signature.length === 0) {
@@ -103,12 +166,66 @@ export async function verifyReceipt(receipt, options = {}) {
103
166
  reason: "signature does not match the payload — the receipt was altered or was signed by a different key",
104
167
  };
105
168
  }
169
+ // Only now, with the signature proven, is it worth asking whether the receipt covers
170
+ // the inputs the caller has in hand. Doing this earlier would let a forgery masquerade
171
+ // as a mismatch, which is a less serious verdict than it deserves.
172
+ const mismatched = [];
173
+ const checkDigest = async (expected, claimed, which) => {
174
+ if (expected === undefined)
175
+ return;
176
+ if (typeof claimed !== "string") {
177
+ mismatched.push(which);
178
+ return;
179
+ }
180
+ const actual = await sha256Hex(expected);
181
+ if (actual !== claimed)
182
+ mismatched.push(which);
183
+ };
184
+ await checkDigest(options.expectedRequest, receipt.request_sha256, "request");
185
+ await checkDigest(options.expectedPolicy, receipt.policy_sha256, "policy");
186
+ if (mismatched.length > 0) {
187
+ return {
188
+ ok: false,
189
+ status: "inputs-mismatch",
190
+ reason: `signature is valid but the receipt does not cover the supplied ${mismatched.join(" and ")} input`,
191
+ mismatched,
192
+ };
193
+ }
194
+ if (options.maxAgeSeconds !== undefined) {
195
+ const age = ageSeconds(receipt.issued_at, options.now);
196
+ if (age === null) {
197
+ // Garbage here is inside the signature: the issuer signed it, so it is the receipt
198
+ // that is invalid, not the verifier's input.
199
+ return {
200
+ ok: false,
201
+ status: "invalid",
202
+ reason: `issued_at is not a parseable timestamp: ${JSON.stringify(receipt.issued_at)}`,
203
+ };
204
+ }
205
+ if (age < -MAX_CLOCK_SKEW_SECONDS) {
206
+ return {
207
+ ok: false,
208
+ status: "invalid",
209
+ reason: `issued_at is ${Math.round(-age)}s in the future, beyond any plausible clock skew — this receipt could not have been issued yet`,
210
+ };
211
+ }
212
+ if (age > options.maxAgeSeconds) {
213
+ return {
214
+ ok: false,
215
+ status: "stale",
216
+ reason: `receipt is ${Math.round(age)}s old, older than the ${options.maxAgeSeconds}s bound`,
217
+ age_seconds: age,
218
+ max_age_seconds: options.maxAgeSeconds,
219
+ };
220
+ }
221
+ }
106
222
  return {
107
223
  ok: true,
108
224
  status: "signed-and-valid",
109
225
  verdict: receipt.verdict?.decision,
110
226
  issued_at: receipt.issued_at,
111
227
  key_id: receipt.key_id,
228
+ key_source: options.jwk !== undefined || options.keyUrl !== undefined ? "supplied" : "published",
112
229
  };
113
230
  }
114
231
  catch (error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paystage/mcp",
3
- "version": "0.3.3",
3
+ "version": "0.3.5",
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",
@@ -22,7 +22,7 @@
22
22
  "server.json",
23
23
  "!dist/**/*.map"
24
24
  ],
25
- "mcpName": "xyz.paystage/mcp",
25
+ "mcpName": "io.github.base-buzz/mcp",
26
26
  "engines": {
27
27
  "node": ">=20"
28
28
  },
@@ -52,7 +52,7 @@
52
52
  "@modelcontextprotocol/server": "^2.4.0",
53
53
  "@paystage/auth-watch": "0.2.0",
54
54
  "@paystage/policy": "0.2.1",
55
- "@paystage/preflight": "0.2.2",
55
+ "@paystage/preflight": "0.2.3",
56
56
  "@paystage/trade-preflight": "0.2.0",
57
57
  "@paystage/velocity": "0.2.0",
58
58
  "zod": "^4.6.7"
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": "xyz.paystage/mcp",
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.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.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
  }