pivx-402 1.0.0

package/dist/src/nonce-store.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryNonceStore = void 0;
+exports.randomNonce = randomNonce;
+/** In-memory store. Fine for a single process; swap for Redis in production. */
+class InMemoryNonceStore {
+    ttlMs;
+    used = new Map();
+    lastSweep = 0;
+    /** Minimum gap between sweeps. Sweep is O(n); don't run it on every claim. */
+    static SWEEP_INTERVAL_MS = 60_000;
+    constructor(ttlMs = 24 * 60 * 60 * 1000) {
+        this.ttlMs = ttlMs;
+    }
+    async claim(nonce) {
+        this.maybeSweep();
+        if (this.used.has(nonce))
+            return false;
+        this.used.set(nonce, Date.now());
+        return true;
+    }
+    maybeSweep() {
+        const now = Date.now();
+        if (now - this.lastSweep < InMemoryNonceStore.SWEEP_INTERVAL_MS)
+            return;
+        this.lastSweep = now;
+        const cutoff = now - this.ttlMs;
+        for (const [k, t] of this.used)
+            if (t < cutoff)
+                this.used.delete(k);
+    }
+}
+exports.InMemoryNonceStore = InMemoryNonceStore;
+function randomNonce() {
+    // 16 bytes hex -> 32 chars. Fits in a single OP_RETURN push easily.
+    const bytes = new Uint8Array(16);
+    // crypto.getRandomValues is available in Node 19+ via the global crypto object.
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/dist/src/types.d.ts

@@ -0,0 +1,75 @@
+export type Network = "pivx-mainnet" | "pivx-testnet" | "pivx-regtest";
+export type Scheme = "pivx-transparent" | "pivx-shield";
+export interface PaymentRequirement {
+    scheme: Scheme;
+    network: Network;
+    asset: "PIV";
+    /** Decimal string, e.g. "0.01". */
+    maxAmountRequired: string;
+    /** Destination PIVX address. */
+    payTo: string;
+    /** Server-generated nonce. Client MUST embed this in an OP_RETURN. */
+    nonce: string;
+    /** Minimum confirmations before the payment is accepted. 0 = mempool ok. */
+    minConfirmations: number;
+    /** Seconds until the requirement expires. */
+    maxTimeoutSeconds: number;
+    /** The resource being paid for, e.g. "/api/weather". */
+    resource: string;
+    description?: string;
+}
+export interface PaymentRequiredEnvelope {
+    x402Version: 1;
+    accepts: PaymentRequirement[];
+    error?: string;
+}
+export interface PaymentProof {
+    x402Version: 1;
+    scheme: Scheme;
+    network: Network;
+    payload: ProofPayload;
+}
+/** Same shape for transparent and shielded — txid is public either way. */
+export interface ProofPayload {
+    /** Broadcast txid of the payment. */
+    txid: string;
+    /** Echoed back from the requirement so the server can match. */
+    nonce: string;
+}
+export type TransparentProofPayload = ProofPayload;
+export type ShieldedProofPayload = ProofPayload;
+export interface TxOutput {
+    /** Amount in PIV as a decimal string. null for OP_RETURN. */
+    value: string | null;
+    /** Recipient address, or null for non-address outputs (OP_RETURN, multisig, etc.). */
+    address: string | null;
+    /** Decoded OP_RETURN data as a UTF-8 string, or null if not an OP_RETURN. */
+    opReturnText: string | null;
+}
+export interface TxInfo {
+    txid: string;
+    confirmations: number;
+    outputs: TxOutput[];
+}
+/** A shielded (Sapling) output visible to the holder of the relevant viewing key. */
+export interface ShieldedOutput {
+    /** Shielded address (ps1... on mainnet). */
+    address: string;
+    /** Amount in PIV as a decimal string. */
+    value: string;
+    /** Decoded memo as UTF-8 text. null if memo is not valid UTF-8. */
+    memoText: string | null;
+    /** True if this output is one we sent (visible via outgoing viewing key). */
+    outgoing: boolean;
+}
+export interface ShieldedTxInfo {
+    txid: string;
+    confirmations: number;
+    shieldedOutputs: ShieldedOutput[];
+}
+export interface VerificationResult {
+    ok: boolean;
+    /** Set when ok=false. Stable codes for clients to react to. */
+    reason?: "tx_not_found" | "insufficient_confirmations" | "wrong_recipient" | "insufficient_amount" | "missing_nonce" | "nonce_replayed" | "scheme_unsupported" | "network_mismatch" | "shielded_backend_unavailable";
+    details?: string;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/verifier.d.ts

@@ -0,0 +1,14 @@
+import type { PivxBackend } from "./backends";
+import type { NonceStore } from "./nonce-store";
+import type { PaymentProof, PaymentRequirement, VerificationResult } from "./types";
+export interface VerifierOptions {
+    backend: PivxBackend;
+    nonceStore: NonceStore;
+}
+export declare class Verifier {
+    private readonly opts;
+    constructor(opts: VerifierOptions);
+    verify(requirement: PaymentRequirement, proof: PaymentProof): Promise<VerificationResult>;
+    private verifyTransparent;
+    private verifyShielded;
+}

package/dist/src/verifier.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Verifier = void 0;
+const amount_1 = require("./amount");
+class Verifier {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async verify(requirement, proof) {
+        if (proof.scheme !== requirement.scheme) {
+            return { ok: false, reason: "scheme_unsupported", details: `proof scheme ${proof.scheme} != ${requirement.scheme}` };
+        }
+        if (proof.network !== requirement.network) {
+            return { ok: false, reason: "network_mismatch" };
+        }
+        if (proof.payload.nonce !== requirement.nonce) {
+            return { ok: false, reason: "missing_nonce", details: "proof nonce does not match requirement" };
+        }
+        let onChain;
+        switch (requirement.scheme) {
+            case "pivx-transparent":
+                onChain = await this.verifyTransparent(requirement, proof);
+                break;
+            case "pivx-shield":
+                onChain = await this.verifyShielded(requirement, proof);
+                break;
+            default:
+                return assertNever(requirement.scheme);
+        }
+        if (!onChain.ok)
+            return onChain;
+        // Replay protection: claim the nonce only once, after all other checks pass.
+        const claimed = await this.opts.nonceStore.claim(requirement.nonce);
+        if (!claimed)
+            return { ok: false, reason: "nonce_replayed" };
+        return { ok: true };
+    }
+    async verifyTransparent(requirement, proof) {
+        const tx = await this.opts.backend.getTransaction(proof.payload.txid);
+        if (!tx)
+            return { ok: false, reason: "tx_not_found" };
+        if (tx.confirmations < requirement.minConfirmations) {
+            return {
+                ok: false,
+                reason: "insufficient_confirmations",
+                details: `have ${tx.confirmations}, need ${requirement.minConfirmations}`,
+            };
+        }
+        const required = (0, amount_1.pivToSats)(requirement.maxAmountRequired);
+        const paid = tx.outputs
+            .filter((o) => o.address === requirement.payTo && o.value !== null)
+            .reduce((acc, o) => acc + (0, amount_1.pivToSats)(o.value), 0n);
+        if (paid === 0n)
+            return { ok: false, reason: "wrong_recipient" };
+        if (paid < required) {
+            return {
+                ok: false,
+                reason: "insufficient_amount",
+                details: `paid ${paid} sats, need ${required} sats`,
+            };
+        }
+        const hasNonce = tx.outputs.some((o) => o.opReturnText === requirement.nonce);
+        if (!hasNonce)
+            return { ok: false, reason: "missing_nonce", details: "OP_RETURN with nonce not found" };
+        return { ok: true };
+    }
+    async verifyShielded(requirement, proof) {
+        if (!this.opts.backend.viewShieldedTransaction) {
+            return {
+                ok: false,
+                reason: "shielded_backend_unavailable",
+                details: "configured backend cannot decrypt shielded outputs",
+            };
+        }
+        const tx = await this.opts.backend.viewShieldedTransaction(proof.payload.txid);
+        if (!tx)
+            return { ok: false, reason: "tx_not_found" };
+        if (tx.confirmations < requirement.minConfirmations) {
+            return {
+                ok: false,
+                reason: "insufficient_confirmations",
+                details: `have ${tx.confirmations}, need ${requirement.minConfirmations}`,
+            };
+        }
+        // Only consider incoming (non-outgoing) outputs to our shielded address.
+        const incoming = tx.shieldedOutputs.filter((o) => !o.outgoing && o.address === requirement.payTo);
+        if (incoming.length === 0)
+            return { ok: false, reason: "wrong_recipient" };
+        const required = (0, amount_1.pivToSats)(requirement.maxAmountRequired);
+        // Match an output whose memo carries the nonce; aggregate its value.
+        const matching = incoming.filter((o) => o.memoText === requirement.nonce);
+        if (matching.length === 0) {
+            return { ok: false, reason: "missing_nonce", details: "no shielded output with the nonce in its memo" };
+        }
+        const paid = matching.reduce((acc, o) => acc + (0, amount_1.pivToSats)(o.value), 0n);
+        if (paid < required) {
+            return {
+                ok: false,
+                reason: "insufficient_amount",
+                details: `paid ${paid} sats, need ${required} sats`,
+            };
+        }
+        return { ok: true };
+    }
+}
+exports.Verifier = Verifier;
+function assertNever(x) {
+    throw new Error(`unreachable scheme: ${String(x)}`);
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "pivx-402",
+  "version": "1.0.0",
+  "description": "HTTP 402 Payment Required middleware for PIVX — pay-per-request APIs with transparent or shielded PIV.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "demo:server": "tsx demo/server.ts",
+    "demo:cat": "tsx demo/cat.ts",
+    "demo:client": "tsx demo/client.ts",
+    "demo:pay": "tsx demo/pay-cli.ts",
+    "test": "node --test --import=tsx test/*.test.ts"
+  },
+  "keywords": [
+    "pivx",
+    "x402",
+    "http-402",
+    "payment-required",
+    "micropayments",
+    "express",
+    "middleware",
+    "cryptocurrency",
+    "ai-agents",
+    "agentic-payments",
+    "shield",
+    "sapling"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Luke-Larsen/402-PIVX.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Luke-Larsen/402-PIVX/issues"
+  },
+  "homepage": "https://github.com/Luke-Larsen/402-PIVX#readme",
+  "dependencies": {
+    "express": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}