@blockrun/franklin 3.17.0 → 3.19.0

package/dist/panel/server.js

@@ -7,6 +7,8 @@ import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadChain, saveChain } from '../config.js';
+import { listNumbers as gatewayListNumbers, renewNumber as gatewayRenewNumber, buyNumber as gatewayBuyNumber, releaseNumber as gatewayReleaseNumber, } from '../phone/client.js';
+import { readCache as readPhoneCache, writeCache as writePhoneCache, clearCache as clearPhoneCache, isFresh as isPhoneCacheFresh, } from '../phone/cache.js';
 import { getStatsSummary, getStatsFilePath } from '../stats/tracker.js';
 import { generateInsights } from '../stats/insights.js';
 import { listSessions, loadSessionHistory } from '../session/storage.js';
@@ -24,7 +26,7 @@ const sseClients = new Set();
 function json(res, data, status = 200) {
     res.writeHead(status, {
         'Content-Type': 'application/json',
-        'Access-Control-Allow-Origin': '*',
+        'Cache-Control': 'no-store',
     });
     res.end(JSON.stringify(data));
 }
@@ -37,6 +39,39 @@ function isLoopback(req) {
     const addr = req.socket.remoteAddress || '';
     return addr === '127.0.0.1' || addr === '::1' || addr === '::ffff:127.0.0.1';
 }
+function isLocalHostname(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
+}
+/**
+ * Loopback binding prevents LAN exposure, but it does not stop a malicious
+ * website open in the user's browser from issuing requests to localhost.
+ * Browsers attach Origin on cross-origin fetches, so spendful and
+ * wallet-mutating routes require either no Origin (curl/direct navigation)
+ * or the exact same local origin that served the panel page.
+ */
+function isTrustedPanelOrigin(req) {
+    const origin = req.headers.origin;
+    if (!origin)
+        return true;
+    if (Array.isArray(origin))
+        return false;
+    const host = req.headers.host;
+    if (!host)
+        return false;
+    try {
+        const originUrl = new URL(origin);
+        const hostUrl = new URL(`http://${host}`);
+        return originUrl.protocol === 'http:' &&
+            originUrl.host === hostUrl.host &&
+            isLocalHostname(originUrl.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function isLocalPanelRequest(req) {
+    return isLoopback(req) && isTrustedPanelOrigin(req);
+}
 async function readBody(req, maxBytes = 16 * 1024) {
     return new Promise((resolve, reject) => {
         let size = 0;
@@ -65,6 +100,25 @@ function broadcast(data) {
         }
     }
 }
+/**
+ * Resolve the current active wallet address (Base or Solana, depending on
+ * the active chain). Used by phone endpoints that key the cache by wallet,
+ * and that must sign x402 payments out of the wallet the user owns.
+ *
+ * Throws if no wallet exists yet — the UI handles this by showing an
+ * empty state with a "Create wallet" CTA before any phone calls can be made.
+ */
+async function currentWalletAddress() {
+    const chain = loadChain();
+    if (chain === 'solana') {
+        const { setupAgentSolanaWallet } = await import('@blockrun/llm');
+        const client = await setupAgentSolanaWallet({ silent: true });
+        return await client.getWalletAddress();
+    }
+    const { setupAgentWallet } = await import('@blockrun/llm');
+    const client = setupAgentWallet({ silent: true });
+    return client.getWalletAddress();
+}
 export function createPanelServer(port) {
     const html = getHTML();
     const server = http.createServer(async (req, res) => {
@@ -239,9 +293,9 @@ export function createPanelServer(port) {
                 // ─── Wallet secret (loopback only) ──────────────────────────────────
                 // Returns the private key so the user can back it up / move it.
                 // Hardened: loopback-only (belt-and-suspenders on the 127.0.0.1 bind),
-                // no-store cache header, JSON only.
+                // same-origin for browser requests, no-store cache header, JSON only.
                 if (p === '/api/wallet/secret') {
-                    if (!isLoopback(req)) {
+                    if (!isLocalPanelRequest(req)) {
                         json(res, { error: 'forbidden' }, 403);
                         return;
                     }
@@ -271,9 +325,9 @@ export function createPanelServer(port) {
                 // ─── Wallet import (loopback only) ──────────────────────────────────
                 // Overwrites the local wallet with a user-supplied private key.
                 // Destructive — overwrites the existing wallet file without backup,
-                // so the UI warns the user. Loopback-only.
+                // so the UI warns the user. Loopback + same-origin only.
                 if (p === '/api/wallet/import' && req.method === 'POST') {
-                    if (!isLoopback(req)) {
+                    if (!isLocalPanelRequest(req)) {
                         json(res, { error: 'forbidden' }, 403);
                         return;
                     }
@@ -329,7 +383,7 @@ export function createPanelServer(port) {
                 // reads and for the *next* agent invocation, but won't flip chain
                 // mid-session for an already-running agent. UI copy makes this clear.
                 if (p === '/api/chain' && req.method === 'POST') {
-                    if (!isLoopback(req)) {
+                    if (!isLocalPanelRequest(req)) {
                         json(res, { error: 'forbidden' }, 403);
                         return;
                     }
@@ -364,6 +418,163 @@ export function createPanelServer(port) {
                     }
                     return;
                 }
+                // ─── Phone & Voice ──────────────────────────────────────────────────
+                // GET  /api/phone/numbers           — list wallet-owned numbers (cached)
+                // POST /api/phone/numbers/refresh   — force-refresh from BlockRun ($0.001)
+                // POST /api/phone/numbers/renew     — extend lease 30d ($5)
+                // POST /api/phone/numbers/buy       — provision new number ($5)
+                // POST /api/phone/numbers/release   — release (free)
+                //
+                // Renewals are explicit user clicks. No silent auto-renew: a wallet
+                // that runs dry between charges would fail the renewal and surprise
+                // the user. Notifications at T-7/3/1 days keep them in the loop.
+                //
+                // All spendful/mutating endpoints are loopback + same-origin because
+                // they spend money out of the user's wallet. Even the list endpoint can
+                // cost $0.001 on cache miss, so it gets the same browser-origin guard.
+                if (p === '/api/phone/numbers' && (!req.method || req.method === 'GET')) {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden', numbers: [] }, 403);
+                        return;
+                    }
+                    try {
+                        const wallet = await currentWalletAddress();
+                        const chain = loadChain();
+                        const cache = readPhoneCache();
+                        if (cache && isPhoneCacheFresh(cache, wallet, chain)) {
+                            json(res, {
+                                wallet,
+                                chain,
+                                fetchedAt: cache.fetchedAt,
+                                fromCache: true,
+                                numbers: cache.numbers,
+                            });
+                            return;
+                        }
+                        // Cache stale or missing — fetch fresh (costs $0.001).
+                        // We pay through the panel's wallet, which is the same wallet
+                        // that owns the numbers, so the gateway returns this user's list.
+                        const fresh = await gatewayListNumbers({ walletAddress: wallet });
+                        json(res, {
+                            wallet,
+                            chain,
+                            fetchedAt: Date.now(),
+                            fromCache: false,
+                            paid: fresh.paid,
+                            numbers: fresh.numbers,
+                        });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message, numbers: [] }, 500);
+                    }
+                    return;
+                }
+                if (p === '/api/phone/numbers/refresh' && req.method === 'POST') {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const wallet = await currentWalletAddress();
+                        clearPhoneCache();
+                        const fresh = await gatewayListNumbers({ walletAddress: wallet });
+                        broadcast({ type: 'phone.refreshed' });
+                        json(res, {
+                            wallet,
+                            chain: loadChain(),
+                            paid: fresh.paid,
+                            numbers: fresh.numbers,
+                        });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
+                if (p === '/api/phone/numbers/renew' && req.method === 'POST') {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const raw = await readBody(req);
+                        const body = JSON.parse(raw);
+                        const target = (body.phoneNumber || '').trim();
+                        if (!target) {
+                            json(res, { error: 'phoneNumber required' }, 400);
+                            return;
+                        }
+                        const result = await gatewayRenewNumber(target);
+                        // Patch the cache in place so the panel UI gets the new expiry
+                        // without a follow-up $0.001 list call.
+                        const cache = readPhoneCache();
+                        if (cache) {
+                            const idx = cache.numbers.findIndex(n => n.phone_number === target);
+                            if (idx >= 0) {
+                                cache.numbers[idx] = {
+                                    ...cache.numbers[idx],
+                                    expires_at: result.expires_at,
+                                    active: true,
+                                };
+                                writePhoneCache({ wallet: cache.wallet, chain: cache.chain, numbers: cache.numbers });
+                            }
+                        }
+                        broadcast({ type: 'phone.renewed', phoneNumber: target, expires_at: result.expires_at });
+                        json(res, { ok: true, ...result });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
+                if (p === '/api/phone/numbers/buy' && req.method === 'POST') {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const raw = await readBody(req);
+                        const body = JSON.parse(raw);
+                        const result = await gatewayBuyNumber({
+                            country: body.country,
+                            areaCode: body.areaCode,
+                        });
+                        clearPhoneCache(); // forces next /api/phone/numbers to re-list
+                        broadcast({ type: 'phone.bought', phoneNumber: result.phone_number });
+                        json(res, { ok: true, ...result });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
+                if (p === '/api/phone/numbers/release' && req.method === 'POST') {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const raw = await readBody(req);
+                        const body = JSON.parse(raw);
+                        const target = (body.phoneNumber || '').trim();
+                        if (!target) {
+                            json(res, { error: 'phoneNumber required' }, 400);
+                            return;
+                        }
+                        const result = await gatewayReleaseNumber(target);
+                        const cache = readPhoneCache();
+                        if (cache) {
+                            const next = cache.numbers.filter(n => n.phone_number !== target);
+                            writePhoneCache({ wallet: cache.wallet, chain: cache.chain, numbers: next });
+                        }
+                        broadcast({ type: 'phone.released', phoneNumber: target });
+                        json(res, { ok: true, ...result });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
                 if (p === '/api/markets') {
                     // Snapshot of every active data provider for the Markets panel:
                     // pipeline wiring (which endpoint serves which asset class), live

package/dist/phone/cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared cache for the user's BlockRun-provisioned phone numbers.
+ *
+ * Why a cache: `POST /v1/phone/numbers/list` costs $0.001 per call. The
+ * panel ticks countdowns once per minute and the terminal status bar
+ * re-renders on every prompt cycle — both surfaces hitting the gateway
+ * directly would burn pointless micropayments. We hit the gateway only
+ * on cache-miss, panel-reload, or after a state-changing call (buy /
+ * renew / release).
+ *
+ * Storage: ~/.blockrun/phone-numbers.json. Read by both the Ink terminal
+ * status bar and the web panel, so they always agree on which numbers
+ * the wallet owns and how many days remain.
+ */
+import { type Chain } from '../config.js';
+export interface PhoneNumberRecord {
+    phone_number: string;
+    chain: Chain;
+    expires_at: string;
+    active: boolean;
+}
+interface CacheFile {
+    fetchedAt: number;
+    wallet: string;
+    chain: Chain;
+    numbers: PhoneNumberRecord[];
+}
+/** 6 hours — long enough to not thrash the gateway, short enough that
+ * a number provisioned on another device shows up the same day. */
+export declare const CACHE_TTL_MS: number;
+export declare function readCache(): CacheFile | null;
+export declare function writeCache(data: {
+    wallet: string;
+    chain: Chain;
+    numbers: PhoneNumberRecord[];
+}): void;
+export declare function clearCache(): void;
+export declare function isFresh(cache: CacheFile | null, wallet: string, chain: Chain): boolean;
+/**
+ * Compute days-remaining for a number's lease. Negative when expired.
+ * UI uses this for the colour ladder (green / amber / red).
+ */
+export declare function daysRemaining(expiresAt: string): number;
+export {};

package/dist/phone/cache.js

@@ -0,0 +1,74 @@
+/**
+ * Shared cache for the user's BlockRun-provisioned phone numbers.
+ *
+ * Why a cache: `POST /v1/phone/numbers/list` costs $0.001 per call. The
+ * panel ticks countdowns once per minute and the terminal status bar
+ * re-renders on every prompt cycle — both surfaces hitting the gateway
+ * directly would burn pointless micropayments. We hit the gateway only
+ * on cache-miss, panel-reload, or after a state-changing call (buy /
+ * renew / release).
+ *
+ * Storage: ~/.blockrun/phone-numbers.json. Read by both the Ink terminal
+ * status bar and the web panel, so they always agree on which numbers
+ * the wallet owns and how many days remain.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR } from '../config.js';
+const CACHE_PATH = path.join(BLOCKRUN_DIR, 'phone-numbers.json');
+/** 6 hours — long enough to not thrash the gateway, short enough that
+ * a number provisioned on another device shows up the same day. */
+export const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+export function readCache() {
+    try {
+        const raw = fs.readFileSync(CACHE_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.numbers))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCache(data) {
+    try {
+        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+        const payload = {
+            fetchedAt: Date.now(),
+            wallet: data.wallet,
+            chain: data.chain,
+            numbers: data.numbers,
+        };
+        fs.writeFileSync(CACHE_PATH, JSON.stringify(payload, null, 2) + '\n', {
+            mode: 0o600,
+        });
+    }
+    catch {
+        /* best-effort — cache is an optimization, not a source of truth */
+    }
+}
+export function clearCache() {
+    try {
+        fs.unlinkSync(CACHE_PATH);
+    }
+    catch { /* not there, fine */ }
+}
+export function isFresh(cache, wallet, chain) {
+    if (!cache)
+        return false;
+    if (cache.wallet !== wallet)
+        return false;
+    if (cache.chain !== chain)
+        return false;
+    return Date.now() - cache.fetchedAt < CACHE_TTL_MS;
+}
+/**
+ * Compute days-remaining for a number's lease. Negative when expired.
+ * UI uses this for the colour ladder (green / amber / red).
+ */
+export function daysRemaining(expiresAt) {
+    const expiry = new Date(expiresAt).getTime();
+    const now = Date.now();
+    return Math.floor((expiry - now) / (24 * 60 * 60 * 1000));
+}

package/dist/phone/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * BlockRun phone API client.
+ *
+ * Thin wrapper over `/v1/phone/numbers/{list,buy,renew,release}` that
+ * handles the x402 payment handshake using the wallet Franklin already
+ * loads at startup. Pattern mirrors `src/tools/modal.ts` — first POST
+ * returns 402 with payment requirements, we sign with the local wallet,
+ * retry once with X-PAYMENT.
+ *
+ * Used by:
+ *   - panel server (renew button, buy flow, refresh button)
+ *   - phone cache refresh (background)
+ *   - future Phone/Call tools surfaced to the agent
+ */
+import { type Chain } from '../config.js';
+import { type PhoneNumberRecord } from './cache.js';
+export interface ListNumbersResult {
+    numbers: PhoneNumberRecord[];
+    count: number;
+    /** $0.001 was paid for this list call. UI can show it. */
+    paid: number;
+}
+/**
+ * Fetch the wallet's owned numbers from BlockRun. Refreshes the local
+ * cache on success so the terminal status bar picks up the same data.
+ */
+export declare function listNumbers(opts: {
+    walletAddress: string;
+}): Promise<ListNumbersResult>;
+export interface RenewResult {
+    phone_number: string;
+    expires_at: string;
+    paid: number;
+}
+export declare function renewNumber(phoneNumber: string): Promise<RenewResult>;
+export interface BuyResult {
+    phone_number: string;
+    expires_at: string;
+    chain: Chain;
+    paid: number;
+}
+export declare function buyNumber(opts: {
+    country?: string;
+    areaCode?: string;
+}): Promise<BuyResult>;
+export interface ReleaseResult {
+    released: boolean;
+    phone_number: string;
+}
+export declare function releaseNumber(phoneNumber: string): Promise<ReleaseResult>;

package/dist/phone/client.js

@@ -0,0 +1,162 @@
+/**
+ * BlockRun phone API client.
+ *
+ * Thin wrapper over `/v1/phone/numbers/{list,buy,renew,release}` that
+ * handles the x402 payment handshake using the wallet Franklin already
+ * loads at startup. Pattern mirrors `src/tools/modal.ts` — first POST
+ * returns 402 with payment requirements, we sign with the local wallet,
+ * retry once with X-PAYMENT.
+ *
+ * Used by:
+ *   - panel server (renew button, buy flow, refresh button)
+ *   - phone cache refresh (background)
+ *   - future Phone/Call tools surfaced to the agent
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, USER_AGENT } from '../config.js';
+import { writeCache } from './cache.js';
+function phoneEndpoint(chain, path) {
+    return `${API_URLS[chain]}/v1/phone/${path}`;
+}
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.clone().json());
+            if (body.x402 || body.accepts)
+                header = btoa(JSON.stringify(body));
+        }
+        catch { /* not JSON, no header */ }
+    }
+    return header;
+}
+async function signPayment(response, chain, endpoint, resourceDescription) {
+    const paymentHeader = await extractPaymentReq(response);
+    if (!paymentHeader)
+        return null;
+    if (chain === 'solana') {
+        const wallet = await getOrCreateSolanaWallet();
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+        const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+        const feePayer = details.extra?.feePayer || details.recipient;
+        const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+            resourceUrl: details.resource?.url || endpoint,
+            resourceDescription: details.resource?.description || resourceDescription,
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    else {
+        const wallet = getOrCreateWallet();
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        const details = extractPaymentDetails(paymentRequired);
+        const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+            resourceUrl: details.resource?.url || endpoint,
+            resourceDescription: details.resource?.description || resourceDescription,
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+}
+async function postWithPayment(endpoint, body, resourceDescription, timeoutMs = 30_000) {
+    const chain = loadChain();
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': USER_AGENT,
+    };
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const payload = JSON.stringify(body);
+        let response = await fetch(endpoint, {
+            method: 'POST',
+            signal: ctrl.signal,
+            headers,
+            body: payload,
+        });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint, resourceDescription);
+            if (!paymentHeaders) {
+                return { ok: false, status: 402, body: { error: 'payment signing failed' }, raw: '' };
+            }
+            response = await fetch(endpoint, {
+                method: 'POST',
+                signal: ctrl.signal,
+                headers: { ...headers, ...paymentHeaders },
+                body: payload,
+            });
+        }
+        const raw = await response.text().catch(() => '');
+        let parsed = {};
+        try {
+            parsed = raw ? JSON.parse(raw) : {};
+        }
+        catch { /* leave as {} */ }
+        return { ok: response.ok, status: response.status, body: parsed, raw };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch the wallet's owned numbers from BlockRun. Refreshes the local
+ * cache on success so the terminal status bar picks up the same data.
+ */
+export async function listNumbers(opts) {
+    const chain = loadChain();
+    const result = await postWithPayment(phoneEndpoint(chain, 'numbers/list'), {}, 'List wallet-owned BlockRun phone numbers');
+    if (!result.ok) {
+        const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
+        throw new Error(message);
+    }
+    const numbers = Array.isArray(result.body.numbers)
+        ? result.body.numbers
+        : [];
+    writeCache({ wallet: opts.walletAddress, chain, numbers });
+    return { numbers, count: numbers.length, paid: 0.001 };
+}
+export async function renewNumber(phoneNumber) {
+    const chain = loadChain();
+    const result = await postWithPayment(phoneEndpoint(chain, 'numbers/renew'), { phoneNumber }, `Renew BlockRun phone number ${phoneNumber}`);
+    if (!result.ok) {
+        const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
+        throw new Error(message);
+    }
+    return {
+        phone_number: String(result.body.phone_number ?? phoneNumber),
+        expires_at: String(result.body.expires_at ?? ''),
+        paid: 5.0,
+    };
+}
+export async function buyNumber(opts) {
+    const chain = loadChain();
+    const body = { country: opts.country || 'US' };
+    if (opts.areaCode)
+        body.areaCode = opts.areaCode;
+    const result = await postWithPayment(phoneEndpoint(chain, 'numbers/buy'), body, `Provision a new BlockRun phone number (${opts.country || 'US'})`);
+    if (!result.ok) {
+        const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
+        throw new Error(message);
+    }
+    return {
+        phone_number: String(result.body.phone_number ?? ''),
+        expires_at: String(result.body.expires_at ?? ''),
+        chain: result.body.chain || chain,
+        paid: 5.0,
+    };
+}
+export async function releaseNumber(phoneNumber) {
+    const chain = loadChain();
+    const result = await postWithPayment(phoneEndpoint(chain, 'numbers/release'), { phoneNumber }, `Release BlockRun phone number ${phoneNumber}`);
+    if (!result.ok) {
+        const message = typeof result.body.error === 'string' ? result.body.error : `gateway ${result.status}`;
+        throw new Error(message);
+    }
+    return {
+        released: Boolean(result.body.released),
+        phone_number: String(result.body.phone_number ?? phoneNumber),
+    };
+}