@agent-shield/sdk 0.4.1 → 0.5.2

package/dist/wrapper/shield.js

@@ -0,0 +1,236 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTeeWallet = isTeeWallet;
+exports.shield = shield;
+const web3_js_1 = require("@solana/web3.js");
+const policies_1 = require("./policies");
+const inspector_1 = require("./inspector");
+const engine_1 = require("./engine");
+const errors_1 = require("./errors");
+const state_1 = require("./state");
+const registry_1 = require("./registry");
+/**
+ * Type guard to detect TEE-backed wallets at runtime.
+ */
+function isTeeWallet(wallet) {
+    return "provider" in wallet && typeof wallet.provider === "string";
+}
+/**
+ * Wrap any wallet with client-side spending controls.
+ *
+ * @example
+ * ```typescript
+ * import { shieldWallet } from '@agent-shield/sdk';
+ *
+ * const protectedWallet = shieldWallet(wallet, { maxSpend: '500 USDC/day' });
+ * const agent = new SolanaAgentKit(protectedWallet, RPC_URL, config);
+ * ```
+ *
+ * With no config, secure defaults are applied:
+ * - 1000 USDC/day, 1000 USDT/day, 10 SOL/day spending caps
+ * - Unknown programs blocked
+ * - 60 transactions/hour rate limit
+ * @internal Use shieldWallet() instead
+ */
+function shield(wallet, policies, options) {
+    let resolved = (0, policies_1.resolvePolicies)(policies);
+    const connection = options?.connection;
+    const state = new state_1.ShieldState(options?.storage);
+    const onDenied = options?.onDenied;
+    const onApproved = options?.onApproved;
+    const onPolicyUpdate = options?.onPolicyUpdate;
+    const onPause = options?.onPause;
+    const onResume = options?.onResume;
+    let paused = false;
+    const shielded = {
+        publicKey: wallet.publicKey,
+        innerWallet: wallet,
+        shieldState: state,
+        isHardened: false,
+        get resolvedPolicies() {
+            return resolved;
+        },
+        get isPaused() {
+            return paused;
+        },
+        async signTransaction(tx) {
+            if (paused) {
+                return wallet.signTransaction(tx);
+            }
+            // Resolve ALTs for VersionedTransactions when connection is available
+            let lookupTableAccounts;
+            if (connection &&
+                tx instanceof web3_js_1.VersionedTransaction &&
+                tx.message.addressTableLookups.length > 0) {
+                lookupTableAccounts = await (0, inspector_1.resolveTransactionAddressLookupTables)(tx, connection);
+            }
+            const analysis = (0, inspector_1.analyzeTransaction)(tx, wallet.publicKey, lookupTableAccounts);
+            const violations = (0, engine_1.evaluatePolicy)(analysis, resolved, state);
+            if (violations.length > 0) {
+                const error = new errors_1.ShieldDeniedError(violations);
+                onDenied?.(error);
+                throw error;
+            }
+            // Policy passed — sign with underlying wallet
+            const signed = await wallet.signTransaction(tx);
+            // Record the spend and transaction
+            (0, engine_1.recordTransaction)(analysis, state);
+            onApproved?.(null);
+            return signed;
+        },
+        async signAllTransactions(txs) {
+            if (paused) {
+                if (wallet.signAllTransactions) {
+                    return wallet.signAllTransactions(txs);
+                }
+                return Promise.all(txs.map((tx) => wallet.signTransaction(tx)));
+            }
+            // Resolve ALTs for any VersionedTransactions in the batch,
+            // caching resolved ALTs across the batch to avoid redundant RPCs.
+            const altCache = new Map();
+            const analyses = [];
+            for (const tx of txs) {
+                let lookupTableAccounts;
+                if (connection &&
+                    tx instanceof web3_js_1.VersionedTransaction &&
+                    tx.message.addressTableLookups.length > 0) {
+                    const cached = [];
+                    let hasMissing = false;
+                    for (const lookup of tx.message.addressTableLookups) {
+                        const key = lookup.accountKey.toBase58();
+                        const existing = altCache.get(key);
+                        if (existing) {
+                            cached.push(existing);
+                        }
+                        else {
+                            hasMissing = true;
+                        }
+                    }
+                    if (hasMissing) {
+                        const fetched = await (0, inspector_1.resolveTransactionAddressLookupTables)(tx, connection);
+                        for (const alt of fetched) {
+                            altCache.set(alt.key.toBase58(), alt);
+                        }
+                        // Rebuild from cache to get all ALTs in order
+                        cached.length = 0;
+                        for (const lookup of tx.message.addressTableLookups) {
+                            const alt = altCache.get(lookup.accountKey.toBase58());
+                            if (alt)
+                                cached.push(alt);
+                        }
+                    }
+                    lookupTableAccounts = cached;
+                }
+                analyses.push((0, inspector_1.analyzeTransaction)(tx, wallet.publicKey, lookupTableAccounts));
+            }
+            const cp = state.checkpoint();
+            try {
+                for (const analysis of analyses) {
+                    const violations = (0, engine_1.evaluatePolicy)(analysis, resolved, state);
+                    if (violations.length > 0) {
+                        throw new errors_1.ShieldDeniedError(violations);
+                    }
+                    // Record into state so next tx sees cumulative spend
+                    (0, engine_1.recordTransaction)(analysis, state);
+                }
+                // All passed — sign with underlying wallet
+                let signed;
+                if (wallet.signAllTransactions) {
+                    signed = await wallet.signAllTransactions(txs);
+                }
+                else {
+                    signed = await Promise.all(txs.map((tx) => wallet.signTransaction(tx)));
+                }
+                onApproved?.(null);
+                return signed;
+            }
+            catch (err) {
+                // Rollback phantom spends on ANY error (policy denial or signing failure)
+                state.rollback(cp);
+                // Fire callbacks AFTER rollback so state is consistent when handler reads it
+                if (err instanceof errors_1.ShieldDeniedError) {
+                    onDenied?.(err);
+                }
+                throw err;
+            }
+        },
+        updatePolicies(newPolicies) {
+            resolved = (0, policies_1.resolvePolicies)(newPolicies);
+            onPolicyUpdate?.(newPolicies);
+        },
+        resetState() {
+            state.reset();
+        },
+        pause() {
+            paused = true;
+            onPause?.();
+        },
+        resume() {
+            paused = false;
+            onResume?.();
+        },
+        getSpendingSummary() {
+            const tokens = resolved.spendLimits.map((limit) => {
+                const spent = state.getSpendInWindow(limit.mint, limit.windowMs ?? 86400000);
+                const remaining = limit.amount > spent ? limit.amount - spent : BigInt(0);
+                const tokenInfo = (0, registry_1.getTokenInfo)(limit.mint);
+                return {
+                    mint: limit.mint,
+                    symbol: tokenInfo?.symbol,
+                    spent,
+                    limit: limit.amount,
+                    remaining,
+                    windowMs: limit.windowMs ?? 86400000,
+                };
+            });
+            const txCount = state.getTransactionCountInWindow(resolved.rateLimit.windowMs);
+            const rateLimit = {
+                count: txCount,
+                limit: resolved.rateLimit.maxTransactions,
+                remaining: Math.max(0, resolved.rateLimit.maxTransactions - txCount),
+                windowMs: resolved.rateLimit.windowMs,
+            };
+            return { tokens, rateLimit, isPaused: paused };
+        },
+    };
+    // Wire up x402 fetch support (lazy-loaded)
+    shielded.fetch = async (url, init) => {
+        const { shieldedFetch } = await Promise.resolve().then(() => __importStar(require("./x402")));
+        return shieldedFetch(shielded, url, { ...init, connection });
+    };
+    return shielded;
+}
+//# sourceMappingURL=shield.js.map

package/dist/wrapper/shield.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shield.js","sourceRoot":"","sources":["../../src/wrapper/shield.ts"],"names":[],"mappings":"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"}

package/dist/wrapper/state.d.ts

@@ -0,0 +1,3 @@
+export { ShieldState } from "@agent-shield/core";
+export type { ShieldStorage, SpendEntry, TxEntry } from "@agent-shield/core";
+//# sourceMappingURL=state.d.ts.map

package/dist/wrapper/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/wrapper/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/wrapper/state.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShieldState = void 0;
+var core_1 = require("@agent-shield/core");
+Object.defineProperty(exports, "ShieldState", { enumerable: true, get: function () { return core_1.ShieldState; } });
+//# sourceMappingURL=state.js.map

package/dist/wrapper/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/wrapper/state.ts"],"names":[],"mappings":";;;AAAA,2CAAiD;AAAxC,mGAAA,WAAW,OAAA"}

package/dist/wrapper/x402.d.ts

@@ -0,0 +1,153 @@
+/**
+ * x402 — HTTP 402 Payment Required support for shielded wallets.
+ *
+ * Implements the x402 V2 protocol (coinbase/x402) for machine-to-machine
+ * crypto payments. The client signs a payment, retries with PAYMENT-SIGNATURE
+ * header, and the API server settles via a facilitator.
+ *
+ * @see https://x402.org
+ */
+import { PublicKey, TransactionInstruction, Connection } from "@solana/web3.js";
+import type { ShieldedWallet } from "./shield";
+import type { ResolvedPolicies } from "./policies";
+import type { ShieldState } from "./state";
+/**
+ * x402 V2 PaymentRequired — decoded from PAYMENT-REQUIRED header.
+ * Mirrors @x402/core/types PaymentRequired.
+ */
+export interface PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource: ResourceInfo;
+    accepts: PaymentRequirements[];
+    extensions?: Record<string, unknown>;
+}
+/** A single payment option offered by the server. */
+export interface PaymentRequirements {
+    scheme: string;
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+}
+/** Resource metadata embedded in PaymentRequired. */
+export interface ResourceInfo {
+    url: string;
+    description: string;
+    mimeType: string;
+}
+/** The signed payment payload sent back to the server. */
+export interface PaymentPayload {
+    x402Version: number;
+    resource: ResourceInfo;
+    accepted: PaymentRequirements;
+    payload: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+}
+/** Settlement response decoded from PAYMENT-RESPONSE header. */
+export interface SettleResponse {
+    success: boolean;
+    transaction?: string;
+    network?: string;
+    payer?: string;
+    errorReason?: string;
+}
+/** Options for shieldedFetch(). */
+export interface ShieldedFetchOptions extends RequestInit {
+    /** Solana RPC connection for blockhash + ATA resolution. */
+    connection?: Connection;
+    /** If true, evaluate policies but don't pay. */
+    dryRun?: boolean;
+    /** Max payment in token base units — reject if server asks more. */
+    maxPayment?: string;
+}
+/** Extended response with x402 payment metadata. */
+export interface ShieldedFetchResponse extends Response {
+    x402?: X402PaymentResult;
+}
+/** Payment metadata attached to a ShieldedFetchResponse. */
+export interface X402PaymentResult {
+    paid: boolean;
+    amountPaid: string;
+    asset: string;
+    payTo: string;
+    settlement?: SettleResponse;
+}
+export declare class X402ParseError extends Error {
+    constructor(message: string);
+}
+export declare class X402PaymentError extends Error {
+    constructor(message: string);
+}
+export declare class X402UnsupportedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Decode a base64-encoded PAYMENT-REQUIRED header value.
+ */
+export declare function decodePaymentRequiredHeader(header: string): PaymentRequired;
+/**
+ * Encode a PaymentPayload as a base64 string for PAYMENT-SIGNATURE header.
+ */
+export declare function encodePaymentSignatureHeader(payload: PaymentPayload): string;
+/**
+ * Decode a base64-encoded PAYMENT-RESPONSE header value.
+ */
+export declare function decodePaymentResponseHeader(header: string): SettleResponse;
+/**
+ * Select a Solana-compatible payment option from the accepts array.
+ *
+ * @param paymentRequired The decoded PAYMENT-REQUIRED payload
+ * @param allowedTokens   Optional set of token mint addresses to accept
+ * @returns The first matching PaymentRequirements, or throws
+ */
+export declare function selectPaymentOption(paymentRequired: PaymentRequired, allowedTokens?: Set<string>): PaymentRequirements;
+/**
+ * Evaluate an x402 payment against shield policies without recording spend.
+ *
+ * Creates a synthetic TransactionAnalysis from the payment requirements
+ * and runs it through the existing policy engine.
+ */
+export declare function evaluateX402Payment(selected: PaymentRequirements, policies: ResolvedPolicies, state: ShieldState): import("./errors").PolicyViolation[];
+/**
+ * Build an SPL TransferChecked instruction for an x402 payment.
+ */
+export declare function buildX402TransferInstruction(params: {
+    from: PublicKey;
+    payTo: PublicKey;
+    asset: PublicKey;
+    amount: bigint;
+    decimals: number;
+}): TransactionInstruction;
+/**
+ * Encode a signed transaction into a full x402 V2 PaymentPayload.
+ */
+export declare function encodeX402Payload(signedTx: Uint8Array, resource: ResourceInfo, accepted: PaymentRequirements): string;
+/**
+ * Fetch a URL with automatic x402 payment support.
+ *
+ * Flow:
+ * 1. Make the initial HTTP request
+ * 2. If 402, parse PAYMENT-REQUIRED header
+ * 3. Select a Solana payment option
+ * 4. Evaluate against shield policies (fast deny)
+ * 5. Build, sign, and encode payment transaction
+ * 6. Retry with PAYMENT-SIGNATURE header
+ * 7. Return response with x402 metadata
+ *
+ * The client NEVER settles — the API server calls the facilitator.
+ */
+export declare function shieldedFetch(wallet: ShieldedWallet, url: string | URL, options?: ShieldedFetchOptions): Promise<ShieldedFetchResponse>;
+/**
+ * Create a wallet-bound fetch function with automatic x402 payment support.
+ *
+ * @example
+ * ```typescript
+ * const fetch = createShieldedFetchForWallet(shieldedWallet, { connection });
+ * const res = await fetch('https://api.example.com/paid-endpoint');
+ * ```
+ */
+export declare function createShieldedFetchForWallet(wallet: ShieldedWallet, defaults?: Omit<ShieldedFetchOptions, "body" | "method">): (url: string | URL, init?: RequestInit) => Promise<ShieldedFetchResponse>;
+//# sourceMappingURL=x402.d.ts.map

package/dist/wrapper/x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/wrapper/x402.ts"],"names":[],"mappings":"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"}