feat: cross flow wallet auth

[cyaiox]

Summary

Adds end-to-end cross-platform (@cross) coverage for the auth handoff between the Decentraland web dapp and the Unity desktop client — in both directions — plus the runner infrastructure that lets a single Playwright session orchestrate staged dotnet test assertions against a long-running, AltTester-instrumented Explorer.

The two stacks never call each other directly. They communicate only through flat files on disk (the same contract the real launcher/client use), so the C#/.NET and TS/Playwright suites stay fully decoupled.

Flow 1 — client → web wallet device-pairing (explorer-wallet-login.spec.ts)

Verifies the wallet sign-in a user starts inside the client and completes in the browser:

1. C# WalletLoginCapture.TestCaptureWalletAuthHandoff clicks Metamask on Unity's auth screen. The client's auth-api round-trip ends in Application.OpenURL, which the #if ALTTESTER hook in UnityAppWebBrowser intercepts to write auth-url.txt instead of opening the system browser.
2. In parallel, Playwright signs up a fresh DCL profile on /auth/login (existing-profile path via AUTH_TEST_WALLET_PRIVATE_KEY, or fresh-wallet + QuickSetup signup as a clean-env fallback) so the identity exists by the time we reach the requests page.
3. Playwright reads auth-url.txt, derives requestId from the redirectTo query param, and navigates to /auth/requests/<id>?targetConfigId=default. That connection makes auth-api emit request-validation-status, which activates Unity's Verification.Dapp.Screen with the validation code.
4. Device-pairing safety check (the real product feature): C# WalletLoginCodeRead.TestReadVerificationCode reads Unity's code and writes it to disk; Playwright deep-scans the verify-sign-in card for the web-side code, then asserts expect(webCode).toBe(unityCode). Skipping this makes the test green but doesn't validate the security property users rely on.
5. Click "YES, THEY ARE THE SAME" → signature flows back over the auth-api websocket → WalletLoginInWorldEmote.TestInWorldAndRunEmote asserts the HUD is up and plays Fist Pump.

Flow 2 — web → client signup handoff (web-to-client-handoff.spec.ts)

Verifies the web-first path: fresh-user OTP signup on the dapp boots the client authenticated as the right user:

1. OTP signup on the dapp. The spec races two post-OTP URLs to detect new-user (/auth/quick-setup) vs. recurrent (/) and resolves the username it will later assert.
2. The personalised download CTA's URL embeds an auth-redeemable session UUID. The POM intercepts the underlying network request (the dapp re-serves the .dmg as a Blob, so download.url() is useless), and parseAuthTokenFromDownloadUrl derives the UUID in pure JS — a verbatim port of the launcher's auto_auth.rs algorithm, so we exercise the dapp's URL-mint contract without running the launcher binary.
3. The UUID is written to auth-token-bridge.txt; the expected username to expected-username.txt.
4. The instrumented Explorer is launched fresh (its TokenFileAuthenticator reads the bridge on first-launch — pre-launching would invalidate Flow 2's contract).
5. Identity guard (load-bearing): C# WebFirstLoginUsernameAssert.TestInWorldUsernameMatches polls the welcome-screen greeting and accepts either Welcome <name> (new user) or Welcome back <name> (returning). It then runs the shared TestInWorldAndRunEmote. The order matters — a mismatch aborts the suite before any in-world side effects land on the wrong account.

Infrastructure & supporting changes

• explorer-runner.ts — setupExplorerStack / teardownExplorerStack spawn AltTester Desktop + Explorer as detached background processes that outlive individual dotnet test --filter runs; runExplorerTest(filterName) does plain staged dotnet test; EXPLORER_BUILD_TARGET selects the Unity build (absolute path → mf --local-build; branch/PR/version → mf explorer install). Also launchInstrumentedExplorer / relaunchExplorer (sharing an openExplorerApp helper) and clearExplorerIdentityCache (recursive fs.rmSync) for Flow 2's fresh-boot requirement.
• Helpers — auth-request-bridge.ts (Flow 1 file IPC), token-bridge.ts + download-gateway.ts (Flow 2 bridge + URL→UUID parser), persistent-data-path.ts (single macOS-only getCrossStackPath() resolver replacing duplicated platform switches), plus shared sleep() and uniqueUsername() to drop local copies.
• C# fixtures & views — CrossWalletLoginTests.cs (capture + code-read stages + shared CrossPlatformPaths), CrossWalletLoginTestsWithEmoteRun.cs (in-world + emote), CrossWebFirstLoginTests.cs (identity guard); new VerificationDappAuthScreenView, additions to AuthenticationMainScreenView, and ViewContainer registration.
• Diagnostics — DiagnosticTests gains a [Category("Diagnostic")] scene-tree dump (consolidated from the deleted SceneInspector.cs) for future locator discovery; doesn't run in default invocations.
• Docs — web/CLAUDE.md documents both flows, the file-IPC contract, and the runner conventions; .env.example gains the EXPLORER_BUILD_TARGET block.

Notes

• The runner stack and IPC paths are macOS-only (open/pkill/lsof, ~/Library/Application Support/...). Flow 1 files live under the Explorer's persistentDataPath (.../Decentraland/Explorer/ — verified at runtime; see the comment in CrossWalletLoginTests.cs re: the PR-prose folder-name slip); Flow 2 files live under .../DecentralandLauncherLight/.
• If any of those paths or fixture names change, the TS helpers + spec headers + explorer-runner.ts must be updated together.

Dependencies

Depends on: decentraland/unity-explorer#8862 — the #if ALTTESTER OpenUrl hook (writes auth-url.txt, suppresses Application.OpenURL in ALTTESTER builds) that Flow 1 relies on. Pin via EXPLORER_BUILD_TARGET until merged.

[decentraland-bot]

Review — feat: cross flow wallet auth

Files changed: 25 (+2130 -117) · CI: pending

Substantial cross-platform auth E2E infrastructure. Well-documented, clear orchestration design with file-based IPC between Playwright (TS) and Unity (C#). The two-flow architecture (client→web and web→client) is sound. That said, there are a few correctness issues that should be resolved before merge.

---

P1 — Major (should fix before merge)

1. [Correctness] Likely macOS path mismatch between C# test paths and Unity's Application.persistentDataPath
CrossPlatformPaths.AuthUrlPath in CrossWalletLoginTests.cs builds:

~/Library/Application Support/Decentraland/Explorer/auth-url.txt

But PR #8862's description states Unity's Application.persistentDataPath on macOS resolves to:

~/Library/Application Support/Decentraland/Decentraland Unity Explorer/auth-url.txt

The product name in ProjectSettings.asset determines the folder name. If it's "Decentraland Unity Explorer" (as the companion PR states), the C# test will poll a directory that Unity never writes to — and the test will always time out. The same mismatch applies to AuthVerificationCodePath.

Please verify the actual value of Application.persistentDataPath at runtime and align the C# CrossPlatformPaths constants. Same for the TS-side getAuthUrlPath() and getAuthVerificationCodePath() in auth-request-bridge.ts.

2. [Correctness] Windows persistentDataPath uses LocalLow, not Roaming
The TS helpers (getAuthUrlPath, getAuthVerificationCodePath) use process.env['APPDATA'] (= %APPDATA% = Roaming) but Unity's Application.persistentDataPath on Windows maps to %USERPROFILE%\AppData\LocalLow\<company>\<product>. These are different directories. While the tests are currently macOS-only (the process management uses pkill, open, lsof), the path functions claim cross-platform support. Either:

• Fix the Windows path to use LOCALAPPDATA + Low, or
• Remove the win32/linux branches and throw "macOS only" until cross-platform support is actually needed.

3. [Correctness] readWebCode() is fragile — will match any digit-only element on the page
In explorer-wallet-login.spec.ts, the DOM deep-scan finds ALL leaf elements with digit-only text and returns the first group (grouped.find(s => s.length >= 1)). If the page contains other numeric content (counters, timestamps, prices, user counts), this will silently return the wrong value and the code-match assertion may produce confusing false passes or failures.
Suggestion: scope the scan to the verify-sign-in container (e.g. page.locator('[data-testid="verify-sign-in-approve-button"]').locator('..').locator('..')) rather than the entire document. Or wait for the TODO data-testid on the code element.

---

P2 — Minor (non-blocking improvements)

4. [Duplication] Platform-path switch blocks repeated 4×
getAuthUrlPath(), getAuthVerificationCodePath(), getExpectedUsernamePath(), and getTokenBridgePath() each have identical switch(process.platform) structures differing only in the directory and filename. Extract a shared getPersistentDataPath(app: 'explorer' | 'launcher', filename: string): string helper.

5. [Duplication] sleep() utility defined in multiple files
Both auth-request-bridge.ts and explorer-runner.ts define their own sleep(). Consider using a shared utility from shared/helpers/.

6. [Duplication] uniqueUsername() defined identically in two spec files
explorer-wallet-login.spec.ts and web-to-client-handoff.spec.ts both define const uniqueUsername = (): string => \QA${randomBytes(3).toString('hex')}``. Extract to a shared test helper.

7. [YAGNI] AltTester WebSocket client is entirely unimplemented
shared/alttester/ adds ~400 lines (client + protocol + index + README) where every method throws "not yet implemented". The README explicitly says "scaffold only — not yet functional" and lists a 5-step follow-up plan. Consider deferring this to the PR that actually implements it — shipping dead code adds review surface and maintenance burden without runtime value.

8. [Style] SceneInspector.cs overlaps with DiagnosticTests.DiagnoseAuthScreenUsernameLabel
Both are diagnostic scene-dump tools with similar patterns (enumerate all elements, filter, dump). Consider consolidating into a single diagnostic fixture.

---

Security Review

No security issues found.

• Private keys are either from env vars or generated ephemerally via viem — none hardcoded.
• File-based IPC is local-only, limited to well-known paths under Application.persistentDataPath and the launcher data dir.
• Auth tokens written to disk are test-only artifacts.
• Process spawning (mf, dotnet, open, pkill) uses controlled arguments — no user-input injection vectors.
• .env.example contains only placeholder values.
• The AltTester WebSocket client connects to localhost:13000 only.

Consumer Impact

Test-only code — no public API surface changes. No downstream consumers affected.

Verdict

REQUEST CHANGES — P1 items #1 (path mismatch) and #3 (fragile code reader) should be addressed. #1 in particular is likely a correctness bug that would cause both flows to fail at runtime. #2 is worth addressing for code hygiene even though it's not exercised on macOS.

---

Reviewed by Jarvis 🤖 · Requested by Gabriel Díaz via Slack

[decentraland-bot]

[P1] The path components "Decentraland", "Explorer" may not match Unity's actual Application.persistentDataPath, which uses companyName/productName from ProjectSettings.asset. PR #8862's description states the macOS path is ~/Library/Application Support/Decentraland/Decentraland Unity Explorer/. If the product name is indeed "Decentraland Unity Explorer" (not just "Explorer"), this path will never find the file Unity writes.

Please verify by logging Application.persistentDataPath at runtime and aligning this constant.

[decentraland-bot]

[P1] Same path concern as the C# side — 'Decentraland/Explorer' must exactly match Unity's Application.persistentDataPath folder name. If the Unity product name is "Decentraland Unity Explorer", this should be 'Decentraland/Decentraland Unity Explorer'.

Also: the 'Decentraland/Explorer' string passed to path.join creates a single segment containing a / on Windows. Use separate arguments: 'Decentraland', 'Explorer'.

[decentraland-bot]

[P1] This DOM scan finds any digit-only leaf element on the page. If there's a page-visit counter, user count, or other numeric element, grouped.find(s => s.length >= 1) will return whichever appears first in DOM order — not necessarily the verification code.

Consider scoping the scan to the verify-sign-in container:

const container = page.locator('[data-testid="verify-sign-in-approve-button"]').locator('xpath=ancestor::div[contains(@class, "verify")]')
const webCode = await container.evaluate(/* ... */)

Or, use a more targeted selector matching the known MUI class pattern for the code digits.

[decentraland-bot]

[P2] The win32 case uses APPDATA (Roaming), but Unity's Application.persistentDataPath on Windows resolves to %USERPROFILE%\AppData\LocalLow\<company>\<product> — a different directory. This will silently fail if anyone runs these tests on Windows.

[decentraland-bot]

[P2 — YAGNI] Every method in this file throws 'not yet implemented'. The README says this is a scaffold for a follow-up session. Consider deferring the entire shared/alttester/ directory to the PR that actually implements the WebSocket transport — it avoids shipping ~400 lines of dead code that reviewers and maintainers need to track.

[decentraland-bot]

Re-review — feat: cross flow wallet auth

Files changed: 22 (+1770 -150) · CI: in progress

All six findings from the prior review have been addressed — nice work. The path mismatch is thoroughly documented with runtime verification, the Windows/Linux dead branches are gone (replaced by a clean macOS-only throw in persistent-data-path.ts), the web code reader is now scoped to the approve button's ancestor, the duplicated sleep/uniqueUsername utilities are extracted, and the AltTester scaffold was dropped. The codebase is cleaner and the orchestration design is solid.

One new P1 and a handful of P2s from this pass:

---

P1 — Major (should fix before merge)

1. [Documentation] CLAUDE.md directory tree references a non-existent file
The tree listing shows:

└── client-to-web-handoff.spec.ts     # @cross — Flow 1

But the actual file created in this PR is explorer-wallet-login.spec.ts. No file named client-to-web-handoff.spec.ts exists on this branch. CLAUDE.md is the primary developer navigation aid for this repo — a wrong filename will send anyone looking for the Flow 1 spec on a dead-end hunt.

Fix: replace client-to-web-handoff.spec.ts with explorer-wallet-login.spec.ts in the directory tree.

---

P2 — Minor (non-blocking improvements)

2. [Robustness] clearExplorerIdentityCache will throw on subdirectories
fs.unlinkSync only removes files — if Thirdweb/EcosystemWallet ever contains subdirectories, the function throws EISDIR (not caught by the ENOENT guard). Consider fs.rmSync(thirdwebDir, { recursive: true, force: true }) followed by re-creating the empty dir, or just fs.rmSync with force: true since the dir itself isn't needed.

3. [Duplication] relaunchExplorer duplicates launchInstrumentedExplorer's open-command logic
Both independently resolve the app path and construct the same open args (--skip-version-check, --position 100,100, --dclenv org, --alttester). Extract a shared openExplorerApp(appPath) helper so the args stay in sync.

4. [Precision] readWebCode() match threshold is very permissive
.find(s => s.length >= 1) matches any group containing a single digit. The scoping to the approve button's ancestor is a big improvement, but a s.length >= 2 threshold would further reduce the chance of matching a stray "2" or "0" in non-code UI elements.

---

Security Review

No security issues found.

• Private keys are ephemeral (viem generatePrivateKey) or from env vars — none hardcoded.
• File-based IPC is local-only, limited to well-known paths under ~/Library/Application Support/.
• Process spawning uses controlled, non-user-derived arguments — no injection vectors.
• .env.example contains only placeholder values.
• Auth tokens and bridge files are test-only artifacts.
• The clearExplorerIdentityCache function operates on a known fixed path.

Consumer Impact

Test-only code — no public API surface changes. No downstream consumers affected.

Previous Review Findings — All Addressed ✅

#	Finding	Resolution
P1-1	macOS path mismatch (Explorer vs Decentraland Unity Explorer)	Documented runtime verification in CrossPlatformPaths + persistent-data-path.ts
P1-2	Windows %APPDATA% vs LocalLow	Replaced with macOS-only throw in persistent-data-path.ts
P1-3	readWebCode() document-wide scan	Scoped to approve button ancestor tree
P2-4	Platform-path duplication × 4	Extracted to getCrossStackPath in persistent-data-path.ts
P2-5	Duplicate sleep()	Extracted to shared/helpers/async.ts
P2-6	Duplicate uniqueUsername()	Now imports from existing helpers/test-user.ts
P2-7	Unimplemented AltTester scaffold	Removed from PR
P2-8	SceneInspector overlap with DiagnosticTests	Folded into DiagnosticTests.cs

---

Reviewed by Jarvis 🤖 · Requested by Gabriel Díaz via Slack

[decentraland-bot]

[P1] This references client-to-web-handoff.spec.ts which does not exist on this branch. The actual Flow 1 spec file is explorer-wallet-login.spec.ts.

Suggested fix:

    │       └── explorer-wallet-login.spec.ts      # @cross — Flow 1: client launches → browser wallet pairing → in-world + emote

[decentraland-bot]

[P2] fs.unlinkSync only removes files — if Thirdweb/EcosystemWallet ever contains subdirectories, this throws EISDIR which isn't caught by the ENOENT guard. Consider:

fs.rmSync(thirdwebDir, { recursive: true, force: true })

This handles both files and subdirectories, and force: true suppresses ENOENT.

[decentraland-bot]

[P2] This duplicates the app-path resolution + open args from launchInstrumentedExplorer (lines 93-106). If the args ever diverge (e.g., adding a new flag), one callsite will be stale. Consider extracting a shared openExplorerApp(appPath: string) helper that both functions call.

[decentraland-bot]

[P2] .find(s => s.length >= 1) matches any group with a single digit — e.g., a "0 notifications" badge or a step indicator like "2". The scoping to the approve button's ancestor tree reduces this risk significantly, but a s.length >= 2 threshold would be a cheap additional guard:

.find(s => s.length >= 2) ?? null

(Assuming the device-pairing code is always at least 2 digits.)

[decentraland-bot]

Re-review (3rd pass) — feat: cross flow wallet auth

Files changed: 22 (+1770 -150) · CI: ✅ passing

All four findings from the prior review have been addressed — nice clean-up. The codebase is in solid shape: the two-flow architecture is well-orchestrated, the file-based IPC is well-documented with verified-at-runtime annotations, the shared helper extraction (persistent-data-path.ts, openExplorerApp, sleep, uniqueUsername) removes the duplication, clearExplorerIdentityCache now uses rmSync(recursive, force) correctly, and the readWebCode DOM scan is properly scoped with a >= 2 digit floor.

---

P2 — Minor (non-blocking)

1. [Documentation] CLAUDE.md and spec JSDoc claim specs are skipped / blocked, but they aren't
Three documentation surfaces are out of sync with the actual code:

• CLAUDE.md tree annotations say (skipped, see TODO) for both spec files, but neither test.describe uses .skip.
• CLAUDE.md prose says Flow 2 is "Blocked on: (a) the post-signup CTA selector in PostSignupPage.downloadSignedLauncher" and Flow 1 is "Blocked on locating where the client surfaces the code and URL" — but the PR implements both (captureSignedDownloadUrl for Flow 2, VerificationDappAuthScreenView.CodeText + auth-url.txt for Flow 1). Also PostSignupPage.downloadSignedLauncher doesn't exist — the actual method is captureSignedDownloadUrl.
• explorer-wallet-login.spec.ts JSDoc says "Stays test.describe.skip until two prereqs land" but the code isn't skipped. Meanwhile web-to-client-handoff.spec.ts correctly says "Both locators that previously blocked this spec are resolved."

Suggestion: update the CLAUDE.md tree annotations to remove (skipped, see TODO), update the prose paragraphs to say "Blocked on" → "Depends on" (for Flow 1's unity-explorer branch dep) or remove the "Blocked on" entirely (for Flow 2 where blockers are resolved), fix the stale method name reference, and update the explorer-wallet-login.spec.ts JSDoc to match reality.

2. [Style] waitForNoEstablishedConnection lacks JSDoc
Unlike its siblings waitForPort and waitForEstablishedConnection, this function has no documentation comment. A one-liner describing its purpose ("Polls until the ESTABLISHED connection drops on the given port") would be consistent.

---

Previous Review Findings — All Addressed ✅

#	Finding	Resolution
P1-1	CLAUDE.md references client-to-web-handoff.spec.ts (non-existent)	Tree now lists the correct filenames
P2-2	clearExplorerIdentityCache throws EISDIR on subdirs	Uses fs.rmSync({ recursive: true, force: true })
P2-3	relaunchExplorer duplicates open command logic	Shared openExplorerApp(context) helper
P2-4	readWebCode() match threshold >= 1 too permissive	Now requires s.length >= 2

Security Review

No security issues found.

• Private keys are ephemeral (viem generatePrivateKey) or loaded from env vars — none hardcoded.
• File-based IPC uses fixed, well-known paths under ~/Library/Application Support/ — no user input in path construction.
• Process spawning (mf, dotnet, open, pkill, lsof) uses controlled, non-user-derived arguments — no injection vectors.
• .env.example contains only placeholder values (all-zeros private keys, commented-out vars).
• Auth tokens written to disk are test-only artifacts, local to the CI runner.
• The clearExplorerIdentityCache function operates on a known fixed path.

Consumer Impact

Test-only code — no public API surface changes. No downstream consumers affected.

Verdict

APPROVE — no P0 or P1 issues. The architecture is sound, the code is clean, all prior findings are addressed. The P2 documentation items can be cleaned up in a follow-up.

---

Reviewed by Jarvis 🤖 · Requested by Gabriel Díaz via Slack

[decentraland-bot]

[P2] Documentation says (skipped, see TODO) for both spec files, but neither test.describe block actually uses .skip. Also, the prose below (lines 308-310) says both flows are "Blocked on" things that this PR actually implements — the blockers are resolved. Consider removing the (skipped, see TODO) annotations and updating the prose to reflect the current state.

[decentraland-bot]

[P2] This JSDoc says "Stays test.describe.skip until two prereqs land" but the test.describe on line 65 doesn't use .skip. Meanwhile web-to-client-handoff.spec.ts correctly notes "Both locators that previously blocked this spec are resolved." Consider updating this header to match reality.

[decentraland-bot]

[P2] waitForNoEstablishedConnection is the only polling function in this file without a JSDoc comment. Its siblings waitForPort and waitForEstablishedConnection both have documentation — a one-liner here would be consistent.