fix(cli): switch OAuth callback to plain HTTP localhost

bgagent · claude · bgagent · commit e259da1432a4 · 2026-05-20T10:54:32.000-07:00
Per RFC 8252 §7.3, OAuth providers (including Linear) treat
http://localhost as a special case that doesn't need TLS — the
connection never leaves the host. The previous self-signed-cert HTTPS
approach forced testers through a "connection not private" warning that
scared them off mid-setup.

Drops the openssl shell-out + temp-cert plumbing (~60 lines) along with
the user-facing warning copy in `bgagent linear setup`. Updates the
callback constants to http://localhost:8080/oauth/callback and the test
suite to plain http.GET.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/cli/src/commands/linear.ts b/cli/src/commands/linear.ts
@@ -381,8 +381,7 @@ export function makeLinearCommand(): Command {
           const opened = await openBrowser(authorizationUrl);
           if (opened) {
             console.log('  → Opened your browser to the Linear consent screen.');
-            console.log('    Your browser will warn about a self-signed cert on the localhost callback —');
-            console.log('    click through (Advanced → Proceed). The cert is local-only.');
+            console.log('    The browser will redirect to a localhost page after you Authorize — that\'s expected.');
           } else {
             console.log('  → Could not open browser automatically. Open this URL manually:');
             console.log(`    ${authorizationUrl}`);
diff --git a/cli/src/oauth-callback-server.ts b/cli/src/oauth-callback-server.ts
@@ -17,23 +17,27 @@
  *  SOFTWARE.
  */
 
-import { execFileSync } from 'child_process';
-import * as fs from 'fs';
-import * as https from 'https';
-import * as os from 'os';
-import * as path from 'path';
+import * as http from 'http';
 import { URL } from 'url';
 import { CliError } from './errors';
 
 /**
  * Localhost OAuth callback URL used during `bgagent linear setup`.
- * Must match the URL allowlisted on the CLI workload identity in CDK
- * (cdk/src/constructs/cli-workload-identity.ts).
+ *
+ * HTTP (not HTTPS) is intentional. Per RFC 8252 §7.3 (OAuth 2.0 for
+ * Native Apps) and Linear's docs, providers MUST treat http://localhost
+ * URLs as a special case and not require TLS — the connection never
+ * leaves the host. Using HTTP here removes the self-signed-cert browser
+ * warning that scared early testers during the Phase 2.0b smoke.
+ *
+ * The redirect_uri value sent to Linear MUST byte-match what's configured
+ * in Linear's app — keep this constant in sync with the LINEAR_SETUP_GUIDE
+ * playbook entry.
  */
 export const CALLBACK_HOST = 'localhost';
-export const CALLBACK_PORT = 8443;
+export const CALLBACK_PORT = 8080;
 export const CALLBACK_PATH = '/oauth/callback';
-export const CALLBACK_URL = `https://${CALLBACK_HOST}:${CALLBACK_PORT}${CALLBACK_PATH}`;
+export const CALLBACK_URL = `http://${CALLBACK_HOST}:${CALLBACK_PORT}${CALLBACK_PATH}`;
 
 const SUCCESS_HTML = `<!doctype html>
 <html><head><meta charset="utf-8"><title>bgagent setup</title>
@@ -45,60 +49,6 @@ const FAILURE_HTML = `<!doctype html>
 <style>body{font-family:system-ui,sans-serif;max-width:480px;margin:8em auto;text-align:center;color:#222}h1{color:#c00}p{color:#666}</style></head>
 <body><h1>✗ Authorization not captured</h1><p>The callback URL did not include a session_id. Re-run <code>bgagent linear setup</code> and try again.</p></body></html>`;
 
-/**
- * Generate a self-signed cert + key pair for localhost using openssl.
- *
- * The cert is created in a temp dir and removed on close; the user's
- * browser will warn ("connection not private") on the redirect because
- * it's self-signed. This is acceptable: the cert is only used between
- * the user's browser and `localhost`, never traverses the network.
- *
- * Why openssl shell-out instead of node-forge or selfsigned: avoids a
- * runtime dependency for a one-off setup-time operation. openssl ships
- * with macOS and most Linux distros; if it's missing, fail loudly with
- * a remediation hint rather than silently falling back.
- */
-export function generateSelfSignedCert(): { certPath: string; keyPath: string; cleanup: () => void } {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bgagent-oauth-'));
-  const keyPath = path.join(tmpDir, 'key.pem');
-  const certPath = path.join(tmpDir, 'cert.pem');
-
-  try {
-    // -batch suppresses the interactive subject prompt; -subj sets a minimal
-    // subject. Localhost cert with 1-day validity (we only need it for the
-    // setup session — if you don't finish in 24h, regenerate).
-    execFileSync('openssl', [
-      'req',
-      '-x509',
-      '-newkey', 'rsa:2048',
-      '-keyout', keyPath,
-      '-out', certPath,
-      '-days', '1',
-      '-nodes',
-      '-subj', '/CN=localhost',
-      '-batch',
-    ], { stdio: 'pipe' });
-  } catch (err) {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-    throw new CliError(
-      `Failed to generate localhost cert via openssl: ${err instanceof Error ? err.message : String(err)}. `
-      + `Confirm \`openssl\` is installed and on PATH (ships with macOS and most Linux distros).`,
-    );
-  }
-
-  return {
-    certPath,
-    keyPath,
-    cleanup: () => {
-      try {
-        fs.rmSync(tmpDir, { recursive: true, force: true });
-      } catch {
-        // Best effort — leftover certs in /tmp are harmless.
-      }
-    },
-  };
-}
-
 export interface CallbackResult {
   /**
    * Value of the `session_id` query param if present (AgentCore-style
@@ -157,7 +107,6 @@ export async function awaitOauthCallback(
   options: CallbackServerOptions = {},
 ): Promise<CallbackResult> {
   const timeoutMs = options.timeoutMs ?? 700_000;
-  const cert = generateSelfSignedCert();
 
   return new Promise<CallbackResult>((resolve, reject) => {
     let settled = false;
@@ -167,7 +116,6 @@ export async function awaitOauthCallback(
       try {
         fn();
       } finally {
-        cert.cleanup();
         clearTimeout(timer);
         // .close() shuts down the listener; in-flight responses still complete.
         try {
@@ -178,11 +126,7 @@ export async function awaitOauthCallback(
       }
     };
 
-    const server = https.createServer(
-      {
-        key: fs.readFileSync(cert.keyPath),
-        cert: fs.readFileSync(cert.certPath),
-      },
+    const server = http.createServer(
       (req, res) => {
         // Defensive: if we somehow get a request after settling, just close it.
         if (settled || !req.url) {
diff --git a/cli/test/oauth-callback-server.test.ts b/cli/test/oauth-callback-server.test.ts
@@ -17,28 +17,24 @@
  *  SOFTWARE.
  */
 
-import * as fs from 'fs';
-import * as https from 'https';
+import * as http from 'http';
 import {
   awaitOauthCallback,
   CALLBACK_PORT,
   CALLBACK_URL,
-  generateSelfSignedCert,
 } from '../src/oauth-callback-server';
 
 /**
- * Make a self-signed-cert-tolerant HTTPS GET request to localhost.
- * Returns the response status + body. Closes the connection cleanly so
- * the server can finish settling without hanging the test.
+ * Make a plain HTTP GET request to localhost. Returns the response
+ * status + body. Closes the connection cleanly so the server can
+ * finish settling without hanging the test.
  */
 function localGet(urlSuffix: string): Promise<{ status: number; body: string }> {
   return new Promise((resolve, reject) => {
-    const req = https.get({
+    const req = http.get({
       host: 'localhost',
       port: CALLBACK_PORT,
       path: urlSuffix,
-      // We're testing our own self-signed cert, so accept it.
-      rejectUnauthorized: false,
     }, (res) => {
       let body = '';
       res.on('data', (chunk) => { body += chunk; });
@@ -48,25 +44,11 @@ function localGet(urlSuffix: string): Promise<{ status: number; body: string }>
   });
 }
 
-describe('generateSelfSignedCert', () => {
-  test('produces readable cert + key files and a working cleanup', () => {
-    const cert = generateSelfSignedCert();
-    expect(fs.existsSync(cert.certPath)).toBe(true);
-    expect(fs.existsSync(cert.keyPath)).toBe(true);
-    // Cert PEM has the standard header — quick sanity check.
-    expect(fs.readFileSync(cert.certPath, 'utf-8')).toContain('-----BEGIN CERTIFICATE-----');
-    expect(fs.readFileSync(cert.keyPath, 'utf-8')).toContain('-----BEGIN PRIVATE KEY-----');
-    cert.cleanup();
-    expect(fs.existsSync(cert.certPath)).toBe(false);
-    expect(fs.existsSync(cert.keyPath)).toBe(false);
-  });
-});
-
 describe('awaitOauthCallback', () => {
-  // The real OAuth flow waits on Linear/AWS — to avoid binding port 8443 in
-  // CI (which may be in use), these tests run sequentially via Jest's default
-  // test isolation per file. The 8443 port must be free for these tests; if
-  // a developer has another bgagent setup running locally, expect EADDRINUSE.
+  // The real OAuth flow waits on Linear — to avoid binding the callback port
+  // (8080) in CI when it might be in use, these tests run sequentially via
+  // Jest's default test isolation per file. If a developer has another
+  // bgagent setup running locally, expect EADDRINUSE.
 
   test('captures session_id from the first valid request and resolves', async () => {
     // Fire the server + the request in parallel; the server resolves once it
@@ -158,6 +140,8 @@ describe('awaitOauthCallback', () => {
     // Regression-lock: the URL is also baked into the CDK construct's
     // allowlist (cdk/src/constructs/cli-workload-identity.ts default).
     // Drift here = silent OAuth failure at runtime ("redirect_uri not allowlisted").
-    expect(CALLBACK_URL).toBe('https://localhost:8443/oauth/callback');
+    // RFC 8252 §7.3: http://localhost is the right shape for native-app OAuth
+    // callbacks (no TLS required, no cert warnings). Port 8080 is conventional.
+    expect(CALLBACK_URL).toBe('http://localhost:8080/oauth/callback');
   });
 });
