fix(login): tolerate stray loopback callbacks instead of bailing

ktamas77 · ktamas77 · commit e5b356d825d2 · 2026-05-04T04:11:28.000-07:00
A single stray request to the CLI's loopback /callback endpoint with a
missing or stale state would close the server and abort the login,
even when the legitimate browser redirect was about to arrive. This
made login flaky in the presence of browser prefetchers, restored
tabs from earlier login attempts, or any background loopback probe.

Now empty/unrecognised payloads and state mismatches respond 400 to
the offending request but keep listening; the login only fails on a
state-matching request that's missing a token, or on a thrown error.

Add an opt-in --debug flag on \`timebook login\` that prints every
request hitting /callback (method, url, ua, referer) so the source of
stray hits can be identified when needed.
diff --git a/README.md b/README.md
@@ -111,6 +111,12 @@ timebook login
 
 You can also pass `--api-url` and `--web-url` to `timebook login` once; subsequent commands re-use the saved values.
 
+If `timebook login` errors with `State mismatch` or you want to see exactly which requests reach the loopback callback, run with `--debug`:
+
+```bash
+timebook login --debug
+```
+
 ## Develop
 
 ```bash
diff --git a/src/commands/login.ts b/src/commands/login.ts
@@ -22,6 +22,8 @@ interface LoginOptions {
   port?: number;
   /** Open the browser automatically. Default true. */
   openBrowser?: boolean;
+  /** Log every request that hits the loopback /callback. */
+  debug?: boolean;
 }
 
 const SUCCESS_HTML = `<!doctype html>
@@ -97,18 +99,36 @@ export async function loginCommand(opts: LoginOptions = {}): Promise<void> {
         return;
       }
 
+      if (opts.debug) {
+        console.error(
+          c.dim(
+            `[callback] ${req.method ?? '?'} ${req.url ?? '/'} ` +
+              `ua=${(req.headers['user-agent'] ?? '').slice(0, 60)} ` +
+              `referer=${req.headers.referer ?? '-'}`,
+          ),
+        );
+      }
+
       try {
         const payload = await extractPayload(req, url);
         if (!payload) {
+          // Empty / unrecognised — could be a probe. Reply 400 but keep
+          // listening; the legit callback may still arrive.
+          if (opts.debug) {
+            console.error(c.dim('[callback] ignored: empty/unrecognized payload'));
+          }
           fail(res, 'Empty or unrecognized callback payload');
-          reject(new Error('Empty callback — missing token/secret or state in redirect'));
-          server.close();
           return;
         }
         if (payload.state !== state) {
+          // Stale state — almost always a stray request (prefetch, old tab).
+          // Don't bail the whole login on it; just refuse this one.
+          if (opts.debug) {
+            console.error(
+              c.dim(`[callback] ignored: state mismatch (got ${payload.state ?? '∅'})`),
+            );
+          }
           fail(res, 'Invalid or missing state');
-          reject(new Error('State mismatch — login was cancelled or replayed'));
-          server.close();
           return;
         }
         if (!payload.token || typeof payload.token !== 'string') {
diff --git a/src/index.ts b/src/index.ts
@@ -48,18 +48,28 @@ async function main(): Promise<void> {
     .option('--no-open', 'Do not auto-open the browser; print the URL instead')
     .option('--web-url <url>', 'Override the Timebook web URL')
     .option('--api-url <url>', 'Override the Timebook API URL')
-    .action(async (opts: { port?: number; open: boolean; webUrl?: string; apiUrl?: string }) => {
-      try {
-        await loginCommand({
-          port: opts.port,
-          openBrowser: opts.open,
-          webUrl: opts.webUrl,
-          apiUrl: opts.apiUrl,
-        });
-      } catch (err) {
-        fail(err);
-      }
-    });
+    .option('--debug', 'Print every loopback request hitting /callback (diagnostic)')
+    .action(
+      async (opts: {
+        port?: number;
+        open: boolean;
+        webUrl?: string;
+        apiUrl?: string;
+        debug?: boolean;
+      }) => {
+        try {
+          await loginCommand({
+            port: opts.port,
+            openBrowser: opts.open,
+            webUrl: opts.webUrl,
+            apiUrl: opts.apiUrl,
+            debug: opts.debug,
+          });
+        } catch (err) {
+          fail(err);
+        }
+      },
+    );
 
   program
     .command('logout')
