OAuth Test Data Needs a Session Boundary

OAuth tests often fail in a deceptively reassuring way: the provider returns a valid authorization code, the callback succeeds, and the test reports a green login. But which browser started that flow? Which test identity was attached to it? Was the code fresh, or did a retry consume an older response?

The answer should not depend on a shared inbox, a lucky timing window, or a test runner guessing which message is newest. OAuth test data needs the same boundaries as production data. A temporary mailbox can make setup convenient, but it does not prove that a callback belongs to the browser session that requested it.

Why a valid code is not enough

An authorization code proves that an identity provider issued something for an authorization request. It does not, by itself, prove that the current browser initiated that request. If a callback accepts any valid-looking code, a test can accidentally validate the wrong flow, and a real application may be exposed to login CSRF or account-linking mistakes.

The distinction is important when teams use an email temporary free service or a disposable email address for test setup. Those tools help isolate mail from real users. They should not become an authentication shortcut.

For every callback, the application should be able to answer four questions:

• Which local session began the flow?
• Which provider, redirect URI, and client were expected?
• Which test identity was reserved for the attempt?
• Has this exact authorization response already been consumed?

If those answers are missing, the test is checking delivery and luck more than authentication.

A small threat model for test identities

Start with the failures that matter, rather than a long list of OAuth terminology. In a browser test or preview environment, I would model these outcomes:

1. A callback from one test is accepted by another browser session.
2. A stale authorization code is consumed after a retry.
3. An inbox message from an earlier run is mistaken for the current verification message.
4. A shared test account is linked to the wrong local user.
5. Logs contain the code, mailbox address, or enough query data to recover the flow.

The first two are integrity problems. The third is a test-isolation problem that can hide the first two. The last two create privacy and account ownership risks. None require an exotic attacker; parallel CI jobs and slow provider responses are enough to expose them.

Separate product identity from test convenience

A test email address is an input fixture, not an identity oracle. Store a run ID, scenario name, and expiry beside the fixture so the test can prove which data it owns. Do not infer ownership from the newest message or from a display name.

For example, a fixture record might contain:

type TestIdentity = {
  runId: string;
  scenario: string;
  address: string;
  provider: string;
  expiresAt: number;
  consumedAt?: number;
};

The address can be generated for a run, but the run still needs an independent correlation value. If a test uses tem email or tempail as an informal label in debugging notes, keep those strings out of policy decisions and account keys. A typo is not a stable identity boundary.

Teams should also decide what happens when an address is unavailable. Failing the test with an explicit fixture error is safer then silently falling back to a shared mailbox. That fallback can make a flaky test look healthy while it is reading another scenario's message.

Bind every test identity to one browser attempt

At the beginning of an OAuth flow, create a short-lived attempt record. Bind state and PKCE to the initiating session, and associate the attempt with the reserved test identity. Store a hash of state where practical, while keeping the verifier available for the code exchange.

type OAuthAttempt = {
  stateHash: string;
  codeVerifier: string;
  testRunId: string;
  redirectUri: string;
  expiresAt: number;
  used: boolean;
};

session.oauthAttempt = {
  stateHash: sha256(state),
  codeVerifier,
  testRunId: currentRunId,
  redirectUri: EXPECTED_REDIRECT_URI,
  expiresAt: Date.now() + 5 * 60_000,
  used: false,
};

On return, compare the received state with the stored value, check the expiry, and consume the attempt atomically. The test should also confirm that the callback's provider and redirect URI match the attempt. A retry should create a new attempt, not reopen the old one.

This is a useful place to review expiring signup privacy logs, because test artifacts can outlive the browser session that created them. Retention is part of the boundary, not just housekeeping.

Validate before creating a session

Keep the order of checks obvious and boring:

1. Confirm the callback reached the expected route and provider.
2. Reject an error response unless its state matches the active attempt.
3. Validate state, PKCE, expiry, and one-time use.
4. Exchange the code with the exact redirect URI from the attempt.
5. Validate issuer, audience, nonce when applicable, and token claims.
6. Map the provider subject and issuer to the intended local account.
7. Create the local session only after all checks pass.

Do not use the mailbox address as the only account key. Addresses can be recycled, normalized differently, or shared by a test harness. The provider issuer plus stable subject is a stronger identity pair. The test fixture should then assert that the resulting local account is the one expected for its run.

For email-based OAuth flows, read the mailbox boundary separately from the callback boundary. This explanation of a mailbox trust boundary for OAuth email links is a good companion review. Mailbox access can support a flow, but it must not erase browser-session checks.

Log evidence, not secrets

Useful diagnostics include a correlation ID, run ID, provider, scenario, event name, and elapsed time. They do not need the raw code, state, nonce, access token, full email address, or complete callback query string.

When a check fails, record a reason category such as state_mismatch, attempt_expired, fixture_owned_by_other_run, or code_replay. This makes failures actionable without turning CI logs into a second credential store. It also helps separate an inbox delay from a real callback rejection.

A practical review checklist

Before shipping an OAuth test flow, check:

• Is every fixture owned by one run and scenario?
• Is the test identity expired and cleaned up on both success and failure?
• Are state and PKCE bound to the initiating browser session?
• Is an authorization attempt consumed atomically and only once?
• Are provider, issuer, audience, nonce, and redirect URI validated?
• Is the local account keyed by a stable provider subject, not only an email address?
• Can a retry distinguish a fresh message from an earlier run?
• Do logs expose only bounded, non-secret evidence?

Questions teams usually ask

Can a temporary mailbox replace state validation?

No. It can help prove that a message was delivered to a controlled fixture. It cannot prove that the current browser initiated the OAuth request.

Should every CI job get a different address?

Prefer an address or mailbox namespace that is isolated by run and scenario. If the provider cannot offer that, use strict correlation and cleanup, and treat collisions as test failures rather than hiding them.

What should happen when the callback is late?

Fail closed after the attempt expires, retain a small diagnostic receipt, and ask the test to start a fresh flow. Extending the same attempt indefinitely makes stale responses harder to detect.

The goal is not to make test infrastructure complicated. It is to make a successful OAuth test explainable: this browser started this attempt, this fixture belonged to this run, this code was exchanged once, and this local account was the intended one. That is a modest boundary, but it prevents a surprising number of green tests that should have been red.