fix(auth-service): hide Resend on OTP screen when sign-in cannot recover

Previously the OTP screen always offered "Resend code", even when the
upstream PAR row had silently lapsed (suspended tab, mobile background,
heartbeat throttling). The user could click Resend, receive a fresh
email, type the new code, and only then see "Sign in failed" — wasting
their time on a code that could not have worked.

The screen now never surfaces actions that cannot complete the flow:

- Track lastSuccessfulHeartbeatAt; treat the PAR as dead once we cross
  upstream's 5 min AUTHORIZATION_INACTIVITY_TIMEOUT without a fresh ok
  ping (the upstream death point is exact — no margin needed).
- Hide #btn-resend and surface a #btn-start-over (→ /auth/abort) the
  moment parLikelyDead() flips. Reconciled on every heartbeat tick
  (including transient ticks, so a stale-by-time case still hides the
  button) and on the visibilitychange event (so a backgrounded tab
  returning to focus reflects reality immediately).
- Inline "Send a new code" action on the OTP-expired error now branches:
  parLikelyDead() → "Start over"; otherwise existing "Send a new code".

This is the proactive UI complement to the existing reactive abort gate.
Server-side enforcement of the same invariant on /email-otp/send-
verification-otp and /sign-in/email-otp is a separate follow-up.

Test: new @resend-hidden-when-par-dead scenario; full
@otp-and-par-expiry / @par-heartbeat / @resend-after-par-dead /
@otp-expiry suite still passes (7 scenarios, 78 steps).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: aspiers

.changeset/hide-resend-when-sign-in-cannot-recover.md

@@ -0,0 +1,5 @@
+---
+'@certified-app/auth-service': patch
+---
+
+Hide the "Resend code" button on the OTP screen when the sign-in can no longer be recovered, and offer "Start over" instead. Previously, a user who left the OTP screen open long enough for the underlying sign-in window to lapse could click "Resend code", receive a fresh email, type the new code, and only then see "Sign in failed" — wasting their time on a code that could not have worked. The screen now only ever offers actions that can actually complete the sign-in.

e2e/step-definitions/auth.steps.ts

@@ -839,3 +839,49 @@ Then(
     }
   },
 )
+
+// ---------------------------------------------------------------------------
+// Resend-button visibility (fix for the "fresh OTP wasted on dead PAR" UX)
+// ---------------------------------------------------------------------------
+//
+// The page never offers an action that cannot complete the flow. When the
+// PAR is dead, the standalone Resend button is removed from view and a
+// Start over button takes its place — clicking it bails to /auth/abort
+// rather than issuing an OTP that would only fail downstream. The steps
+// below trigger the page's reactive ping (via the visibilitychange
+// handler that fires on tab-foreground) so it can observe the dead PAR
+// and reconcile the UI without a 5-minute wall-clock wait.
+
+When('the OTP form re-checks PAR liveness', async function (this: EpdsWorld) {
+  const page = getPage(this)
+  // Drive the page's reactive ping via a string-source script.
+  // Using page.evaluate(() => ...) inlines esbuild's __name helper,
+  // which then fails in Playwright's evaluation context with
+  // "ReferenceError: __name is not defined". Passing a string
+  // bypasses the bundler.
+  await page.evaluate(`(function () {
+      Object.defineProperty(document, 'visibilityState', {
+        configurable: true,
+        get: function () { return 'visible' },
+      })
+      document.dispatchEvent(new Event('visibilitychange'))
+    })()`)
+})
+
+Then(
+  'the Resend code button is no longer offered',
+  async function (this: EpdsWorld) {
+    const page = getPage(this)
+    await expect(page.locator('#btn-resend')).toBeHidden({ timeout: 5_000 })
+  },
+)
+
+Then(
+  'a Start over button is offered instead',
+  async function (this: EpdsWorld) {
+    const page = getPage(this)
+    await expect(page.locator('#btn-start-over')).toBeVisible({
+      timeout: 5_000,
+    })
+  },
+)

features/passwordless-authentication.feature

@@ -343,6 +343,28 @@ Feature: Passwordless authentication via email OTP
     And the user requests a new OTP via the resend button
     Then the browser lands back at the demo client with an auth error
 
+  # The page never offers actions that cannot complete the flow. When
+  # the upstream PAR has died (silent timeout, suspended tab,
+  # heartbeat throttling), the standalone Resend button is removed
+  # from view and replaced with a Start over button — so the user
+  # never wastes time typing a fresh OTP that could not have worked.
+  # This is the proactive complement to @resend-after-par-dead's
+  # reactive abort gate: rather than letting the click happen and
+  # bouncing it server-side, we surface only forward paths that can
+  # actually succeed.
+  @email @otp-and-par-expiry @resend-hidden-when-par-dead
+  Scenario: Resend button is hidden when the PAR has died — Start over is offered instead
+    When the demo client initiates an OAuth login
+    Then the browser is redirected to the auth service login page
+    And the login page displays an email input form
+    When the user enters a unique test email and submits
+    Then an OTP email arrives in the mail trap for the test email
+    And the login page shows an OTP verification form
+    When the PAR request_uri has expired before the bridge fires
+    And the OTP form re-checks PAR liveness
+    Then the Resend code button is no longer offered
+    And a Start over button is offered instead
+
   @email @otp-and-par-expiry @prompt-login
   Scenario: prompt=login + expired PAR — clean exit back to the OAuth client
     Given a returning user has a PDS account

packages/auth-service/src/routes/login-page.ts

@@ -743,17 +743,38 @@ export function renderLoginPage(opts: {
       var heartbeatEnabled = ${JSON.stringify(opts.heartbeatEnabled)};
       var heartbeatHandle = null;
       var heartbeatIntervalMs = 3 * 60 * 1000;
+      // Upstream's AUTHORIZATION_INACTIVITY_TIMEOUT — once this much
+      // wall-clock time has elapsed since our last successful PAR
+      // refresh, the upstream row is guaranteed to be dead. Used by
+      // parLikelyDead() to hide Resend before the user can click it.
+      var parInactivityTimeoutMs = 5 * 60 * 1000;
+      // Page load is the implicit first PAR refresh — atproto's
+      // PAR_EXPIRES_IN gives a fresh row 5 min on creation, and the
+      // user just hit /oauth/authorize seconds ago. Treat now as
+      // last-known-alive until the first ping confirms otherwise.
+      var lastSuccessfulHeartbeatAt = Date.now();
       // Set to true the moment we know the flow can no longer
       // complete (PAR or auth_flow gone). Resend / Verify gates
       // check this so a click that races the proactive notice
       // still bails to /auth/abort instead of issuing a fresh OTP
       // that would only fail.
       var flowAborted = false;
+      // True iff we have proof the PAR is still alive (last ping
+      // was ok:true and was recent enough to fall inside the
+      // upstream inactivity window). Used to gate every "offer the
+      // user a Resend" decision so they only ever see actions that
+      // can actually complete the flow.
+      function parLikelyDead() {
+        if (flowAborted) return true;
+        return Date.now() - lastSuccessfulHeartbeatAt >= parInactivityTimeoutMs;
+      }
       function pingHeartbeat() {
         return fetch('/auth/ping', { credentials: 'include', cache: 'no-store' })
           .then(function(r) { return r.json(); })
           .then(function(body) {
-            if (body && body.ok === false && body.reason !== 'transient') {
+            if (body && body.ok === true) {
+              lastSuccessfulHeartbeatAt = Date.now();
+            } else if (body && body.ok === false && body.reason !== 'transient') {
               // Auth flow / PAR genuinely dead — no point pinging again,
               // and no point letting the user keep typing. 'transient'
               // (5xx / network blip) does NOT stop the interval; the
@@ -763,7 +784,13 @@ export function renderLoginPage(opts: {
             }
             return body;
           })
-          .catch(function() { return null; /* network blip — caller may retry */ });
+          .catch(function() { return null; /* network blip — caller may retry */ })
+          .finally(function() {
+            // Always reconcile visibility — a 'transient' tick that
+            // pushes us past the inactivity window must hide Resend
+            // even though we never got a definitive 'par_expired'.
+            refreshResendVisibility();
+          });
       }
       function startHeartbeat() {
         if (!heartbeatEnabled) return;
@@ -777,6 +804,16 @@ export function renderLoginPage(opts: {
         }
       }
       window.addEventListener('beforeunload', stopHeartbeat);
+      // When the tab returns to the foreground after being hidden,
+      // setInterval may have been throttled enough that PAR has
+      // silently lapsed. Re-ping immediately so the UI reflects
+      // reality before the user clicks anything.
+      document.addEventListener('visibilitychange', function() {
+        if (document.visibilityState === 'visible' && heartbeatEnabled) {
+          pingHeartbeat();
+          refreshResendVisibility();
+        }
+      });
 
       // Show the proactive "this won't work — start over" notice when
       // the flow is unrecoverable. Disables the OTP boxes, the verify
@@ -819,6 +856,41 @@ export function renderLoginPage(opts: {
         errorEl.appendChild(startOverBtn);
       }
 
+      /**
+       * Toggle the standalone Resend button between visible and
+       * hidden based on whether the PAR is still alive. The button
+       * is removed from view (display:none) rather than just
+       * disabled — a button the user cannot productively click
+       * shouldn't be on the page at all. When hidden, a "Start over"
+       * link is shown in its place so the user always has a forward
+       * path. Idempotent — safe to call from heartbeat ticks,
+       * visibility change handlers, and inline render paths.
+       */
+      function refreshResendVisibility() {
+        var resendBtn = document.getElementById('btn-resend');
+        var startOverLink = document.getElementById('btn-start-over');
+        if (!resendBtn) return;
+        if (parLikelyDead()) {
+          resendBtn.style.display = 'none';
+          if (!startOverLink) {
+            startOverLink = document.createElement('button');
+            startOverLink.type = 'button';
+            startOverLink.id = 'btn-start-over';
+            startOverLink.className = 'btn-secondary';
+            startOverLink.textContent = 'Start over';
+            startOverLink.addEventListener('click', function() {
+              window.location.href = '/auth/abort';
+            });
+            resendBtn.parentNode.insertBefore(startOverLink, resendBtn);
+          }
+        } else {
+          resendBtn.style.display = '';
+          if (startOverLink && startOverLink.parentNode) {
+            startOverLink.parentNode.removeChild(startOverLink);
+          }
+        }
+      }
+
       /**
        * Reactive gate used by the Resend and Verify click handlers.
        * Pings /auth/ping synchronously; if the result indicates the
@@ -983,6 +1055,7 @@ export function renderLoginPage(opts: {
         if (otpBoxes.length) otpBoxes[0].focus();
         clearError();
         startHeartbeat();
+        refreshResendVisibility();
       }
 
       function showEmailStep() {
@@ -1104,15 +1177,21 @@ export function renderLoginPage(opts: {
             // expired") plus generic "expir"/"too long" variants.
             var isExpired = /expir|too long/i.test(result.error);
             if (isExpired) {
-              // The inline action triggers the same Resend handler,
-              // which itself runs abortIfFlowDead() before issuing
-              // a new code. So even if the PAR is dead the user
-              // gets the spec-compliant bounce rather than a fresh
-              // OTP that wouldn't work — no need to gate the
-              // action's visibility separately here.
-              showErrorWithAction(result.error, 'Send a new code', function() {
-                document.getElementById('btn-resend').click();
-              });
+              // Only offer "Send a new code" when the PAR is still
+              // alive. If it isn't, a fresh OTP would issue but
+              // never complete — wasting the user's time on a code
+              // that can't work. Show "Start over" instead so the
+              // only forward path we surface is one that will
+              // actually succeed.
+              if (parLikelyDead()) {
+                showErrorWithAction(result.error, 'Start over', function() {
+                  window.location.href = '/auth/abort';
+                });
+              } else {
+                showErrorWithAction(result.error, 'Send a new code', function() {
+                  document.getElementById('btn-resend').click();
+                });
+              }
             } else {
               showError(result.error);
             }
@@ -1185,8 +1264,10 @@ export function renderLoginPage(opts: {
           });
         }
         // OTP form is already visible server-side; showOtpStep() never
-        // ran, so kick off the heartbeat ourselves.
+        // ran, so kick off the heartbeat ourselves and reflect the
+        // current PAR-liveness state in the Resend button visibility.
         startHeartbeat();
+        refreshResendVisibility();
       }
     })();
   </script>