aeron-wallet 0.1.0 → 0.2.0

package/README.md

@@ -32,6 +32,9 @@ need ETH: the facilitator relays the transaction and pays gas.
 | `balance` | ETH and USDG balances, read from chain. |
 | `pay <url> [json]` | Call an x402 endpoint, paying if it answers 402. |
 | `history` | The last 10 payments, from the local log. |
+| `session create` | Mint a scoped session: hosts, budget, per-call cap, expiry. |
+| `session list` | Every session, what it spent, and whether it is still live. |
+| `session revoke <id>` | Kill a session. It stops paying on its next call. |
 | `mcp` | Run as an MCP server over stdio. The default with no arguments. |
 
 ## MCP
@@ -47,7 +50,47 @@ need ETH: the facilitator relays the transaction and pays gas.
 }
 ```
 
-Four tools: `get_address`, `get_balance`, `pay`, `history`.
+Four tools: `get_address`, `get_balance`, `pay`, `history`. An unbound server
+also gets `create_session`, `list_sessions`, and `revoke_session`.
+
+## Sessions
+
+A session is a scope you can hand to an agent without handing over the wallet.
+It names the hosts that may be paid, a total budget, a per-call cap, and an
+expiry:
+
+```bash
+aeron-wallet session create --host inference.aeron.sh --budget 0.25 --ttl 2h
+```
+
+That prints a token, once. Bind a server to it and every call through that
+server inherits the scope:
+
+```json
+{
+  "mcpServers": {
+    "aeron-wallet": {
+      "command": "npx",
+      "args": ["-y", "aeron-wallet", "mcp"],
+      "env": { "AERON_WALLET_SESSION": "<token>" }
+    }
+  }
+}
+```
+
+A bound server deliberately has no session tools. An agent that could mint
+itself a wider session would not be contained by one. It also cannot reach a
+host outside the scope: the wallet refuses before the request goes out, so an
+agent talked into paying an attacker's endpoint never contacts it.
+
+Revoking takes effect on the next call, including for a server already
+running, because the scope is re-read every time rather than captured at
+startup.
+
+`aeron-wallet pay --session <token> <url>` applies a scope to a single call.
+
+Sessions narrow the wallet; they never widen it. The caps below still apply
+underneath, so a $5 session on a $1/day wallet spends $1 a day.
 
 ## Your key
 
@@ -83,6 +126,7 @@ The wallet refuses to sign above either cap, so a loop cannot drain it.
 | `USDG_ADDRESS` | `0x5fc5360d0400a0fd4f2af552add042d716f1d168` |
 | `AERON_WALLET_DIR` | `~/.aeron/wallet` |
 | `AERON_WALLET_KEY` | unset. Overrides the stored key. |
+| `AERON_WALLET_SESSION` | unset. Binds the whole process to one session. |
 
 ## Where payments go
 

package/dist/cli-sessions.js

@@ -0,0 +1,91 @@
+import { parseTtlSeconds } from './sessions.js';
+/** Collect repeated `--flag value` pairs. Unknown flags are an error, not a shrug. */
+function readFlags(args, known) {
+    const flags = new Map();
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg.startsWith('--'))
+            throw new Error(`unexpected argument "${arg}"`);
+        const name = arg.slice(2);
+        if (!known.includes(name))
+            throw new Error(`unknown flag --${name}; expected ${known.map((k) => `--${k}`).join(', ')}`);
+        const value = args[i + 1];
+        if (value === undefined || value.startsWith('--'))
+            throw new Error(`--${name} needs a value`);
+        flags.set(name, [...(flags.get(name) ?? []), value]);
+        i += 1;
+    }
+    return flags;
+}
+function positiveNumber(raw, label) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`${label} must be a positive number, got "${raw}"`);
+    return value;
+}
+const CREATE_FLAGS = ['host', 'budget', 'ttl', 'max-per-call'];
+function create(args, sessions, cfg, out) {
+    const flags = readFlags(args, CREATE_FLAGS);
+    const hosts = (flags.get('host') ?? []).flatMap((h) => h.split(',')).map((h) => h.trim()).filter(Boolean);
+    if (hosts.length === 0)
+        throw new Error('at least one --host is required; a session with no scope is not a scope');
+    const budgetRaw = flags.get('budget')?.[0];
+    const ttlRaw = flags.get('ttl')?.[0];
+    if (!budgetRaw)
+        throw new Error('--budget is required, in USD');
+    if (!ttlRaw)
+        throw new Error('--ttl is required, for example 2h');
+    const budgetUsd = positiveNumber(budgetRaw, '--budget');
+    const maxPerCallUsd = flags.has('max-per-call')
+        ? positiveNumber(flags.get('max-per-call')[0], '--max-per-call')
+        : Math.min(cfg.MAX_PER_CALL_USD, budgetUsd);
+    const { session, token } = sessions.create({
+        hosts,
+        budgetUsd,
+        maxPerCallUsd,
+        ttlSeconds: parseTtlSeconds(ttlRaw),
+    });
+    out(`session  ${session.id}`);
+    out(`hosts    ${session.hosts.join(', ')}`);
+    out(`budget   $${session.budgetUsd} total, $${session.maxPerCallUsd} per call`);
+    out(`expires  ${session.expiresAt}`);
+    out('');
+    out('token, shown once:');
+    out(token);
+    out('');
+    out('Give it to an agent by binding a server to it:');
+    out(`  AERON_WALLET_SESSION=${token} aeron-wallet mcp`);
+    if (budgetUsd > cfg.DAILY_CAP_USD) {
+        out('');
+        out(`note: the wallet's own daily cap of $${cfg.DAILY_CAP_USD} still applies and is lower than this budget.`);
+    }
+}
+function list(sessions, out, now = new Date()) {
+    const all = sessions.list();
+    if (all.length === 0) {
+        out('no sessions');
+        return;
+    }
+    for (const s of all) {
+        const state = s.revokedAt ? 'revoked' : Date.parse(s.expiresAt) < now.getTime() ? 'expired' : 'active';
+        out(`${s.id}  ${state.padEnd(7)}  $${s.spentUsd.toFixed(4)}/$${s.budgetUsd}  ${s.hosts.join(',')}  until ${s.expiresAt}`);
+    }
+}
+export function runSessionCommand(args, deps) {
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case 'create':
+            return create(rest, deps.sessions, deps.cfg, deps.out);
+        case 'list':
+            return list(deps.sessions, deps.out);
+        case 'revoke': {
+            const id = rest[0];
+            if (!id)
+                throw new Error('usage: session revoke <id>');
+            deps.out(deps.sessions.revoke(id) ? `revoked ${id}` : `no active session with id ${id}`);
+            return;
+        }
+        default:
+            throw new Error('usage: session create|list|revoke');
+    }
+}

package/dist/cli.js

@@ -5,11 +5,14 @@ import { createHistory } from './history.js';
 import { createChainClient, readBalances } from './balances.js';
 import { payX402, resolveDomain } from './payer.js';
 import { startMcpServer } from './mcp.js';
+import { bindSession, createSessions } from './sessions.js';
+import { runSessionCommand } from './cli-sessions.js';
 const out = (line) => process.stdout.write(`${line}\n`);
 async function main() {
     const cfg = loadConfig();
     const { account, created } = loadOrCreateAccount(cfg);
     const history = createHistory(cfg);
+    const sessions = createSessions(cfg);
     const publicClient = createChainClient(cfg);
     let cachedDomain = null;
     const domain = async () => {
@@ -17,7 +20,19 @@ async function main() {
             cachedDomain = await resolveDomain(publicClient, cfg);
         return cachedDomain;
     };
-    const [command = 'mcp', ...rest] = process.argv.slice(2);
+    const [command = 'mcp', ...argv] = process.argv.slice(2);
+    // A `--session <token>` flag scopes one call; AERON_WALLET_SESSION scopes
+    // the whole process, which is how you hand a sub-agent a bounded server.
+    const flagAt = argv.indexOf('--session');
+    const inlineToken = flagAt === -1 ? undefined : argv[flagAt + 1];
+    if (flagAt !== -1 && !inlineToken)
+        throw new Error('--session needs a token');
+    const rest = flagAt === -1 ? argv : [...argv.slice(0, flagAt), ...argv.slice(flagAt + 2)];
+    const token = inlineToken ?? cfg.AERON_WALLET_SESSION;
+    const binding = token ? bindSession(sessions, token) : null;
+    if (binding && !binding.current()) {
+        throw new Error('that session token is unknown, revoked, or already gone');
+    }
     if (created && command !== 'mcp') {
         out(`new wallet created at ${cfg.AERON_WALLET_DIR} (hot wallet; keep balances small)`);
     }
@@ -38,7 +53,7 @@ async function main() {
             if (!url)
                 throw new Error('usage: pay <url> [json-body]');
             const body = rest[1];
-            const result = await payX402(url, { method: 'POST', headers: { 'content-type': 'application/json' }, ...(body ? { body } : {}) }, { cfg, account, history, domain: await domain() });
+            const result = await payX402(url, { method: 'POST', headers: { 'content-type': 'application/json' }, ...(body ? { body } : {}) }, { cfg, account, history, domain: await domain(), binding });
             out(JSON.stringify(result, null, 2));
             if (!result.paid && result.reason)
                 process.exitCode = 1;
@@ -50,12 +65,16 @@ async function main() {
             }
             return;
         }
+        case 'session': {
+            runSessionCommand(rest, { sessions, cfg, out });
+            return;
+        }
         case 'mcp': {
-            await startMcpServer({ cfg, account, history, publicClient, domain });
+            await startMcpServer({ cfg, account, history, publicClient, domain, sessions, binding });
             return;
         }
         default:
-            throw new Error(`unknown command: ${command} (use address|balance|pay|history|mcp)`);
+            throw new Error(`unknown command: ${command} (use address|balance|pay|history|session|mcp)`);
     }
 }
 main().catch((err) => {

package/dist/config.js

@@ -15,6 +15,12 @@ const envSchema = z.object({
         .optional()
         .or(z.literal('').transform(() => undefined)),
     AERON_WALLET_DIR: z.string().default(join(homedir(), '.aeron', 'wallet')),
+    /** Bind this process to one session. The scope then applies to every call. */
+    AERON_WALLET_SESSION: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional()
+        .or(z.literal('').transform(() => undefined)),
     /** Budget caps, USD. The wallet refuses to sign above these. */
     MAX_PER_CALL_USD: z.coerce.number().positive().default(0.05),
     DAILY_CAP_USD: z.coerce.number().positive().default(1),

package/dist/mcp.js

@@ -3,8 +3,10 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { readBalances } from './balances.js';
 import { payX402 } from './payer.js';
+import { parseTtlSeconds } from './sessions.js';
 export async function startMcpServer(deps) {
-    const { cfg, account, history, publicClient } = deps;
+    const { cfg, account, history, publicClient, sessions } = deps;
+    const binding = deps.binding ?? null;
     const server = new McpServer({ name: 'aeron-wallet', version: '0.1.0' });
     server.tool('get_address', 'The wallet address on Robinhood Chain. Fund it with USDG to pay for services.', {}, async () => ({
         content: [{ type: 'text', text: JSON.stringify({ address: account.address, network: cfg.network }) }],
@@ -13,7 +15,9 @@ export async function startMcpServer(deps) {
         const balances = await readBalances(publicClient, cfg, account.address);
         return { content: [{ type: 'text', text: JSON.stringify({ address: account.address, ...balances }) }] };
     });
-    server.tool('pay', 'Call a machine-payable (x402) endpoint and pay in USDG if it answers 402. Budget caps apply.', {
+    server.tool('pay', binding
+        ? 'Call a machine-payable (x402) endpoint and pay in USDG if it answers 402. This server is bound to a session: calls outside its hosts, per-call cap, budget, or expiry are refused.'
+        : 'Call a machine-payable (x402) endpoint and pay in USDG if it answers 402. Budget caps apply.', {
         url: z.string().url(),
         method: z.enum(['GET', 'POST']).default('POST'),
         body: z.string().optional().describe('JSON body to send'),
@@ -23,11 +27,54 @@ export async function startMcpServer(deps) {
             method,
             headers: { 'content-type': 'application/json' },
             ...(body ? { body } : {}),
-        }, { cfg, account, history, domain });
+        }, { cfg, account, history, domain, binding });
         return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     });
     server.tool('history', 'Recent payments made by this wallet.', { limit: z.number().int().min(1).max(50).default(10) }, async ({ limit }) => ({
         content: [{ type: 'text', text: JSON.stringify(history.recent(limit)) }],
     }));
+    if (!binding)
+        registerSessionTools(server, sessions, cfg);
     await server.connect(new StdioServerTransport());
 }
+/**
+ * Only an unbound server gets these. Handing them to a bound agent would let
+ * it write itself a wider scope, which is the whole thing a session prevents.
+ */
+function registerSessionTools(server, sessions, cfg) {
+    server.tool('create_session', 'Create a scoped session: allowed hosts, a total budget, a per-call cap, and an expiry. Returns a token that binds an agent to that scope.', {
+        hosts: z.array(z.string().min(1)).min(1).describe('hostnames this session may pay, e.g. inference.aeron.sh'),
+        budgetUsd: z.number().positive().describe('total USD this session may spend'),
+        ttl: z.string().describe('lifetime, e.g. 90, 30m, 2h, 1d'),
+        maxPerCallUsd: z.number().positive().optional(),
+    }, async ({ hosts, budgetUsd, ttl, maxPerCallUsd }) => {
+        const { session, token } = sessions.create({
+            hosts,
+            budgetUsd,
+            maxPerCallUsd: maxPerCallUsd ?? Math.min(cfg.MAX_PER_CALL_USD, budgetUsd),
+            ttlSeconds: parseTtlSeconds(ttl),
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        id: session.id,
+                        token,
+                        hosts: session.hosts,
+                        budgetUsd: session.budgetUsd,
+                        maxPerCallUsd: session.maxPerCallUsd,
+                        expiresAt: session.expiresAt,
+                        bind: `AERON_WALLET_SESSION=${token} aeron-wallet mcp`,
+                    }),
+                },
+            ],
+        };
+    });
+    server.tool('list_sessions', 'Every session, with what it has spent and whether it is still live.', {}, async () => ({
+        content: [{ type: 'text', text: JSON.stringify(sessions.list()) }],
+    }));
+    server.tool('revoke_session', 'Revoke a session by id. It stops paying on its next call.', { id: z.string().min(1) }, async ({ id }) => ({
+        content: [{ type: 'text', text: JSON.stringify({ id, revoked: sessions.revoke(id) }) }],
+    }));
+}

package/dist/payer.js

@@ -1,6 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { z } from 'zod';
 import { hashDomain } from 'viem';
+import { checkSession } from './sessions.js';
 /** EIP-3009 typed data, mirrored from the facilitator side. */
 const TRANSFER_WITH_AUTHORIZATION_TYPES = {
     TransferWithAuthorization: [
@@ -54,6 +55,15 @@ const body402Schema = z.looseObject({
     x402Version: z.number(),
     accepts: z.array(requirementsSchema).min(1),
 });
+/** Refused by the wallet before any request went out. */
+const refused = (reason, amountUsd = 0) => ({
+    paid: false,
+    status: 0,
+    amountUsd,
+    transaction: null,
+    body: '',
+    reason,
+});
 /**
  * The x402 client flow: call, read the 402 offer, enforce budget caps, sign
  * an exact-amount EIP-3009 authorization, retry with X-PAYMENT.
@@ -62,6 +72,16 @@ export async function payX402(url, init, deps) {
     const { cfg, account, history, domain } = deps;
     const fetchImpl = deps.fetchImpl ?? fetch;
     const now = deps.now ?? (() => Math.floor(Date.now() / 1000));
+    // Scope first: an out-of-scope host should never even be contacted.
+    const binding = deps.binding ?? null;
+    if (binding) {
+        const session = binding.current();
+        if (!session)
+            return refused('this session is no longer active');
+        const preflight = checkSession(session, { url, amountUsd: 0, now: Date.now() });
+        if (!preflight.ok)
+            return refused(preflight.reason);
+    }
     const first = await fetchImpl(url, init);
     const firstBody = await first.text();
     if (first.status !== 402) {
@@ -85,6 +105,15 @@ export async function payX402(url, init, deps) {
             reason: `amount $${amountUsd} exceeds per-call cap $${cfg.MAX_PER_CALL_USD}`,
         };
     }
+    if (binding) {
+        const session = binding.current();
+        if (!session)
+            return refused('this session is no longer active', amountUsd);
+        const outcome = checkSession(session, { url, amountUsd, now: Date.now() });
+        if (!outcome.ok) {
+            return { paid: false, status: 402, amountUsd, transaction: null, body: firstBody, reason: outcome.reason };
+        }
+    }
     const spent = history.spentTodayUsd();
     if (spent + amountUsd > cfg.DAILY_CAP_USD) {
         return {
@@ -141,6 +170,8 @@ export async function payX402(url, init, deps) {
         }
     }
     const settled = second.status < 400;
+    if (settled && binding)
+        binding.recordSpend(amountUsd);
     history.append({
         ts: new Date().toISOString(),
         url,

package/dist/sessions.js

@@ -0,0 +1,131 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { join } from 'node:path';
+import { z } from 'zod';
+const sessionSchema = z.object({
+    id: z.string().min(1),
+    tokenHash: z.string().regex(/^[0-9a-f]{64}$/),
+    hosts: z.array(z.string().min(1)).min(1),
+    budgetUsd: z.number().positive(),
+    maxPerCallUsd: z.number().positive(),
+    spentUsd: z.number().min(0),
+    createdAt: z.string(),
+    expiresAt: z.string(),
+    revokedAt: z.string().nullable(),
+});
+const TTL_PATTERN = /^(\d+)([mhd])?$/;
+const TTL_UNITS = { m: 60, h: 3600, d: 86400 };
+/** Read a duration written as seconds, or with an m/h/d suffix. */
+export function parseTtlSeconds(input) {
+    const match = TTL_PATTERN.exec(input.trim());
+    if (!match)
+        throw new Error(`invalid duration "${input}"; use 90, 30m, 2h, or 1d`);
+    const amount = Number(match[1]);
+    if (amount <= 0)
+        throw new Error(`duration must be greater than zero, got "${input}"`);
+    return amount * (match[2] ? TTL_UNITS[match[2]] : 1);
+}
+const hash = (token) => createHash('sha256').update(token).digest('hex');
+function sameHash(a, b) {
+    const left = Buffer.from(a, 'hex');
+    const right = Buffer.from(b, 'hex');
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/** Everything a session forbids, decided without touching disk or the chain. */
+export function checkSession(session, input) {
+    const deny = (reason) => ({ ok: false, reason });
+    if (session.revokedAt)
+        return deny(`session ${session.id} was revoked at ${session.revokedAt}`);
+    if (input.now > Date.parse(session.expiresAt)) {
+        return deny(`session ${session.id} expired at ${session.expiresAt}`);
+    }
+    let host;
+    try {
+        host = new URL(input.url).hostname;
+    }
+    catch {
+        return deny(`could not read a host from "${input.url}"`);
+    }
+    if (!session.hosts.includes(host)) {
+        return deny(`host ${host} is outside this session's scope (${session.hosts.join(', ')})`);
+    }
+    if (input.amountUsd > session.maxPerCallUsd) {
+        return deny(`$${input.amountUsd} is over the session per-call cap of $${session.maxPerCallUsd}`);
+    }
+    const remaining = session.budgetUsd - session.spentUsd;
+    if (input.amountUsd > remaining) {
+        return deny(`session budget spent: $${remaining.toFixed(6)} left of $${session.budgetUsd}`);
+    }
+    return { ok: true };
+}
+export function bindSession(store, token) {
+    return {
+        current: () => store.findByToken(token),
+        recordSpend: (amountUsd) => {
+            const session = store.findByToken(token);
+            if (session)
+                store.recordSpend(session.id, amountUsd);
+        },
+    };
+}
+export function createSessions(cfg) {
+    const filePath = join(cfg.AERON_WALLET_DIR, 'sessions.json');
+    function readAll() {
+        if (!existsSync(filePath))
+            return [];
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(filePath, 'utf8'));
+        }
+        catch {
+            throw new Error(`sessions file is not valid JSON: ${filePath}`);
+        }
+        const parsed = z.array(sessionSchema).safeParse(raw);
+        if (!parsed.success)
+            throw new Error(`sessions file is malformed: ${filePath}`);
+        return parsed.data;
+    }
+    function writeAll(sessions) {
+        mkdirSync(cfg.AERON_WALLET_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(filePath, `${JSON.stringify(sessions, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(filePath, 0o600);
+    }
+    const strip = ({ tokenHash: _tokenHash, ...rest }) => rest;
+    return {
+        create(grant, now = new Date()) {
+            const token = randomBytes(32).toString('hex');
+            const session = {
+                id: randomBytes(4).toString('hex'),
+                tokenHash: hash(token),
+                hosts: [...grant.hosts],
+                budgetUsd: grant.budgetUsd,
+                maxPerCallUsd: grant.maxPerCallUsd,
+                spentUsd: 0,
+                createdAt: now.toISOString(),
+                expiresAt: new Date(now.getTime() + grant.ttlSeconds * 1000).toISOString(),
+                revokedAt: null,
+            };
+            writeAll([...readAll(), session]);
+            return { session, token };
+        },
+        list() {
+            return readAll().map(strip);
+        },
+        findByToken(token) {
+            if (!/^[0-9a-f]{64}$/.test(token))
+                return null;
+            const wanted = hash(token);
+            return readAll().find((s) => !s.revokedAt && sameHash(s.tokenHash, wanted)) ?? null;
+        },
+        recordSpend(id, amountUsd) {
+            writeAll(readAll().map((s) => (s.id === id ? { ...s, spentUsd: s.spentUsd + amountUsd } : s)));
+        },
+        revoke(id, now = new Date()) {
+            const sessions = readAll();
+            if (!sessions.some((s) => s.id === id && !s.revokedAt))
+                return false;
+            writeAll(sessions.map((s) => (s.id === id ? { ...s, revokedAt: now.toISOString() } : s)));
+            return true;
+        },
+    };
+}

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "aeron-wallet",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "mcpName": "io.github.aeronlabs/aeron-wallet",
   "description": "Non-custodial agent wallet for Robinhood Chain. Pays x402 requests in USDG. Ships as a CLI and an MCP server.",
   "license": "MIT",
   "homepage": "https://aeron.sh/wallet/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aeronlabs/aeron-wallet.git"
+  },
   "type": "module",
   "bin": {
     "aeron-wallet": "dist/cli.js"