Cognito password reset: ClientId mismatch diagnostic

The trap

Cognito’s ConfirmForgotPassword validates the verification code against the same ClientId that issued it. When the reset page submits with a different ClientId, Cognito returns ExpiredCodeException (not CodeMismatchException). The symptom (“expired”) points at code lifetime, but the cause is identity-routing.

The error is identical whether the code was issued 1 hour ago or 5 seconds ago. The lifetime-vs-routing distinction is invisible at the API surface.

How the system routes today

The custom_message Lambda appends cid (event.callerContext.clientId) and pid (event.userPoolId) to every reset URL:

https://www.thephenom.app/reset-password?code=<C>&email=<E>&cid=<originating-client>&pid=<pool>

The reset-password.js page reads ?cid= and uses it as the ClientId for ConfirmForgotPassword. Falls back to the staging hasura client 6sjjnkaeagnqgkmbl1mr5rtfsr for emails already in flight that predate this change.

Any client in any pool that initiates a reset can complete it on www.thephenom.app/reset-password.

Per-pool coverage matrix

To regenerate the current client_id list from AWS:

for POOL in us-east-1_AkG9mnbjA us-east-1_n8gO6SbP6 us-east-1_knEL7cqS3; do
  echo "=== $POOL ==="
  aws cognito-idp list-user-pool-clients --user-pool-id $POOL \
    --output text --query 'UserPoolClients[].[ClientId,ClientName]'
done

If the client_id list changes (new app client added or an old one rotated), update the matrix here AND the KNOWN_CLIENT_IDS array in Phenom-earth/www/tests/reset-password.test.js.

The test guardrail

Phenom-earth/www/tests/reset-password.test.js asserts 14 things via jsdom: 4 base invariants and 10 per-client routing assertions (one for every Cognito app client across all three pools listed above).

Base invariants:

1. The page reads ?cid= from the URL when present.
2. ConfirmForgotPassword is called with the cid value, not a hardcoded ID.
3. The fallback to the hardcoded staging hasura client engages when ?cid= is absent (back-compat for already-sent emails).
4. Regression guard: when ?cid= is present, the page does NOT silently use a hardcoded ID, even if someone re-adds one elsewhere in the file.

Per-client routing (10 assertions, one per known client):

For each (cid, label) in KNOWN_CLIENT_IDS, the test verifies that when the URL contains ?cid=<cid>, ConfirmForgotPassword’s request body carries exactly ClientId: <cid>. Catches a regression class that the base invariants miss: a change that hardcodes a different client_id passes the “falls back to default” test but breaks for every other client.

The test runs on every PR via .github/workflows/reset-password-guardrail.yml. If routing regresses for any single client, CI fails before the change ships.

What this guardrail covers and does not cover:

• Catches static-routing regressions in the reset page itself.
• Catches accidental removal of ?cid= handling.
• Does NOT exercise the full live flow (Cognito API, real Lambda invocation, SES delivery). A separate scheduled E2E probe against a test user in phenom-dev-local is the right complement; see “Known follow-up” below.

Diagnostic playbook

Symptom: ExpiredCodeException immediately after a fresh code is issued.

Step 1: Inspect the URL the reset email links to. Does it carry ?cid=?

• If ?cid= is absent: the Lambda has not been updated for this pool yet, or the Lambda version rolled back. Check the deployed Lambda version.
• If ?cid= is present but has the wrong value: the Lambda is reading from the wrong context field.

Step 2: Inspect the validation handler. Is the ClientId hardcoded or read from ?cid=?

Do not assume code lifetime. Cognito will not surface the routing mismatch as a separate error code; it returns ExpiredCodeException regardless.

Confirming routing via CLI:

# 1. Trigger a reset for a test user and note the cid in the URL from the email.
aws cognito-idp forgot-password \
  --client-id <ISSUING_CLIENT_ID> \
  --username test-staging@thephenom.app \
  --region us-east-1

# 2. Attempt ConfirmForgotPassword with the CORRECT cid (should succeed with a valid code):
aws cognito-idp confirm-forgot-password \
  --client-id <ISSUING_CLIENT_ID> \
  --username test-staging@thephenom.app \
  --confirmation-code XXXXXX \
  --password 'NewPassword!2026Aa#' \
  --region us-east-1

# 3. Attempt ConfirmForgotPassword with a DIFFERENT client_id (reproduces the trap):
aws cognito-idp confirm-forgot-password \
  --client-id <DIFFERENT_CLIENT_ID> \
  --username test-staging@thephenom.app \
  --confirmation-code XXXXXX \
  --password 'NewPassword!2026Aa#' \
  --region us-east-1
# → ExpiredCodeException

Quick reference

• Symptom: ExpiredCodeException immediately after a fresh code is issued
• Real cause: ConfirmForgotPassword submitted with a different ClientId than the one that issued the code
• Where to look first: the URL the reset email links to: does it carry ?cid=?
• Where to look second: the validation handler: is the ClientId hardcoded or read from the URL?
• What NOT to assume: the code lifetime

Design rule for auth-callback flows

Any email-based callback flow against Cognito (or any auth provider with per-client codes) must follow three rules:

1. The token is bound to the client that issued it. Pass enough context in the callback URL (client_id, pool_id, tenant_id, whatever scopes the binding) so the callback page can route correctly. Hardcoding one ClientId is fine for a single-client flow; the moment you have two clients, hardcoding is a silent multi-tenant bug.

2. ExpiredCodeException is a routing symptom, not only a lifetime symptom. When the same code returns ExpiredCodeException from validator-A and succeeds against validator-B, the bug is the ClientId mismatch.

3. Test the routing, not the renderer. Page-render tests can be green while the page sends auth requests to the wrong endpoint. The guardrail that pays for itself asserts the network call’s body.ClientId matches the ?cid= from the URL.

Known follow-up

• E2E synthetic probe: a scheduled GitHub Action that runs ForgotPassword + ConfirmForgotPassword against a known test user in phenom-dev-local once per hour and alerts on any non-success path. Catches issues the unit-level guardrail cannot, such as Lambda misconfiguration, IAM role drift, or SES sender-reputation flips. Best home: phenom-infra/.github/workflows/.