@paystage/x-evm 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 CHANGED
@@ -1,3 +1,48 @@
1
- # Temporary Holding Version
1
+ # @paystage/x-evm
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Guard for [`@x402/evm`](https://www.npmjs.com/package/@x402/evm): evaluate the payment requirements
4
+ **before** the EVM scheme signs.
5
+
6
+ ```bash
7
+ npm i @paystage/x-evm
8
+ ```
9
+
10
+ ```ts
11
+ import { ExactEvmScheme } from "@x402/evm/exact/client";
12
+ import { guardScheme } from "@paystage/x-evm";
13
+
14
+ const scheme = guardScheme(new ExactEvmScheme(signer), { policy });
15
+ // createPaymentPayload now throws instead of signing a payment the policy refuses
16
+ ```
17
+
18
+ ## Why this exists
19
+
20
+ `@x402/evm` does one thing well: it builds and signs the payload. That is exactly why a policy cannot
21
+ live there — by the time `createPaymentPayload` runs, the decision to sign has already been made.
22
+
23
+ `createPaymentPayload()` is the single choke point every scheme variant shares, so one wrapper covers
24
+ `ExactEvmScheme`, `UptoEvmScheme`, `BatchSettlementEvmScheme` and anything else inheriting it.
25
+
26
+ ## A refusal throws
27
+
28
+ Not a return value. A caller that ignores a return value would sign anyway, and the point is that it
29
+ cannot. Catch `PaymentRefusedError` and read `.verdict.reasons` — the sentences name what failed, so
30
+ they can be pasted into a policy fix.
31
+
32
+ ## Works with batching schemes too
33
+
34
+ `@circle-fin/x402-batching`'s `BatchEvmScheme` exposes `createPaymentPayload` like every other scheme,
35
+ plus batching hooks. The guard wraps only that one method, so the hooks are untouched and a guarded
36
+ batched payment is evaluated exactly like a single one. There is no separate batching package because
37
+ none is needed — there is a test that proves the hooks survive.
38
+
39
+ ## What it does not do
40
+
41
+ No network calls, no keys, no signing of its own. It evaluates the requirements you were already
42
+ given and either lets the scheme proceed or refuses. Evaluation is local and synchronous in effect.
43
+
44
+ ## Tests
45
+
46
+ Seven, and the ones that matter count signatures: a refused payment must leave `created === 0`.
47
+
48
+ MIT.
@@ -0,0 +1,49 @@
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 ADDED
@@ -0,0 +1,60 @@
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
+ }
package/package.json CHANGED
@@ -1,6 +1,28 @@
1
1
  {
2
2
  "name": "@paystage/x-evm",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "PayStage guard for @x402/evm — evaluate the payment requirements before the EVM scheme signs",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
10
+ "files": ["dist", "README.md"],
11
+ "repository": {
12
+ "type": "git",
13
+ "url": "git+https://github.com/base-buzz/paystage.git",
14
+ "directory": "packages/x-evm"
15
+ },
16
+ "keywords": ["x402", "evm", "agent-payments", "preflight", "guard"],
17
+ "scripts": {
18
+ "build": "tsc -p tsconfig.json",
19
+ "test": "vitest run"
20
+ },
21
+ "peerDependencies": { "@x402/evm": ">=2.29.0" },
22
+ "peerDependenciesMeta": { "@x402/evm": { "optional": true } },
23
+ "dependencies": {
24
+ "@paystage/preflight": "0.2.3",
25
+ "@paystage/policy": "0.2.1"
26
+ },
27
+ "devDependencies": { "typescript": "^5.9.3", "vitest": "^4.1.12" }
28
+ }