feat: trigger the deep-link login handoff via flow=deeplink and a UUID request id

[LautaroPetaccio]

Summary

Reworks the /auth/requests/:requestId deep-link login handoff so the Explorer team can correlate a login with the instance that requested it.

Previously the handoff (post the signed identity → open the client via decentraland://open?signin=<identityId>, skipping the recover/verify flow) was triggered by a magic request id, client-login. Now it is triggered by the ?flow=deeplink query param (compared case-insensitively), and the route requestId must be a valid UUID v4 — the client-generated correlation id — which is forwarded to the client as the deep link's authRequestId.

When flow=deeplink is set there is no longer any need to retrieve an id from, or make a request to, the auth-server.

Behavior

• ?flow=deeplink + valid UUID v4 id → post identity, open the client, forward the UUID as authRequestId. Never calls recover.
• ?flow=deeplink + non-UUID id → rejected up front with the error view ("The sign-in link is invalid."), no identity post, no recover.
• No flow param → unchanged normal request flow (recover/verify/transaction).

Removed

• The client-login pseudo request id (CLIENT_LOGIN_REQUEST_ID).
• The recover-based deep-link sign-in variant: the VerifySignIn deep-link copy, the DEEP_LINK_SIGN_IN analytics type, and the now-unreachable isDeepLinkFlow argument of the auth clients' recover().
• The dead request.deep_link_confirm / request.sign_in translation keys (all 5 locales). login.sign_in is untouched.

Implementation

• shared/locations.ts: new isDeepLinkFlowEnabled (case-insensitive) and isValidUuidV4 helpers; buildRequestPageUrl reuses the shared param constants.
• RequestPage.tsx: keys the handoff off isDeepLinkFlow; guards a malformed id in both effects; forwards the route UUID as the signin authRequestId.
• httpClient.ts / wsClient.ts: drop the unused recover param (analytics for the recover path is now always VERIFY_SIGN_IN).

Testing

• Unit: RequestPage.spec.tsx and locations.spec.ts updated to the new contract (case-insensitive flow, UUID validation, route-UUID-as-authRequestId, invalid-id error). Full suite: 788 passing.
• E2E (request-edge-cases.spec.ts, real browser): valid-UUID handoff (posts identity, no recover) and invalid-UUID error view, plus the untouched different-account / expired / fulfilled cases.
• tsc and eslint clean.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
auth	Ready	Preview, Comment	Jul 13, 2026 4:59pm

[decentraland-bot]

Review — PR #430

feat: trigger the deep-link login handoff via flow=deeplink and a UUID request id

Clean, well-structured PR. The migration from the magic client-login request ID to ?flow=deeplink + UUID v4 validation is correct and thoroughly tested. No security, correctness, or architectural concerns.

What was checked

• UUID v4 regex (locations.ts): correctly anchored (^/$, no multiline flag), validates version digit 4 and variant bits [89ab], case-insensitive. No bypass vectors (trailing newline, whitespace, wrong version/variant all rejected — confirmed by tests).
• Deep link injection surface: the validated UUID (only [0-9a-fA-F-] chars) is passed through URLSearchParams in getSigninDeeplink, which encodes values. No injection risk.
• Flow gating (RequestPage.tsx): isInvalidDeepLinkId correctly short-circuits both effects before any profile work or identity posting. The loadRequest() path is only reached when isDeepLinkFlow is false, so removing the old && !isDeepLinkFlow guard on the skipSetup check is safe.
• recover() param removal (httpClient.ts, wsClient.ts): clean parallel change, no callers still pass the removed param.
• Dead code removal: CLIENT_LOGIN_REQUEST_ID, DEEP_LINK_SIGN_IN analytics type, isDeepLinkFlow prop on VerifySignIn, and translation keys across 5 locales — all confirmed zero remaining references.
• Consumer impact: CLIENT_LOGIN_REQUEST_ID and the client-login string have no external consumers across the decentraland org. Safe to remove.
• Git conventions: title (feat: ...) and branch (feat/deep-link-login-by-uuid) follow semantic commit / ADR-6.
• CI: all checks passing (tests, e2e, audit, CodeQL, lint).

Findings

[P2] RequestPage.spec.tsx:93 — buildRequestPageUrl mock discards options
The mock (requestId, targetConfigId) => ... ignores the third options argument, so tests cannot verify that flow=deeplink, bridgeOnly, and authRequestId are correctly preserved through login round-trip redirects. Not introduced by this PR — pre-existing.

[P2] locations.spec.ts — UUID variant coverage
The valid-UUID test only exercises variant bit a (a456). Adding a case with variant 8, 9, or b would confirm the regex accepts all valid variants.

[P2] Pre-existing — loginMethodParam missing from Effect 2 deps (RequestPage.tsx:~807)
loginMethodParam is read inside Effect 2 but absent from its dependency array. Safe in practice (derived from searchParams) but would trigger the exhaustive-deps lint rule. Not introduced by this PR.

Verdict

Approved — no P0 or P1 findings. The three P2s are pre-existing or minor test-coverage suggestions.

---

Reviewed by Jarvis 🤖 · Requested by Lautaro Petaccio (<@U5RLBKGB3>) via Slack