@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/wake-proxy/__tests__/ws-teardown-accounting.test.js

@@ -0,0 +1,143 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { WebSocket } from 'ws';
+import { configureWakeProxyRuntime } from '../home.js';
+import { proxyInternals } from '../proxy.js';
+import { getTenantActivitySnapshot } from '../state.js';
+// Regression for REPORT.md secondary defect: `activeCounts.ws` stayed non-zero after browsers
+// disconnected (stuck at 3 with no browser connected). Every terminal WS path — browser close,
+// upstream error, and wake timeout — must release the 'ws' activity so the count drains back to 0.
+const machineId = 'igd2fkrn1y1ol3vw5i6mt';
+const nodeId = 'mqt64sus-e71caa94';
+const routeUrl = 'https://7878-igd2fkrn1y1ol3vw5i6mt.example.dev';
+const now = '2026-06-25T00:00:00.000Z';
+function makeHome(tenantId) {
+    return {
+        tenantId,
+        providerName: 'none',
+        machineId,
+        homeStorage: {
+            kind: 'volume',
+            durability: 'durable-volume',
+            longTermContract: true,
+            ownerMachineId: machineId,
+            guestHome: '/home/agent',
+            volumeId: '48b59d07-8cc9-46f9-bdfd-ac99a55dff40',
+            mountPath: '/home/agent',
+        },
+        state: 'running',
+        nodeId,
+        relayToken: 'relay-token',
+        webRoute: {
+            routeId: '7878-igd2fkrn1y1ol3vw5i6mt.example.dev',
+            machineId,
+            targetPort: 7878,
+            url: routeUrl,
+            concreteUrl: routeUrl,
+            concreteUrlSource: 'provider',
+            createdAt: now,
+            raw: null,
+        },
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+function makeRuntime(tenantId, wakeTimeoutMs) {
+    const tempDir = mkdtempSync(join(tmpdir(), 'crouter-hearth-ws-'));
+    const registryPath = join(tempDir, 'homes.json');
+    const statePath = join(tempDir, 'state.json');
+    writeFileSync(registryPath, `${JSON.stringify({ [tenantId]: makeHome(tenantId) }, null, 2)}\n`, 'utf8');
+    const runtime = {
+        proxy: {
+            host: '127.0.0.1',
+            port: 7878,
+            publicOrigin: 'https://hearth-wake-proxy.fly.dev',
+            statePath,
+            m0RegistryPath: registryPath,
+            ownerUserId: 'owner-user',
+            defaultTenantId: tenantId,
+            ownerTokenHash: 'hash',
+            idlePauseMs: 0,
+            wakeTimeoutMs,
+            readyTimeoutMs: 2_000,
+            cookieSecure: true,
+            seedHome: null,
+        },
+        m0: {
+            providerName: 'none',
+            registryPath,
+            guestUser: 'agent',
+            guestHome: '/home/agent',
+            guestCodePath: '/opt/crouter',
+            webPort: 7878,
+            nodeKind: 'general',
+            piPackages: [],
+            piAuthJson: null,
+            relayToken: null,
+        },
+    };
+    configureWakeProxyRuntime(runtime);
+    return runtime;
+}
+// Minimal WebSocket stand-in: the proxy only touches readyState, on/off/emit, ping, terminate,
+// send, and close. Events are driven manually; close() records but does not auto-emit so the two
+// legs don't cascade through each other.
+class FakeWs extends EventEmitter {
+    readyState = WebSocket.OPEN;
+    closeCalls = [];
+    terminateCount = 0;
+    ping() { }
+    send() { }
+    terminate() {
+        this.terminateCount += 1;
+        this.readyState = WebSocket.CLOSED;
+    }
+    close(code, reason) {
+        this.closeCalls.push({ code: code ?? 1000, reason: reason ?? '' });
+        this.readyState = WebSocket.CLOSED;
+    }
+}
+function wsCount(tenantId) {
+    return getTenantActivitySnapshot(tenantId).counts.ws;
+}
+test('ws activity drains to 0 when the browser closes', async () => {
+    const tenantId = 'ws-close';
+    const runtime = makeRuntime(tenantId, 30_000);
+    const browser = new FakeWs();
+    const upstream = new FakeWs();
+    await proxyInternals.proxyWebSocketBrowser(browser, nodeId, tenantId, runtime, {
+        ensureAwake: async () => ({ routeUrl, relayToken: 'relay-token' }),
+        createUpstream: () => upstream,
+    });
+    assert.equal(wsCount(tenantId), 1);
+    browser.emit('close', 1000, Buffer.from('bye'));
+    assert.equal(wsCount(tenantId), 0);
+});
+test('ws activity drains to 0 when the upstream leg errors', async () => {
+    const tenantId = 'ws-upstream-error';
+    const runtime = makeRuntime(tenantId, 30_000);
+    const browser = new FakeWs();
+    const upstream = new FakeWs();
+    await proxyInternals.proxyWebSocketBrowser(browser, nodeId, tenantId, runtime, {
+        ensureAwake: async () => ({ routeUrl, relayToken: 'relay-token' }),
+        createUpstream: () => upstream,
+    });
+    assert.equal(wsCount(tenantId), 1);
+    upstream.emit('error', new Error('upstream boom'));
+    assert.equal(wsCount(tenantId), 0);
+});
+test('ws activity drains to 0 when the wake times out', async () => {
+    const tenantId = 'ws-wake-timeout';
+    const runtime = makeRuntime(tenantId, 20);
+    const browser = new FakeWs();
+    await proxyInternals.proxyWebSocketBrowser(browser, nodeId, tenantId, runtime, {
+        // Never resolves — withWakeTimeout(20ms) rejects and the catch path must release the activity.
+        ensureAwake: () => new Promise(() => { }),
+        createUpstream: () => new FakeWs(),
+    });
+    assert.equal(wsCount(tenantId), 0);
+});

package/dist/hearth/wake-proxy/anthropic-oauth.d.ts

@@ -0,0 +1,58 @@
+import type { TenantId } from '../../core/hearth/types.js';
+export declare const ANTHROPIC_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+export declare const ANTHROPIC_AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
+export declare const ANTHROPIC_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+export declare const ANTHROPIC_REDIRECT_URI = "http://localhost:53692/callback";
+export declare const ANTHROPIC_SCOPES = "org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload";
+export declare const ANTHROPIC_SESSION_TTL_MS: number;
+export declare const ANTHROPIC_CALLBACK_MAX_URL_LENGTH = 2048;
+export declare const ANTHROPIC_TOKEN_TIMEOUT_MS = 30000;
+export declare const ANTHROPIC_TOKEN_SKEW_MS: number;
+export interface AnthropicOAuthCredential {
+    type: 'oauth';
+    refresh: string;
+    access: string;
+    expires: number;
+}
+export interface AnthropicOAuthSession {
+    tenantId: TenantId;
+    sessionId: string;
+    state: string;
+    verifier: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface AnthropicOAuthStartSuccess {
+    ok: true;
+    sessionId: string;
+    authUrl: string;
+    expiresAt: number;
+}
+export type AnthropicOAuthStartResult = AnthropicOAuthStartSuccess;
+export interface AnthropicOAuthFinishInput {
+    tenantId: TenantId;
+    sessionId: string;
+    redirectUrl: string;
+}
+export interface AnthropicOAuthFinishSuccess extends AnthropicOAuthCredential {
+    ok: true;
+    sessionId: string;
+    credential: AnthropicOAuthCredential;
+    expiresAt: number;
+}
+export interface AnthropicOAuthFinishFailure {
+    ok: false;
+    status: 400 | 401 | 409 | 502;
+    error: string;
+}
+export type AnthropicOAuthFinishResult = AnthropicOAuthFinishSuccess | AnthropicOAuthFinishFailure;
+export interface AnthropicOAuthDeps {
+    now?: () => number;
+    randomBytes?: (size: number) => Buffer;
+    sha256?: (input: string) => Buffer;
+    fetch?: typeof fetch;
+    fetchTimeoutMs?: number;
+}
+export declare function startAnthropicOAuthSession(tenantId: TenantId, now?: () => number, deps?: Pick<AnthropicOAuthDeps, 'randomBytes' | 'sha256'>): AnthropicOAuthStartResult;
+export declare function finishAnthropicOAuthSession(input: AnthropicOAuthFinishInput, deps?: AnthropicOAuthDeps): Promise<AnthropicOAuthFinishResult>;
+export declare function redactAnthropicOAuthMessage(message: string): string;

package/dist/hearth/wake-proxy/anthropic-oauth.js

@@ -0,0 +1,189 @@
+import { createHash, randomBytes as nodeRandomBytes } from 'node:crypto';
+import { redactWakeProxyMessage } from './redact.js';
+export const ANTHROPIC_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
+export const ANTHROPIC_AUTHORIZE_URL = 'https://claude.ai/oauth/authorize';
+export const ANTHROPIC_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
+export const ANTHROPIC_REDIRECT_URI = 'http://localhost:53692/callback';
+export const ANTHROPIC_SCOPES = 'org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload';
+export const ANTHROPIC_SESSION_TTL_MS = 10 * 60_000;
+export const ANTHROPIC_CALLBACK_MAX_URL_LENGTH = 2048;
+export const ANTHROPIC_TOKEN_TIMEOUT_MS = 30_000;
+export const ANTHROPIC_TOKEN_SKEW_MS = 5 * 60_000;
+const sessions = new Map();
+function defaultRandomBytes(size) {
+    return nodeRandomBytes(size);
+}
+function defaultSha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest();
+}
+function purgeExpiredSessions(now, tenantId) {
+    for (const [key, session] of sessions) {
+        if ((tenantId === undefined || key === tenantId) && session.expiresAt <= now) {
+            sessions.delete(key);
+        }
+    }
+}
+function buildAuthUrl(session, challenge) {
+    const params = new URLSearchParams({
+        // claude.ai/oauth/authorize requires `code=true` (the Claude Code authorize
+        // flow param); omitting it makes the endpoint reject with "Invalid request
+        // format". Claude Code also requires `state` to be the PKCE verifier so
+        // the authorize request satisfies `code_challenge === S256(state)`; the
+        // installed @earendil-works/pi-ai adapter does the same (`state: verifier`).
+        code: 'true',
+        client_id: ANTHROPIC_CLIENT_ID,
+        response_type: 'code',
+        redirect_uri: ANTHROPIC_REDIRECT_URI,
+        scope: ANTHROPIC_SCOPES,
+        state: session.state,
+        code_challenge: challenge,
+        code_challenge_method: 'S256',
+    });
+    return `${ANTHROPIC_AUTHORIZE_URL}?${params.toString()}`;
+}
+function buildSession(tenantId, now, randomBytes, sha256) {
+    const sessionId = randomBytes(16).toString('base64url');
+    const verifier = randomBytes(32).toString('base64url');
+    const session = {
+        tenantId,
+        sessionId,
+        state: verifier,
+        verifier,
+        createdAt: now,
+        expiresAt: now + ANTHROPIC_SESSION_TTL_MS,
+    };
+    const challenge = sha256(verifier).toString('base64url');
+    return { session, authUrl: buildAuthUrl(session, challenge) };
+}
+function safeError(status, error) {
+    return { ok: false, status, error: redactWakeProxyMessage(error) };
+}
+function parseCallbackUrl(raw) {
+    if (raw.length > ANTHROPIC_CALLBACK_MAX_URL_LENGTH) {
+        return safeError(400, 'Anthropic callback URL is too long');
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return safeError(400, 'Anthropic callback URL is invalid');
+    }
+    if (url.protocol !== 'http:' || url.hostname !== 'localhost' || url.port !== '53692' || url.pathname !== '/callback') {
+        return safeError(400, 'Anthropic callback URL must be http://localhost:53692/callback');
+    }
+    const error = url.searchParams.get('error');
+    if (error !== null && error.trim() !== '') {
+        return safeError(400, `Anthropic callback reported error=${error}`);
+    }
+    const code = url.searchParams.get('code')?.trim() ?? '';
+    const state = url.searchParams.get('state')?.trim() ?? '';
+    if (code === '' || state === '') {
+        return safeError(400, 'Anthropic callback is missing code or state');
+    }
+    return { code, state };
+}
+async function postJson(url, body, deps) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort(new Error('Anthropic OAuth token exchange timed out'));
+    }, deps.fetchTimeoutMs);
+    timeout.unref();
+    try {
+        const response = await deps.fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const responseBody = await response.text();
+        if (!response.ok) {
+            return safeError(502, `Anthropic token exchange failed with HTTP ${response.status} ${response.statusText}${responseBody.trim() === '' ? '' : `: ${responseBody}`}`);
+        }
+        return { ok: true, body: responseBody };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return safeError(502, `Anthropic token exchange request failed: ${message}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function validateTokenExchangeResponse(body, now) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return safeError(502, `Anthropic token exchange returned invalid JSON: ${body}`);
+    }
+    const access = typeof parsed.access_token === 'string' ? parsed.access_token.trim() : '';
+    const refresh = typeof parsed.refresh_token === 'string' ? parsed.refresh_token.trim() : '';
+    const expiresIn = typeof parsed.expires_in === 'number' ? parsed.expires_in : Number.NaN;
+    if (access === '' || refresh === '' || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+        return safeError(502, 'Anthropic token exchange response is missing access_token, refresh_token, or positive expires_in');
+    }
+    return { type: 'oauth', access, refresh, expires: now() + expiresIn * 1000 - ANTHROPIC_TOKEN_SKEW_MS };
+}
+export function startAnthropicOAuthSession(tenantId, now = Date.now, deps = {}) {
+    const randomBytes = deps.randomBytes ?? defaultRandomBytes;
+    const sha256 = deps.sha256 ?? defaultSha256;
+    const current = now();
+    // A fresh start always supersedes any prior pending session for this tenant
+    // (stale lock, double-click, or lost popup). The newest session wins; any
+    // superseded callback then fails the sessionId/state checks in
+    // finishAnthropicOAuthSession, so old state can never write credentials.
+    // GC expired sessions across all tenants while we hold the map.
+    purgeExpiredSessions(current);
+    const { session, authUrl } = buildSession(tenantId, current, randomBytes, sha256);
+    sessions.set(tenantId, session);
+    return { ok: true, sessionId: session.sessionId, authUrl, expiresAt: session.expiresAt };
+}
+export async function finishAnthropicOAuthSession(input, deps = {}) {
+    const now = deps.now ?? Date.now;
+    const fetchImpl = deps.fetch ?? fetch;
+    const fetchTimeoutMs = deps.fetchTimeoutMs ?? ANTHROPIC_TOKEN_TIMEOUT_MS;
+    const current = now();
+    purgeExpiredSessions(current, input.tenantId);
+    const session = sessions.get(input.tenantId);
+    if (session === undefined) {
+        return safeError(400, 'Anthropic OAuth session not found or expired');
+    }
+    sessions.delete(input.tenantId);
+    if (session.sessionId !== input.sessionId) {
+        return safeError(400, 'Anthropic OAuth session id does not match the active session');
+    }
+    const parsed = parseCallbackUrl(input.redirectUrl);
+    if ('status' in parsed)
+        return parsed;
+    if (parsed.state !== session.state) {
+        return safeError(400, 'Anthropic OAuth callback state mismatch');
+    }
+    const result = await postJson(ANTHROPIC_TOKEN_URL, {
+        grant_type: 'authorization_code',
+        client_id: ANTHROPIC_CLIENT_ID,
+        code: parsed.code,
+        state: parsed.state,
+        redirect_uri: ANTHROPIC_REDIRECT_URI,
+        code_verifier: session.verifier,
+    }, { fetch: fetchImpl, fetchTimeoutMs });
+    if ('status' in result)
+        return result;
+    const credential = validateTokenExchangeResponse(result.body, now);
+    if ('status' in credential)
+        return credential;
+    return {
+        ok: true,
+        sessionId: session.sessionId,
+        ...credential,
+        credential,
+        expiresAt: credential.expires,
+    };
+}
+export function redactAnthropicOAuthMessage(message) {
+    return redactWakeProxyMessage(message);
+}

package/dist/hearth/wake-proxy/auth.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HearthProxyConfig, HearthProxyState, HearthWakeProxyRuntime } from './types.js';
+export type OwnerAuthSource = 'query' | 'bearer' | 'cookie';
+export interface OwnerAuthResult {
+    ownerUserId: string;
+    tenantId: string;
+    source: OwnerAuthSource;
+    token: string;
+}
+export interface ResolveOwnerAuthOptions {
+    rejectQuery?: boolean;
+    requireCookieOrigin?: boolean;
+}
+export declare function currentProxyState(runtime: HearthWakeProxyRuntime): HearthProxyState;
+export declare function resolveOwnerAuth(req: IncomingMessage, config: HearthProxyConfig, state: HearthProxyState, options?: ResolveOwnerAuthOptions): OwnerAuthResult | null;
+export declare function resolveOwnerWriteAuth(req: IncomingMessage, config: HearthProxyConfig, state: HearthProxyState): OwnerAuthResult | null;
+export declare function requireOwner(req: IncomingMessage, res: ServerResponse, config: HearthProxyConfig, state: HearthProxyState): {
+    ownerUserId: string;
+    tenantId: string;
+} | null;
+export declare function setOwnerCookie(res: ServerResponse, token: string, config: HearthProxyConfig): void;
+export declare function ownerAuthRedactedMessage(message: string): string;

package/dist/hearth/wake-proxy/auth.js

@@ -0,0 +1,128 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { general } from '../../core/errors.js';
+import { ensureProxyState, loadProxyState } from './state.js';
+const COOKIE_NAME = 'hearth_owner';
+function sha256Hex(token) {
+    return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+function normalizeHash(hash) {
+    const trimmed = hash.trim();
+    const body = trimmed.startsWith('sha256:') ? trimmed.slice('sha256:'.length) : trimmed;
+    return /^[0-9a-fA-F]{64}$/.test(body) ? body.toLowerCase() : '';
+}
+function parseCookieHeader(header) {
+    const out = {};
+    if (header === undefined || header.trim() === '')
+        return out;
+    for (const part of header.split(';')) {
+        const idx = part.indexOf('=');
+        if (idx <= 0)
+            continue;
+        const key = part.slice(0, idx).trim();
+        const value = part.slice(idx + 1).trim();
+        if (key !== '')
+            out[key] = value;
+    }
+    return out;
+}
+function requestUrl(req) {
+    return new URL(req.url ?? '/', 'http://127.0.0.1');
+}
+export function currentProxyState(runtime) {
+    return loadProxyState(runtime.proxy.statePath) ?? ensureProxyState(runtime.proxy);
+}
+function queryToken(req) {
+    const token = requestUrl(req).searchParams.get('token')?.trim() ?? '';
+    return token === '' ? null : token;
+}
+function bearerToken(req) {
+    const authorization = req.headers.authorization;
+    if (typeof authorization !== 'string')
+        return null;
+    const match = /^Bearer\s+(.+)$/.exec(authorization.trim());
+    const token = match?.[1]?.trim() ?? '';
+    return token === '' ? null : token;
+}
+function cookieToken(req) {
+    const token = parseCookieHeader(req.headers.cookie)[COOKIE_NAME];
+    if (token === undefined || token.trim() === '')
+        return null;
+    try {
+        return decodeURIComponent(token.trim());
+    }
+    catch {
+        return null;
+    }
+}
+function tokenMatches(secretHash, token) {
+    const expected = normalizeHash(secretHash);
+    if (expected === '')
+        return false;
+    const candidate = sha256Hex(token);
+    return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(candidate, 'hex'));
+}
+export function resolveOwnerAuth(req, config, state, options = {}) {
+    const query = queryToken(req);
+    if (query !== null) {
+        if (options.rejectQuery === true)
+            return null;
+        if (tokenMatches(state.owner.tokenHash, query)) {
+            return { ownerUserId: state.owner.ownerUserId, tenantId: state.owner.defaultTenantId, source: 'query', token: query };
+        }
+        return null;
+    }
+    const bearer = bearerToken(req);
+    if (bearer !== null) {
+        if (tokenMatches(state.owner.tokenHash, bearer)) {
+            return { ownerUserId: state.owner.ownerUserId, tenantId: state.owner.defaultTenantId, source: 'bearer', token: bearer };
+        }
+        return null;
+    }
+    const cookie = cookieToken(req);
+    if (cookie !== null) {
+        if (!tokenMatches(state.owner.tokenHash, cookie))
+            return null;
+        const origin = req.headers.origin?.trim() ?? '';
+        if (options.requireCookieOrigin === true) {
+            if (origin === '' || origin !== config.publicOrigin) {
+                throw general('owner cookie origin mismatch', { expectedOrigin: config.publicOrigin, origin: origin === '' ? null : origin });
+            }
+        }
+        else if (origin !== '' && origin !== config.publicOrigin) {
+            throw general('owner cookie origin mismatch', { expectedOrigin: config.publicOrigin, origin });
+        }
+        return { ownerUserId: state.owner.ownerUserId, tenantId: state.owner.defaultTenantId, source: 'cookie', token: cookie };
+    }
+    return null;
+}
+export function resolveOwnerWriteAuth(req, config, state) {
+    return resolveOwnerAuth(req, config, state, { rejectQuery: true, requireCookieOrigin: true });
+}
+export function requireOwner(req, res, config, state) {
+    const auth = resolveOwnerAuth(req, config, state);
+    if (auth !== null)
+        return { ownerUserId: auth.ownerUserId, tenantId: auth.tenantId };
+    if (!res.headersSent) {
+        res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' });
+    }
+    res.end('owner token required\n');
+    return null;
+}
+export function setOwnerCookie(res, token, config) {
+    void config.cookieSecure;
+    const cookie = [
+        `${COOKIE_NAME}=${encodeURIComponent(token)}`,
+        'Path=/',
+        'HttpOnly',
+        'Secure',
+        'SameSite=Lax',
+        `Max-Age=${365 * 24 * 60 * 60}`,
+    ].join('; ');
+    res.setHeader('Set-Cookie', cookie);
+}
+export function ownerAuthRedactedMessage(message) {
+    return message
+        .replace(/(Authorization:\s*Bearer\s+)[^\s]+/gi, '$1[redacted]')
+        .replace(/([?&]token=)[^&#\s]+/gi, '$1[redacted]')
+        .replace(/(hearth_owner=)[^;\s]+/gi, '$1[redacted]');
+}

package/dist/hearth/wake-proxy/config.d.ts

@@ -0,0 +1,2 @@
+import type { HearthProxyConfig } from './types.js';
+export declare function loadHearthProxyConfig(env?: NodeJS.ProcessEnv): HearthProxyConfig;