@paystage/receipt-verify 0.0.0-stage → 0.1.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 +59 -2
- package/dist/index.d.ts +10 -0
- package/dist/index.js +8 -0
- package/dist/verify.d.ts +122 -0
- package/dist/verify.js +259 -0
- package/package.json +61 -4
package/README.md
CHANGED
|
@@ -1,3 +1,60 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @paystage/receipt-verify
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Verify a PayStage verdict receipt **without installing the server**. Two inputs: the receipt, and a fetch of the published JWKS. No keys, no signing, no `@paystage/mcp`.
|
|
4
|
+
|
|
5
|
+
A receipt says a decision was made, over these inputs, at this time. This package is the path that turns that sentence into something a third party can check: parse the receipt, select the signing key by `kid` from the published key set, verify the ES256 signature, then check expiry and — when you supply the payment in front of you — the payment binding. It returns the same verdict shape as `@paystage/mcp`'s `verifyReceipt`, so the status strings are not a second vocabulary.
|
|
6
|
+
|
|
7
|
+
## Usage
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
import { verifyReceipt } from "@paystage/receipt-verify";
|
|
11
|
+
|
|
12
|
+
const receipt = await (await fetch("https://api.paystage.xyz/v1/evaluate_mcp_payment", {
|
|
13
|
+
method: "POST",
|
|
14
|
+
headers: { "content-type": "application/json" },
|
|
15
|
+
body: JSON.stringify({ payment_required, policy }),
|
|
16
|
+
})).json().then((body) => body.receipt);
|
|
17
|
+
|
|
18
|
+
const verdict = await verifyReceipt(receipt, {
|
|
19
|
+
// Optional: check that this receipt is about the payment you are holding.
|
|
20
|
+
payment: { scheme, network, asset, amount, payee },
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
if (verdict.ok) {
|
|
24
|
+
console.log(verdict.status, verdict.verdict); // "signed-and-valid" pay | review | do_not_pay
|
|
25
|
+
} else {
|
|
26
|
+
console.log(verdict.status, verdict.reason);
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The key is fetched from `https://api.paystage.xyz/.well-known/paystage-receipt-key.json`. Override `keyUrl` to pin a copy, or pass `jwk` to verify against a key you already hold; `key_source` in the result says which was used.
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
// Fully offline: supply the key yourself.
|
|
34
|
+
const verdict = await verifyReceipt(receipt, { jwk });
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Verdict statuses
|
|
38
|
+
|
|
39
|
+
| status | `ok` | meaning |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `signed-and-valid` | `true` | signature proves the payload; expiry and payment binding passed |
|
|
42
|
+
| `invalid` | `false` | bad signature, unsupported version, bad `alg`, malformed timestamp or signature |
|
|
43
|
+
| `expired` | `false` | signed and genuine, but `expires_at` has passed |
|
|
44
|
+
| `payment-mismatch` | `false` | genuine, but it is about a different payment (or predates binding) |
|
|
45
|
+
| `stale` | `false` | genuine, but older than the `maxAgeSeconds` bound you set |
|
|
46
|
+
| `inputs-mismatch` | `false` | genuine, but its digests do not cover `expectedRequest` / `expectedPolicy` |
|
|
47
|
+
| `unsigned` | `false` | no signature, so it cannot prove who decided it |
|
|
48
|
+
| `unverifiable` | `false` | the key could not be fetched, or the receipt names a `kid` the issuer does not publish |
|
|
49
|
+
|
|
50
|
+
An unknown `kid` fails closed: it is `unverifiable`, never a guess at another key. This verifier is ES256-only (ECDSA P-256 + SHA-256); it rejects any other key or receipt algorithm rather than following the issuer to a new one silently.
|
|
51
|
+
|
|
52
|
+
## Tests
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
npm test -w @paystage/receipt-verify
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Tests are offline: throwaway keys are generated in-process and the JWKS response is stubbed. One fixture is a real receipt captured from the live hosted endpoint, verified against a snapshot of the published JWKS with the clock pinned just after issue.
|
|
59
|
+
|
|
60
|
+
MIT.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@paystage/receipt-verify` — check a PayStage receipt with the receipt and
|
|
3
|
+
* a fetch, without installing the MCP server.
|
|
4
|
+
*
|
|
5
|
+
* The public surface is deliberately the same vocabulary as `@paystage/mcp`'s
|
|
6
|
+
* verifier so a caller can swap one for the other without translating statuses.
|
|
7
|
+
*/
|
|
8
|
+
export { DEFAULT_KEY_URL, JWK_ALG, RECEIPT_ALG, canonicalize, receiptPayload, verifyReceipt, } from "./verify.js";
|
|
9
|
+
export type { JwkLike, KeySource, ReceiptLike, VerifyOptions, VerifyVerdict } from "./verify.js";
|
|
10
|
+
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@paystage/receipt-verify` — check a PayStage receipt with the receipt and
|
|
3
|
+
* a fetch, without installing the MCP server.
|
|
4
|
+
*
|
|
5
|
+
* The public surface is deliberately the same vocabulary as `@paystage/mcp`'s
|
|
6
|
+
* verifier so a caller can swap one for the other without translating statuses.
|
|
7
|
+
*/
|
|
8
|
+
export { DEFAULT_KEY_URL, JWK_ALG, RECEIPT_ALG, canonicalize, receiptPayload, verifyReceipt, } from "./verify.js";
|
package/dist/verify.d.ts
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
/** The `alg` the issuer writes into a receipt. */
|
|
2
|
+
export declare const RECEIPT_ALG = "ECDSA-P256-SHA256";
|
|
3
|
+
/** The JWKS algorithm identifier for the same key. */
|
|
4
|
+
export declare const JWK_ALG = "ES256";
|
|
5
|
+
/** Standard JWKS path; the legacy `/v1/public/receipt-key.json` answers the same keys. */
|
|
6
|
+
export declare const DEFAULT_KEY_URL = "https://api.paystage.xyz/.well-known/paystage-receipt-key.json";
|
|
7
|
+
/** Minimal JWK shape: the fields Web Crypto reads, without a lib.dom dependency. */
|
|
8
|
+
export interface JwkLike {
|
|
9
|
+
kty?: string;
|
|
10
|
+
crv?: string;
|
|
11
|
+
x?: string;
|
|
12
|
+
y?: string;
|
|
13
|
+
kid?: string;
|
|
14
|
+
use?: string;
|
|
15
|
+
alg?: string;
|
|
16
|
+
[key: string]: unknown;
|
|
17
|
+
}
|
|
18
|
+
/** JSON with recursively sorted keys and no insignificant whitespace. */
|
|
19
|
+
export declare function canonicalize(value: unknown): string;
|
|
20
|
+
export interface ReceiptLike {
|
|
21
|
+
signed?: boolean;
|
|
22
|
+
alg?: string;
|
|
23
|
+
key_id?: string;
|
|
24
|
+
signature?: string;
|
|
25
|
+
v?: number;
|
|
26
|
+
issuer?: string;
|
|
27
|
+
issued_at?: string;
|
|
28
|
+
expires_at?: string;
|
|
29
|
+
payment?: {
|
|
30
|
+
scheme?: string;
|
|
31
|
+
network?: string;
|
|
32
|
+
asset?: string;
|
|
33
|
+
amount?: string;
|
|
34
|
+
payee?: string;
|
|
35
|
+
};
|
|
36
|
+
service?: {
|
|
37
|
+
name?: string;
|
|
38
|
+
version?: string;
|
|
39
|
+
};
|
|
40
|
+
verdict?: {
|
|
41
|
+
decision?: string;
|
|
42
|
+
reasons?: string[];
|
|
43
|
+
summary?: string;
|
|
44
|
+
};
|
|
45
|
+
request_sha256?: string;
|
|
46
|
+
policy_sha256?: string;
|
|
47
|
+
[key: string]: unknown;
|
|
48
|
+
}
|
|
49
|
+
export declare function receiptPayload(receipt: ReceiptLike): Record<string, unknown>;
|
|
50
|
+
export interface VerifyOptions {
|
|
51
|
+
/** Published JWK. Fetched from DEFAULT_KEY_URL when omitted. */
|
|
52
|
+
jwk?: JwkLike;
|
|
53
|
+
/** Inputs to check the receipt against; their digests are recomputed rather than taken on trust. */
|
|
54
|
+
expectedRequest?: unknown;
|
|
55
|
+
expectedPolicy?: unknown;
|
|
56
|
+
/** Reject a receipt older than this many seconds. A bound set by the verifier, not the issuer. */
|
|
57
|
+
maxAgeSeconds?: number;
|
|
58
|
+
/** Injectable clock, so freshness tests do not depend on wall time. */
|
|
59
|
+
now?: Date;
|
|
60
|
+
/** The payment this receipt is being checked against. */
|
|
61
|
+
payment?: {
|
|
62
|
+
scheme?: string;
|
|
63
|
+
network?: string;
|
|
64
|
+
asset?: string;
|
|
65
|
+
amount?: string;
|
|
66
|
+
payee?: string;
|
|
67
|
+
};
|
|
68
|
+
/** Override for tests and point-in-time checks. */
|
|
69
|
+
keyUrl?: string;
|
|
70
|
+
fetchImpl?: typeof fetch;
|
|
71
|
+
}
|
|
72
|
+
export type KeySource = "published" | "supplied";
|
|
73
|
+
export type VerifyVerdict = {
|
|
74
|
+
ok: true;
|
|
75
|
+
status: "signed-and-valid";
|
|
76
|
+
verdict?: string;
|
|
77
|
+
issued_at?: string;
|
|
78
|
+
key_id?: string;
|
|
79
|
+
key_source: KeySource;
|
|
80
|
+
} | {
|
|
81
|
+
ok: false;
|
|
82
|
+
status: "expired";
|
|
83
|
+
reason: string;
|
|
84
|
+
expires_at: string;
|
|
85
|
+
expired_by_seconds: number;
|
|
86
|
+
} | {
|
|
87
|
+
ok: false;
|
|
88
|
+
status: "payment-mismatch";
|
|
89
|
+
reason: string;
|
|
90
|
+
mismatched: string[];
|
|
91
|
+
} | {
|
|
92
|
+
ok: false;
|
|
93
|
+
status: "stale";
|
|
94
|
+
reason: string;
|
|
95
|
+
age_seconds: number;
|
|
96
|
+
max_age_seconds: number;
|
|
97
|
+
} | {
|
|
98
|
+
ok: false;
|
|
99
|
+
status: "inputs-mismatch";
|
|
100
|
+
reason: string;
|
|
101
|
+
mismatched: Array<"request" | "policy">;
|
|
102
|
+
} | {
|
|
103
|
+
ok: false;
|
|
104
|
+
status: "unsigned";
|
|
105
|
+
reason: string;
|
|
106
|
+
inputs?: "match" | "mismatch";
|
|
107
|
+
mismatched?: Array<"request" | "policy">;
|
|
108
|
+
} | {
|
|
109
|
+
ok: false;
|
|
110
|
+
status: "invalid";
|
|
111
|
+
reason: string;
|
|
112
|
+
} | {
|
|
113
|
+
ok: false;
|
|
114
|
+
status: "unverifiable";
|
|
115
|
+
reason: string;
|
|
116
|
+
};
|
|
117
|
+
/**
|
|
118
|
+
* Check a receipt. Returns a verdict rather than throwing, because "I could not check this" is a
|
|
119
|
+
* distinct outcome from "this is forged".
|
|
120
|
+
*/
|
|
121
|
+
export declare function verifyReceipt(receipt: ReceiptLike, options?: VerifyOptions): Promise<VerifyVerdict>;
|
|
122
|
+
//# sourceMappingURL=verify.d.ts.map
|
package/dist/verify.js
ADDED
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Verify a PayStage verdict receipt without installing the server.
|
|
3
|
+
*
|
|
4
|
+
* A receipt is proof rather than a claim only if a third party can check it with the receipt and a
|
|
5
|
+
* fetch. This is that path: the same verdict shape as `packages/mcp/src/verify.ts`, with no server
|
|
6
|
+
* import and no dependency on `@paystage/mcp`. Canonicalisation (sorted keys, no whitespace) and
|
|
7
|
+
* signature encoding (WebCrypto raw `r||s`) must match the issuer byte for byte.
|
|
8
|
+
*
|
|
9
|
+
* This verifier is **ES256 only** (ECDSA P-256 + SHA-256): it validates what it knows and refuses
|
|
10
|
+
* the rest rather than following the issuer upward.
|
|
11
|
+
*/
|
|
12
|
+
const webcrypto = globalThis.crypto;
|
|
13
|
+
const RECEIPT_VERSION = 1;
|
|
14
|
+
/** The `alg` the issuer writes into a receipt. */
|
|
15
|
+
export const RECEIPT_ALG = "ECDSA-P256-SHA256";
|
|
16
|
+
/** The JWKS algorithm identifier for the same key. */
|
|
17
|
+
export const JWK_ALG = "ES256";
|
|
18
|
+
/** Standard JWKS path; the legacy `/v1/public/receipt-key.json` answers the same keys. */
|
|
19
|
+
export const DEFAULT_KEY_URL = "https://api.paystage.xyz/.well-known/paystage-receipt-key.json";
|
|
20
|
+
/** How far ahead of the verifier's clock an `issued_at` may be. Five minutes covers honest skew. */
|
|
21
|
+
const MAX_CLOCK_SKEW_SECONDS = 300;
|
|
22
|
+
/** JSON with recursively sorted keys and no insignificant whitespace. */
|
|
23
|
+
export function canonicalize(value) {
|
|
24
|
+
if (value === null || typeof value !== "object")
|
|
25
|
+
return JSON.stringify(value) ?? "null";
|
|
26
|
+
if (Array.isArray(value))
|
|
27
|
+
return `[${value.map(canonicalize).join(",")}]`;
|
|
28
|
+
const entries = Object.entries(value)
|
|
29
|
+
.filter(([, v]) => v !== undefined)
|
|
30
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
|
|
31
|
+
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(",")}}`;
|
|
32
|
+
}
|
|
33
|
+
/** SHA-256 over the canonical form, lowercase hex — the issuer's rule. */
|
|
34
|
+
async function sha256Hex(value) {
|
|
35
|
+
const digest = await webcrypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalize(value)));
|
|
36
|
+
return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
|
|
37
|
+
}
|
|
38
|
+
function base64UrlToBytes(value) {
|
|
39
|
+
return Uint8Array.from(atob(value.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));
|
|
40
|
+
}
|
|
41
|
+
/** Age in seconds, or null when `issued_at` is not a timestamp. */
|
|
42
|
+
function ageSeconds(issuedAt, now) {
|
|
43
|
+
if (typeof issuedAt !== "string")
|
|
44
|
+
return null;
|
|
45
|
+
const then = Date.parse(issuedAt);
|
|
46
|
+
return Number.isNaN(then) ? null : ((now ?? new Date()).getTime() - then) / 1000;
|
|
47
|
+
}
|
|
48
|
+
/** Fields added by signing. Everything else is the signed payload. */
|
|
49
|
+
const SIGNATURE_FIELDS = ["signed", "alg", "key_id", "signature"];
|
|
50
|
+
export function receiptPayload(receipt) {
|
|
51
|
+
const payload = {};
|
|
52
|
+
for (const [key, value] of Object.entries(receipt)) {
|
|
53
|
+
if (!SIGNATURE_FIELDS.includes(key))
|
|
54
|
+
payload[key] = value;
|
|
55
|
+
}
|
|
56
|
+
return payload;
|
|
57
|
+
}
|
|
58
|
+
/** Fetch and select a key, or return the verdict saying why nothing can be checked. */
|
|
59
|
+
async function publishedKey(receipt, options) {
|
|
60
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
61
|
+
try {
|
|
62
|
+
const res = await fetchImpl(options.keyUrl ?? DEFAULT_KEY_URL);
|
|
63
|
+
if (!res.ok)
|
|
64
|
+
return { error: { ok: false, status: "unverifiable", reason: `key endpoint returned ${res.status}` } };
|
|
65
|
+
// Two shapes: a JWKS (`{ keys: [...] }`) and the original single key (`{ jwk }`). Selection is by
|
|
66
|
+
// the `key_id` the receipt carries, so rotation stays additive.
|
|
67
|
+
const body = (await res.json());
|
|
68
|
+
const keys = body.keys ?? [];
|
|
69
|
+
if (keys.length > 0) {
|
|
70
|
+
const match = receipt.key_id === undefined ? keys[0] : keys.find((k) => k.kid === receipt.key_id);
|
|
71
|
+
if (match === undefined) {
|
|
72
|
+
return {
|
|
73
|
+
error: {
|
|
74
|
+
ok: false,
|
|
75
|
+
status: "unverifiable",
|
|
76
|
+
reason: `the published key set has no key with kid ${String(receipt.key_id)} — the receipt names a key this issuer does not publish`,
|
|
77
|
+
},
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
return { jwk: match };
|
|
81
|
+
}
|
|
82
|
+
if (body.configured === true && body.jwk !== undefined)
|
|
83
|
+
return { jwk: body.jwk };
|
|
84
|
+
return { error: { ok: false, status: "unverifiable", reason: "issuer has not published a signing key, so nothing can be checked" } };
|
|
85
|
+
}
|
|
86
|
+
catch (error) {
|
|
87
|
+
return { error: { ok: false, status: "unverifiable", reason: `could not fetch the key: ${error instanceof Error ? error.message : String(error)}` } };
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Check a receipt. Returns a verdict rather than throwing, because "I could not check this" is a
|
|
92
|
+
* distinct outcome from "this is forged".
|
|
93
|
+
*/
|
|
94
|
+
export async function verifyReceipt(receipt, options = {}) {
|
|
95
|
+
if (receipt === null || typeof receipt !== "object")
|
|
96
|
+
return { ok: false, status: "invalid", reason: "receipt is not an object" };
|
|
97
|
+
if (receipt.v !== undefined && receipt.v !== RECEIPT_VERSION) {
|
|
98
|
+
return {
|
|
99
|
+
ok: false,
|
|
100
|
+
status: "invalid",
|
|
101
|
+
reason: `unsupported receipt version ${String(receipt.v)} (this verifier understands ${RECEIPT_VERSION})`,
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
const decision = receipt.verdict?.decision;
|
|
105
|
+
if (decision !== undefined && !["pay", "review", "do_not_pay"].includes(decision)) {
|
|
106
|
+
return { ok: false, status: "invalid", reason: `unknown verdict ${JSON.stringify(decision)} — expected pay, review or do_not_pay` };
|
|
107
|
+
}
|
|
108
|
+
const digestMismatches = async () => {
|
|
109
|
+
const mismatched = [];
|
|
110
|
+
for (const [expected, claimed, which] of [
|
|
111
|
+
[options.expectedRequest, receipt.request_sha256, "request"],
|
|
112
|
+
[options.expectedPolicy, receipt.policy_sha256, "policy"],
|
|
113
|
+
]) {
|
|
114
|
+
if (expected !== undefined && (typeof claimed !== "string" || (await sha256Hex(expected)) !== claimed)) {
|
|
115
|
+
mismatched.push(which);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
return mismatched;
|
|
119
|
+
};
|
|
120
|
+
if (receipt.signed !== true) {
|
|
121
|
+
const mismatched = await digestMismatches();
|
|
122
|
+
return {
|
|
123
|
+
ok: false,
|
|
124
|
+
status: "unsigned",
|
|
125
|
+
reason: "receipt carries no signature — it is useful as a record of what was decided, but it cannot prove who decided it",
|
|
126
|
+
...(options.expectedRequest === undefined && options.expectedPolicy === undefined
|
|
127
|
+
? {}
|
|
128
|
+
: { inputs: mismatched.length === 0 ? "match" : "mismatch", mismatched }),
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
if (typeof receipt.signature !== "string" || receipt.signature.length === 0) {
|
|
132
|
+
return { ok: false, status: "invalid", reason: "signed: true but no signature field" };
|
|
133
|
+
}
|
|
134
|
+
if (receipt.alg !== undefined && receipt.alg !== RECEIPT_ALG) {
|
|
135
|
+
return { ok: false, status: "invalid", reason: `unexpected alg: ${receipt.alg} — this verifier is ES256-only` };
|
|
136
|
+
}
|
|
137
|
+
let jwk = options.jwk;
|
|
138
|
+
if (jwk === undefined) {
|
|
139
|
+
const found = await publishedKey(receipt, options);
|
|
140
|
+
if ("error" in found)
|
|
141
|
+
return found.error;
|
|
142
|
+
jwk = found.jwk;
|
|
143
|
+
}
|
|
144
|
+
// ES256 only: refuse a key that names another curve or algorithm rather than importing and hoping.
|
|
145
|
+
if (jwk.kty !== "EC" || String(jwk.crv) !== "P-256" || (jwk.alg !== undefined && jwk.alg !== JWK_ALG)) {
|
|
146
|
+
return {
|
|
147
|
+
ok: false,
|
|
148
|
+
status: "invalid",
|
|
149
|
+
reason: `the verifying key is not an ES256 (P-256) key: kty=${String(jwk.kty)} crv=${String(jwk.crv)} alg=${String(jwk.alg)}`,
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
const data = new TextEncoder().encode(canonicalize(receiptPayload(receipt)));
|
|
153
|
+
let signature;
|
|
154
|
+
try {
|
|
155
|
+
const decoded = base64UrlToBytes(receipt.signature);
|
|
156
|
+
// Copy into a plain ArrayBuffer so the BufferSource type is exact under TS 5.9's generic typed arrays.
|
|
157
|
+
signature = new Uint8Array(decoded.length);
|
|
158
|
+
signature.set(decoded);
|
|
159
|
+
}
|
|
160
|
+
catch {
|
|
161
|
+
return { ok: false, status: "invalid", reason: "signature is not valid base64url" };
|
|
162
|
+
}
|
|
163
|
+
try {
|
|
164
|
+
const publicKey = await webcrypto.subtle.importKey("jwk", jwk, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
|
|
165
|
+
// WebCrypto's ECDSA verify with SHA-256 is ES256; the curve and JWK alg are pinned above.
|
|
166
|
+
const valid = await webcrypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, publicKey, signature, data);
|
|
167
|
+
if (!valid) {
|
|
168
|
+
return {
|
|
169
|
+
ok: false,
|
|
170
|
+
status: "invalid",
|
|
171
|
+
reason: "signature does not match the payload — the receipt was altered or was signed by a different key",
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
// Only with the signature proven is it worth asking whether the receipt covers the caller's inputs.
|
|
175
|
+
const mismatched = await digestMismatches();
|
|
176
|
+
if (mismatched.length > 0) {
|
|
177
|
+
return {
|
|
178
|
+
ok: false,
|
|
179
|
+
status: "inputs-mismatch",
|
|
180
|
+
reason: `signature is valid but the receipt does not cover the supplied ${mismatched.join(" and ")} input`,
|
|
181
|
+
mismatched,
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
// A signed receipt carries its own lifetime. Checked after the signature: an expired *signed*
|
|
185
|
+
// receipt is the case that matters, and an unsigned one is already not trusted.
|
|
186
|
+
if (receipt.expires_at !== undefined) {
|
|
187
|
+
const expiresAt = Date.parse(receipt.expires_at);
|
|
188
|
+
const now = options.now ?? new Date();
|
|
189
|
+
if (Number.isNaN(expiresAt)) {
|
|
190
|
+
return { ok: false, status: "invalid", reason: `expires_at is not a parseable timestamp: ${JSON.stringify(receipt.expires_at)}` };
|
|
191
|
+
}
|
|
192
|
+
if (now.getTime() > expiresAt) {
|
|
193
|
+
const expiredBy = Math.round((now.getTime() - expiresAt) / 1000);
|
|
194
|
+
return {
|
|
195
|
+
ok: false,
|
|
196
|
+
status: "expired",
|
|
197
|
+
reason: `this decision expired ${expiredBy}s ago (${receipt.expires_at}); ask for a fresh evaluation`,
|
|
198
|
+
expires_at: receipt.expires_at,
|
|
199
|
+
expired_by_seconds: expiredBy,
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
if (options.payment !== undefined) {
|
|
204
|
+
const bound = receipt.payment;
|
|
205
|
+
if (bound === undefined) {
|
|
206
|
+
return {
|
|
207
|
+
ok: false,
|
|
208
|
+
status: "payment-mismatch",
|
|
209
|
+
reason: "this receipt predates payment binding, so it cannot be shown to be about the supplied payment",
|
|
210
|
+
mismatched: ["binding"],
|
|
211
|
+
};
|
|
212
|
+
}
|
|
213
|
+
const fields = ["scheme", "network", "asset", "amount", "payee"].filter((field) => {
|
|
214
|
+
const wanted = options.payment?.[field];
|
|
215
|
+
return wanted !== undefined && String(wanted) !== String(bound[field]);
|
|
216
|
+
});
|
|
217
|
+
if (fields.length > 0) {
|
|
218
|
+
return {
|
|
219
|
+
ok: false,
|
|
220
|
+
status: "payment-mismatch",
|
|
221
|
+
reason: `signature is valid but the receipt covers a different payment (${fields.join(", ")})`,
|
|
222
|
+
mismatched: fields,
|
|
223
|
+
};
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
if (options.maxAgeSeconds !== undefined) {
|
|
227
|
+
const age = ageSeconds(receipt.issued_at, options.now);
|
|
228
|
+
if (age === null)
|
|
229
|
+
return { ok: false, status: "invalid", reason: `issued_at is not a parseable timestamp: ${JSON.stringify(receipt.issued_at)}` };
|
|
230
|
+
if (age < -MAX_CLOCK_SKEW_SECONDS) {
|
|
231
|
+
return {
|
|
232
|
+
ok: false,
|
|
233
|
+
status: "invalid",
|
|
234
|
+
reason: `issued_at is ${Math.round(-age)}s in the future, beyond any plausible clock skew — this receipt could not have been issued yet`,
|
|
235
|
+
};
|
|
236
|
+
}
|
|
237
|
+
if (age > options.maxAgeSeconds) {
|
|
238
|
+
return {
|
|
239
|
+
ok: false,
|
|
240
|
+
status: "stale",
|
|
241
|
+
reason: `receipt is ${Math.round(age)}s old, older than the ${options.maxAgeSeconds}s bound`,
|
|
242
|
+
age_seconds: age,
|
|
243
|
+
max_age_seconds: options.maxAgeSeconds,
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
return {
|
|
248
|
+
ok: true,
|
|
249
|
+
status: "signed-and-valid",
|
|
250
|
+
verdict: receipt.verdict?.decision,
|
|
251
|
+
issued_at: receipt.issued_at,
|
|
252
|
+
key_id: receipt.key_id,
|
|
253
|
+
key_source: options.jwk !== undefined || options.keyUrl !== undefined ? "supplied" : "published",
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
catch (error) {
|
|
257
|
+
return { ok: false, status: "invalid", reason: `could not verify: ${error instanceof Error ? error.message : String(error)}` };
|
|
258
|
+
}
|
|
259
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,63 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paystage/receipt-verify",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "verify a PayStage verdict receipt without installing the server: fetch the published JWKS by kid, check the ES256 signature, expiry and payment binding. Same verdict shape as @paystage/mcp.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"import": "./dist/index.js"
|
|
13
|
+
},
|
|
14
|
+
"./package.json": "./package.json"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"!dist/**/*.map"
|
|
19
|
+
],
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=20"
|
|
22
|
+
},
|
|
23
|
+
"keywords": [
|
|
24
|
+
"payment-safety",
|
|
25
|
+
"x402",
|
|
26
|
+
"agent-payments",
|
|
27
|
+
"receipt",
|
|
28
|
+
"receipt-verification",
|
|
29
|
+
"verify-receipt",
|
|
30
|
+
"jwks",
|
|
31
|
+
"es256",
|
|
32
|
+
"ecdsa",
|
|
33
|
+
"offline-verification",
|
|
34
|
+
"verify-without-trust",
|
|
35
|
+
"agent-payment-safety",
|
|
36
|
+
"usdc",
|
|
37
|
+
"base",
|
|
38
|
+
"no-server",
|
|
39
|
+
"signature-verification"
|
|
40
|
+
],
|
|
41
|
+
"homepage": "https://paystage.xyz",
|
|
42
|
+
"repository": {
|
|
43
|
+
"type": "git",
|
|
44
|
+
"url": "git+https://github.com/base-buzz/paystage.git",
|
|
45
|
+
"directory": "packages/receipt-verify"
|
|
46
|
+
},
|
|
47
|
+
"bugs": {
|
|
48
|
+
"url": "https://github.com/base-buzz/paystage/issues"
|
|
49
|
+
},
|
|
50
|
+
"publishConfig": {
|
|
51
|
+
"access": "public"
|
|
52
|
+
},
|
|
53
|
+
"scripts": {
|
|
54
|
+
"build": "tsc -p tsconfig.json",
|
|
55
|
+
"test": "vitest run",
|
|
56
|
+
"typecheck": "tsc --noEmit"
|
|
57
|
+
},
|
|
58
|
+
"devDependencies": {
|
|
59
|
+
"typescript": "^5.9.3",
|
|
60
|
+
"vitest": "^4.1.12"
|
|
61
|
+
},
|
|
62
|
+
"private": false
|
|
63
|
+
}
|