feat(auth): per-request backend JWT + E2E round-trip (#2770)

[piyalbasu]

TL;DR

Builds the client side of Freighter's stateless backend auth: a function that mints a fresh, short-lived signed token for each request to freighter-backend-v2, signed with the anonymous auth key derived in #2769 — so the backend can verify who's calling without the wallet ever doing a signing prompt or revealing its Stellar address. Includes a tiny request wrapper that retries once if a token is rejected, and a gated Playwright integration test that proves the whole round-trip works against a live backend.

This is the piece that lets you test the auth middleware end-to-end (#2770). It's still scoped narrowly: it does not yet wire auth into the real BE v2 requests — that's a later ticket. Nothing user-facing changes yet.

Stacked on #2769 (PR #2876) — review/merge that first; this PR's base is feat/2769-derive-auth-keypair, so the diff here is only the #2770 work.

Design doc lives in wallet-eng-monorepo (design-docs/contact-lists/Freighter Per-Request Backend JWT Design Doc.md).

Draft: opening for early review of the JWT contract and the E2E approach.

Implementation details (for agents/reviewers)

What changed (all new, under @shared/api/helpers/ + a gated integration test):

• buildAuthJwt.ts — mints a compact EdDSA JWS per request. Header {alg:"EdDSA",typ:"JWT"}; claims sub (lowercase-hex auth pubkey = userId), iss ("freighter-extension"), iat, exp (iat+15s), bodyHash (hex SHA-256 of raw body via crypto.subtle; empty-bytes hash for no body), methodAndPath ("<METHOD> <path>", method upper-cased, path includes query — bound to the server's r.URL.RequestURI()). Signs b64url(header).b64url(payload) with Keypair.sign(); url-safe base64, no padding. now is injectable for deterministic tests.
• authedFetch.ts — attaches Authorization: Bearer <jwt>, builds a fresh JWT per call, and on 401 rebuilds a fresh JWT and retries exactly once. Defaults Content-Type: application/json for non-GET. Normalizes the method to upper-case on the wire so it always matches the upper-cased method baked into the JWT's methodAndPath claim (fetch only auto-uppercases the standard verbs, not PATCH/custom — the mismatch would be a silent 401). baseUrl trailing slash normalized so the fetched URL can't diverge from the signed methodAndPath. (No custom-header passthrough yet — the auth middleware only reads Authorization and the backend enforces no request Content-Type, so it's unneeded until a real endpoint requires it.)
• extension/e2e-tests/integration-tests/authJwt.test.ts — a gated Playwright integration test (request/APIRequestContext fixture, pure HTTP — no browser/extension launch). Derives a keypair from the [Extension] Derive auth keypair from seed for backend authentication #2769 vector mnemonic (known userId) and hits GET /api/v1/auth/whoami, asserting: valid→200+matching userId; tampered bodyHash→401; flipped-signature→401; expired→401. Gated behind IS_INTEGRATION_MODE=true via test.skip, so it never runs in the normal stubbed e2e/CI pass.
• @shared/api/helpers/__tests__/buildAuthJwt.test.ts (7), authedFetch.test.ts (6) — unit tests.

Why a gated Playwright test (not a jest integration test): it lives beside the other integration-tests/, reuses the request fixture for a real HTTP round-trip against a locally-run or staging backend, and stays skipped unless IS_INTEGRATION_MODE=true so CI never depends on a live backend. whoami is GET-only, so the four cases are mapped onto it: tampered body = a JWT carrying a non-empty bodyHash while the GET body is empty; wrong key = a flipped signature byte; expired = a backdated now.

How to run the E2E round-trip:

# point at a live backend (defaults to staging if BACKEND_V2_URL is unset):
#   freighter-backend-v2: make run   # serves :3002, then set BACKEND_V2_URL=http://localhost:3002
IS_INTEGRATION_MODE=true yarn workspace extension test:e2e authJwt

Env: BACKEND_V2_URL (default https://freighter-backend-v2-stg.stellar.org), AUTH_E2E_MNEMONIC (default: the #2769 vector mnemonic, known userId).

The staging deploy must run an image that includes the whoami/auth route; an older image returns 404 and the valid case fails.

Verification: yarn jest @shared/api → 10 suites / 84 tests pass under jest-fixed-jsdom (real WebCrypto). The integration test is test.skip-gated, so without IS_INTEGRATION_MODE it reports as skipped rather than failing. Reviewed per-task + a whole-branch review.

Notes:

• One prior review suggestion (assert the two retry JWTs differ) was rejected: iat is whole-seconds and Ed25519 is deterministic, so within-second retries are byte-identical — that assertion would be flaky and the property is behaviorally moot. The "fresh per request" guarantee is structural (buildAuthJwt is rebuilt inside the retry).
• The two translation.json keys in the diff are the husky i18next-scanner hook backfilling a pre-existing master gap — unrelated to this feature.

Follow-ups (out of scope): wire authedFetch into the real background contacts path; optionally run the gated integration test in CI against staging once stable; freighter-mobile builds the equivalent against the same contract.

[github-actions]

PR Preview build is ready: https://github.com/stellar/freighter/releases/tag/untagged-f40a2047c614474fe4b0 (SDF collaborators only — install instructions in the release description)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9594e947b3

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[JakeUrban]

I think codex found a bug, and I'm skeptical of the need for the retry logic in authedFetch, but other than that this LGTM.

[JakeUrban]

Is the example provided in the comment correct? The "trailing slash" description makes it sound like what we're normalizing is /api/ vs /api.

[piyalbasu]

Good point — the original wording was muddled. Clarified in ac942ce/fae6da34. The trailing-slash strip only prevents a // when baseUrl ends in / and path starts with /; it isn't what guarantees the signed path. The actual correctness now comes from deriving the signed methodAndPath from new URL(url).pathname + search, so the signed claim and the wire request can't diverge regardless of slashes or where the /api/v1 prefix sits.

[JakeUrban]

What are we guarding against with this retry? My understanding is that 401 is returned either because the token is invalid or the user is truly unauthorized. If the first token is invalid, why would the second not be?

[piyalbasu]

It guards the clock-skew / in-flight-expiry case from the design doc's Failure Modes table ("Client clock skew → JWT expires before reaching server → Client retries with fresh JWT on 401 → Transient; retry succeeds"). The JWT has a 15s lifetime, so a token that's valid when signed can age out between signing and the server validating it (latency, or client clock drift beyond the server's ±5s leeway). Regenerating produces a fresh iat/exp that recovers that transient case.

You're right that a token invalid for a structural reason (wrong key, bad bodyHash/methodAndPath) will 401 again on retry — that's expected, and we just surface the error after the single retry. The retry isn't meant to fix those.

The reason we retry automatically rather than rely on the caller: many of these requests will be non-interactive — e.g. the background polling of /account-balances — so there's no user in the loop to manually re-trigger after a transient clock-skew 401. The auto-retry handles it transparently. Clock skew should be rare, so the cost is an occasional extra request, capped at one.

[piyalbasu]

That being said - we could also add this as a per-endpoint configuration if we'd rather limit how often we do this