@paystage/x-evm 0.1.0 → 0.1.1-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 +7 -0
- package/package.json +32 -9
- package/dist/index.d.ts +0 -49
- package/dist/index.js +0 -60
package/README.md
CHANGED
|
@@ -29,6 +29,13 @@ Not a return value. A caller that ignores a return value would sign anyway, and
|
|
|
29
29
|
cannot. Catch `PaymentRefusedError` and read `.verdict.reasons` — the sentences name what failed, so
|
|
30
30
|
they can be pasted into a policy fix.
|
|
31
31
|
|
|
32
|
+
## Works across chains, not just EVM
|
|
33
|
+
|
|
34
|
+
The name says EVM but the guard wraps `createPaymentPayload`, which every x402 client scheme exposes —
|
|
35
|
+
`@x402/svm`'s `ExactSvmScheme`, `UptoSvmScheme` and `BatchSvmScheme` included. A Solana payment is
|
|
36
|
+
evaluated by the same policy; `allowed_networks` is what decides, so an `eip155:`-only policy refuses
|
|
37
|
+
it with a reason rather than signing it.
|
|
38
|
+
|
|
32
39
|
## Works with batching schemes too
|
|
33
40
|
|
|
34
41
|
`@circle-fin/x402-batching`'s `BatchEvmScheme` exposes `createPaymentPayload` like every other scheme,
|
package/package.json
CHANGED
|
@@ -1,28 +1,51 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paystage/x-evm",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1-canary.22",
|
|
4
4
|
"description": "PayStage guard for @x402/evm — evaluate the payment requirements before the EVM scheme signs",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "./dist/index.js",
|
|
8
8
|
"types": "./dist/index.d.ts",
|
|
9
|
-
"exports": {
|
|
10
|
-
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"import": "./dist/index.js"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"dist",
|
|
17
|
+
"README.md"
|
|
18
|
+
],
|
|
11
19
|
"repository": {
|
|
12
20
|
"type": "git",
|
|
13
21
|
"url": "git+https://github.com/base-buzz/paystage.git",
|
|
14
22
|
"directory": "packages/x-evm"
|
|
15
23
|
},
|
|
16
|
-
"keywords": [
|
|
24
|
+
"keywords": [
|
|
25
|
+
"x402",
|
|
26
|
+
"evm",
|
|
27
|
+
"agent-payments",
|
|
28
|
+
"preflight",
|
|
29
|
+
"guard"
|
|
30
|
+
],
|
|
17
31
|
"scripts": {
|
|
18
32
|
"build": "tsc -p tsconfig.json",
|
|
19
33
|
"test": "vitest run"
|
|
20
34
|
},
|
|
21
|
-
"peerDependencies": {
|
|
22
|
-
|
|
35
|
+
"peerDependencies": {
|
|
36
|
+
"@x402/evm": ">=2.29.0"
|
|
37
|
+
},
|
|
38
|
+
"peerDependenciesMeta": {
|
|
39
|
+
"@x402/evm": {
|
|
40
|
+
"optional": true
|
|
41
|
+
}
|
|
42
|
+
},
|
|
23
43
|
"dependencies": {
|
|
24
|
-
"@paystage/preflight": "0.2.3",
|
|
25
|
-
"@paystage/policy": "0.2.1"
|
|
44
|
+
"@paystage/preflight": "0.2.3-canary.22",
|
|
45
|
+
"@paystage/policy": "0.2.1-canary.22"
|
|
26
46
|
},
|
|
27
|
-
"devDependencies": {
|
|
47
|
+
"devDependencies": {
|
|
48
|
+
"typescript": "^5.9.3",
|
|
49
|
+
"vitest": "^4.1.12"
|
|
50
|
+
}
|
|
28
51
|
}
|
package/dist/index.d.ts
DELETED
|
@@ -1,49 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* PayStage guard for `@x402/evm`.
|
|
3
|
-
*
|
|
4
|
-
* `@x402/evm` does the thing that matters and does it well: it builds and signs an EVM payment
|
|
5
|
-
* payload. That is exactly why it cannot be the place a policy is enforced — by the time
|
|
6
|
-
* `createPaymentPayload` runs, the decision has already been made to sign.
|
|
7
|
-
*
|
|
8
|
-
* This wraps that method. `createPaymentPayload(x402Version, requirements, context)` is the single
|
|
9
|
-
* choke point every scheme variant goes through, so one wrapper covers `ExactEvmScheme`,
|
|
10
|
-
* `UptoEvmScheme`, `BatchSettlementEvmScheme` and anything else that inherits it.
|
|
11
|
-
*
|
|
12
|
-
* A refusal is a thrown error, not a return value: a caller that ignores a return value would sign
|
|
13
|
-
* anyway, and the whole point is that it cannot.
|
|
14
|
-
*/
|
|
15
|
-
import type { Policy } from "@paystage/policy";
|
|
16
|
-
export interface GuardOptions {
|
|
17
|
-
/** The policy to evaluate against. No policy means no payment — see `requirePolicy`. */
|
|
18
|
-
policy: Policy;
|
|
19
|
-
/** Called with every verdict, before the decision is enforced. Never receives a signature. */
|
|
20
|
-
onVerdict?: (verdict: GuardVerdict) => void;
|
|
21
|
-
/** Default true. When false, a `review` verdict is allowed through and only denials throw. */
|
|
22
|
-
refuseReview?: boolean;
|
|
23
|
-
}
|
|
24
|
-
export interface GuardVerdict {
|
|
25
|
-
decision: "pay" | "review" | "do_not_pay";
|
|
26
|
-
reasons: Array<{
|
|
27
|
-
code: string;
|
|
28
|
-
detail?: string;
|
|
29
|
-
}>;
|
|
30
|
-
network?: string;
|
|
31
|
-
amount?: string;
|
|
32
|
-
}
|
|
33
|
-
export declare class PaymentRefusedError extends Error {
|
|
34
|
-
readonly verdict: GuardVerdict;
|
|
35
|
-
constructor(verdict: GuardVerdict);
|
|
36
|
-
}
|
|
37
|
-
/** The shape of the scheme method we wrap. Deliberately structural, not a dependency on its types. */
|
|
38
|
-
interface SchemeLike {
|
|
39
|
-
createPaymentPayload(x402Version: number, paymentRequirements: unknown, context?: unknown): Promise<unknown>;
|
|
40
|
-
}
|
|
41
|
-
/**
|
|
42
|
-
* Wrap a scheme instance so its payload creation is gated.
|
|
43
|
-
*
|
|
44
|
-
* Returns the same object rather than a copy, so identity checks and `instanceof` keep working.
|
|
45
|
-
*/
|
|
46
|
-
export declare function guardScheme<T extends SchemeLike>(scheme: T, options: GuardOptions): T;
|
|
47
|
-
/** Convenience: construct a scheme already guarded. */
|
|
48
|
-
export declare function createGuardedScheme<T extends SchemeLike>(Scheme: new (...args: any[]) => T, args: ConstructorParameters<typeof Scheme>, options: GuardOptions): T;
|
|
49
|
-
export {};
|
package/dist/index.js
DELETED
|
@@ -1,60 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* PayStage guard for `@x402/evm`.
|
|
3
|
-
*
|
|
4
|
-
* `@x402/evm` does the thing that matters and does it well: it builds and signs an EVM payment
|
|
5
|
-
* payload. That is exactly why it cannot be the place a policy is enforced — by the time
|
|
6
|
-
* `createPaymentPayload` runs, the decision has already been made to sign.
|
|
7
|
-
*
|
|
8
|
-
* This wraps that method. `createPaymentPayload(x402Version, requirements, context)` is the single
|
|
9
|
-
* choke point every scheme variant goes through, so one wrapper covers `ExactEvmScheme`,
|
|
10
|
-
* `UptoEvmScheme`, `BatchSettlementEvmScheme` and anything else that inherits it.
|
|
11
|
-
*
|
|
12
|
-
* A refusal is a thrown error, not a return value: a caller that ignores a return value would sign
|
|
13
|
-
* anyway, and the whole point is that it cannot.
|
|
14
|
-
*/
|
|
15
|
-
import { evaluatePayment, normalizePaymentRequired } from "@paystage/preflight";
|
|
16
|
-
export class PaymentRefusedError extends Error {
|
|
17
|
-
verdict;
|
|
18
|
-
constructor(verdict) {
|
|
19
|
-
const codes = verdict.reasons.map((r) => r.code).join(", ") || "no reason given";
|
|
20
|
-
super(`PayStage refused this payment (${verdict.decision}): ${codes}`);
|
|
21
|
-
this.name = "PaymentRefusedError";
|
|
22
|
-
this.verdict = verdict;
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
function toVerdict(result) {
|
|
26
|
-
// `@paystage/preflight` returns reasons as sentences, not coded objects — the sentence is what a
|
|
27
|
-
// human reads in a log, so it is carried through unchanged rather than re-parsed into a code.
|
|
28
|
-
const reasons = (result.reasons ?? []).map((text) => ({ code: String(text) }));
|
|
29
|
-
return {
|
|
30
|
-
decision: result.decision,
|
|
31
|
-
reasons,
|
|
32
|
-
};
|
|
33
|
-
}
|
|
34
|
-
/**
|
|
35
|
-
* Wrap a scheme instance so its payload creation is gated.
|
|
36
|
-
*
|
|
37
|
-
* Returns the same object rather than a copy, so identity checks and `instanceof` keep working.
|
|
38
|
-
*/
|
|
39
|
-
export function guardScheme(scheme, options) {
|
|
40
|
-
const refuseReview = options.refuseReview !== false;
|
|
41
|
-
const original = scheme.createPaymentPayload.bind(scheme);
|
|
42
|
-
scheme.createPaymentPayload = async function guarded(x402Version, paymentRequirements, context) {
|
|
43
|
-
const challenge = normalizePaymentRequired({
|
|
44
|
-
x402Version,
|
|
45
|
-
accepts: [paymentRequirements],
|
|
46
|
-
});
|
|
47
|
-
const result = evaluatePayment(challenge, options.policy);
|
|
48
|
-
const verdict = toVerdict(result);
|
|
49
|
-
options.onVerdict?.(verdict);
|
|
50
|
-
const blocked = verdict.decision === "do_not_pay" || (verdict.decision === "review" && refuseReview);
|
|
51
|
-
if (blocked)
|
|
52
|
-
throw new PaymentRefusedError(verdict);
|
|
53
|
-
return original(x402Version, paymentRequirements, context);
|
|
54
|
-
};
|
|
55
|
-
return scheme;
|
|
56
|
-
}
|
|
57
|
-
/** Convenience: construct a scheme already guarded. */
|
|
58
|
-
export function createGuardedScheme(Scheme, args, options) {
|
|
59
|
-
return guardScheme(new Scheme(...args), options);
|
|
60
|
-
}
|