feat(redirects): make allowed redirect hosts configurable

[gjtorikian]

The authorize endpoints only ever accepted localhost, 127.0.0.1 and [::1] as a redirect_uri host, which keeps a reachable emulator from being used as an open redirect. Test environments that fake production-like hostnames — to stay as close to production as possible — had no way to opt in.

• Configured hosts add to the localhost set rather than replacing it, so the guard stays on by default and every existing callback keeps working. There is no way to end up with a weaker default by accident.
• Three ways to set it, matching how the emulator already exposes options: --redirect-hosts (repeatable, comma-separated), WORKOS_EMULATE_REDIRECT_HOSTS, and createEmulator({ allowedRedirectHosts }). The flag wins over the environment.
• An entry is a hostname (app.example.test), a subdomain wildcard (*.example.test, which deliberately does not match the apex), or * to turn the check off. A whole origin (https://app.example.test:8443) is accepted and reduced to its hostname, since an origin is usually what people have on hand.
• Entries are normalized at startup, so a host that could never match (https://, anything with whitespace) fails loudly instead of silently rejecting every request. Survives reset().
• Both sides are reduced to the single form a request carries, so a host stays configurable the way it is actually written: IPv6 in any legal spelling ([FD00::0001]), IPv4 in any shorthand URL accepts (10.1, 192.168.001.1, 2130706433), an internationalized name either bare or punycoded (møller.test), and a trailing dot optional. Without that, an ordinary way of writing an address validated, started the emulator and then matched nothing.
• Applies at all four redirect sites: redirect_uri on /user_management/authorize, /sso/authorize and /data-integrations/:slug/authorize, plus return_to on /user_management/sessions/logout.
• Interactive mode checks the host on the GET, before the login page renders the redirect_uri into a hidden field, rather than leaving every check to the form's POST. A host the emulator will not redirect to no longer serves a working sign-in form and then refuses once someone has filled it in.
• Logout re-serializes return_to into the Location header the way the three authorize endpoints already did, instead of echoing it verbatim. A space is legal in the URI a request carries — searchParams.get decodes a raw + into one — and is not legal in the header it produces.

assertLocalRedirectUri is renamed to assertAllowedRedirectUri and now takes the store. It was never part of the public export surface, so this is not a breaking change for consumers.

Separately, every option-derived store entry is now applied from one closure, at startup and again from reset(). store.reset() drops all data, and only the redirect hosts were being restored — so reset() quietly returned an interactive emulator to serving redirects, and dropped webhookRetryConfig and webhookDebugMode with it.

Closes #49

[greptile-apps]

Greptile Summary

The PR makes redirect-host allowlisting configurable while retaining the localhost defaults and completes validation for malformed host patterns.

• Adds CLI, environment-variable, and programmatic configuration paths.
• Normalizes and validates hostnames, origins, wildcard subdomains, IP literals, and internationalized names at startup.
• Applies the allowlist across authorization and logout redirects and restores option-backed state after reset.
• Adds comprehensive normalization, routing, scheme-safety, and reset coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported malformed host-pattern acceptance is addressed by validation before and after canonicalization.

Important Files Changed

Filename	Overview
src/workos/helpers.ts	Implements startup normalization and strict host-pattern validation, including the complete fix for the previously reported malformed-pattern acceptance.
src/index.ts	Normalizes programmatic redirect-host options, stores them for route checks, and reapplies option-backed data after reset.
src/cli.ts	Adds repeatable redirect-host flags, environment fallback, comma splitting, and empty-value validation.
src/workos/redirect-hosts.spec.ts	Covers malformed patterns, canonicalization, wildcard behavior, endpoint enforcement, unsafe schemes, and reset persistence.
src/workos/routes/auth.ts	Applies the configurable redirect guard to AuthKit authorization paths, including interactive requests.
src/workos/routes/sso.ts	Applies the configurable redirect guard to SSO authorization paths, including interactive requests.
src/workos/routes/data-integrations.ts	Uses the configured allowlist when validating data-integration callback redirects.
src/workos/routes/sessions.ts	Validates and safely serializes session logout return targets through the shared redirect guard.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[CLI, environment, or createEmulator options] --> B[Split configured entries]
    B --> C[Normalize and validate hosts at startup]
    C --> D[Store normalized allowlist]
    D --> E[Authorize and logout routes]
    E --> F[Parse redirect URI]
    F --> G{Safe scheme and non-empty hostname?}
    G -- No --> H[Return invalid_redirect_uri]
    G -- Yes --> I{Matches localhost or configured host?}
    I -- No --> H
    I -- Yes --> J[Issue redirect]

Loading

_{Reviews (6): Last reviewed commit: "fix(emulator): re-apply option data afte..." | Re-trigger Greptile}