@principles/pd-cli 1.142.4 → 1.144.0

package/src/services/console-launcher.ts

@@ -21,6 +21,7 @@ import * as http from 'http';
 // ─── Public types ────────────────────────────────────────────────────────────
 
 export type ConsoleStatus = 'reused' | 'started' | 'failed' | 'refused';
+export type ConsoleAuthenticationMode = 'authenticated' | 'no_auth';
 
 export interface ConsoleLaunchResult {
   status: ConsoleStatus;
@@ -34,6 +35,8 @@ export interface ConsoleLaunchResult {
   reused: boolean;
   /** True when a browser should/has been opened (skipped in --json mode). */
   browserOpened: boolean;
+  /** Verified for successful launch/reuse; omitted when no server was reached. */
+  authenticationMode?: ConsoleAuthenticationMode;
   /**
    * PID of the freshly spawned console server process. Present only when
    * status === 'started'; absent on 'reused' (the server was started by
@@ -58,6 +61,10 @@ const DEFAULT_PORT = 3100;
 const DEFAULT_HOST = '127.0.0.1';
 const PORT_FALLBACK_LIMIT = 20; // try 3100..3119 before giving up
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 // ─── Loopback safety (ERR-049) ──────────────────────────────────────────────
 
 /** Returns true if the host resolves to a loopback address. */
@@ -138,13 +145,20 @@ export interface HealthProbeOptions {
 }
 
 /** Probe a port to see if it serves a healthy PD Console. */
-export async function probeConsoleHealth(opts: HealthProbeOptions): Promise<{ healthy: boolean; reason?: string }> {
+export interface ConsoleHealthProbeResult {
+  healthy: boolean;
+  authenticationMode?: ConsoleAuthenticationMode;
+  reason?: string;
+  failureKind?: 'unauthorized' | 'invalid_response' | 'unreachable';
+}
+
+export async function probeConsoleHealth(opts: HealthProbeOptions): Promise<ConsoleHealthProbeResult> {
   const { host, port, timeoutMs = 1500, token } = opts;
 
   if (Object.hasOwn(globalThis, '__mockProbeConsoleHealth')) {
     const mock = Reflect.get(globalThis, '__mockProbeConsoleHealth') as (
       o: HealthProbeOptions
-    ) => Promise<{ healthy: boolean; reason?: string }>;
+    ) => Promise<ConsoleHealthProbeResult>;
     return mock(opts);
   }
   return new Promise((resolve) => {
@@ -157,7 +171,7 @@ export async function probeConsoleHealth(opts: HealthProbeOptions): Promise<{ he
       (res) => {
         // 401 means auth required — treat as unhealthy, not a generic error
         if (res.statusCode === 401) {
-          resolve({ healthy: false, reason: 'console health endpoint returned 401 (unauthorized) — check PD_CONSOLE_TOKEN' });
+          resolve({ healthy: false, failureKind: 'unauthorized', reason: 'console health endpoint returned 401 (unauthorized) — check PD_CONSOLE_TOKEN' });
           return;
         }
         if (res.statusCode !== 200) {
@@ -170,13 +184,19 @@ export async function probeConsoleHealth(opts: HealthProbeOptions): Promise<{ he
         });
         res.on('end', () => {
           try {
-            const body = JSON.parse(data) as unknown;
-            if (body && typeof body === 'object') {
+            const body: unknown = JSON.parse(data);
+            if (isRecord(body)) {
               const isHealthy =
                 (Object.hasOwn(body, 'healthy') && Reflect.get(body, 'healthy') === true) ||
                 (Object.hasOwn(body, 'success') && Reflect.get(body, 'success') === true);
               if (isHealthy) {
-                resolve({ healthy: true });
+                const dataValue = Object.hasOwn(body, 'data') ? Reflect.get(body, 'data') : undefined;
+                const payloadRecord = isRecord(dataValue) ? dataValue : body;
+                const mode = Reflect.get(payloadRecord, 'authenticationMode');
+                resolve({
+                  healthy: true,
+                  ...(mode === 'authenticated' || mode === 'no_auth' ? { authenticationMode: mode } : {}),
+                });
               } else {
                 resolve({ healthy: false, reason: 'console health JSON was missing healthy/success markers' });
               }
@@ -387,6 +407,17 @@ export async function planConsoleLaunch(input: OrchestratorInput): Promise<Orche
   // Step 1: Is there already a healthy console on the preferred port?
   const health = await probeConsoleHealth({ host, port: preferredPort, token });
   if (health.healthy) {
+    if (token && health.authenticationMode !== 'authenticated') {
+      return {
+        status: 'refused',
+        url: '',
+        port: preferredPort,
+        host,
+        reused: false,
+        reason: 'console_authentication_mode_mismatch',
+        nextAction: `Stop the Console on port ${preferredPort}, then retry so Companion can start an authenticated Console.`,
+      };
+    }
     return {
       status: 'reused',
       url: buildConsoleUrl(host, preferredPort),
@@ -396,6 +427,18 @@ export async function planConsoleLaunch(input: OrchestratorInput): Promise<Orche
     };
   }
 
+  if (token && health.failureKind === 'unauthorized') {
+    return {
+      status: 'refused',
+      url: '',
+      port: preferredPort,
+      host,
+      reused: false,
+      reason: 'console_authentication_failed',
+      nextAction: 'Verify PD_CONSOLE_TOKEN matches the running Console, stop that Console, then retry.',
+    };
+  }
+
   // Step 2: Is the preferred port simply occupied by something else?
   const preferredInUse = await isPortInUse(host, preferredPort);
 

package/tests/commands/console-open.test.ts

@@ -311,6 +311,46 @@ describe('planConsoleLaunch — reused (healthy console on preferred port)', ()
     }
   });
 
+  it('does not reuse a verified no-auth Console when a token is configured', async () => {
+    const server = http.createServer((_req, res) => {
+      res.statusCode = 200;
+      res.end(JSON.stringify({ success: true, data: { authenticationMode: 'no_auth' } }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const addr = server.address();
+    if (typeof addr !== 'object' || !addr) throw new Error('no addr');
+    try {
+      const result = await planConsoleLaunch({
+        workspaceDir: '/tmp/anywhere', preferredPort: addr.port,
+        host: '127.0.0.1', token: 'configured-token',
+      });
+      expect(result.status).toBe('refused');
+      expect(result.reason).toBe('console_authentication_mode_mismatch');
+    } finally {
+      await new Promise<void>((resolve) => server.close(resolve));
+    }
+  });
+
+  it('fails loud when the configured token is rejected by an existing Console', async () => {
+    const server = http.createServer((_req, res) => {
+      res.statusCode = 401;
+      res.end('unauthorized');
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const addr = server.address();
+    if (typeof addr !== 'object' || !addr) throw new Error('no addr');
+    try {
+      const result = await planConsoleLaunch({
+        workspaceDir: '/tmp/anywhere', preferredPort: addr.port,
+        host: '127.0.0.1', token: 'wrong-token',
+      });
+      expect(result.status).toBe('refused');
+      expect(result.reason).toBe('console_authentication_failed');
+    } finally {
+      await new Promise<void>((resolve) => server.close(resolve));
+    }
+  });
+
   it('does NOT classify a non-console responder as reused', async () => {
     // Server returns 200 on any path but with a non-OK status code from /api/health
     const server = http.createServer((req, res) => {
@@ -387,6 +427,22 @@ describe('probeConsoleHealth', () => {
     }
   });
 
+  it('returns the verified authentication mode from the health contract', async () => {
+    const server = http.createServer((_req, res) => {
+      res.statusCode = 200;
+      res.end(JSON.stringify({ success: true, data: { authenticationMode: 'authenticated' } }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const addr = server.address();
+    if (typeof addr !== 'object' || !addr) throw new Error('no addr');
+    try {
+      const h = await probeConsoleHealth({ host: '127.0.0.1', port: addr.port, token: 'token' });
+      expect(h).toMatchObject({ healthy: true, authenticationMode: 'authenticated' });
+    } finally {
+      await new Promise<void>((resolve) => server.close(resolve));
+    }
+  });
+
   it('returns healthy=false with reason for a server that returns 500', async () => {
     const server = http.createServer((req, res) => {
       res.statusCode = 500;
@@ -491,8 +547,11 @@ describe('CLI command wiring (pd console open)', () => {
   let cliPath: string;
   let workspaceRoot: string;
   let tmp: string;
+  let originalConsoleToken: string | undefined;
 
   beforeEach(() => {
+    originalConsoleToken = process.env.PD_CONSOLE_TOKEN;
+    delete process.env.PD_CONSOLE_TOKEN;
     workspaceRoot = path.resolve(__dirname, '../../../..');
     cliPath = path.join(workspaceRoot, 'packages', 'pd-cli', 'dist', 'index.js');
     tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-console-open-test-'));
@@ -520,7 +579,7 @@ describe('CLI command wiring (pd console open)', () => {
       const server = http.createServer((req, res) => {
         if (req.url === '/api/health') {
           res.writeHead(200, {'Content-Type': 'application/json'});
-          res.end(JSON.stringify({success: true}));
+          res.end(JSON.stringify({success: true, data: {authenticationMode: 'no_auth'}}));
         } else {
           res.writeHead(404);
           res.end();
@@ -533,6 +592,8 @@ describe('CLI command wiring (pd console open)', () => {
   });
 
   afterEach(() => {
+    if (originalConsoleToken === undefined) delete process.env.PD_CONSOLE_TOKEN;
+    else process.env.PD_CONSOLE_TOKEN = originalConsoleToken;
     delete process.env.__PD_CONSOLE_TEST_FAKE_HOME;
     try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
   });
@@ -598,13 +659,32 @@ describe('CLI command wiring (pd console open)', () => {
     }
   }, 20_000);
 
+  it('kills and refuses a fresh Console whose reported authentication mode mismatches the configured token', async () => {
+    process.env.PD_CONSOLE_TOKEN = 'configured-token';
+    let run: CliJsonRun | undefined;
+    try {
+      run = await runPdUntilJson(
+        ['console', 'open', '--workspace', tmp, '--port', '49391', '--json', '--no-browser'],
+        workspaceRoot,
+      );
+      if (!isRecord(run.parsed)) throw new Error('CLI JSON output was not an object');
+      expect(run.parsed.status).toBe('refused');
+      expect(run.parsed.reason).toBe('console_authentication_mode_mismatch');
+      expect(run.parsed).not.toHaveProperty('serverPid');
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(await isPortInUse('127.0.0.1', 49391)).toBe(false);
+    } finally {
+      await teardownCliTree(run);
+    }
+  }, 20_000);
+
   it('pd console open --json reused path does NOT include serverPid (PRI-526)', async () => {
     // Stand up a fake healthy console in-process, then point the CLI at its
     // port: planConsoleLaunch probes /api/health → 200 → reused, no spawn.
     const server = http.createServer((req, res) => {
       if (req.url === '/api/health') {
         res.statusCode = 200;
-        res.end(JSON.stringify({ success: true }));
+        res.end(JSON.stringify({ success: true, data: { authenticationMode: 'no_auth' } }));
         return;
       }
       res.statusCode = 404;
@@ -622,6 +702,7 @@ describe('CLI command wiring (pd console open)', () => {
       if (!isRecord(run.parsed)) throw new Error('CLI JSON output was not an object');
       expect(run.parsed.status).toBe('reused');
       expect(run.parsed.reused).toBe(true);
+      expect(run.parsed.authenticationMode).toBe('no_auth');
       expect(run.parsed).not.toHaveProperty('serverPid');
     } finally {
       await teardownCliTree(run);