## ARENA BATTLE — ACCESS AND WALLET SECURITY / v15 R26

## Identity and one player session
The operator derives `externalId` from its authenticated member session. Do not accept a member identity, balance or tenant identity merely because the browser supplies it. `tenantId` + `externalId` maps to one stable Arena Battle player. A new launch for that player at the same site replaces the previous player session. Membership at another site remains separate. This is a server-session rule, not proof of physical device identity: it cannot identify a copied identical session token as another device. [1]

## Server-to-server API
Keep API keys exclusively in the operator backend; give the browser a short-lived launch ticket. Never put API keys, wallet signing secrets or panel passwords in URLs, client assets or error logs. Production must use HTTPS. Allowed origins govern iframe/client access and do not replace server authentication. [2]

Site IP policy defaults to disabled for existing sites; no policy is enabled without supplied addresses. An authorized administrator can save up to 50 IPv4, IPv6 or CIDR entries. Example request body:

```json Site IP policy
{
  "enabled": true,
  "ipAllowlist": [
    "198.51.100.8",
    "2001:db8:1::/64"
  ]
}
```

These are documentation addresses: replace them with the backend's fixed egress addresses. An enabled empty list is rejected. Both the key-level IP rule and the site policy must permit the peer; key scopes and expiry still apply. Changes are audited.

Provider panel: read with `sites.read`; update with `sites.manage` and the authenticated admin session/CSRF header.

```http Provider panel routes
GET /control/api/tenants/:id/api-security
PATCH /control/api/tenants/:id/api-security
```

Operator panel: reads its own policy only and cannot edit it.

```http Operator panel route
GET /operator-api/api-security
```

Revoke a player’s sessions from the operator backend with a server key that has launch scope.

```http Server API route
POST /provider/v1/player/:externalId/sessions/revoke
```

```json Session revocation body
{}
```

The socket peer is the default client address. Since R46, explicitly configured `TRUSTED_PROXY_IPS` may supply one valid `X-Real-IP` value, verified per request. Forwarding headers from unlisted peers are ignored; `X-Forwarded-For` / Forwarded chains are not parsed. Trusted Nginx must overwrite `X-Real-IP` from its own connection peer. Keep the backend port private. Both key-level and tenant-level IP restrictions use that verified address. Allowing the same proxy IP for every operator does not distinguish their source addresses. See deployment/nginx.conf.example and deployment/INSTALL-TR.txt, then verify the actual network deployment. IP policy never replaces API keys or signed callbacks. [3]

## One wallet and retries
The operator ledger owns spendable money in seamless mode. All operator products must update that ledger atomically. Reservations, refunds and settlements use durable operation identities. On timeout retry the same content and identity; do not create a second operation ID. An unacknowledged payment remains pending until reconciled. Balance revisions prevent old replies from overwriting newer balances. Transaction authorization and money validation belong on the server. [4,5]

Both directions verify HMAC-SHA256 over the exact UTF-8 body and timestamp. Never expose the callback secret to the browser. Implement signed success/error replies, durable receipts, current balances on retries, integer minor units and bounds as specified in SEAMLESS-WALLET.en.txt. An IP rule is not a wallet signature.

## Panel two-factor authentication
Provider and operator panel accounts can enroll a TOTP authenticator. Enrollment takes effect only after code verification; an enrolled account does not receive a session from password verification alone. Six-digit codes use 30-second steps, and an accepted code cannot be reused. Store recovery codes securely offline; each code is single-use. [6]

TOTP is not a phishing-resistant WebAuthn/passkey mechanism. Use a separate strong password, verify the login domain and keep the enrollment secret/QR private. [7] Administrators and operators must enroll and verify their own authenticator; existing accounts are not silently enrolled.

## Operations
Use HTTPS, clock synchronization, network access restrictions and resource limits at the production edge. Give API keys the minimum scopes, a suitable expiry and required source-IP limits. For key rotation, deploy the replacement key to the operator backend, verify connectivity, then revoke the old key. Coordinate wallet-secret changes at both endpoints; reconcile uncertain operations before retiring records.

Encrypt backups of databases, transaction records and encryption-key files in the data directory. In particular, losing `panel-mfa-master.key` makes existing TOTP secrets unreadable; generating a new file does not recover the original secrets. Exercise restores in an isolated environment. Before using an older backup in production, reconcile pending and completed operations with the operator ledger so restored receipts cannot create repeat money movements. Monitor audit logs and pending-payment age.

## References
- [1] OWASP Session Management: https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
- [2] OWASP REST Security: https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html
- [3] 155.io integration security: https://docs.155.io/security
- [4] OWASP Transaction Authorization: https://cheatsheetseries.owasp.org/cheatsheets/Transaction_Authorization_Cheat_Sheet.html
- [5] Stripe idempotent requests: https://docs.stripe.com/api/idempotent_requests
- [6] RFC 6238 TOTP: https://datatracker.ietf.org/doc/html/rfc6238
- [7] OWASP Multifactor Authentication: https://cheatsheetseries.owasp.org/cheatsheets/Multifactor_Authentication_Cheat_Sheet.html

These references support design principles; they do not certify or independently audit this product. Local accounting/access regressions do not replace acceptance tests of the operator's production wallet and network deployment.
