@magnetoagents/cli 0.1.0 → 0.2.0

package/README.md

@@ -55,6 +55,8 @@ Resolution order:
 |-----|---------|
 | `MAGNETO_API_BASE` or `MAGNETO_BASE_URL` | `https://magnetoapp.io` (client appends `/api/v1`) |
 | `MAGNETO_TIMEOUT_MS` | `30000` (JSON requests only; streams and signed-URL downloads are exempt) |
+| `MAGNETO_WALLET_PRIVATE_KEY` | (unset) 32-byte hex key `0x`+64. Env only — never a flag, never `credentials.json`. |
+| `MAGNETO_X402_NETWORK` | `eip155:84532,eip155:8453` (comma-separated allowlist) |
 
 Local / worktree:
 
@@ -63,10 +65,12 @@ export MAGNETO_API_BASE=http://localhost:${FRONTEND_PORT:-3000}
 # worktree ports often come from repo `.ports.env`
 ```
 
-The client retries **once** on HTTP 429, honoring `Retry-After` (delta-seconds or HTTP-date, capped at 60s).
+The client retries **once** on HTTP 429, honoring `Retry-After` (delta-seconds or HTTP-date, capped at 60s). A payable HTTP 402 with `PAYMENT-REQUIRED` is a **sibling** one-shot retry (see [Payments (x402)](#payments-x402)).
 
 ## Commands
 
+Global option (any command): `--max-payment <usd>` — refuse x402 charges strictly above this USD amount (default `0.10`). Equal-to-cap is paid.
+
 ```bash
 magneto login <key>
 
@@ -124,7 +128,7 @@ Mutations (`create`, `start`, `stop`, `restart`, `resize`, `delete`, `skills ins
 | Code | Meaning |
 |------|---------|
 | `0` | Success |
-| `1` | API or client error (including 402 / 404 / 409 / 422 / 429-after-retry / 5xx / timeout / missing key) |
+| `1` | API or client error (including 402 / cap-refuse / no-wallet challenge / 404 / 409 / 422 / 429-after-retry / 5xx / timeout / missing key) |
 | `2` | HTTP 401 or 403 |
 | `N` | `magneto bash` only: remote `exit_code` on HTTP 200 (`N & 255`) |
 
@@ -136,6 +140,22 @@ error: <detail> (HTTP <status>) · request-id: <id> · Retry-After: <n>
 
 `request-id` / `Retry-After` segments are omitted when the server did not send them.
 
+## Payments (x402)
+
+Uncovered `sk_live_*` keys hitting a priced `/api/v1` route receive HTTP 402 + a `PAYMENT-REQUIRED` header (x402 v2). The CLI is an optional **payer**:
+
+| Wallet env | What happens |
+|------------|----------------|
+| `MAGNETO_WALLET_PRIVATE_KEY` set | Decode the challenge, pick the first `accepted` entry on the network allowlist, refuse if the amount **exceeds** `--max-payment` (default `$0.10`; equal is paid), EIP-3009-sign (`exact`/`quote`) or Permit2-sign (`upto`), retry **once** with `PAYMENT-SIGNATURE`. On success, stderr prints `paid $X · tx <hash>`. Stdout stays the command's JSON/table. |
+| unset | Print a challenge summary (price, network, asset) plus `set MAGNETO_WALLET_PRIVATE_KEY to pay, or subscribe: https://magnetoapp.io/pricing`, exit 1. Nothing is signed. |
+| Bare 402 (no `PAYMENT-REQUIRED`) | Today's `error: <detail> (HTTP 402)` line, exit 1. Desktop subscription / key budget / PAYG ceiling — not a machine challenge. |
+
+`--max-payment 0` refuses every priced challenge. A second 402 after a signed retry is terminal (no loop).
+
+**Never pass the wallet key as a flag. Never put it in `~/.magneto/credentials.json`.** Shells log argv; the credentials file is long-lived. Use a testnet key for CI and a tiny hot wallet only.
+
+`MAGNETO_X402_NETWORK` overrides the allowlist (default Base Sepolia `eip155:84532` and Base mainnet `eip155:8453`). Pin Sepolia with `MAGNETO_X402_NETWORK=eip155:84532`.
+
 ## Scopes
 
 Keys are minted in the dashboard. Default scopes do **not** include `exec`.

package/dist/cli.js

@@ -3,8 +3,9 @@ import { Command } from 'commander';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createClient, MagnetoApiError, normalizeApiBase } from './client.js';
+import { createClient, MagnetoApiError, PaymentCapError, normalizeApiBase, } from './client.js';
 import { resolveApiKey, writeCredentials } from './credentials.js';
+import { DEFAULT_MAX_PAYMENT_USD, PRICING_URL, allowedNetworksFromEnv, formatShortAsset, formatUsdDisplay, readWalletPrivateKey, requirementAmountAtomic, } from './x402.js';
 import { ACCOUNT_SPEC, COMPUTERS_SPEC, FILES_SPEC, InvalidOutputFormatError, parseOutputFlag, RUN_GET_SPEC, RUNS_SPEC, SKILLS_SPEC, TEMPLATES_SPEC, UPTIME_SPEC, formatOutput, resolveOutputFormat, } from './format.js';
 import { openUrl as defaultOpenUrl } from './open-url.js';
 import { readPackageVersion } from './package-version.js';
@@ -33,7 +34,26 @@ export function handleError(err, io) {
         throw err;
     }
     const { stderr, exit } = resolveIo(io);
+    if (err instanceof PaymentCapError) {
+        stderr.write(`error: ${err.message}\n`);
+        return exit(1);
+    }
     if (err instanceof MagnetoApiError) {
+        if (err.status === 402 && err.paymentRequirements) {
+            const first = err.paymentRequirements.accepted?.[0];
+            const atomic = first ? requirementAmountAtomic(first) : undefined;
+            const price = atomic ? formatUsdDisplay(atomic) : '$0.00';
+            const bits = [`error: Payment required: ${price} (HTTP 402)`];
+            if (err.requestId)
+                bits.push(`request-id: ${err.requestId}`);
+            stderr.write(`${bits.join(' · ')}\n`);
+            if (first?.network)
+                stderr.write(`network: ${first.network}\n`);
+            if (first?.asset)
+                stderr.write(`asset: ${formatShortAsset(first.asset)}\n`);
+            stderr.write(`set MAGNETO_WALLET_PRIVATE_KEY to pay, or subscribe: ${PRICING_URL}\n`);
+            return exit(1);
+        }
         const bits = [`error: ${err.detail} (HTTP ${err.status})`];
         if (err.requestId)
             bits.push(`request-id: ${err.requestId}`);
@@ -112,6 +132,14 @@ function formatUsageBlob(value) {
 export function buildProgram(io) {
     const resolved = resolveIo(io);
     const { stdout, stderr, exit, env, openUrl } = resolved;
+    function parseMaxPayment(raw) {
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n < 0) {
+            stderr.write(`error: invalid --max-payment ${raw}\n`);
+            exit(1);
+        }
+        return n;
+    }
     function requireClient() {
         const apiKey = resolveApiKey(env);
         if (!apiKey) {
@@ -120,10 +148,22 @@ export function buildProgram(io) {
         }
         const timeoutRaw = env.MAGNETO_TIMEOUT_MS;
         const parsedTimeout = timeoutRaw != null ? Number(timeoutRaw) : NaN;
+        const rawMax = program.opts().maxPayment;
+        const maxPaymentUsd = rawMax == null || rawMax === '' ? DEFAULT_MAX_PAYMENT_USD : Number(rawMax);
+        if (!Number.isFinite(maxPaymentUsd) || maxPaymentUsd < 0) {
+            stderr.write(`error: invalid --max-payment ${String(rawMax)}\n`);
+            return exit(1);
+        }
         return createClient({
             apiKey,
             baseUrl: env.MAGNETO_API_BASE ?? env.MAGNETO_BASE_URL,
             fetchImpl: resolved.fetchImpl,
+            walletPrivateKey: readWalletPrivateKey(env) ?? undefined,
+            maxPaymentUsd,
+            allowedNetworks: allowedNetworksFromEnv(env),
+            onPaid: ({ usd, tx }) => {
+                stderr.write(`paid $${usd} · tx ${tx}\n`);
+            },
             ...(Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? { timeoutMs: parsedTimeout } : {}),
         });
     }
@@ -153,7 +193,8 @@ export function buildProgram(io) {
     program
         .name('magneto')
         .description('Magneto CLI — public /api/v1 with sk_live_* keys')
-        .version(readPackageVersion());
+        .version(readPackageVersion())
+        .option('--max-payment <usd>', 'Refuse x402 charges above this USD amount (default 0.10)', parseMaxPayment, DEFAULT_MAX_PAYMENT_USD);
     program.exitOverride((err) => {
         exit(typeof err.exitCode === 'number' ? err.exitCode : 1);
     });
@@ -658,7 +699,10 @@ function isEntrypoint() {
     if (!invoked)
         return false;
     try {
-        return path.resolve(invoked) === fileURLToPath(import.meta.url);
+        // npm installs bins as SYMLINKS (node_modules/.bin/magneto → dist/cli.js);
+        // path.resolve() does not follow them, so realpath both sides or the CLI
+        // silently no-ops on every installed invocation (0.1.0 regression).
+        return fs.realpathSync(invoked) === fs.realpathSync(fileURLToPath(import.meta.url));
     }
     catch {
         return false;

package/dist/client.d.ts

@@ -1,3 +1,6 @@
+import { type PaymentRequiredPayload } from './x402.js';
+export type { PaymentRequiredPayload, PaymentRequirement } from './x402.js';
+export { PaymentCapError } from './x402.js';
 export type MagnetoClientOptions = {
     apiKey: string;
     /** Origin or full API base. Accepts `https://magnetoapp.io` or `.../api/v1`. */
@@ -7,13 +10,26 @@ export type MagnetoClientOptions = {
     timeoutMs?: number;
     /** Injected so tests can assert 429 sleep without waiting. */
     sleepImpl?: (ms: number) => Promise<void>;
+    /** From `MAGNETO_WALLET_PRIVATE_KEY` only — never a flag or credentials.json. */
+    walletPrivateKey?: string;
+    /** From `--max-payment`. Default `$0.10`. */
+    maxPaymentUsd?: number;
+    /** From `MAGNETO_X402_NETWORK` or the default Base Sepolia + Base pair. */
+    allowedNetworks?: string[];
+    /** Fired after a successful paid retry when `PAYMENT-RESPONSE` decodes. */
+    onPaid?: (info: {
+        usd: string;
+        tx: string;
+        network: string;
+    }) => void;
 };
 export declare class MagnetoApiError extends Error {
     status: number;
     detail: string;
     retryAfter?: string;
     requestId?: string;
-    constructor(status: number, detail: string, retryAfter?: string, requestId?: string);
+    paymentRequirements?: PaymentRequiredPayload;
+    constructor(status: number, detail: string, retryAfter?: string, requestId?: string, paymentRequirements?: PaymentRequiredPayload);
 }
 /**
  * Parse `Retry-After` as delta-seconds or HTTP-date.

package/dist/client.js

@@ -1,18 +1,22 @@
 // Thin fetch client for Magneto public `/api/v1` (#110 / #440).
 import fs from 'node:fs';
 import path from 'node:path';
+import { DEFAULT_ALLOWED_NETWORKS, DEFAULT_MAX_PAYMENT_USD, PaymentCapError, atomicUsdcToUsd, exceedsMaxPayment, pickRequirement, requirementAmountAtomic, signPayment, toBase64Url, tryDecodePaymentRequired, tryDecodePaymentResponse, } from './x402.js';
+export { PaymentCapError } from './x402.js';
 export class MagnetoApiError extends Error {
     status;
     detail;
     retryAfter;
     requestId;
-    constructor(status, detail, retryAfter, requestId) {
+    paymentRequirements;
+    constructor(status, detail, retryAfter, requestId, paymentRequirements) {
         super(detail);
         this.name = 'MagnetoApiError';
         this.status = status;
         this.detail = detail;
         this.retryAfter = retryAfter;
         this.requestId = requestId;
+        this.paymentRequirements = paymentRequirements;
     }
 }
 const RETRY_AFTER_DEFAULT_MS = 1000;
@@ -82,11 +86,14 @@ export function createClient(opts) {
         catch {
             // ignore non-JSON error bodies
         }
-        return new MagnetoApiError(res.status, detail, res.headers.get('Retry-After') ?? undefined, res.headers.get('x-request-id') ?? undefined);
+        return new MagnetoApiError(res.status, detail, res.headers.get('Retry-After') ?? undefined, res.headers.get('x-request-id') ?? undefined, tryDecodePaymentRequired(res.headers.get('PAYMENT-REQUIRED')));
     }
     async function send(sendOpts) {
         const url = resolveUrl(sendOpts.path);
         let attempt = 0;
+        let paymentAttempted = false;
+        let paymentSignature;
+        let signedRequirement;
         for (;;) {
             const headers = {
                 Accept: 'application/json',
@@ -95,6 +102,9 @@ export function createClient(opts) {
             if (sendOpts.auth !== false) {
                 headers.Authorization = `Bearer ${opts.apiKey}`;
             }
+            if (paymentSignature) {
+                headers['PAYMENT-SIGNATURE'] = paymentSignature;
+            }
             let payload;
             if (sendOpts.body instanceof FormData) {
                 payload = sendOpts.body;
@@ -120,6 +130,39 @@ export function createClient(opts) {
                 attempt += 1;
                 continue;
             }
+            if (res.status === 402 && !paymentAttempted && opts.walletPrivateKey) {
+                const header = res.headers.get('PAYMENT-REQUIRED');
+                if (header) {
+                    const decoded = tryDecodePaymentRequired(header);
+                    const picked = decoded
+                        ? pickRequirement(decoded.accepted, opts.allowedNetworks ?? DEFAULT_ALLOWED_NETWORKS)
+                        : undefined;
+                    if (picked) {
+                        const maxUsd = opts.maxPaymentUsd ?? DEFAULT_MAX_PAYMENT_USD;
+                        const atomic = requirementAmountAtomic(picked);
+                        if (exceedsMaxPayment(atomic, maxUsd)) {
+                            throw new PaymentCapError(atomic ? atomicUsdcToUsd(atomic) : '0.00', maxUsd);
+                        }
+                        paymentSignature = toBase64Url(await signPayment(picked, opts.walletPrivateKey));
+                        signedRequirement = picked;
+                        paymentAttempted = true;
+                        await res.arrayBuffer().catch(() => undefined);
+                        continue;
+                    }
+                }
+            }
+            if (res.ok && paymentAttempted && opts.onPaid) {
+                const paid = tryDecodePaymentResponse(res.headers.get('PAYMENT-RESPONSE'));
+                if (paid) {
+                    const atomic = paid.amount ??
+                        (signedRequirement ? requirementAmountAtomic(signedRequirement) : undefined);
+                    opts.onPaid({
+                        usd: atomic ? atomicUsdcToUsd(atomic) : '0.00',
+                        tx: paid.transaction,
+                        network: paid.network,
+                    });
+                }
+            }
             return res;
         }
     }

package/dist/x402.d.ts

@@ -0,0 +1,104 @@
+export declare const DEFAULT_ALLOWED_NETWORKS: readonly ["eip155:84532", "eip155:8453"];
+export declare const DEFAULT_MAX_PAYMENT_USD = 0.1;
+export declare const PRICING_URL = "https://magnetoapp.io/pricing";
+export type PaymentRequirement = {
+    scheme?: string;
+    network?: string;
+    asset?: string;
+    amount?: string;
+    maxAmountRequired?: string;
+    payTo?: string;
+    maxTimeoutSeconds?: number;
+    extra?: {
+        name?: string;
+        version?: string;
+        facilitatorAddress?: string;
+        spenderAddress?: string;
+    };
+    resource?: unknown;
+};
+export type PaymentRequiredPayload = {
+    x402Version: 2;
+    accepted: PaymentRequirement[];
+    error?: string;
+};
+export type PaymentResponsePayload = {
+    x402Version: 2;
+    success: boolean;
+    transaction: string;
+    network: string;
+    payer?: string;
+    amount?: string;
+};
+export type Eip3009Authorization = {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+};
+export type Permit2Authorization = {
+    permitted: {
+        token: string;
+        amount: string;
+    };
+    from: string;
+    spender: string;
+    nonce: string;
+    deadline: string;
+    witness: {
+        to: string;
+        facilitator: string;
+        validAfter: string;
+    };
+};
+export type SignedPaymentEnvelope = {
+    x402Version: 2;
+    accepted: PaymentRequirement;
+    payload: {
+        signature: string;
+        authorization: Eip3009Authorization;
+    } | {
+        signature: string;
+        permit2Authorization: Permit2Authorization;
+    };
+};
+export declare class PaymentCapError extends Error {
+    readonly amountUsd: string;
+    readonly maxPaymentUsd: string;
+    constructor(amountUsd: string, maxPaymentUsd: number | string);
+}
+export declare function toBase64Url(json: unknown): string;
+export declare function fromBase64Url(header: string): unknown;
+export declare function decodePaymentRequired(header: string): PaymentRequiredPayload;
+export declare function tryDecodePaymentRequired(header: string | null | undefined): PaymentRequiredPayload | undefined;
+export declare function decodePaymentResponse(header: string): PaymentResponsePayload;
+export declare function tryDecodePaymentResponse(header: string | null | undefined): PaymentResponsePayload | undefined;
+export declare function pickRequirement(accepted: PaymentRequirement[] | undefined, allowedNetworks: readonly string[]): PaymentRequirement | undefined;
+/**
+ * USD → USDC atomic units (6 decimals). `$0.01 → "10000"`.
+ * Rounds to the nearest cent first so we never keep a float micros value.
+ */
+export declare function usdToAtomicUsdc(usd: number): string;
+/**
+ * USDC atomic units → a decimal USD string without float math.
+ * `"10000"` → `"0.01"`.
+ */
+export declare function atomicUsdcToUsd(atomic: string): string;
+export declare function formatUsdDisplay(atomic: string): string;
+export declare function formatMaxPaymentUsd(usd: number): string;
+/**
+ * `true` iff the challenge USD is strictly greater than the cap.
+ * Compare in atomic USDC units so `$0.005` is a real cap, not rounded to a cent.
+ */
+export declare function exceedsMaxPayment(amountAtomic: string | undefined, maxPaymentUsd: number): boolean;
+export declare function requirementAmountAtomic(requirement: PaymentRequirement): string | undefined;
+export declare function allowedNetworksFromEnv(env?: NodeJS.ProcessEnv): string[];
+export declare function readWalletPrivateKey(env?: NodeJS.ProcessEnv): string | null;
+export declare function formatShortAsset(asset: string): string;
+export type SignPaymentOpts = {
+    nowSeconds?: number;
+    nonceBytes?: Uint8Array;
+};
+export declare function signPayment(requirement: PaymentRequirement, privateKey: string, opts?: SignPaymentOpts): Promise<SignedPaymentEnvelope>;

package/dist/x402.js

@@ -0,0 +1,330 @@
+// x402 v2 payer: decode PAYMENT-* headers, cap-check, EIP-3009 / Permit2 sign.
+// Wallet material stays in process env — never interpolate keys into messages.
+import { randomBytes } from 'node:crypto';
+import { privateKeyToAccount } from 'viem/accounts';
+const USDC_DECIMALS = 6;
+const ATOMIC_PER_USD = 10 ** USDC_DECIMALS; // 1_000_000
+const ATOMIC_PER_CENT = ATOMIC_PER_USD / 100; // 10_000
+const PERMIT2 = '0x000000000022D473030F116dDEE9F6B43aC78BA3';
+const UPTO_PERMIT2_PROXY = '0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002';
+const WALLET_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
+const INVALID_WALLET_KEY = 'Invalid MAGNETO_WALLET_PRIVATE_KEY';
+export const DEFAULT_ALLOWED_NETWORKS = ['eip155:84532', 'eip155:8453'];
+export const DEFAULT_MAX_PAYMENT_USD = 0.1;
+export const PRICING_URL = 'https://magnetoapp.io/pricing';
+export class PaymentCapError extends Error {
+    amountUsd;
+    maxPaymentUsd;
+    constructor(amountUsd, maxPaymentUsd) {
+        const cap = typeof maxPaymentUsd === 'number' ? formatMaxPaymentUsd(maxPaymentUsd) : maxPaymentUsd;
+        super(`payment of $${amountUsd} exceeds --max-payment $${cap}`);
+        this.name = 'PaymentCapError';
+        this.amountUsd = amountUsd;
+        this.maxPaymentUsd = cap;
+    }
+}
+export function toBase64Url(json) {
+    return Buffer.from(JSON.stringify(json), 'utf8').toString('base64url');
+}
+export function fromBase64Url(header) {
+    return JSON.parse(Buffer.from(header, 'base64url').toString('utf8'));
+}
+function looksLikeV1(payload) {
+    if (!payload || typeof payload !== 'object')
+        return false;
+    const obj = payload;
+    if (obj.x402Version === 1)
+        return true;
+    if (typeof obj.maxAmountRequired === 'string' && obj.amount === undefined) {
+        return true;
+    }
+    return false;
+}
+export function decodePaymentRequired(header) {
+    let parsed;
+    try {
+        parsed = fromBase64Url(header.trim());
+    }
+    catch {
+        throw new Error('invalid PAYMENT-REQUIRED header');
+    }
+    if (!parsed || typeof parsed !== 'object' || looksLikeV1(parsed)) {
+        throw new Error('invalid PAYMENT-REQUIRED header');
+    }
+    const obj = parsed;
+    if (obj.x402Version !== 2) {
+        throw new Error('invalid PAYMENT-REQUIRED header');
+    }
+    if (!Array.isArray(obj.accepted)) {
+        throw new Error('invalid PAYMENT-REQUIRED header');
+    }
+    return obj;
+}
+export function tryDecodePaymentRequired(header) {
+    if (header == null || header.trim() === '')
+        return undefined;
+    try {
+        return decodePaymentRequired(header);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function decodePaymentResponse(header) {
+    let parsed;
+    try {
+        parsed = fromBase64Url(header.trim());
+    }
+    catch {
+        throw new Error('invalid PAYMENT-RESPONSE header');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('invalid PAYMENT-RESPONSE header');
+    }
+    const obj = parsed;
+    if (obj.x402Version !== 2 || typeof obj.transaction !== 'string' || typeof obj.network !== 'string') {
+        throw new Error('invalid PAYMENT-RESPONSE header');
+    }
+    return obj;
+}
+export function tryDecodePaymentResponse(header) {
+    if (header == null || header.trim() === '')
+        return undefined;
+    try {
+        return decodePaymentResponse(header);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function pickRequirement(accepted, allowedNetworks) {
+    if (!accepted?.length)
+        return undefined;
+    const allow = new Set(allowedNetworks);
+    return accepted.find((entry) => typeof entry.network === 'string' && allow.has(entry.network));
+}
+/**
+ * USD → USDC atomic units (6 decimals). `$0.01 → "10000"`.
+ * Rounds to the nearest cent first so we never keep a float micros value.
+ */
+export function usdToAtomicUsdc(usd) {
+    if (!Number.isFinite(usd) || usd < 0) {
+        throw new Error('Invalid USD amount');
+    }
+    const cents = Math.round(usd * 100);
+    return String(cents * ATOMIC_PER_CENT);
+}
+/**
+ * USDC atomic units → a decimal USD string without float math.
+ * `"10000"` → `"0.01"`.
+ */
+export function atomicUsdcToUsd(atomic) {
+    const micros = BigInt(atomic);
+    const hundred = BigInt(100);
+    const cents = micros / BigInt(ATOMIC_PER_CENT);
+    const dollars = cents / hundred;
+    const remainder = cents % hundred;
+    return `${dollars}.${remainder.toString().padStart(2, '0')}`;
+}
+export function formatUsdDisplay(atomic) {
+    return `$${atomicUsdcToUsd(atomic)}`;
+}
+export function formatMaxPaymentUsd(usd) {
+    const fixed2 = usd.toFixed(2);
+    if (Number(fixed2) === usd)
+        return fixed2;
+    return String(usd);
+}
+/**
+ * `true` iff the challenge USD is strictly greater than the cap.
+ * Compare in atomic USDC units so `$0.005` is a real cap, not rounded to a cent.
+ */
+export function exceedsMaxPayment(amountAtomic, maxPaymentUsd) {
+    let challenge;
+    try {
+        challenge = BigInt(amountAtomic ?? '');
+    }
+    catch {
+        return true;
+    }
+    if (challenge < 0n)
+        return true;
+    if (!Number.isFinite(maxPaymentUsd) || maxPaymentUsd < 0)
+        return true;
+    const cap = BigInt(Math.round(maxPaymentUsd * ATOMIC_PER_USD));
+    return challenge > cap;
+}
+export function requirementAmountAtomic(requirement) {
+    return requirement.amount ?? requirement.maxAmountRequired;
+}
+export function allowedNetworksFromEnv(env = process.env) {
+    const raw = env.MAGNETO_X402_NETWORK?.trim();
+    if (!raw)
+        return [...DEFAULT_ALLOWED_NETWORKS];
+    const parts = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return parts.length > 0 ? parts : [...DEFAULT_ALLOWED_NETWORKS];
+}
+export function readWalletPrivateKey(env = process.env) {
+    const raw = env.MAGNETO_WALLET_PRIVATE_KEY?.trim();
+    if (!raw)
+        return null;
+    if (!WALLET_KEY_RE.test(raw)) {
+        throw new Error(INVALID_WALLET_KEY);
+    }
+    return raw;
+}
+export function formatShortAsset(asset) {
+    if (asset.startsWith('0x') && asset.length >= 12) {
+        return `${asset.slice(0, 8)}…${asset.slice(-4)}`;
+    }
+    return asset;
+}
+function resolveNonceHex(nonceBytes) {
+    const bytes = nonceBytes ?? randomBytes(32);
+    if (bytes.length !== 32) {
+        throw new Error('nonceBytes must be 32 bytes');
+    }
+    return `0x${Buffer.from(bytes).toString('hex')}`;
+}
+export async function signPayment(requirement, privateKey, opts) {
+    const key = privateKey.trim();
+    if (!WALLET_KEY_RE.test(key)) {
+        throw new Error(INVALID_WALLET_KEY);
+    }
+    const chainId = Number(requirement.network?.split(':')[1]);
+    const value = requirementAmountAtomic(requirement);
+    if (!Number.isInteger(chainId) || !requirement.asset || !requirement.payTo || !value) {
+        throw new Error('payment requirement missing network/asset/payTo/amount');
+    }
+    let account;
+    try {
+        account = privateKeyToAccount(key);
+    }
+    catch {
+        throw new Error(INVALID_WALLET_KEY);
+    }
+    const nowSeconds = opts?.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const nonceHex = resolveNonceHex(opts?.nonceBytes);
+    const validBefore = String(nowSeconds + (requirement.maxTimeoutSeconds ?? 600));
+    try {
+        if (requirement.scheme === 'upto') {
+            const facilitator = requirement.extra?.facilitatorAddress?.trim();
+            if (!facilitator) {
+                throw new Error('upto challenge missing extra.facilitatorAddress');
+            }
+            const spender = (requirement.extra?.spenderAddress?.trim() ||
+                UPTO_PERMIT2_PROXY);
+            const permit2Authorization = {
+                permitted: {
+                    token: requirement.asset,
+                    amount: value,
+                },
+                from: account.address,
+                spender,
+                nonce: BigInt(nonceHex).toString(),
+                deadline: validBefore,
+                witness: {
+                    to: requirement.payTo,
+                    facilitator,
+                    validAfter: '0',
+                },
+            };
+            const signature = await account.signTypedData({
+                domain: {
+                    name: 'Permit2',
+                    chainId,
+                    verifyingContract: PERMIT2,
+                },
+                types: {
+                    PermitWitnessTransferFrom: [
+                        { name: 'permitted', type: 'TokenPermissions' },
+                        { name: 'spender', type: 'address' },
+                        { name: 'nonce', type: 'uint256' },
+                        { name: 'deadline', type: 'uint256' },
+                        { name: 'witness', type: 'Witness' },
+                    ],
+                    TokenPermissions: [
+                        { name: 'token', type: 'address' },
+                        { name: 'amount', type: 'uint256' },
+                    ],
+                    Witness: [
+                        { name: 'to', type: 'address' },
+                        { name: 'facilitator', type: 'address' },
+                        { name: 'validAfter', type: 'uint256' },
+                    ],
+                },
+                primaryType: 'PermitWitnessTransferFrom',
+                message: {
+                    permitted: {
+                        token: permit2Authorization.permitted.token,
+                        amount: BigInt(value),
+                    },
+                    spender,
+                    nonce: BigInt(nonceHex),
+                    deadline: BigInt(validBefore),
+                    witness: {
+                        to: permit2Authorization.witness.to,
+                        facilitator: permit2Authorization.witness.facilitator,
+                        validAfter: BigInt(0),
+                    },
+                },
+            });
+            return {
+                x402Version: 2,
+                accepted: requirement,
+                payload: { signature, permit2Authorization },
+            };
+        }
+        const authorization = {
+            from: account.address,
+            to: requirement.payTo,
+            value,
+            validAfter: '0',
+            validBefore,
+            nonce: nonceHex,
+        };
+        const signature = await account.signTypedData({
+            domain: {
+                name: requirement.extra?.name ?? 'USDC',
+                version: requirement.extra?.version ?? '2',
+                chainId,
+                verifyingContract: requirement.asset,
+            },
+            types: {
+                TransferWithAuthorization: [
+                    { name: 'from', type: 'address' },
+                    { name: 'to', type: 'address' },
+                    { name: 'value', type: 'uint256' },
+                    { name: 'validAfter', type: 'uint256' },
+                    { name: 'validBefore', type: 'uint256' },
+                    { name: 'nonce', type: 'bytes32' },
+                ],
+            },
+            primaryType: 'TransferWithAuthorization',
+            message: {
+                from: authorization.from,
+                to: authorization.to,
+                value: BigInt(value),
+                validAfter: BigInt(authorization.validAfter),
+                validBefore: BigInt(authorization.validBefore),
+                nonce: authorization.nonce,
+            },
+        });
+        return {
+            x402Version: 2,
+            accepted: requirement,
+            payload: { signature, authorization },
+        };
+    }
+    catch (err) {
+        if (err instanceof Error && err.message === INVALID_WALLET_KEY)
+            throw err;
+        if (err instanceof Error && err.message === 'upto challenge missing extra.facilitatorAddress') {
+            throw err;
+        }
+        throw new Error(INVALID_WALLET_KEY);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magnetoagents/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Magneto CLI — drive computers via sk_live_* keys against /api/v1",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "pretest": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
@@ -29,7 +30,8 @@
     "access": "public"
   },
   "dependencies": {
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "viem": "^2.55.19"
   },
   "devDependencies": {
     "@types/node": "^20.17.0",