@minicode-dev/chat 0.1.11 → 0.1.12

package/README.md

@@ -337,3 +337,96 @@ Use WASD/arrows, mouse and click/space on desktop, or the joystick, arena touch
 button on mobile. Minimize preserves the match; reload/reopening the chat is not a persisted
 match recovery flow. Wi-Fi versus cellular connectivity and runtime TURN still require real-device
 validation.
+
+### Manual TURN recovery inside TANQUES LIVE
+
+Both players need a version with manual TURN support. No Django endpoint, consumer,
+WebSocket protocol change, Cloudflare SDK, or application-level screen is required.
+The existing `webrtc.iceServers` and `iceTransportPolicy` provider settings continue
+working. Manual settings belong only to the current match and are not persisted.
+
+1. Invite the other player and accept the match normally. Local/direct connections
+   keep working without TURN.
+2. During negotiation (or even during a connected match), choose **Configurar
+   conexión alternativa**. A slow or failed negotiation also shows a connection notice.
+3. **One player** pastes the JSON containing temporary `iceServers` and selects
+   **Aplicar y reconectar**. The other player receives and applies it automatically;
+   they do not need to paste anything.
+4. Wait for the sharing confirmation, then inspect the actual connection state.
+   Applied credentials do not by themselves prove that TURN is reachable or in use.
+
+The modal accepts `{ "iceServers": [...] }` and a full Cloudflare envelope such as
+`{ "success": true, "result": { "iceServers": [...] } }`. It rejects invalid JSON,
+STUN-only configurations, invalid ICE URLs, missing TURN passwords, known expired
+credentials, and API-token fields. Limits: 6,000 characters/UTF-8 bytes, eight ICE
+servers and sixteen URLs. Only `stun:`, `stuns:`, `turn:` and `turns:` URLs are allowed.
+
+**Never paste the permanent Cloudflare TURN API token.** Generate temporary
+credentials externally in your terminal. For example, with your credentials already
+set in your terminal environment (not in React), this copies only the temporary
+response to the macOS clipboard:
+
+```sh
+curl --fail --silent --show-error \
+  "https://rtc.live.cloudflare.com/v1/turn/keys/${CLOUDFLARE_TURN_KEY_ID}/credentials/generate-ice-servers" \
+  --header "Authorization: Bearer ${CLOUDFLARE_TURN_KEY_API_TOKEN}" \
+  --header "Content-Type: application/json" \
+  --data '{"ttl":3600}' | pbcopy
+```
+
+The library never calls that API. The optional **Validez restante en segundos** field
+means remaining validity from now, not the original issuance TTL. Leave it blank
+when unknown; Cloudflare's opaque username is not treated as an expiry timestamp.
+You can also supply `expiresAt` (ISO text or Unix milliseconds) or `expiresIn`/`ttl`
+(remaining seconds) in the JSON. Known-expired settings are refused; expiry unknown
+cannot be detected reliably from every ICE authentication failure, so obtain and
+paste new credentials if the old ones stop working.
+
+Recovery uses the private chat signaling already used for SDP/ICE. A tab-bound,
+ephemeral ECDH/AES-GCM exchange encrypts the credentials before they enter the chat
+transport. The host coordinates preparation, confirmation and recovery so either
+player can initiate without racing two restart offers. A healthy direct connection
+with policy `all` is kept; new fallback settings do not trigger an unnecessary
+restart. Otherwise the link updates `setConfiguration()` and restarts ICE, or
+recreates only PeerConnections when necessary. Positions, health and match state
+remain in the existing simulation. Drafts clear on closing/applying the dialog;
+credentials and encryption keys clear when the match ends or is destroyed.
+
+The library excludes these internal frames from its visible client history and
+unread counts; any server that stores all chat frames may still retain encrypted
+signaling. No plaintext TURN password is sent in those frames. This relies on the
+existing authenticated private-room relay; it is not protection against an actively
+malicious signaling server. HTTPS (or localhost) and Web Crypto are required. Without
+Web Crypto, sharing fails safely instead of sending plaintext. Closing the dialog
+does not end the match; an already-started synchronization can still finish.
+
+**Diagnostics and real-network validation:**
+
+- Open **Diagnóstico de conexión** to see SDP/ICE/gathering states, DataChannel
+  readiness, reconnects, connection time, RTT and sanitized ICE errors/counters.
+- `turnConfigured` only means a TURN URL is configured. `candidates.localRelay`
+  means relay candidates were gathered. `selectedPair.relay: true` means the actual
+  selected candidate pair uses TURN. No passwords, usernames, SDP or private candidate
+  addresses are included in the panel.
+- To verify TURN, temporarily enable **Forzar relay para diagnóstico**. It is shared
+  with the settings so both peers use `iceTransportPolicy: "relay"`. Confirm both
+  DataChannels are open, `phase` is `connected`, the selected pair is relay, and
+  movement counters increase on both devices. Disable the option for normal play.
+- Test from two devices on different networks (for example Wi-Fi and cellular),
+  with current temporary credentials. Also test interruption/retry and renewing
+  credentials from either player. No implementation can guarantee connectivity
+  through every restrictive firewall; TURN/TLS over TCP may add latency/jitter.
+- The local two-player demo remains `/tanks-live-lab.html?user=ana` and
+  `/tanks-live-lab.html?user=luis`. Automated tests use fake RTC/TURN to verify
+  synchronization, retries, privacy and state preservation; they do not prove that
+  a real TURN service is reachable across networks.
+
+For repeatable browser QA, `scripts/check-manual-turn-browser.mjs` uses Playwright
+as an optional development tool (not a library dependency). Run the demo, make a
+Playwright installation available, then run the script. `CHAT_DEMO_URL` overrides
+the default `http://127.0.0.1:5173`; `PLAYWRIGHT_MODULE` and
+`PLAYWRIGHT_EXECUTABLE_PATH` can select an existing tooling installation. It checks
+two real local browser peers, host/guest manual sharing with dummy credentials,
+invalid inputs, light/dark/mobile dialogs, cancellation and simulated blocked ICE.
+Its headless-only flags allow local candidates without mDNS resolution. The script
+never tests real TURN credentials or proves Wi-Fi/cellular connectivity.