@paystage/mcp 0.3.0 → 0.3.2

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
@@ -85,11 +85,56 @@ this tool.
85
85
  | `@paystage/velocity` | 0.2.0 | Rate / spend-pattern checks |
86
86
  | `@paystage/policy` | 0.2.0 | Shared policy schema + loader |
87
87
 
88
+ ## Verify a receipt
89
+
90
+ Every verdict can carry a signed receipt. `paystage-verify` checks one without trusting
91
+ us — it fetches the published key and verifies the signature over the canonical payload.
92
+
93
+ ```sh
94
+ npx -y -p @paystage/mcp paystage-verify receipt.json
95
+ cat receipt.json | npx -y -p @paystage/mcp paystage-verify -
96
+ ```
97
+
98
+ Exit codes are distinct on purpose:
99
+
100
+ | Code | Meaning |
101
+ |---|---|
102
+ | 0 | signature matches the payload |
103
+ | 1 | **invalid** — altered, or signed by a different key |
104
+ | 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 |
106
+
107
+ "Invalid" and "could not check" are different facts and must not collapse into one
108
+ failure. `--key <file>` verifies against a local JWK for point-in-time checks.
109
+
110
+ ## Supply chain and access
111
+
112
+ This is the umbrella, so its install tree is wider than any single tool and Socket
113
+ flags it accordingly. What it actually contains:
114
+
115
+ | Flag | Where it comes from |
116
+ | --- | --- |
117
+ | Network access, URL strings | `@paystage/auth-watch` (Base RPC reads) and `@paystage/trade-preflight` (one Hyperliquid info query). |
118
+ | Filesystem access | `@paystage/policy` reading your policy file. |
119
+ | Environment variable access | `PAYSTAGE_POLICY_PATH`, `PAYSTAGE_RPC_URL`. |
120
+ | "AI-detected code anomaly" | The official `@modelcontextprotocol/server` SDK's bundled JSON-schema validator, not PayStage code. |
121
+
122
+ The umbrella itself is ~16 KB with no network, no filesystem and no `eval` — the
123
+ capability lives in the dependencies, because that is what the tools are for.
124
+
125
+ Install a narrower surface if you only need part of it: `@paystage/preflight` and
126
+ `@paystage/policy` make no network calls at all.
127
+
128
+ Full table: [SECURITY.md](../../SECURITY.md).
129
+
88
130
  ## Links
89
131
 
132
+ - Verify receipts: `npx -y -p @paystage/mcp paystage-verify <receipt.json>`
133
+
90
134
  - Website: [paystage.xyz](https://paystage.xyz)
91
135
  - HIP-3 context: [docs.trade.xyz](https://docs.trade.xyz)
92
136
  - Source: [github.com/base-buzz/paystage](https://github.com/base-buzz/paystage)
137
+ - X: [x.com/paystage_xyz](https://x.com/paystage_xyz)
93
138
 
94
139
  ## License
95
140
 
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `paystage-verify <file|->` — check a PayStage receipt without trusting PayStage.
4
+ *
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,
7
+ * 3 unverifiable (could not check). Distinct codes so a script can tell "forged" from
8
+ * "no key published yet" — collapsing those into one failure would overstate what we
9
+ * know.
10
+ */
11
+ export {};
12
+ //# sourceMappingURL=verify-cli.d.ts.map
@@ -0,0 +1,116 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `paystage-verify <file|->` — check a PayStage receipt without trusting PayStage.
4
+ *
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,
7
+ * 3 unverifiable (could not check). Distinct codes so a script can tell "forged" from
8
+ * "no key published yet" — collapsing those into one failure would overstate what we
9
+ * know.
10
+ */
11
+ import { readFile } from "node:fs/promises";
12
+ import { DEFAULT_KEY_URL, verifyReceipt } from "./verify.js";
13
+ const EXIT = {
14
+ "signed-and-valid": 0,
15
+ unsigned: 2,
16
+ invalid: 1,
17
+ unverifiable: 3,
18
+ };
19
+ function usage() {
20
+ return [
21
+ "paystage-verify — check a PayStage verdict receipt",
22
+ "",
23
+ "Usage:",
24
+ " paystage-verify <receipt.json> verify a file",
25
+ " cat receipt.json | paystage-verify - verify stdin",
26
+ "",
27
+ "Options:",
28
+ " --key <path> verify against a local JWK instead of the published one",
29
+ " --key-url <u> override the published key endpoint",
30
+ " --json machine-readable output",
31
+ "",
32
+ "Exit codes: 0 valid · 1 invalid · 2 unsigned · 3 unverifiable",
33
+ ].join("\n");
34
+ }
35
+ async function readStdin() {
36
+ const chunks = [];
37
+ for await (const chunk of process.stdin)
38
+ chunks.push(chunk);
39
+ return Buffer.concat(chunks).toString("utf8");
40
+ }
41
+ async function main(argv) {
42
+ const args = argv.slice(2);
43
+ if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
44
+ process.stdout.write(`${usage()}\n`);
45
+ return args.length === 0 ? 1 : 0;
46
+ }
47
+ let source;
48
+ let keyPath;
49
+ let keyUrl;
50
+ let asJson = false;
51
+ for (let i = 0; i < args.length; i += 1) {
52
+ const arg = args[i];
53
+ if (arg === "--json")
54
+ asJson = true;
55
+ else if (arg === "--key")
56
+ keyPath = args[++i];
57
+ else if (arg === "--key-url")
58
+ keyUrl = args[++i];
59
+ else if (arg !== undefined)
60
+ source = arg;
61
+ }
62
+ if (source === undefined) {
63
+ process.stderr.write("paystage-verify: no receipt given\n");
64
+ return 1;
65
+ }
66
+ let raw;
67
+ try {
68
+ raw = source === "-" ? await readStdin() : await readFile(source, "utf8");
69
+ }
70
+ catch (error) {
71
+ process.stderr.write(`paystage-verify: cannot read ${source}: ${error instanceof Error ? error.message : String(error)}\n`);
72
+ return 3;
73
+ }
74
+ let receipt;
75
+ try {
76
+ receipt = JSON.parse(raw);
77
+ }
78
+ catch {
79
+ process.stderr.write(`paystage-verify: ${source} is not valid JSON\n`);
80
+ return 1;
81
+ }
82
+ const options = {};
83
+ if (keyPath !== undefined) {
84
+ try {
85
+ options.jwk = JSON.parse(await readFile(keyPath, "utf8"));
86
+ }
87
+ catch (error) {
88
+ process.stderr.write(`paystage-verify: cannot read key ${keyPath}: ${error instanceof Error ? error.message : String(error)}\n`);
89
+ return 3;
90
+ }
91
+ }
92
+ if (keyUrl !== undefined)
93
+ options.keyUrl = keyUrl;
94
+ const verdict = await verifyReceipt(receipt, options);
95
+ if (asJson) {
96
+ process.stdout.write(`${JSON.stringify(verdict)}\n`);
97
+ }
98
+ else if (verdict.ok) {
99
+ process.stdout.write([
100
+ "VALID — signature matches the payload",
101
+ ` verdict: ${verdict.verdict ?? "(none)"}`,
102
+ ` issued_at: ${verdict.issued_at ?? "(none)"}`,
103
+ ` key_id: ${verdict.key_id ?? "(none)"}`,
104
+ ` key source: ${keyPath ?? keyUrl ?? DEFAULT_KEY_URL}`,
105
+ ].join("\n") + "\n");
106
+ }
107
+ else {
108
+ process.stdout.write(`${verdict.status.toUpperCase()} — ${verdict.reason}\n`);
109
+ }
110
+ return EXIT[verdict.status];
111
+ }
112
+ main(process.argv).then((code) => process.exit(code), (error) => {
113
+ process.stderr.write(`paystage-verify fatal: ${error instanceof Error ? error.message : String(error)}\n`);
114
+ process.exit(3);
115
+ });
116
+ //# sourceMappingURL=verify-cli.js.map
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Receipt verification.
3
+ *
4
+ * A receipt says "this decision was made, over these inputs, at this time". Until
5
+ * someone can check the signature without trusting us, that sentence is a claim
6
+ * rather than a proof — so this module exists to be run by strangers.
7
+ *
8
+ * The two things that must match the issuer byte for byte:
9
+ *
10
+ * 1. **Canonicalisation.** JSON with sorted keys and no whitespace. If this drifts
11
+ * from `apps/hosted/src/receipt.ts`, every valid receipt reports `invalid`, which
12
+ * is worse than not shipping the check at all.
13
+ * 2. **Signature encoding.** WebCrypto (the issuer) emits raw `r||s`; Node's default
14
+ * is DER. Getting this wrong produces the same failure mode, so it is pinned to
15
+ * `ieee-p1363` explicitly.
16
+ */
17
+ /** Minimal JWK shape. The DOM lib's JsonWebKey is not available in a Node-only build. */
18
+ export interface JwkLike {
19
+ kty?: string;
20
+ crv?: string;
21
+ x?: string;
22
+ y?: string;
23
+ [key: string]: unknown;
24
+ }
25
+ export declare const RECEIPT_ALG = "ECDSA-P256-SHA256";
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
+ export declare function canonicalize(value: unknown): string;
29
+ export interface ReceiptLike {
30
+ signed?: boolean;
31
+ alg?: string;
32
+ key_id?: string;
33
+ signature?: string;
34
+ v?: number;
35
+ issuer?: string;
36
+ issued_at?: string;
37
+ service?: {
38
+ name?: string;
39
+ version?: string;
40
+ };
41
+ verdict?: {
42
+ decision?: string;
43
+ reasons?: string[];
44
+ summary?: string;
45
+ };
46
+ request_sha256?: string;
47
+ policy_sha256?: string;
48
+ [key: string]: unknown;
49
+ }
50
+ export declare function receiptPayload(receipt: ReceiptLike): Record<string, unknown>;
51
+ export interface VerifyOptions {
52
+ /** Published JWK. Fetched from DEFAULT_KEY_URL when omitted. */
53
+ jwk?: JwkLike;
54
+ /** Override for tests and for point-in-time checks. */
55
+ keyUrl?: string;
56
+ fetchImpl?: typeof fetch;
57
+ }
58
+ export type VerifyVerdict = {
59
+ ok: true;
60
+ status: "signed-and-valid";
61
+ verdict?: string;
62
+ issued_at?: string;
63
+ key_id?: string;
64
+ } | {
65
+ ok: false;
66
+ status: "unsigned";
67
+ reason: string;
68
+ } | {
69
+ ok: false;
70
+ status: "invalid";
71
+ reason: string;
72
+ } | {
73
+ ok: false;
74
+ status: "unverifiable";
75
+ reason: string;
76
+ };
77
+ /**
78
+ * Check a receipt. Returns a verdict rather than throwing, because "I could not check
79
+ * this" is a distinct and important outcome from "this is forged".
80
+ */
81
+ export declare function verifyReceipt(receipt: ReceiptLike, options?: VerifyOptions): Promise<VerifyVerdict>;
82
+ //# sourceMappingURL=verify.d.ts.map
package/dist/verify.js ADDED
@@ -0,0 +1,122 @@
1
+ /**
2
+ * Receipt verification.
3
+ *
4
+ * A receipt says "this decision was made, over these inputs, at this time". Until
5
+ * someone can check the signature without trusting us, that sentence is a claim
6
+ * rather than a proof — so this module exists to be run by strangers.
7
+ *
8
+ * The two things that must match the issuer byte for byte:
9
+ *
10
+ * 1. **Canonicalisation.** JSON with sorted keys and no whitespace. If this drifts
11
+ * from `apps/hosted/src/receipt.ts`, every valid receipt reports `invalid`, which
12
+ * is worse than not shipping the check at all.
13
+ * 2. **Signature encoding.** WebCrypto (the issuer) emits raw `r||s`; Node's default
14
+ * is DER. Getting this wrong produces the same failure mode, so it is pinned to
15
+ * `ieee-p1363` explicitly.
16
+ */
17
+ import { createPublicKey, verify as nodeVerify } from "node:crypto";
18
+ export const RECEIPT_ALG = "ECDSA-P256-SHA256";
19
+ export const DEFAULT_KEY_URL = "https://api.paystage.xyz/v1/public/receipt-key.json";
20
+ /** JSON with recursively sorted keys and no insignificant whitespace. */
21
+ export function canonicalize(value) {
22
+ if (value === null || typeof value !== "object")
23
+ return JSON.stringify(value) ?? "null";
24
+ if (Array.isArray(value))
25
+ return `[${value.map(canonicalize).join(",")}]`;
26
+ const entries = Object.entries(value)
27
+ .filter(([, v]) => v !== undefined)
28
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
29
+ return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(",")}}`;
30
+ }
31
+ /** Fields added by signing. Everything else is the signed payload. */
32
+ const SIGNATURE_FIELDS = ["signed", "alg", "key_id", "signature"];
33
+ export function receiptPayload(receipt) {
34
+ const payload = {};
35
+ for (const [key, value] of Object.entries(receipt)) {
36
+ if (SIGNATURE_FIELDS.includes(key))
37
+ continue;
38
+ payload[key] = value;
39
+ }
40
+ return payload;
41
+ }
42
+ function base64UrlToBuffer(value) {
43
+ const padded = value.replace(/-/g, "+").replace(/_/g, "/");
44
+ return Buffer.from(padded, "base64");
45
+ }
46
+ /**
47
+ * Check a receipt. Returns a verdict rather than throwing, because "I could not check
48
+ * this" is a distinct and important outcome from "this is forged".
49
+ */
50
+ export async function verifyReceipt(receipt, options = {}) {
51
+ if (receipt === null || typeof receipt !== "object") {
52
+ return { ok: false, status: "invalid", reason: "receipt is not an object" };
53
+ }
54
+ if (receipt.signed !== true) {
55
+ return {
56
+ ok: false,
57
+ status: "unsigned",
58
+ reason: "receipt carries no signature — it is still useful as a record of what was decided, but it cannot prove who decided it",
59
+ };
60
+ }
61
+ if (typeof receipt.signature !== "string" || receipt.signature.length === 0) {
62
+ return { ok: false, status: "invalid", reason: "signed: true but no signature field" };
63
+ }
64
+ if (receipt.alg !== undefined && receipt.alg !== RECEIPT_ALG) {
65
+ return { ok: false, status: "invalid", reason: `unexpected alg: ${receipt.alg}` };
66
+ }
67
+ let jwk = options.jwk;
68
+ if (jwk === undefined) {
69
+ const url = options.keyUrl ?? DEFAULT_KEY_URL;
70
+ const fetchImpl = options.fetchImpl ?? fetch;
71
+ try {
72
+ const res = await fetchImpl(url);
73
+ if (!res.ok) {
74
+ return { ok: false, status: "unverifiable", reason: `key endpoint returned ${res.status}` };
75
+ }
76
+ const body = (await res.json());
77
+ if (body.configured !== true || body.jwk === undefined) {
78
+ return {
79
+ ok: false,
80
+ status: "unverifiable",
81
+ reason: "issuer has not published a signing key, so nothing can be checked",
82
+ };
83
+ }
84
+ jwk = body.jwk;
85
+ }
86
+ catch (error) {
87
+ return {
88
+ ok: false,
89
+ status: "unverifiable",
90
+ reason: `could not fetch the key: ${error instanceof Error ? error.message : String(error)}`,
91
+ };
92
+ }
93
+ }
94
+ const data = Buffer.from(canonicalize(receiptPayload(receipt)), "utf8");
95
+ const signature = base64UrlToBuffer(receipt.signature);
96
+ try {
97
+ const publicKey = createPublicKey({ key: jwk, format: "jwk" });
98
+ const valid = nodeVerify("sha256", data, { key: publicKey, dsaEncoding: "ieee-p1363" }, signature);
99
+ if (!valid) {
100
+ return {
101
+ ok: false,
102
+ status: "invalid",
103
+ reason: "signature does not match the payload — the receipt was altered or was signed by a different key",
104
+ };
105
+ }
106
+ return {
107
+ ok: true,
108
+ status: "signed-and-valid",
109
+ verdict: receipt.verdict?.decision,
110
+ issued_at: receipt.issued_at,
111
+ key_id: receipt.key_id,
112
+ };
113
+ }
114
+ catch (error) {
115
+ return {
116
+ ok: false,
117
+ status: "invalid",
118
+ reason: `could not verify: ${error instanceof Error ? error.message : String(error)}`,
119
+ };
120
+ }
121
+ }
122
+ //# sourceMappingURL=verify.js.map
package/package.json CHANGED
@@ -1,11 +1,12 @@
1
1
  {
2
2
  "name": "@paystage/mcp",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
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",
7
7
  "bin": {
8
- "paystage-mcp": "./dist/cli.js"
8
+ "paystage-mcp": "dist/cli.js",
9
+ "paystage-verify": "dist/verify-cli.js"
9
10
  },
10
11
  "files": [
11
12
  "dist",
@@ -41,8 +42,8 @@
41
42
  "dependencies": {
42
43
  "@modelcontextprotocol/server": "^2.4.0",
43
44
  "@paystage/auth-watch": "0.2.0",
44
- "@paystage/policy": "0.2.0",
45
- "@paystage/preflight": "0.2.0",
45
+ "@paystage/policy": "0.2.1",
46
+ "@paystage/preflight": "0.2.2",
46
47
  "@paystage/trade-preflight": "0.2.0",
47
48
  "@paystage/velocity": "0.2.0",
48
49
  "zod": "^4.6.7"
package/server.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "name": "xyz.paystage/mcp",
4
4
  "title": "PayStage",
5
5
  "description": "Umbrella MCP: payment preflight, auth watch, HIP-3 trade preflight, velocity checks",
6
- "version": "0.3.0",
6
+ "version": "0.3.2",
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.0",
18
+ "version": "0.3.2",
19
19
  "transport": {
20
20
  "type": "stdio"
21
21
  },