feat(flutter): wallet connection with Freighter and a mock wallet

[Pericena]

Refs #25 — stacked on #112 (base feat/27-deploy-flow). Review after #111 and #112.

What

• WalletPort is the only signing boundary: connect, disconnect, address, network, signTransaction (returns the signed XDR; the server submits, contract docs: add API contract between Flutter app and Serverpod #77 Decision A) and signAuthEntry.
• FreighterWallet over a small JS bridge (@stellar/freighter-api 6.0.1), from the feat(spike): prove Flutter Web Freighter signing and Testnet SAC payments #70 spike. Before any prompt it applies the chore(frontend): enforce pre-prompt checks in the #68 wallet spike adapter #69 checks: Testnet passphrase, no fee-bump envelopes, no trailing bytes, transactions only for the connected account, auth entries with non-zero expiration. After signing it verifies the transaction is unchanged and signed by the connected account.
• WalletController exposes one explicit WalletStatus: disconnected, connecting, connected, signing, signed, rejected, wrongNetwork, error. It blocks signing before any prompt when the wallet is not on Testnet (any adapter); a network/account switch forgets the session.
• MockWallet for tests and the demo console (--dart-define=WALLET=mock); Freighter is the default on the web.
• Wallet sheet (S09): connect, waiting, connected (Testnet badge, copyable address, disconnect), signing, signed, signature rejected, wrong network, not installed (install link), locked, account changed — each with a retry.
• Demo flows (deploy, hire) sign a harmless, never-submitted Testnet envelope so Freighter shows its prompt; they stay labelled as demos.
• README: architecture, how to test with Freighter, build and test commands.

Security

The app only handles the public address, network, unsigned XDR and signed XDR. No secret keys are stored or logged. Mainnet is not supported.

Tests

• 160 passing: Freighter adapter checks, connection and signing states (signing, signed, rejected, wrong network, error, disconnect).
• flutter analyze: no issues.

Pending (why Refs, not Closes)

• Screenshot/GIF with real Freighter on Testnet.
• The backend receiving the signed XDR depends on the relay/endpoint (feat(server): escrow relay prepare and submit endpoints for hires #96 / feat: register agent flow (wallet and on-chain identity) #18).

[cloudflare-workers-and-pages]

Deploying puls3 with    Cloudflare Pages

Latest commit:	f58652e
Status:	✅  Deploy successful!
Preview URL:	https://17777abf.puls3-4lw.pages.dev
Branch Preview URL:	https://feat-25-wallet-connection.puls3-4lw.pages.dev

View logs

[TOMOKI977]

Really solid security work here. I checked every claim in the PR body against the code, and each check is actually enforced:

• Testnet only, at connect() and again before each prompt.
• Fee-bump envelopes refused.
• Canonical re-encode, so trailing bytes are rejected.
• Transaction and operation sources bound to the connected account.
• Auth entries with zero expiration refused.
• After signing, the body is compared unchanged and the signature is verified against the connected key with Dart's hard-coded Testnet hash.

The demo envelope is a single manage_data that can't move value. Nothing sensitive is logged. The WalletPort seam, the sealed exceptions and the single WalletStatus make it easy to follow.

I'm requesting changes for one issue, the same one I raised on #112. It is now reachable with a real wallet:

Starting a deploy with no connected wallet can trap the user. The preparing step awaits _wallet.connect() without a timeout (deploy_flow_controller.dart:189). With Freighter that call is an untimed requestAccess() (freighter_bridge.js:32, freighter_bridge_web.dart:105). While preparing, the sheet hides Close and blocks back (deploy_flow.dart:109-114), and it can't be dismissed (deploy_sheet.dart:20-21). If Freighter never settles the promise (popup ignored, blocked, or stuck on the lock screen), the only way out is reloading the page. An already-connected wallet avoids it (wallet_controller.dart:74-75), but Studio doesn't require connecting first. A timeout on wallet calls in the bridge or controller fixes it for both flows, as would letting the user close while the wallet step is pending. Please add a test with a connect() that never completes.

Also please fix two tests that can't fail as written. freighter_wallet_test.dart:130-131 and :184-188 check wallet.address / bridge.signCalls before the future settles. Use await expectLater(...) first, as you already do at 134-142.

Not blocking, worth a follow-up:

• Unknown errors read as "you rejected". _translate maps anything without a known code to WalletSignatureRejected (freighter_bridge_web.dart:123-124). A JS TypeError or an extension crash tells the user "You rejected the transaction" with nothing logged. A generic WalletUnavailable (or an error state) plus a log would be more honest.
• The bridge loads @stellar/freighter-api from esm.sh at runtime (freighter_bridge.js:6), with no integrity pin and no CSP, and index.html blocks app startup on that import. A slow CDN delays the app for everyone, and a CDN that is down shows "Freighter not found" even when it is installed. Your comment already notes that production should bundle it. Let's track that as an issue before the public demo.
• main.dart:19-26 falls back to MockWallet for any WALLET value other than exactly freighter. An assert or a log would catch a typo.
• WalletController has no in-flight guard on connect/_sign/disconnect. For example, disconnecting during a pending connect ends up connected again (freighter_wallet.dart:43).
• Untested branches: the signAuthEntry session checks and its post-sign checks (signer mismatch, signature length, bad base64), ADDRESS_V2 credentials, a fee-bump or unsigned envelope returned by the wallet, and the WalletAccountChanged path through the controller.
• Smaller notes: wallet_sheet.dart:28 uses a raw 600 instead of Puls3Breakpoints.narrowGutter. _Connecting and _Signing duplicate the progress bar block. The README port list is missing signAuthEntry.

[TOMOKI977]

Opened #116 to track bundling @stellar/freighter-api locally and adding a CSP before the app is public (#31). It doesn't need to block this PR.

[TOMOKI977]

@Pericena Heads-up: CI changes when #114 (Serverpod 4.0.4) merges. Once it lands on main:

1. Upgrade locally to Flutter 3.44.4 (Dart 3.12.2) and serverpod_cli 4.0.4. The steps are in docs/operations/serverpod-4-migration.md.
2. Update your branch from main and run dart pub get again. The lockfile moves to Serverpod 4.0.4, and checks run with the new toolchain.
3. Generated code and migrations: if you touch a *.spy.yaml or an endpoint, run serverpod generate with 4.0.4 and commit the output, since CI fails on any generated diff. Create new migrations with 4.0.4 too, so they sort after upgrade-4-0.
4. Two new required CI jobs:
   • docker builds the server image.
   • scripts runs the offline tests in scripts/tests/, including the env inventory: every PULS3_* variable read in code must be listed in .env.example. Secrets stay commented out there, with an entry in docs/infra/secrets.md.
5. Cloudflare Pages builds with scripts/cloudflare-pages-build.sh, which pins the same Flutter version as CI.

Specific to this PR: after rebasing #112, rebase this one onto it (or onto main once #112 merges). It currently has conflicts with main. The new stellar_flutter_sdk dependency will resolve against the Serverpod 4 lockfile, so run flutter pub get and commit the lockfile change.