@lucid-agents/opencode-x402-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daydreams AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# opencode-x402-auth
+
+OpenCode auth plugin for the x402 payment protocol. Sign ERC-2612 permits with your wallet to pay for LLM inference.
+
+## Installation
+
+```bash
+# npm
+npm install opencode-x402-auth
+
+# bun
+bun add opencode-x402-auth
+```
+
+## Quick Start
+
+### 1. Configure OpenCode
+
+Add the plugin to your `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-x402-auth"],
+  "provider": {
+    "x402": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "x402 Router",
+      "options": {
+        "baseURL": "http://localhost:8080/v1"
+      },
+      "models": {
+        "openai:gpt-4": { "name": "GPT-4" },
+        "anthropic:claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" }
+      }
+    }
+  },
+  "model": "x402/anthropic:claude-sonnet-4-20250514"
+}
+```
+
+### 2. Connect Your Wallet
+
+In OpenCode, run `/connect` and select "x402":
+
+1. Choose **"Connect Wallet (Private Key)"**
+2. Enter your wallet's private key (0x-prefixed)
+3. The plugin will sign permits automatically
+
+### 3. Start Coding
+
+That's it! The plugin automatically:
+- Fetches router configuration
+- Signs ERC-2612 permits for each request
+- Injects the `PAYMENT-SIGNATURE` header
+
+## How It Works
+
+```
+OpenCode → Plugin (signs permit) → x402 Router → LLM Provider
+                ↓
+         Your Wallet (ERC-2612 permit)
+```
+
+1. **You make a request** - OpenCode sends a chat message
+2. **Plugin intercepts** - Before the request reaches the router
+3. **Permit is signed** - Using your wallet's private key (EIP-712)
+4. **Header is injected** - `PAYMENT-SIGNATURE: <base64-encoded-permit>`
+5. **Router processes** - Validates permit, forwards to provider
+6. **Response streams** - Back through OpenCode to you
+7. **Payment tracked** - Router tracks cost asynchronously
+
+## Configuration Options
+
+### Via `/connect` in OpenCode
+
+| Option | Description |
+|--------|-------------|
+| **Connect Wallet** | Enter your private key (stored locally) |
+| **Configure Router URL** | Set custom router endpoint |
+| **Set Permit Cap** | Maximum USDC per permit session |
+
+### Environment Variables
+
+```bash
+# Optional: Override router URL
+export X402_ROUTER_URL="https://router.example.com"
+
+# Optional: Override permit cap (in USDC)
+export X402_PERMIT_CAP="50"
+```
+
+## Supported Networks
+
+| Network | CAIP-2 ID | USDC Contract |
+|---------|-----------|---------------|
+| Base Mainnet | `eip155:8453` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+| Base Sepolia | `eip155:84532` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
+| Ethereum Mainnet | `eip155:1` | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
+
+## Security
+
+**Important security considerations:**
+
+1. **Use a dedicated wallet** - Create a wallet specifically for AI spending
+2. **Fund minimally** - Only keep what you're willing to spend
+3. **Set low caps** - Start with $1-10 permit caps
+4. **Private key storage** - Stored locally in OpenCode's auth store (`~/.local/share/opencode/auth.json`)
+
+**Never use your main wallet's private key.** Create a burner wallet and fund it with small amounts.
+
+## API Reference
+
+### Plugin Export
+
+```typescript
+import { X402AuthPlugin } from "opencode-x402-auth";
+
+// The plugin is auto-loaded by OpenCode
+// Manual usage:
+const plugin = await X402AuthPlugin({ client });
+```
+
+### Types
+
+```typescript
+interface X402Auth {
+  type: "wallet" | "manual";
+  privateKey?: string;
+  routerUrl?: string;
+  permitCap?: string;  // In token units (6 decimals for USDC)
+  network?: string;    // CAIP-2 format
+}
+```
+
+## Troubleshooting
+
+### "402 Payment Required"
+
+The permit wasn't accepted. Check:
+1. Wallet has sufficient USDC balance
+2. Router is running and accessible
+3. Permit cap is high enough for the request
+
+### "Failed to fetch router config"
+
+Router endpoint unreachable. Verify:
+1. Router URL is correct
+2. Router is running: `curl http://localhost:8080/health`
+
+### "Invalid private key format"
+
+Private key must be:
+- 66 characters (including `0x` prefix)
+- Valid hex string
+- Example: `0x1234567890abcdef...` (64 hex chars after 0x)
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/daydreamsai/router.git
+cd router/packages/opencode-x402-auth
+
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Type check
+bun tsc --noEmit
+```
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Permit caching utilities for x402 auth plugin
+ */
+export interface CachedPermit {
+    paymentSig: string;
+    deadline: number;
+    maxValue: string;
+    nonce: string;
+    network: string;
+    asset: string;
+    payTo: string;
+}
+export interface ErrorResponse {
+    code?: string;
+    error?: string;
+    message?: string;
+}
+export declare class PermitCache {
+    private cache;
+    get(network: string, asset: string, payTo: string): CachedPermit | null;
+    set(permit: CachedPermit): void;
+    invalidate(network: string, asset: string, payTo: string): void;
+    clear(): void;
+    private buildKey;
+    private isNearDeadline;
+}
+export declare function isCapExhausted(error: ErrorResponse): boolean;
+export declare function isSessionClosed(error: ErrorResponse): boolean;
+export declare function shouldInvalidatePermit(error: ErrorResponse): boolean;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAmC;IAEhD,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAevE,GAAG,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAK/B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAK/D,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,cAAc;CAIvB;AAUD,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAK5D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAK7D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAEpE"}

package/dist/cache.js

@@ -0,0 +1,66 @@
+/**
+ * Permit caching utilities for x402 auth plugin
+ */
+// ============================================================================
+// Permit Cache
+// ============================================================================
+const PRE_INVALIDATE_WINDOW_SECONDS = 60;
+export class PermitCache {
+    cache = new Map();
+    get(network, asset, payTo) {
+        const key = this.buildKey(network, asset, payTo);
+        const permit = this.cache.get(key);
+        if (!permit) {
+            return null;
+        }
+        if (this.isNearDeadline(permit.deadline)) {
+            this.cache.delete(key);
+            return null;
+        }
+        return permit;
+    }
+    set(permit) {
+        const key = this.buildKey(permit.network, permit.asset, permit.payTo);
+        this.cache.set(key, permit);
+    }
+    invalidate(network, asset, payTo) {
+        const key = this.buildKey(network, asset, payTo);
+        this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    buildKey(network, asset, payTo) {
+        return `${network.toLowerCase()}:${asset.toLowerCase()}:${payTo.toLowerCase()}`;
+    }
+    isNearDeadline(deadline) {
+        const now = Math.floor(Date.now() / 1000);
+        return deadline - now <= PRE_INVALIDATE_WINDOW_SECONDS;
+    }
+}
+// ============================================================================
+// Error helpers
+// ============================================================================
+function normalizeErrorText(error, message) {
+    return `${error ?? ""} ${message ?? ""}`.toLowerCase();
+}
+export function isCapExhausted(error) {
+    if (!error)
+        return false;
+    if (error.code === "cap_exhausted")
+        return true;
+    const text = normalizeErrorText(error.error, error.message);
+    return text.includes("cap exhausted");
+}
+export function isSessionClosed(error) {
+    if (!error)
+        return false;
+    if (error.code === "session_closed")
+        return true;
+    const text = normalizeErrorText(error.error, error.message);
+    return text.includes("session closed");
+}
+export function shouldInvalidatePermit(error) {
+    return isCapExhausted(error) || isSessionClosed(error);
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsBH,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E,MAAM,6BAA6B,GAAG,EAAE,CAAC;AAEzC,MAAM,OAAO,WAAW;IACd,KAAK,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEhD,GAAG,CAAC,OAAe,EAAE,KAAa,EAAE,KAAa;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,GAAG,CAAC,MAAoB;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,UAAU,CAAC,OAAe,EAAE,KAAa,EAAE,KAAa;QACtD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAEO,QAAQ,CAAC,OAAe,EAAE,KAAa,EAAE,KAAa;QAC5D,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;IAClF,CAAC;IAEO,cAAc,CAAC,QAAgB;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,OAAO,QAAQ,GAAG,GAAG,IAAI,6BAA6B,CAAC;IACzD,CAAC;CACF;AAED,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E,SAAS,kBAAkB,CAAC,KAAc,EAAE,OAAgB;IAC1D,OAAO,GAAG,KAAK,IAAI,EAAE,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC,WAAW,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAoB;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,IAAI,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAoB;IAClD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,IAAI,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAoB;IACzD,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * OpenCode x402 Auth Plugin
+ *
+ * Enables OpenCode to authenticate with the x402 Inference Router using
+ * wallet-signed ERC-2612 permits for crypto-native payment.
+ *
+ * @example
+ * ```json
+ * // opencode.json
+ * {
+ *   "plugins": ["opencode-x402-auth"],
+ *   "provider": {
+ *     "x402": {
+ *       "npm": "@ai-sdk/openai-compatible",
+ *       "options": { "baseURL": "http://localhost:8080/v1" }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+/** Authentication state stored by OpenCode */
+export interface X402Auth {
+    type: "wallet" | "manual";
+    privateKey?: string;
+    routerUrl?: string;
+    permitCap?: string;
+    network?: string;
+}
+/** OpenCode plugin client interface */
+export interface PluginClient {
+    auth: {
+        get(params: {
+            path: {
+                id: string;
+            };
+        }): Promise<X402Auth | null>;
+        set(params: {
+            path: {
+                id: string;
+            };
+            body: X402Auth;
+        }): Promise<void>;
+    };
+}
+/** OpenCode auth method result */
+export type AuthResult = {
+    type: "success";
+    key?: string;
+    refresh?: string;
+    access?: string;
+    expires?: number;
+} | {
+    type: "failed";
+};
+/**
+ * Clear the router config cache (for testing)
+ */
+export declare function clearRouterConfigCache(): void;
+/**
+ * OpenCode x402 Auth Plugin
+ *
+ * Provides wallet-based authentication for x402 payment protocol.
+ * Signs ERC-2612 permits to authorize spending on each request.
+ */
+export declare function X402AuthPlugin({ client }: {
+    client: PluginClient;
+}): Promise<{
+    auth: {
+        provider: string;
+        /**
+         * Loader function - called to configure authentication for requests
+         */
+        loader: (getAuth: () => Promise<X402Auth | null>, provider: {
+            options?: {
+                baseURL?: string;
+            };
+            models?: Record<string, unknown>;
+        }) => Promise<{
+            fetch?: undefined;
+        } | {
+            fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+        }>;
+        /**
+         * Authentication methods available in /connect
+         */
+        methods: {
+            label: string;
+            type: "manual";
+            authorize: () => Promise<{
+                instructions: string;
+                method: "code" | "key";
+                callback: (input: string) => Promise<AuthResult>;
+            }>;
+        }[];
+    };
+}>;
+export default X402AuthPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAiBH,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqCD,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QACJ,GAAG,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;QAChE,GAAG,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAC;YAAC,IAAI,EAAE,QAAQ,CAAA;SAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACtE,CAAC;CACH;AAED,kCAAkC;AAClC,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAwUvB;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAoBD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE;;;QAKnE;;WAEG;0BAEQ,MAAM,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,YAC7B;YAAE,OAAO,CAAC,EAAE;gBAAE,OAAO,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE;;;2BAyDvD,MAAM,GAAG,GAAG,GAAG,OAAO,SAAS,WAAW;;QAyCnE;;WAEG;;;;6BAqDsB,OAAO,CAAC;gBAC3B,YAAY,EAAE,MAAM,CAAC;gBACrB,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;gBACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;aAClD,CAAC;;;GAuFX;AAGD,eAAe,cAAc,CAAC"}