@blockrun/franklin 3.49.22 → 3.49.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,8 @@ import path from 'node:path';
3
3
  import os from 'node:os';
4
4
  import chalk from 'chalk';
5
5
  import { DEFAULT_PROXY_PORT } from '../config.js';
6
- import { CLAUDE_SETTINGS_FILE, PROXY_AUTH_PLACEHOLDER, proxyBaseUrl } from '../proxy/claude-settings.js';
6
+ import { CLAUDE_SETTINGS_FILE, proxyBaseUrl, restrictToOwner } from '../proxy/claude-settings.js';
7
+ import { getOrCreateProxyToken } from '../proxy/token.js';
7
8
  const LAUNCH_AGENT_DIR = path.join(os.homedir(), 'Library', 'LaunchAgents');
8
9
  const LAUNCH_AGENT_PLIST = path.join(LAUNCH_AGENT_DIR, 'ai.blockrun.franklin.plist');
9
10
  const LEGACY_LAUNCH_AGENT_PLIST = path.join(LAUNCH_AGENT_DIR, 'ai.blockrun.runcode.plist');
@@ -27,7 +28,8 @@ export async function initCommand(options) {
27
28
  ...(settings.env ?? {}),
28
29
  // 127.0.0.1, never localhost: see proxy/claude-settings.ts.
29
30
  ANTHROPIC_BASE_URL: proxyBaseUrl(port),
30
- ANTHROPIC_AUTH_TOKEN: PROXY_AUTH_PLACEHOLDER,
31
+ // The proxy refuses requests without its token (proxy/token.ts).
32
+ ANTHROPIC_AUTH_TOKEN: getOrCreateProxyToken(),
31
33
  ANTHROPIC_MODEL: 'blockrun/auto',
32
34
  ANTHROPIC_DEFAULT_SONNET_MODEL: 'anthropic/claude-sonnet-4.6',
33
35
  ANTHROPIC_DEFAULT_OPUS_MODEL: 'anthropic/claude-opus-5',
@@ -35,6 +37,7 @@ export async function initCommand(options) {
35
37
  };
36
38
  fs.mkdirSync(path.dirname(CLAUDE_SETTINGS_FILE), { recursive: true });
37
39
  fs.writeFileSync(CLAUDE_SETTINGS_FILE, JSON.stringify(settings, null, 2));
40
+ restrictToOwner(CLAUDE_SETTINGS_FILE); // holds the proxy token now
38
41
  console.log(chalk.green(`✓ Configured ${CLAUDE_SETTINGS_FILE}`));
39
42
  // ── 2. Install macOS LaunchAgent (auto-start on login) ─────────────────
40
43
  if (process.platform === 'darwin') {
@@ -9,7 +9,8 @@ import { loadChain, CHAIN_LABELS, DEFAULT_PROXY_PORT } from '../config.js';
9
9
  import { gatewayBase } from '../payments/auth-mode.js';
10
10
  import { loadConfig } from './config.js';
11
11
  import { printBanner } from '../banner.js';
12
- import { proxyBaseUrl, migrateClaudeSettingsBaseUrl, CLAUDE_SETTINGS_FILE } from '../proxy/claude-settings.js';
12
+ import { proxyBaseUrl, migrateClaudeSettings, CLAUDE_SETTINGS_FILE } from '../proxy/claude-settings.js';
13
+ import { getOrCreateProxyToken } from '../proxy/token.js';
13
14
  export async function proxyCommand(options) {
14
15
  const version = options.version ?? '1.0.0';
15
16
  const chain = loadChain();
@@ -94,9 +95,11 @@ function launchProxy(server, port, debug) {
94
95
  server.listen(port, '127.0.0.1', () => {
95
96
  console.log(chalk.green(`✓ Proxy running on port ${port}`));
96
97
  // `franklin daemon` and the LaunchAgent both start here, so this one call
97
- // fixes a localhost base URL that an older `franklin init` wrote.
98
- if (migrateClaudeSettingsBaseUrl()) {
99
- console.log(chalk.yellow(` Updated ANTHROPIC_BASE_URL in ${CLAUDE_SETTINGS_FILE} to 127.0.0.1. Restart Claude Code to pick it up.`));
98
+ // updates the env block an older `franklin init` wrote (127.0.0.1 base
99
+ // URL, real proxy token in place of the old placeholder).
100
+ const token = getOrCreateProxyToken();
101
+ if (migrateClaudeSettings(token)) {
102
+ console.log(chalk.yellow(` Updated Franklin's settings in ${CLAUDE_SETTINGS_FILE} (127.0.0.1 address, proxy token). Restart Claude Code to pick them up.`));
100
103
  }
101
104
  console.log(chalk.dim(` Usage tracking: ~/.blockrun/franklin-stats.json`));
102
105
  if (debug)
@@ -104,7 +107,7 @@ function launchProxy(server, port, debug) {
104
107
  console.log(chalk.dim(` Run 'franklin stats' to view statistics\n`));
105
108
  console.log('Set these in your shell to route Anthropic-compatible CLI agents through franklin:\n');
106
109
  console.log(chalk.bold(` export ANTHROPIC_BASE_URL=${proxyBaseUrl(port)}`));
107
- console.log(chalk.bold(` export ANTHROPIC_AUTH_TOKEN=x402-proxy-handles-auth`));
110
+ console.log(chalk.bold(` export ANTHROPIC_AUTH_TOKEN=$(cat ~/.blockrun/proxy-token)`));
108
111
  console.log(`\nThen run ${chalk.bold('claude')} in another terminal.`);
109
112
  });
110
113
  const shutdown = () => {
@@ -9,13 +9,19 @@
9
9
  * replies would reach the agent as model output, tool calls included.
10
10
  */
11
11
  export declare const CLAUDE_SETTINGS_FILE: string;
12
- /** The auth token `franklin init` writes; marks the env block as ours. */
12
+ /**
13
+ * The auth value `franklin init` wrote before 3.49.23, when the proxy took no
14
+ * token. It still marks an env block as Franklin's for the migration below.
15
+ */
13
16
  export declare const PROXY_AUTH_PLACEHOLDER = "x402-proxy-handles-auth";
14
17
  export declare function proxyBaseUrl(port: number): string;
18
+ /** The settings file now holds the proxy token: owner-only, like the token file. */
19
+ export declare function restrictToOwner(file: string): void;
15
20
  /**
16
- * Rewrite a `localhost` ANTHROPIC_BASE_URL written by `franklin init` to
17
- * 127.0.0.1. Only touches an env block that is Franklin's (our placeholder
18
- * auth token) and a URL in exactly the form init wrote, so a user's own
21
+ * Bring the env block an older `franklin init` wrote up to date: a
22
+ * `localhost` ANTHROPIC_BASE_URL becomes 127.0.0.1, and the placeholder
23
+ * ANTHROPIC_AUTH_TOKEN becomes the proxy's real token. Only touches a block
24
+ * that is Franklin's (placeholder or current token), so a user's own
19
25
  * settings are left alone. Returns true when it changed the file.
20
26
  */
21
- export declare function migrateClaudeSettingsBaseUrl(file?: string): boolean;
27
+ export declare function migrateClaudeSettings(token: string, file?: string): boolean;
@@ -12,19 +12,32 @@ import fs from 'node:fs';
12
12
  import os from 'node:os';
13
13
  import path from 'node:path';
14
14
  export const CLAUDE_SETTINGS_FILE = path.join(os.homedir(), '.claude', 'settings.json');
15
- /** The auth token `franklin init` writes; marks the env block as ours. */
15
+ /**
16
+ * The auth value `franklin init` wrote before 3.49.23, when the proxy took no
17
+ * token. It still marks an env block as Franklin's for the migration below.
18
+ */
16
19
  export const PROXY_AUTH_PLACEHOLDER = 'x402-proxy-handles-auth';
17
20
  export function proxyBaseUrl(port) {
18
21
  return `http://127.0.0.1:${port}/api`;
19
22
  }
23
+ /** The settings file now holds the proxy token: owner-only, like the token file. */
24
+ export function restrictToOwner(file) {
25
+ if (process.platform === 'win32')
26
+ return;
27
+ try {
28
+ fs.chmodSync(file, 0o600);
29
+ }
30
+ catch { /* best-effort */ }
31
+ }
20
32
  const LEGACY_BASE_URL = /^http:\/\/localhost:(\d{1,5})\/api\/?$/;
21
33
  /**
22
- * Rewrite a `localhost` ANTHROPIC_BASE_URL written by `franklin init` to
23
- * 127.0.0.1. Only touches an env block that is Franklin's (our placeholder
24
- * auth token) and a URL in exactly the form init wrote, so a user's own
34
+ * Bring the env block an older `franklin init` wrote up to date: a
35
+ * `localhost` ANTHROPIC_BASE_URL becomes 127.0.0.1, and the placeholder
36
+ * ANTHROPIC_AUTH_TOKEN becomes the proxy's real token. Only touches a block
37
+ * that is Franklin's (placeholder or current token), so a user's own
25
38
  * settings are left alone. Returns true when it changed the file.
26
39
  */
27
- export function migrateClaudeSettingsBaseUrl(file = CLAUDE_SETTINGS_FILE) {
40
+ export function migrateClaudeSettings(token, file = CLAUDE_SETTINGS_FILE) {
28
41
  let raw;
29
42
  try {
30
43
  raw = fs.readFileSync(file, 'utf-8');
@@ -40,17 +53,27 @@ export function migrateClaudeSettingsBaseUrl(file = CLAUDE_SETTINGS_FILE) {
40
53
  return false; // never rewrite a file we cannot parse
41
54
  }
42
55
  const env = settings.env;
43
- if (!env || env.ANTHROPIC_AUTH_TOKEN !== PROXY_AUTH_PLACEHOLDER)
56
+ if (!env)
44
57
  return false;
45
- const current = env.ANTHROPIC_BASE_URL;
46
- if (typeof current !== 'string')
58
+ const auth = env.ANTHROPIC_AUTH_TOKEN;
59
+ if (auth !== PROXY_AUTH_PLACEHOLDER && auth !== token)
47
60
  return false;
48
- const m = LEGACY_BASE_URL.exec(current);
49
- if (!m)
61
+ let changed = false;
62
+ if (auth === PROXY_AUTH_PLACEHOLDER) {
63
+ env.ANTHROPIC_AUTH_TOKEN = token;
64
+ changed = true;
65
+ }
66
+ const current = env.ANTHROPIC_BASE_URL;
67
+ const m = typeof current === 'string' ? LEGACY_BASE_URL.exec(current) : null;
68
+ if (m) {
69
+ env.ANTHROPIC_BASE_URL = proxyBaseUrl(Number(m[1]));
70
+ changed = true;
71
+ }
72
+ if (!changed)
50
73
  return false;
51
- env.ANTHROPIC_BASE_URL = proxyBaseUrl(Number(m[1]));
52
74
  try {
53
75
  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + (raw.endsWith('\n') ? '\n' : ''));
76
+ restrictToOwner(file);
54
77
  return true;
55
78
  }
56
79
  catch {
@@ -9,6 +9,7 @@ export interface ProxyOptions {
9
9
  fallbackEnabled?: boolean;
10
10
  requestTimeoutMs?: number;
11
11
  streamTimeoutMs?: number;
12
+ authToken?: string;
12
13
  }
13
14
  /**
14
15
  * Decide the `max_tokens` the proxy forwards upstream.
@@ -14,6 +14,7 @@ import { estimateCost } from '../pricing.js';
14
14
  import { freeVisionModel, isFreeModelId } from '../free-models.js';
15
15
  import { getMaxOutputTokens } from '../agent/optimize.js';
16
16
  import { VERSION } from '../config.js';
17
+ import { getOrCreateProxyToken, hasProxyToken } from './token.js';
17
18
  // User-Agent for backend requests
18
19
  const USER_AGENT = `franklin/${VERSION}`;
19
20
  const X_FRANKLIN_VERSION = VERSION;
@@ -216,6 +217,7 @@ export function createProxy(options) {
216
217
  // process.env for the rest of the process — and for any sibling proxy.
217
218
  const effectiveRequestTimeoutMs = options.requestTimeoutMs ?? getProxyRequestTimeoutMs();
218
219
  const effectiveStreamTimeoutMs = options.streamTimeoutMs ?? getProxyStreamTimeoutMs();
220
+ const authToken = options.authToken ?? getOrCreateProxyToken();
219
221
  let baseWallet = null;
220
222
  let solanaWallet = null;
221
223
  // Base and Arc both pay from the EVM wallet; the 402 names the network.
@@ -250,6 +252,22 @@ export function createProxy(options) {
250
252
  res.end();
251
253
  return;
252
254
  }
255
+ // Every request that can reach the gateway, and so spend from the
256
+ // wallet, must carry the proxy token. Loopback alone is not enough:
257
+ // other accounts and local web pages can reach 127.0.0.1 too.
258
+ const pathOnly = (req.url || '').replace(/^\/api/, '').split('?')[0];
259
+ if (pathOnly !== '/health' && !hasProxyToken(req.headers, authToken)) {
260
+ res.writeHead(401, { 'Content-Type': 'application/json' });
261
+ res.end(JSON.stringify({
262
+ type: 'error',
263
+ error: {
264
+ type: 'authentication_error',
265
+ message: 'Franklin proxy: missing or wrong token. Run `franklin init` to configure Claude Code, ' +
266
+ 'or set ANTHROPIC_AUTH_TOKEN to the contents of ~/.blockrun/proxy-token.',
267
+ },
268
+ }));
269
+ return;
270
+ }
253
271
  // Rate limit paid endpoints (anything but /health and /v1/models)
254
272
  const rawPath = req.url?.replace(/^\/api/, '') || '';
255
273
  const isReadOnly = rawPath.startsWith('/health') || rawPath.startsWith('/v1/models');
@@ -445,9 +463,14 @@ export function createProxy(options) {
445
463
  'X-Franklin-Version': X_FRANKLIN_VERSION,
446
464
  };
447
465
  for (const [key, value] of Object.entries(req.headers)) {
448
- if (key.toLowerCase() !== 'host' &&
449
- key.toLowerCase() !== 'content-length' &&
450
- key.toLowerCase() !== 'user-agent' && // Don't forward client's user-agent
466
+ const lower = key.toLowerCase();
467
+ if (lower !== 'host' &&
468
+ lower !== 'content-length' &&
469
+ lower !== 'user-agent' && // Don't forward client's user-agent
470
+ // The client's credential is the local proxy token: never send
471
+ // it upstream. applyGatewayAuth adds the real gateway auth.
472
+ lower !== 'authorization' &&
473
+ lower !== 'x-api-key' &&
451
474
  value) {
452
475
  headers[key] = Array.isArray(value) ? value[0] : value;
453
476
  }
@@ -0,0 +1,19 @@
1
+ /**
2
+ * The local proxy's access token.
3
+ *
4
+ * The proxy signs x402 payments from the user's wallet on every request, so
5
+ * reaching 127.0.0.1:<port> must not be enough to spend: any other account
6
+ * on the machine, or any page on a local dev server, can reach that port.
7
+ * Clients prove they are the user's own by sending this token, which lives
8
+ * in an owner-only file. `franklin init` writes it into Claude Code's
9
+ * settings as ANTHROPIC_AUTH_TOKEN, which Claude Code sends as
10
+ * `Authorization: Bearer <token>`.
11
+ */
12
+ export declare const PROXY_TOKEN_FILE: string;
13
+ /** Read the token, creating it (0600) on first use. Stable across restarts. */
14
+ export declare function getOrCreateProxyToken(file?: string): string;
15
+ /**
16
+ * True when the request carries the token as `Authorization: Bearer <t>`
17
+ * (ANTHROPIC_AUTH_TOKEN) or `x-api-key: <t>` (ANTHROPIC_API_KEY).
18
+ */
19
+ export declare function hasProxyToken(headers: Record<string, string | string[] | undefined>, token: string): boolean;
@@ -0,0 +1,56 @@
1
+ /**
2
+ * The local proxy's access token.
3
+ *
4
+ * The proxy signs x402 payments from the user's wallet on every request, so
5
+ * reaching 127.0.0.1:<port> must not be enough to spend: any other account
6
+ * on the machine, or any page on a local dev server, can reach that port.
7
+ * Clients prove they are the user's own by sending this token, which lives
8
+ * in an owner-only file. `franklin init` writes it into Claude Code's
9
+ * settings as ANTHROPIC_AUTH_TOKEN, which Claude Code sends as
10
+ * `Authorization: Bearer <token>`.
11
+ */
12
+ import crypto from 'node:crypto';
13
+ import fs from 'node:fs';
14
+ import path from 'node:path';
15
+ import { BLOCKRUN_DIR } from '../config.js';
16
+ export const PROXY_TOKEN_FILE = path.join(BLOCKRUN_DIR, 'proxy-token');
17
+ const TOKEN_RE = /^[0-9a-f]{64}$/;
18
+ /** Read the token, creating it (0600) on first use. Stable across restarts. */
19
+ export function getOrCreateProxyToken(file = PROXY_TOKEN_FILE) {
20
+ try {
21
+ const existing = fs.readFileSync(file, 'utf8').trim();
22
+ if (TOKEN_RE.test(existing)) {
23
+ try {
24
+ fs.chmodSync(file, 0o600);
25
+ }
26
+ catch { /* best-effort */ }
27
+ return existing;
28
+ }
29
+ }
30
+ catch { /* missing: create below */ }
31
+ const token = crypto.randomBytes(32).toString('hex');
32
+ fs.mkdirSync(path.dirname(file), { recursive: true });
33
+ fs.writeFileSync(file, token + '\n', { mode: 0o600 });
34
+ fs.chmodSync(file, 0o600);
35
+ return token;
36
+ }
37
+ function safeEqual(got, want) {
38
+ if (got.length !== want.length)
39
+ return false;
40
+ return crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
41
+ }
42
+ /**
43
+ * True when the request carries the token as `Authorization: Bearer <t>`
44
+ * (ANTHROPIC_AUTH_TOKEN) or `x-api-key: <t>` (ANTHROPIC_API_KEY).
45
+ */
46
+ export function hasProxyToken(headers, token) {
47
+ const pick = (v) => (Array.isArray(v) ? v[0] : v);
48
+ const auth = pick(headers['authorization']);
49
+ if (typeof auth === 'string') {
50
+ const m = /^Bearer\s+(\S+)$/i.exec(auth.trim());
51
+ if (m && safeEqual(m[1], token))
52
+ return true;
53
+ }
54
+ const key = pick(headers['x-api-key']);
55
+ return typeof key === 'string' && safeEqual(key.trim(), token);
56
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blockrun/franklin",
3
- "version": "3.49.22",
3
+ "version": "3.49.23",
4
4
  "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
5
5
  "type": "module",
6
6
  "exports": {