Skip to content

docs: describe the magic link redirect allowlist that already ships - #298

Merged
Bccorb merged 1 commit into
mainfrom
docs/magic-link-redirect-allowlist-landed
Sep 8, 2026
Merged

docs: describe the magic link redirect allowlist that already ships#298
Bccorb merged 1 commit into
mainfrom
docs/magic-link-redirect-allowlist-landed

Conversation

@Bccorb

@Bccorb Bccorb commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Closes #242.

The issue is already implemented

#242 asks for a magic_link_redirect_uris system config key, and describes it as blocked on cross-repo work: adding it to SystemConfigSchema in @seamless-auth/types, a version bump, and a coordinated release.

That happened. The key came in with @seamless-auth/types 0.19.0, adopted here in #268, and everything the issue's scope list asks for is in place:

  • SystemConfigSchema declares magic_link_redirect_uris: z.array(RedirectTargetSchema).default([]), and the patch schema accepts it
  • SYSTEM_CONFIG_DEFAULTS sets [], SYSTEM_CONFIG_ENV_MAP maps MAGIC_LINK_REDIRECT_URIS, and parseSystemConfigEnvValue handles it as a string array
  • resolveMagicLinkUrl passes it to allowedRedirect, so a non-empty list is matched exactly and an empty one falls back to comparing against origins
  • tests/unit/services/magicLinkRedirect.spec.ts covers the custom scheme, the exact match refusing an unlisted target on a configured origin, and the empty-list fallback

So there is no code to write. What is left is the last line of the issue: the documentation still describes it as a missing prerequisite.

What changed

docs/api-contract.md, under Magic link destination, said the key "needs a version bump and a coordinated release across this API and both SDKs". It now describes what the key does, why the match is exact (a custom scheme has no origin to compare, so only an operator-listed literal is safe), and the part that is easy to get wrong: once the list is non-empty it is the whole allowlist, so a destination on a configured origin that is not listed is refused. That is the point, since the alternative is widening origins, which gates passkey ceremonies.

docs/configuration.md gains the system_config table row it was missing. Checked against systemConfig.envMap.ts, it was the only env-mapped key absent from that table.

Checks

Documentation only, no source changed.

  • npm run format:check: clean
  • tests/unit/services/magicLinkRedirect.spec.ts and tests/unit/config/systemConfigEnvMap.spec.ts: 17 passed, confirming the behavior the docs now describe

docs/api-contract.md said a destination that cannot be expressed as a WebAuthn
origin "needs a magic_link_redirect_uris system config key" living in
@seamless-auth/types, and that adding it would take a coordinated release. The
key landed with types 0.19.0 in #268: it has a default, an env mapping, a parse
case, and resolveMagicLinkUrl passes it to allowedRedirect, with tests covering a
custom scheme, exact match and the empty-list fallback.

The section now describes what the key does, including that a non-empty list
becomes the whole allowlist rather than widening the origin comparison, and the
system_config table in docs/configuration.md gains the row it was missing. It was
the only env-mapped key absent from that table.

Closes #242
@Bccorb
Bccorb merged commit 343efc3 into main Sep 8, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(magic-link): dedicated redirect allowlist for custom schemes and non-WebAuthn hosts

1 participant