@paystage/mcp 0.4.0 → 0.6.0

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
@@ -188,3 +188,28 @@ signer, which is the entire product.
188
188
  | `decode_payment_required` | what does this base64 402 header actually say |
189
189
  | `validate_policy` | is this policy document valid, and if not why |
190
190
 
191
+ ## Check a policy file before you run anything
192
+
193
+ ```bash
194
+ npx -y -p @paystage/mcp paystage-policy check policy.json
195
+ ```
196
+
197
+ Exit `0` valid, `1` invalid (one line per offending field), `2` unreadable. Offline, no key, no signup —
198
+ the same schema the evaluator enforces, so a file that passes here is a file that will load there.
199
+
200
+ ## Explain a receipt in words
201
+
202
+ ```bash
203
+ npx -y -p @paystage/mcp paystage-explain receipt.json
204
+ ```
205
+
206
+ ```
207
+ Decision: do_not_pay
208
+ signature valid — this receipt is what PayStage issued
209
+ issued 2026-11-15T18:27:34Z by @paystage/hosted
210
+
211
+ · It asks for 1 USDC, and the policy allows at most 0.05 USDC.
212
+ ```
213
+
214
+ It verifies the signature first and says plainly when a receipt cannot be trusted. Rules it does not
215
+ recognise are **quoted, not paraphrased** — guessing at a refusal's meaning is worse than repeating it.
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=explain-cli.d.ts.map
@@ -0,0 +1,95 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `paystage-explain <receipt.json>` — turn a receipt's machine reasons into sentences.
4
+ *
5
+ * A receipt says *what* was decided and cites the rules. It is written for machines, and the person
6
+ * holding it is usually not the one who wrote the policy: "amount 1 USDC exceeds max_amount 0.05 USDC"
7
+ * is precise and still takes a second pass to read. This prints one sentence per reason, verifies the
8
+ * signature first, and says plainly when the receipt cannot be trusted.
9
+ *
10
+ * paystage-explain receipt.json # human output
11
+ * paystage-explain --json receipt.json # machine output
12
+ */
13
+ import { readFileSync } from "node:fs";
14
+ import { verifyReceipt } from "./verify.js";
15
+ const args = process.argv.slice(2);
16
+ const asJson = args.includes("--json");
17
+ const file = args.find((a) => !a.startsWith("-"));
18
+ if (!file) {
19
+ console.error("usage: paystage-explain <receipt.json> [--json]");
20
+ process.exit(2);
21
+ }
22
+ let receipt;
23
+ try {
24
+ receipt = JSON.parse(readFileSync(file, "utf8"));
25
+ }
26
+ catch (err) {
27
+ console.error(`cannot read ${file}: ${err instanceof Error ? err.message : String(err)}`);
28
+ process.exit(2);
29
+ }
30
+ /**
31
+ * One rule, one sentence. The patterns mirror what the evaluator emits — a reason this cannot translate
32
+ * is printed as-is rather than paraphrased, because guessing at a refusal's meaning is worse than
33
+ * quoting it.
34
+ */
35
+ function humanise(reason) {
36
+ let m;
37
+ if ((m = reason.match(/^amount (\S+) (\w+) exceeds max_amount (\S+) (\w+)$/))) {
38
+ return `It asks for ${m[1]} ${m[2]}, and the policy allows at most ${m[3]} ${m[4]}.`;
39
+ }
40
+ if ((m = reason.match(/^network (\S+) not in allowed_networks$/))) {
41
+ return `It settles on ${m[1]}, which the policy does not list as an allowed network.`;
42
+ }
43
+ if ((m = reason.match(/^asset (\S+) on (\S+) not in allowed_assets$/))) {
44
+ return `The token ${m[1]} on ${m[2]} is not an asset the policy accepts — often a lookalike.`;
45
+ }
46
+ if ((m = reason.match(/^payTo (\S+) not in allowed_pay_to \((deny|review)\)$/))) {
47
+ return m[2] === "deny"
48
+ ? `The payee ${m[1]} is not on the allow-list, and the policy refuses unknown payees.`
49
+ : `The payee ${m[1]} is not on the allow-list, so the policy asks a human to look before paying.`;
50
+ }
51
+ if (reason === "known drainer") {
52
+ return "The payee is on the known-drainer list — a cited list of addresses that take funds without delivering.";
53
+ }
54
+ if ((m = reason.match(/^maxTimeoutSeconds (\d+) exceeds policy max_timeout_seconds (\d+)$/))) {
55
+ return `The payment would stay valid for ${m[1]}s, longer than the ${m[2]}s the policy permits.`;
56
+ }
57
+ if ((m = reason.match(/^invalid atomic amount (\S*)$/))) {
58
+ return `The amount is not a whole number of atomic units ("${m[1] ?? ""}"), so it cannot be priced safely.`;
59
+ }
60
+ return reason;
61
+ }
62
+ const verdict = await verifyReceipt(receipt)
63
+ .then((v) => v)
64
+ .catch((err) => ({
65
+ ok: false,
66
+ status: "error",
67
+ reason: err instanceof Error ? err.message : String(err),
68
+ }));
69
+ const decision = receipt.verdict?.decision ?? "unknown";
70
+ const reasons = receipt.verdict?.reasons ?? [];
71
+ if (asJson) {
72
+ console.log(JSON.stringify({ decision, reasons, sentences: reasons.map(humanise), verification: verdict }, null, 2));
73
+ process.exit(0);
74
+ }
75
+ const trust = verdict.status === "signed-and-valid"
76
+ ? "signature valid — this receipt is what PayStage issued"
77
+ : verdict.status === "unsigned"
78
+ ? "UNSIGNED — useful as a record of a decision, but it proves nothing about who made it"
79
+ : `CANNOT BE TRUSTED — ${verdict.reason ?? verdict.status}`;
80
+ console.log(`Decision: ${decision}`);
81
+ console.log(` ${trust}`);
82
+ if (receipt.issued_at)
83
+ console.log(` issued ${receipt.issued_at} by ${receipt.service?.name ?? "unknown"}`);
84
+ console.log("");
85
+ if (reasons.length === 0) {
86
+ console.log(" No rules fired.");
87
+ }
88
+ else {
89
+ for (const r of reasons)
90
+ console.log(` · ${humanise(r)}`);
91
+ }
92
+ if (receipt.verdict?.summary)
93
+ console.log(`\n Summary: ${receipt.verdict.summary}`);
94
+ console.log("");
95
+ //# sourceMappingURL=explain-cli.js.map
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=policy-cli.d.ts.map
@@ -0,0 +1,91 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `paystage-policy check <file>` — does this policy parse?
4
+ *
5
+ * The most common support question is not "what verdict" but "why does my policy file not load". The
6
+ * answer today requires installing a package, writing a script and reading a stack trace. This answers
7
+ * it in one command, offline, with the exact message the evaluator would have produced.
8
+ *
9
+ * paystage-policy check policy.json # exit 0 valid · 1 invalid · 2 unreadable
10
+ * paystage-policy check --json policy.json
11
+ */
12
+ import { readFileSync } from "node:fs";
13
+ import { parsePolicy } from "@paystage/policy";
14
+ const args = process.argv.slice(2);
15
+ const asJson = args.includes("--json");
16
+ const positional = args.filter((a) => !a.startsWith("-"));
17
+ const verb = positional[0] === "check" ? "check" : null;
18
+ const file = verb ? positional[1] : positional[0];
19
+ if (!file) {
20
+ console.error("usage: paystage-policy check <policy.json> [--json]");
21
+ process.exit(2);
22
+ }
23
+ let raw;
24
+ try {
25
+ raw = readFileSync(file, "utf8");
26
+ }
27
+ catch (err) {
28
+ const message = err instanceof Error ? err.message : String(err);
29
+ if (asJson)
30
+ console.log(JSON.stringify({ ok: false, stage: "read", error: message }, null, 2));
31
+ else
32
+ console.error(`cannot read ${file}: ${message}`);
33
+ process.exit(2);
34
+ }
35
+ let parsed;
36
+ try {
37
+ parsed = JSON.parse(raw);
38
+ }
39
+ catch (err) {
40
+ const message = err instanceof Error ? err.message : String(err);
41
+ if (asJson)
42
+ console.log(JSON.stringify({ ok: false, stage: "json", error: message }, null, 2));
43
+ else
44
+ console.error(`${file} is not valid JSON: ${message}`);
45
+ process.exit(1);
46
+ }
47
+ try {
48
+ const policy = parsePolicy(parsed);
49
+ if (asJson) {
50
+ console.log(JSON.stringify({ ok: true, file, policy }, null, 2));
51
+ }
52
+ else {
53
+ const caps = [
54
+ policy.max_amount ? `max_amount ${policy.max_amount.value}` : "no max_amount",
55
+ Array.isArray(policy.allowed_networks) && policy.allowed_networks.length
56
+ ? `networks ${policy.allowed_networks.join(", ")}`
57
+ : "no allowed_networks",
58
+ policy.unknown_payee ? `unknown_payee ${policy.unknown_payee}` : "unknown_payee unset",
59
+ ];
60
+ console.log(`${file}: valid`);
61
+ console.log(` ${caps.join(" · ")}`);
62
+ }
63
+ process.exit(0);
64
+ }
65
+ catch (err) {
66
+ // The Zod message is the point: it names the field and the problem, which is what a stack trace
67
+ // buries. Print it verbatim rather than wrapping it.
68
+ const message = err instanceof Error ? err.message : String(err);
69
+ if (asJson) {
70
+ console.log(JSON.stringify({ ok: false, stage: "policy", error: message }, null, 2));
71
+ process.exit(1);
72
+ }
73
+ console.error(`${file}: invalid`);
74
+ try {
75
+ const issues = JSON.parse(message);
76
+ if (Array.isArray(issues)) {
77
+ // One line per field, because that is the question: which field, and what is wrong with it.
78
+ for (const issue of issues) {
79
+ const where = Array.isArray(issue.path) && issue.path.length ? issue.path.join(".") : "(root)";
80
+ console.error(` ${where}: ${issue.message ?? "invalid"}`);
81
+ }
82
+ process.exit(1);
83
+ }
84
+ }
85
+ catch {
86
+ // Not the structured form; fall through to the raw message.
87
+ }
88
+ console.error(message.split("\n").map((l) => ` ${l}`).join("\n"));
89
+ process.exit(1);
90
+ }
91
+ //# sourceMappingURL=policy-cli.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paystage/mcp",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
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",
@@ -19,7 +19,9 @@
19
19
  },
20
20
  "bin": {
21
21
  "paystage-mcp": "dist/cli.js",
22
- "paystage-verify": "dist/verify-cli.js"
22
+ "paystage-verify": "dist/verify-cli.js",
23
+ "paystage-policy": "dist/policy-cli.js",
24
+ "paystage-explain": "dist/explain-cli.js"
23
25
  },
24
26
  "files": [
25
27
  "dist",
@@ -67,7 +69,7 @@
67
69
  "vitest": "^4.1.12"
68
70
  },
69
71
  "scripts": {
70
- "build": "tsc && chmod +x dist/cli.js dist/verify-cli.js",
72
+ "build": "tsc && chmod +x dist/cli.js dist/verify-cli.js dist/policy-cli.js dist/explain-cli.js",
71
73
  "test": "vitest run",
72
74
  "typecheck": "tsc --noEmit",
73
75
  "prepublishOnly": "npm run build"