@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/hearth/__tests__/model-auth-guest.test.js

@@ -0,0 +1,151 @@
+// model-auth-guest.test.ts — focused P3.3b in-guest model-auth lane regression
+// test, added under Silas's 2026-06-30 category-3 Hearth/control-plane
+// carve-out (CLAUDE.md testing policy) for the load-bearing invariants named
+// in the P3.3b implementation review
+// (.crouter/canvas/nodes/mr1exjvw-73c75466/context/p3p3b-in-guest-model-auth-review.md,
+// "Minor — no ported unit test for the in-guest lane"):
+//
+//   1. Tokenless/invalid-token access to the model-auth lane fails closed with
+//      401 (strict relay-token gate; no loopback bypass) — the design-review
+//      Major that the lane must use `requestTokenMatches`, never
+//      `requestAllowed()` (which would accept a tokenless loopback request).
+//   2. `status` returns 200 with a correct unauthenticated/authenticated body
+//      when there is exactly one pi `auth.json` in the intended store — locks
+//      in the fix for the old M0 wake-proxy 502 bug class.
+//   3. No response body ever includes access/refresh credential material.
+//
+// This drives the real seam end-to-end: `startWebServer` (src/clients/web/
+// server.ts) mounts `handleHearthModelAuthRequest`
+// (../model-auth-guest.ts) behind its relay-token gate, and the test points
+// pi's real `AuthStorage` at a temp dir via `PI_CODING_AGENT_DIR` (the same
+// env var `getAgentDir()` honors in production) so the lane reads/writes a
+// real single `auth.json` with no mocking of the module under test.
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { AuthStorage } from '@earendil-works/pi-coding-agent';
+import { startWebServer } from '../../../clients/web/server.js';
+const RELAY_TOKEN = 'model-auth-test-relay-token';
+const STATUS_PATH = '/__hearth/model-auth/anthropic/status';
+const START_PATH = '/__hearth/model-auth/anthropic/start';
+const FINISH_PATH = '/__hearth/model-auth/anthropic/finish';
+async function withServer(fn) {
+    const server = await startWebServer({ port: 0, host: '127.0.0.1', token: RELAY_TOKEN });
+    try {
+        await fn(server);
+    }
+    finally {
+        await server.close();
+    }
+}
+/** Point pi's AuthStorage at a fresh temp dir (the same env var `getAgentDir()`
+ *  reads in production) for the duration of `fn`, then restore the prior
+ *  value. Returns the temp dir so a caller can seed `auth.json` before use. */
+async function withTempAgentDir(fn) {
+    const agentDir = mkdtempSync(join(tmpdir(), 'model-auth-guest-test-'));
+    const prior = process.env['PI_CODING_AGENT_DIR'];
+    process.env['PI_CODING_AGENT_DIR'] = agentDir;
+    try {
+        await fn(agentDir);
+    }
+    finally {
+        if (prior === undefined) {
+            delete process.env['PI_CODING_AGENT_DIR'];
+        }
+        else {
+            process.env['PI_CODING_AGENT_DIR'] = prior;
+        }
+        rmSync(agentDir, { recursive: true, force: true });
+    }
+}
+test('model-auth lane fails closed with 401 for tokenless and invalid-token requests (no loopback bypass)', async () => {
+    await withTempAgentDir(async (agentDir) => {
+        // Exactly one auth.json present — proves the 401 is the token gate, not a
+        // downstream store-resolution failure.
+        writeFileSync(join(agentDir, 'auth.json'), '{}\n', 'utf8');
+        await withServer(async (server) => {
+            // No credentials at all, on loopback — this is the design-review Major:
+            // the lane must use the strict `requestTokenMatches` predicate, never
+            // `requestAllowed()`, which accepts a tokenless loopback request for every
+            // OTHER route on this same server.
+            for (const [method, path] of [
+                ['GET', STATUS_PATH],
+                ['POST', START_PATH],
+                ['POST', FINISH_PATH],
+            ]) {
+                const res = await fetch(`${server.url}${path}`, { method });
+                assert.equal(res.status, 401, `${method} ${path} with no token`);
+            }
+            // Wrong bearer token.
+            const wrongBearer = await fetch(`${server.url}${STATUS_PATH}`, {
+                headers: { authorization: 'Bearer not-the-relay-token' },
+            });
+            assert.equal(wrongBearer.status, 401);
+            // Wrong query token.
+            const wrongQuery = await fetch(`${server.url}${STATUS_PATH}?token=not-the-relay-token`);
+            assert.equal(wrongQuery.status, 401);
+            // Sanity: the SAME server, SAME loopback bind, with the correct token
+            // succeeds — proves the 401s above are the gate rejecting bad
+            // credentials, not some other failure making every request fail.
+            const correct = await fetch(`${server.url}${STATUS_PATH}`, {
+                headers: { authorization: `Bearer ${RELAY_TOKEN}` },
+            });
+            assert.equal(correct.status, 200);
+        });
+    });
+});
+test('model-auth status returns 200 with correct unauthenticated/authenticated state for a single auth.json (M0 502 regression)', async () => {
+    await withServer(async (server) => {
+        // Unauthenticated: exactly one auth.json, no anthropic credential stored.
+        await withTempAgentDir(async (agentDir) => {
+            writeFileSync(join(agentDir, 'auth.json'), '{}\n', 'utf8');
+            const res = await fetch(`${server.url}${STATUS_PATH}`, {
+                headers: { authorization: `Bearer ${RELAY_TOKEN}` },
+            });
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            assert.deepEqual(body, { storedOauth: false, expiresAt: null, adapterConfigured: true });
+        });
+        // Authenticated: exactly one auth.json, with a real stored anthropic oauth
+        // credential written through the real AuthStorage (not hand-crafted JSON).
+        await withTempAgentDir(async () => {
+            const storage = AuthStorage.create();
+            storage.set('anthropic', { type: 'oauth', access: 'access-secret', refresh: 'refresh-secret', expires: 4_102_444_800_000 });
+            assert.deepEqual(storage.drainErrors(), []);
+            const res = await fetch(`${server.url}${STATUS_PATH}`, {
+                headers: { authorization: `Bearer ${RELAY_TOKEN}` },
+            });
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            assert.deepEqual(body, { storedOauth: true, expiresAt: 4_102_444_800_000, adapterConfigured: true });
+        });
+    });
+});
+test('model-auth status response never includes access/refresh credential material', async () => {
+    await withServer(async (server) => {
+        await withTempAgentDir(async () => {
+            const storage = AuthStorage.create();
+            storage.set('anthropic', {
+                type: 'oauth',
+                access: 'super-secret-access-token',
+                refresh: 'super-secret-refresh-token',
+                expires: 4_102_444_800_000,
+            });
+            assert.deepEqual(storage.drainErrors(), []);
+            const res = await fetch(`${server.url}${STATUS_PATH}`, {
+                headers: { authorization: `Bearer ${RELAY_TOKEN}` },
+            });
+            assert.equal(res.status, 200);
+            const rawText = await res.text();
+            const body = JSON.parse(rawText);
+            // The response is exactly the redacted status shape — no access/refresh
+            // keys or raw secret material anywhere in the body.
+            assert.deepEqual(Object.keys(body).sort(), ['adapterConfigured', 'expiresAt', 'storedOauth']);
+            assert.equal(rawText.includes('super-secret-access-token'), false);
+            assert.equal(rawText.includes('super-secret-refresh-token'), false);
+            assert.equal(/access|refresh/i.test(rawText), false);
+        });
+    });
+});

package/dist/core/hearth/config.d.ts

@@ -0,0 +1,3 @@
+import type { M0Config } from './types.js';
+export declare function hearthHomeImageRefForVersion(version: string): string;
+export declare function loadM0Config(env?: NodeJS.ProcessEnv): M0Config;

package/dist/core/hearth/config.js

@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { general } from '../errors.js';
+const ENV = {
+    provider: 'CRTR_HEARTH_PROVIDER',
+    registry: 'CRTR_HEARTH_M0_REGISTRY',
+    guestUser: 'CRTR_HEARTH_M0_GUEST_USER',
+    guestHome: 'CRTR_HEARTH_M0_GUEST_HOME',
+    guestCode: 'CRTR_HEARTH_M0_GUEST_CODE',
+    webPort: 'CRTR_HEARTH_M0_WEB_PORT',
+    image: 'CRTR_HEARTH_M0_IMAGE',
+    templateVersion: 'CRTR_HEARTH_M0_TEMPLATE_VERSION',
+    volumeSizeGb: 'CRTR_HEARTH_M0_VOLUME_SIZE_GB',
+    nodeKind: 'CRTR_HEARTH_M0_NODE_KIND',
+    piPackages: 'CRTR_HEARTH_M0_PI_PACKAGES',
+    piAuthJson: 'CRTR_HEARTH_M0_PI_AUTH_JSON',
+    relayToken: 'CRTR_HEARTH_M0_RELAY_TOKEN',
+};
+function expandHomePath(input) {
+    if (input.startsWith('~'))
+        return join(homedir(), input.slice(1));
+    return resolve(input);
+}
+function parsePort(value, fallback, name) {
+    if (value === undefined || value === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        throw general(`invalid ${name}: ${value}`, { env: name });
+    }
+    return parsed;
+}
+function parseVolumeSizeGb(value, fallback, name) {
+    if (value === undefined || value === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 10) {
+        throw general(`invalid ${name}: ${value}`, { env: name, minimumGb: 10 });
+    }
+    return parsed;
+}
+function readCrtrVersion() {
+    const file = new URL('../../../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(file, 'utf8'));
+    if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
+        throw general('missing crtr package version', { packageJson: file.pathname });
+    }
+    return pkg.version;
+}
+export function hearthHomeImageRefForVersion(version) {
+    return `crouter-hearth-home-${version.replace(/\./g, '-')}`;
+}
+const SAFE_PI_PACKAGE_SPEC = /^[A-Za-z0-9@/_:.-]+$/;
+const DEFAULT_PI_PACKAGES = ['npm:pi-claude-oauth-adapter@0.1.2'];
+function parsePiPackages(env) {
+    const raw = env[ENV.piPackages]?.trim();
+    if (raw === undefined || raw === '')
+        return [...DEFAULT_PI_PACKAGES];
+    const tokens = raw.split(/[,\s]+/).map((token) => token.trim()).filter((token) => token !== '');
+    if (tokens.length === 0) {
+        throw general(`invalid ${ENV.piPackages}: ${raw}`, { env: ENV.piPackages });
+    }
+    if (tokens.length === 1 && tokens[0]?.toLowerCase() === 'none')
+        return [];
+    if (tokens.some((token) => token.toLowerCase() === 'none')) {
+        throw general(`invalid ${ENV.piPackages}: none must be the only value`, { env: ENV.piPackages });
+    }
+    for (const spec of tokens) {
+        if (!SAFE_PI_PACKAGE_SPEC.test(spec)) {
+            throw general(`invalid ${ENV.piPackages}: ${spec}`, { env: ENV.piPackages, packageSpec: spec });
+        }
+    }
+    return tokens;
+}
+export function loadM0Config(env = process.env) {
+    const providerName = (env[ENV.provider] ?? '').trim().toLowerCase();
+    const registryPath = expandHomePath(env[ENV.registry] ?? '~/.crouter/hearth/m0/homes.json');
+    const guestUser = (env[ENV.guestUser] ?? 'agent').trim();
+    const guestHome = expandHomePath(env[ENV.guestHome] ?? '/home/agent');
+    const guestCodePath = expandHomePath(env[ENV.guestCode] ?? '/opt/crouter');
+    const piPackages = parsePiPackages(env);
+    const webPort = parsePort(env[ENV.webPort], 7878, ENV.webPort);
+    const templateVersion = (env[ENV.templateVersion] ?? readCrtrVersion()).trim();
+    if (templateVersion === '') {
+        throw general(`invalid ${ENV.templateVersion}: empty`, { env: ENV.templateVersion });
+    }
+    const imageRef = (env[ENV.image] ?? hearthHomeImageRefForVersion(templateVersion)).trim();
+    if (imageRef === '') {
+        throw general(`invalid ${ENV.image}: empty`, { env: ENV.image });
+    }
+    const volumeSizeGb = parseVolumeSizeGb(env[ENV.volumeSizeGb], 10, ENV.volumeSizeGb);
+    const nodeKind = (env[ENV.nodeKind] ?? 'general').trim();
+    const piAuthJson = env[ENV.piAuthJson]?.trim() || null;
+    const relayToken = env[ENV.relayToken]?.trim() || null;
+    return {
+        providerName,
+        registryPath,
+        guestUser,
+        guestHome,
+        guestCodePath,
+        piPackages,
+        webPort,
+        imageRef,
+        templateVersion,
+        volumeSizeGb,
+        nodeKind,
+        piAuthJson,
+        relayToken,
+    };
+}

package/dist/core/hearth/guest-env.d.ts

@@ -0,0 +1,9 @@
+import type { M0Config } from './types.js';
+/** The complete home env table per R-DUR-8 — the one place that owns it.
+ *  `HOME`/`CRTR_HOME` resolve onto the durable user volume (canvas/auth/config
+ *  state survives destroy→recreate there); `CRTR_SOCK_DIR`/`CRTR_PIDFILE`
+ *  resolve onto tmpfs (rebound fresh every boot, never stale-on-volume);
+ *  `CRTR_CANVAS_DB` stays UNSET so `canvas.db` follows `CRTR_HOME` onto the
+ *  volume (its fcntl/WAL locks need real local-disk semantics, which the
+ *  block volume provides — unlike the NFS case `CRTR_CANVAS_DB` exists for). */
+export declare function guestEnv(config: M0Config): Record<string, string>;

package/dist/core/hearth/guest-env.js

@@ -0,0 +1,27 @@
+import { join } from 'node:path';
+// tmpfs base for the home's socket + pidfile (R-DUR-8/R-HOME-3): a unix
+// socket cannot bind on the durable NFS/block volume and a pidfile must never
+// be stale-on-volume across destroy/recreate, so both live process-local on
+// tmpfs instead. `/run` is the conventional tmpfs mount on the baked Blaxel
+// image; the bootstrap chain (blaxel-bootstrap.ts) mkdirs this before the
+// daemon starts.
+const GUEST_TMPFS_BASE = '/run/crtr';
+/** The complete home env table per R-DUR-8 — the one place that owns it.
+ *  `HOME`/`CRTR_HOME` resolve onto the durable user volume (canvas/auth/config
+ *  state survives destroy→recreate there); `CRTR_SOCK_DIR`/`CRTR_PIDFILE`
+ *  resolve onto tmpfs (rebound fresh every boot, never stale-on-volume);
+ *  `CRTR_CANVAS_DB` stays UNSET so `canvas.db` follows `CRTR_HOME` onto the
+ *  volume (its fcntl/WAL locks need real local-disk semantics, which the
+ *  block volume provides — unlike the NFS case `CRTR_CANVAS_DB` exists for). */
+export function guestEnv(config) {
+    const home = config.guestHome;
+    return {
+        HOME: home,
+        CRTR_HOME: join(home, '.crouter', 'canvas'),
+        CRTR_SOCK_DIR: join(GUEST_TMPFS_BASE, 'socks'),
+        CRTR_PIDFILE: join(GUEST_TMPFS_BASE, 'crtrd.pid'),
+        PI_CODING_AGENT_DIR: join(home, '.pi', 'agent'),
+        PATH: `${join(home, '.crtr-runtime', 'bin')}:/usr/local/bin:/usr/bin:/bin`,
+        SANDBOX_DISABLE_PROCESS_LOGGING: 'true',
+    };
+}

package/dist/core/hearth/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { loadM0Config } from './config.js';
+export { getHomeBackend, type HomeBackend } from './provider.js';
+export { readRegistry, writeRegistry, getHome, putHome, updateHome, listHomes, acquireRegistryLock } from './registry.js';
+export { guestEnv } from './guest-env.js';

package/dist/core/hearth/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { loadM0Config } from './config.js';
+export { getHomeBackend } from './provider.js';
+export { readRegistry, writeRegistry, getHome, putHome, updateHome, listHomes, acquireRegistryLock } from './registry.js';
+export { guestEnv } from './guest-env.js';

package/dist/core/hearth/model-auth-guest.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Dispatch one `/__hearth/model-auth/anthropic/{status,start,finish}` request.
+ *  The caller (src/clients/web/server.ts) has already matched the path prefix
+ *  and enforced the relay token — this function assumes both are done and
+ *  handles ONLY routing-within-the-lane, method checks, and the Hearth/OAuth
+ *  product logic. Always writes a response; never throws (errors become a
+ *  redacted 502/500 JSON body). */
+export declare function handleHearthModelAuthRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;