@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/auth/token.test.ts

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Session tokens and the cookie name.
+ *
+ * The properties pinned here are the ones a change could silently break while
+ * every request still "works": a token that outlives its expiry, a token that
+ * survives a password change, and a cookie name that collides across ports.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  clearSessionCookieHeader,
+  credentialFingerprint,
+  isSecureRequest,
+  issueSessionToken,
+  readSessionCookie,
+  sessionCookieHeader,
+  sessionCookieName,
+  sessionRemainingMs,
+  SESSION_TTL_MS,
+  verifySessionToken,
+} from '@/server/lib/auth/token';
+
+const SECRET = 'test-secret-value';
+const KEY = '$argon2id$v=19$m=65536,t=2,p=1$fakehash';
+const NOW = 1_700_000_000_000;
+
+function issue(overrides: Partial<Parameters<typeof issueSessionToken>[0]> = {}): string {
+  return issueSessionToken({
+    sessionSecret: SECRET,
+    credentialKey: KEY,
+    now: NOW,
+    ...overrides,
+  });
+}
+
+describe('session tokens', () => {
+  test('a freshly issued token verifies', () => {
+    const token = issue();
+    expect(verifySessionToken(token, { sessionSecret: SECRET, credentialKey: KEY, now: NOW })).toBe(true);
+  });
+
+  test('a token expires at its own deadline, not later', () => {
+    const token = issue({ ttlMs: 1000 });
+    expect(verifySessionToken(token, { sessionSecret: SECRET, credentialKey: KEY, now: NOW + 999 })).toBe(true);
+    expect(verifySessionToken(token, { sessionSecret: SECRET, credentialKey: KEY, now: NOW + 1000 })).toBe(false);
+    expect(verifySessionToken(token, { sessionSecret: SECRET, credentialKey: KEY, now: NOW + 1001 })).toBe(false);
+  });
+
+  test('a changed password revokes every token, because the fingerprint is signed', () => {
+    const token = issue();
+    const otherKey = '$argon2id$v=19$m=65536,t=2,p=1$differenthash';
+    expect(verifySessionToken(token, { sessionSecret: SECRET, credentialKey: otherKey, now: NOW })).toBe(false);
+  });
+
+  test('a rotated secret revokes every token', () => {
+    const token = issue();
+    expect(verifySessionToken(token, { sessionSecret: 'rotated', credentialKey: KEY, now: NOW })).toBe(false);
+  });
+
+  test('the payload cannot be edited, because the signature covers all of it', () => {
+    const token = issue({ ttlMs: 1000 });
+    const [version, expiresAt, fingerprint, mac] = token.split('.');
+    const extended = [version, String(Number(expiresAt) + 86_400_000), fingerprint, mac].join('.');
+    expect(verifySessionToken(extended, { sessionSecret: SECRET, credentialKey: KEY, now: NOW })).toBe(false);
+  });
+
+  test('malformed input is false, never a throw', () => {
+    for (const bad of ['', 'v1', 'v1.a.b', 'v1.a.b.c.d', 'v2.1.2.3', null, undefined]) {
+      expect(verifySessionToken(bad as string, { sessionSecret: SECRET, credentialKey: KEY, now: NOW })).toBe(false);
+    }
+  });
+
+  test('the fingerprint differs per password and per secret', () => {
+    expect(credentialFingerprint(SECRET, KEY)).not.toBe(credentialFingerprint(SECRET, 'other'));
+    expect(credentialFingerprint(SECRET, KEY)).not.toBe(credentialFingerprint('other', KEY));
+  });
+
+  test('default TTL is the documented 12 hours', () => {
+    const token = issue();
+    const expiresAt = Number(token.split('.')[1]);
+    expect(expiresAt - NOW).toBe(SESSION_TTL_MS);
+  });
+});
+
+describe('session cookie name', () => {
+  const headersOf = (entries: Record<string, string>) => new Headers(entries);
+
+  test('folds the request port into the name', () => {
+    expect(sessionCookieName(headersOf({ host: '192.168.0.1:3000' }))).toBe('omp_session_3000');
+    expect(sessionCookieName(headersOf({ host: 'localhost:3001' }))).toBe('omp_session_3001');
+  });
+
+  test('keeps the bare name when the host carries no port', () => {
+    expect(sessionCookieName(headersOf({ host: '192.168.0.1' }))).toBe('omp_session');
+  });
+
+  test('handles bracketed IPv6', () => {
+    expect(sessionCookieName(headersOf({ host: '[::1]:3000' }))).toBe('omp_session_3000');
+    expect(sessionCookieName(headersOf({ host: '[::1]' }))).toBe('omp_session');
+  });
+
+  test('prefers the forwarded host, so a proxy keys by the browser port', () => {
+    expect(sessionCookieName(headersOf({ host: '10.0.0.5:8080', 'x-forwarded-host': 'example.test:3000' })))
+      .toBe('omp_session_3000');
+  });
+
+  test('reads only the slot for this request port', () => {
+    const request = new Request('http://localhost:3001/api/settings', {
+      headers: { host: 'localhost:3001', cookie: 'omp_session_3000=stale; omp_session_3001=fresh' },
+    });
+    expect(readSessionCookie(request)).toBe('fresh');
+  });
+
+  test('a cookie for another port is not found', () => {
+    const request = new Request('http://localhost:3002/api/settings', {
+      headers: { host: 'localhost:3002', cookie: 'omp_session_3000=stale' },
+    });
+    expect(readSessionCookie(request)).toBeNull();
+  });
+});
+
+describe('behaviour behind a reverse proxy', () => {
+  const headersOf = (entries: Record<string, string>) => new Headers(entries);
+  const requestTo = (url: string, entries: Record<string, string> = {}) => new Request(url, { headers: entries });
+
+  test('x-forwarded-proto: https makes the cookie Secure', () => {
+    // The case that decides whether a Cloudflare tunnel works at all: the
+    // browser speaks https while cloudflared forwards plain http to localhost,
+    // so the request's own URL says `http:`. Without reading the header the
+    // session cookie would be issued without `Secure` on an https site — and a
+    // `Secure`-less cookie is what a proxy stripping https would accept.
+    const request = requestTo('http://127.0.0.1:3000/login', { 'x-forwarded-proto': 'https' });
+    expect(isSecureRequest(request)).toBe(true);
+    expect(sessionCookieHeader('omp_session', 'token', SESSION_TTL_MS, isSecureRequest(request))).toContain('Secure');
+  });
+
+  test('a plain local request is not Secure', () => {
+    // Otherwise the cookie could never be set on the plain-http localhost the
+    // server normally runs on.
+    expect(isSecureRequest(requestTo('http://127.0.0.1:3000/'))).toBe(false);
+  });
+
+  test('only the first forwarded proto counts, as the chain sends it', () => {
+    // A chain appends; the client-facing hop is first. A later `http` in the
+    // list describes an internal hop, not the browser's connection.
+    expect(isSecureRequest(requestTo('http://x/', { 'x-forwarded-proto': 'https, http' }))).toBe(true);
+    expect(isSecureRequest(requestTo('http://x/', { 'x-forwarded-proto': 'http, https' }))).toBe(false);
+  });
+
+  test('a tunnel host without a port keeps the bare cookie name', () => {
+    // A trycloudflare quick tunnel is reached as
+    // `https://<name>.trycloudflare.com` — no port — so the name must not gain a
+    // suffix that nothing would read back.
+    const request = requestTo('http://127.0.0.1:3000/api/settings', {
+      host: '127.0.0.1:3000',
+      'x-forwarded-host': 'keys-mighty.trycloudflare.com',
+    });
+    expect(sessionCookieName(request.headers)).toBe('omp_session');
+  });
+
+  test('a proxied host WITH a port keeps that port in the name', () => {
+    const request = requestTo('http://127.0.0.1:3000/api/settings', {
+      host: '127.0.0.1:3000',
+      'x-forwarded-host': 'internal.example:8443',
+    });
+    expect(sessionCookieName(request.headers)).toBe('omp_session_8443');
+  });
+
+  test('the cookie is read back with the same name it was issued under', () => {
+    // Issuance and validation must agree through a proxy hop, or the browser
+    // stores a cookie no request sends.
+    const headers = headersOf({ 'x-forwarded-host': 'keys-mighty.trycloudflare.com' });
+    const name = sessionCookieName(headers);
+    const request = requestTo('http://127.0.0.1:3000/api/settings', {
+      'x-forwarded-host': 'keys-mighty.trycloudflare.com',
+      cookie: `${name}=the-token`,
+    });
+    expect(readSessionCookie(request)).toBe('the-token');
+  });
+});
+
+describe('session cookie attributes', () => {
+  test('is HttpOnly and SameSite=Lax, and omits Secure over plain http', () => {
+    const header = sessionCookieHeader('omp_session_3000', 'token-value', SESSION_TTL_MS, false);
+    expect(header).toContain('HttpOnly');
+    expect(header).toContain('SameSite=Lax');
+    expect(header).toContain('Path=/');
+    expect(header).toContain(`Max-Age=${SESSION_TTL_MS / 1000}`);
+    // Secure on an http origin makes the cookie unsettable, i.e. login that
+    // appears to succeed and never sticks.
+    expect(header).not.toContain('Secure');
+  });
+
+  test('adds Secure when the request was https', () => {
+    expect(sessionCookieHeader('omp_session_3000', 'token-value', SESSION_TTL_MS, true)).toContain('Secure');
+  });
+
+  test('clearing sets Max-Age=0 and an expired date', () => {
+    const header = clearSessionCookieHeader('omp_session_3000', false);
+    expect(header).toContain('Max-Age=0');
+    expect(header).toContain('Expires=Thu, 01 Jan 1970');
+  });
+});
+
+describe('sessionRemainingMs', () => {
+  // Reissuing a session must preserve the lifetime the user chose. Measured:
+  // a 7-day session came back as `Max-Age=43200` after a password change,
+  // because the route read the TTL from a token that had just stopped verifying.
+  test('reports what is left of a valid token', () => {
+    const token = issue({ ttlMs: 60_000 });
+    expect(sessionRemainingMs(token, { sessionSecret: SECRET, credentialKey: KEY, now: NOW })).toBe(60_000);
+    expect(sessionRemainingMs(token, { sessionSecret: SECRET, credentialKey: KEY, now: NOW + 45_000 })).toBe(15_000);
+  });
+
+  test('is null for an expired, foreign or missing token', () => {
+    const token = issue({ ttlMs: 1_000 });
+    expect(sessionRemainingMs(token, { sessionSecret: SECRET, credentialKey: KEY, now: NOW + 1_000 })).toBeNull();
+    expect(sessionRemainingMs(token, { sessionSecret: 'other', credentialKey: KEY, now: NOW })).toBeNull();
+    expect(sessionRemainingMs(token, { sessionSecret: SECRET, credentialKey: 'other', now: NOW })).toBeNull();
+    expect(sessionRemainingMs(null, { sessionSecret: SECRET, credentialKey: KEY, now: NOW })).toBeNull();
+    expect(sessionRemainingMs('garbage', { sessionSecret: SECRET, credentialKey: KEY, now: NOW })).toBeNull();
+  });
+
+  // The deadline is the token's OWN signed expiry, so this cannot be used to
+  // extend a session beyond what was issued.
+  test('never exceeds the token\'s own deadline', () => {
+    const token = issue({ ttlMs: 5_000 });
+    expect(sessionRemainingMs(token, { sessionSecret: SECRET, credentialKey: KEY, now: NOW })).toBe(5_000);
+  });
+});

package/src/server/lib/auth/token.ts

@@ -0,0 +1,220 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Session tokens and the cookie that carries them.
+ *
+ * A session is a stateless signed value — `v1.<expiresAt>.<fingerprint>.<mac>` —
+ * so validating one costs an HMAC and no storage. The middle segment is
+ * `HMAC(secret, passwordHash)`: because it is part of the signed payload, every
+ * token minted before a password change fails verification afterwards. Changing
+ * the password therefore revokes every session, with no session table to sweep.
+ *
+ * The cookie NAME carries the request port. Browsers key cookies by host and
+ * ignore the port (RFC 6265), so two Kabmo instances on one machine share a
+ * jar: without the port in the name, logging into the second silently overwrote
+ * the first instance's cookie. This install routinely has several ports live at
+ * once, so the collision is the normal case rather than an edge one.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/** Cookie base name; the resolved name appends `_<port>` when the host has one. */
+export const SESSION_COOKIE_BASE = 'omp_session';
+
+/** Default session lifetime: 12 hours. */
+export const SESSION_TTL_MS = 12 * 60 * 60 * 1000;
+
+/** Lifetime when the user asks to be remembered on this device: 7 days. */
+export const TRUSTED_DEVICE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+const TOKEN_VERSION = 'v1';
+
+/**
+ * The trailing port of a `Host` authority, or null when there is none.
+ * Handles bracketed IPv6 (`[::1]:3000`) and plain host names.
+ */
+function hostPort(host: string): string | null {
+  if (host.startsWith('[')) {
+    const end = host.indexOf(']');
+    if (end === -1) return null;
+    const rest = host.slice(end + 1);
+    return rest.startsWith(':') && /^\d+$/.test(rest.slice(1)) ? rest.slice(1) : null;
+  }
+  const match = host.match(/:(\d+)$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Cookie name for a request. `x-forwarded-host` wins when present, so an
+ * instance behind a reverse proxy is keyed by the port the browser used rather
+ * than the upstream one.
+ */
+export function sessionCookieName(headers: Headers): string {
+  const forwarded = headers.get('x-forwarded-host');
+  const host = (forwarded ? forwarded.split(',')[0] : headers.get('host') ?? '').trim();
+  if (!host) return SESSION_COOKIE_BASE;
+  const port = hostPort(host);
+  if (!port) return SESSION_COOKIE_BASE;
+  const portNumber = Number.parseInt(port, 10);
+  return Number.isFinite(portNumber) && portNumber > 0 ? `${SESSION_COOKIE_BASE}_${port}` : SESSION_COOKIE_BASE;
+}
+
+/** Read the session token from a request's cookies, or null when absent. */
+export function readSessionCookie(request: Request): string | null {
+  const header = request.headers.get('cookie');
+  if (!header) return null;
+  const name = sessionCookieName(request.headers);
+  for (const segment of header.split(';')) {
+    const index = segment.indexOf('=');
+    if (index === -1) continue;
+    if (segment.slice(0, index).trim() !== name) continue;
+    const value = segment.slice(index + 1).trim();
+    if (!value) return null;
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * `HMAC(secret, credentialKey)` — the value that binds a session to one password.
+ *
+ * The key is what `deriveCredentialKey` produces, NOT the argon2 hash: it has to
+ * be reproducible from the secret and the password alone, or a session would die
+ * with the process that minted it.
+ */
+export function credentialFingerprint(sessionSecret: string, credentialKey: string): string {
+  return createHmac('sha256', sessionSecret).update(credentialKey).digest('base64url');
+}
+
+function sign(sessionSecret: string, payload: string): string {
+  return createHmac('sha256', sessionSecret).update(payload).digest('base64url');
+}
+
+/** Constant-time string comparison that tolerates unequal lengths. */
+function safeEqual(left: string, right: string): boolean {
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+export interface SessionIssueOptions {
+  sessionSecret: string;
+  /** A `deriveCredentialKey` result — never the argon2 hash (see the field). */
+  credentialKey: string;
+  ttlMs?: number;
+  /** Injected for tests; defaults to now. */
+  now?: number;
+}
+
+/** Mint a session token valid for `ttlMs`. */
+export function issueSessionToken({
+  sessionSecret,
+  credentialKey,
+  ttlMs = SESSION_TTL_MS,
+  now = Date.now(),
+}: SessionIssueOptions): string {
+  const expiresAt = now + ttlMs;
+  const payload = [
+    TOKEN_VERSION,
+    String(expiresAt),
+    credentialFingerprint(sessionSecret, credentialKey),
+  ].join('.');
+  return `${payload}.${sign(sessionSecret, payload)}`;
+}
+
+/**
+ * True when `token` was minted by this secret for the CURRENT password and has
+ * not expired. Every failure mode — malformed, wrong version, bad signature,
+ * stale fingerprint, past expiry — is a plain false.
+ */
+export function verifySessionToken(
+  token: string | null | undefined,
+  { sessionSecret, credentialKey, now = Date.now() }: Omit<SessionIssueOptions, 'ttlMs'>,
+): boolean {
+  if (!token) return false;
+  const parts = token.split('.');
+  if (parts.length !== 4) return false;
+  const [version, expiresAt, fingerprint, mac] = parts;
+  if (version !== TOKEN_VERSION) return false;
+  if (!safeEqual(mac, sign(sessionSecret, `${version}.${expiresAt}.${fingerprint}`))) return false;
+  if (!safeEqual(fingerprint, credentialFingerprint(sessionSecret, credentialKey))) return false;
+  const expiry = Number(expiresAt);
+  return Number.isFinite(expiry) && expiry > now;
+}
+
+/**
+ * Remaining lifetime of a VALID token, in ms, or null when it is unusable.
+ *
+ * Reissuing a session (after a password change, after a revocation) has to
+ * preserve what the user chose at the login screen. Measured: a 7-day session
+ * came back as `Max-Age=43200` after a revoke, because those routes minted a
+ * fresh token with the DEFAULT ttl — a silent downgrade from a week to 12 hours
+ * that the user could only discover by being signed out early.
+ *
+ * The deadline is the token's own signed `expiresAt`, so this cannot be talked
+ * into extending a session beyond what was issued.
+ */
+export function sessionRemainingMs(
+  token: string | null | undefined,
+  { sessionSecret, credentialKey, now = Date.now() }: Omit<SessionIssueOptions, 'ttlMs'>,
+): number | null {
+  if (!verifySessionToken(token, { sessionSecret, credentialKey, now })) return null;
+  // `verifySessionToken` proves the token is a string with a numeric expiry.
+  const expiry = Number((token as string).split('.')[1]);
+  if (!Number.isFinite(expiry) || expiry <= now) return null;
+  return expiry - now;
+}
+
+/**
+ * `Set-Cookie` value for a session.
+ *
+ * `SameSite=Lax` rather than `Strict`: this app's own document navigations must
+ * keep the cookie (a Strict cookie is withheld on a top-level navigation from
+ * another site, which would bounce a returning user through the login screen),
+ * while cross-site POSTs still cannot carry it — which is the CSRF exposure that
+ * matters here.
+ *
+ * `Secure` is added only when the request arrived over https. Hardcoding it
+ * would make the cookie unsettable on the plain-http localhost this server
+ * normally runs on, i.e. login would appear to succeed and never stick.
+ */
+export function sessionCookieHeader(name: string, token: string, ttlMs: number, secure: boolean): string {
+  const maxAge = Math.max(0, Math.floor(ttlMs / 1000));
+  const expires = maxAge === 0
+    ? 'Thu, 01 Jan 1970 00:00:00 GMT'
+    : new Date(Date.now() + maxAge * 1000).toUTCString();
+  const attributes = [
+    `${name}=${encodeURIComponent(token)}`,
+    'Path=/',
+    'HttpOnly',
+    'SameSite=Lax',
+    `Max-Age=${maxAge}`,
+    `Expires=${expires}`,
+  ];
+  if (secure) attributes.push('Secure');
+  return attributes.join('; ');
+}
+
+/** `Set-Cookie` value that clears the session cookie. */
+export function clearSessionCookieHeader(name: string, secure: boolean): string {
+  return sessionCookieHeader(name, '', 0, secure);
+}
+
+/** True when the request reached the server over https, directly or via a proxy. */
+export function isSecureRequest(request: Request): boolean {
+  const forwarded = request.headers.get('x-forwarded-proto');
+  if (forwarded) return forwarded.split(',')[0].trim().toLowerCase() === 'https';
+  try {
+    return new URL(request.url).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}

package/src/server/lib/browser/runtime.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+import { findProjectRuntimeDir, isTcpPortLive } from '@/server/lib/browser/runtime';
+
+const tempRoots: string[] = [];
+const savedEnv: Record<string, string | undefined> = {};
+
+async function makeRuntimeDir(name: string): Promise<string> {
+  const dir = join(homedir(), Bun.env.PI_CONFIG_DIR!, 'run', 'daemons', name);
+  await fs.promises.mkdir(join(dir, 'omp.browser.headless.profile'), { recursive: true });
+  await Bun.write(join(dir, 'scope.json'), JSON.stringify({ projectDir: '/tmp/fake-project' }));
+  return dir;
+}
+
+async function writeDevToolsActivePort(runtimeDir: string, port: number, wsPath: string): Promise<void> {
+  await Bun.write(join(runtimeDir, 'omp.browser.headless.profile', 'DevToolsActivePort'), `${port}\n${wsPath}\n`);
+}
+
+beforeEach(async () => {
+  // getConfigRoot() = homedir()/getConfigDirName(), and os.homedir() is
+  // snapshotted at process start — a runtime HOME change is invisible.
+  // PI_CONFIG_DIR is a *relative name* joined onto homedir, so isolate via a
+  // uniquely named config dir inside the real home.
+  savedEnv.PI_CONFIG_DIR = Bun.env.PI_CONFIG_DIR;
+  savedEnv.XDG_STATE_HOME = Bun.env.XDG_STATE_HOME;
+  const name = `.omp-browser-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  tempRoots.push(join(homedir(), name));
+  await fs.promises.mkdir(join(homedir(), name, 'run', 'daemons'), { recursive: true });
+  Bun.env.PI_CONFIG_DIR = name;
+  Bun.env.XDG_STATE_HOME = '';
+});
+
+afterEach(() => {
+  if (savedEnv.PI_CONFIG_DIR === undefined) delete Bun.env.PI_CONFIG_DIR;
+  else Bun.env.PI_CONFIG_DIR = savedEnv.PI_CONFIG_DIR;
+  if (savedEnv.XDG_STATE_HOME === undefined) delete Bun.env.XDG_STATE_HOME;
+  else Bun.env.XDG_STATE_HOME = savedEnv.XDG_STATE_HOME;
+});
+
+afterAll(() => {
+  for (const root of tempRoots) fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('isTcpPortLive', () => {
+  test('true for a listening port', async () => {
+    const server = Bun.listen({ hostname: '127.0.0.1', port: 0, socket: { data() {}, close() {}, error() {} } });
+    try {
+      expect(await isTcpPortLive(server.port)).toBe(true);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test('false for a closed port', async () => {
+    // Grab a free port, then release it so nothing listens there.
+    const server = Bun.listen({ hostname: '127.0.0.1', port: 0, socket: { data() {}, close() {}, error() {} } });
+    const port = server.port;
+    server.stop(true);
+    expect(await isTcpPortLive(port)).toBe(false);
+  });
+});
+
+describe('findProjectRuntimeDir', () => {
+  test('returns endpoint for a live daemon', async () => {
+    const runtimeDir = await makeRuntimeDir('live');
+    const server = Bun.listen({ hostname: '127.0.0.1', port: 0, socket: { data() {}, close() {}, error() {} } });
+    try {
+      await writeDevToolsActivePort(runtimeDir, server.port, '/devtools/browser/live-id');
+      const found = await findProjectRuntimeDir('/tmp/fake-project');
+      expect(found).not.toBeNull();
+      expect(found?.port).toBe(server.port);
+      expect(found?.wsUrl).toBe(`ws://127.0.0.1:${server.port}/devtools/browser/live-id`);
+      expect(found?.daemonName).toBe('omp.browser.headless');
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test('rejects a stale DevToolsActivePort whose port is dead', async () => {
+    const runtimeDir = await makeRuntimeDir('stale');
+    const server = Bun.listen({ hostname: '127.0.0.1', port: 0, socket: { data() {}, close() {}, error() {} } });
+    const port = server.port;
+    server.stop(true);
+    await writeDevToolsActivePort(runtimeDir, port, '/devtools/browser/dead-id');
+    expect(await findProjectRuntimeDir('/tmp/fake-project')).toBeNull();
+  });
+
+  test('returns null for an unknown project', async () => {
+    await makeRuntimeDir('other');
+    const server = Bun.listen({ hostname: '127.0.0.1', port: 0, socket: { data() {}, close() {}, error() {} } });
+    try {
+      await writeDevToolsActivePort(
+        join(homedir(), Bun.env.PI_CONFIG_DIR!, 'run', 'daemons', 'other'),
+        server.port,
+        '/devtools/browser/other',
+      );
+      expect(await findProjectRuntimeDir('/tmp/never-registered')).toBeNull();
+    } finally {
+      server.stop(true);
+    }
+  });
+});