Mobile Payload Encryption Proposal

Why this document

This is a short team-review proposal for adding the existing custom payload-encryption protocol to the native mobile app. It also summarizes the frontend design to review and answers whether two browsers could share a session cookie.

The backend encryption/device implementation is present in this local checkout. This proposal focuses on adapting the mobile client; it does not describe backend prerequisites already completed here.

Frontend flow for review

The current staff/connector worktrees encrypt browser JSON requests to Next.js. Next.js checks the login session and device proof, then creates a separate encrypted request to Django. The browser cookie contains only an opaque session ID; Redis holds the server-side tokens/device record and shared replay data.

Team review: thumbs up/down on this BFF + opaque-cookie + Redis design.

Suggested mobile flow

The mobile app can call Django directly; it does not need a Next.js BFF or a web session cookie.

[Diagram]

Mobile steps

  1. Keep the existing login sequence: POST /api/token/login-pravesh/, then POST /api/token/verify-otp/. Use the returned id_token as the bearer token for protected APIs. The repository docs describe login as redirecting to an OTP path; match the actual deployed response contract.
  2. Before encrypted calls, fetch Django’s public key from GET /api/payload-encryption/public-key/.
  3. After OTP succeeds, register this app installation with POST /api/devices/register/. Send the bearer token and mobile client headers: X-Client-Platform: flutter and X-Device-ID: <installation-id>.
  4. Django returns a server-issued credential device ID and a random device secret. The server-issued ID is distinct from the app’s X-Device-ID.
  5. Store the device secret and tokens in iOS Keychain / Android Keystore-backed secure storage. SQLite is optional for non-secret app state or offline data; it is not required for encryption. Do not store the raw device secret in ordinary SQLite or preferences.
  6. For each protected JSON API call, generate a fresh AES key and IV, encrypt the JSON body, wrap the AES key with Django’s RSA public key, and add the HMAC device proof. Send the existing X-Encrypted, X-Enc-Key, and X-Enc-Meta headers with the bearer token.
  7. Django checks the proof and replay nonce, then continues normal token/permission checks and invokes the existing API view. The device proof does not replace authorization.
  8. On logout or device removal, call DELETE /api/devices/register/ and clear local tokens and device material.

The existing mobile APIs under /api/lead-collection/ continue to use their normal authentication and can_access_pravesh permission checks. Encryption wraps the JSON transport; it does not change the business API contract.

Additional mobile work

Team review: thumbs up/down on direct mobile-to-Django calls, secure local storage, and whether OTP-bound device enrollment is required.

Opaque-cookie question

Two browsers logging in separately normally get different cookies. The session ID is 32 random bytes; Redis prevents overwriting an existing session with the same ID. A random collision is effectively negligible.

The “device key” means the HMAC signing key created from the device secret Django returns after registration. The frontend imports it as a non-extractable Web Crypto key and stores that key with the device ID in IndexedDB. Non-extractable means ordinary JavaScript cannot export the raw key bytes; IndexedDB lets the browser keep using the key after reloads. It does not make the key inaccessible to code running on the same origin: such code can load it and ask Web Crypto to sign.

A copied cookie alone should not be enough to make protected requests, because those requests also need a valid device proof. If someone also obtains usable access to the device key—for example, by compromising the browser/profile or running same-origin malicious code—they can produce proofs and act as that device. Logging out invalidates the shared session for both browsers; clearing the local key alone does not revoke the server-side session.

References

Frontend flow reference

This appendix describes the current staff/connector worktree flow for reviewers. It is separate from the mobile proposal above.

Login and device enrollment

[Diagram]

The browser never gets the upstream tokens in its cookie. The cookie carries a random session ID; the BFF uses it to retrieve the session from Redis. Django stores the registered device credential separately. The device secret is returned to the browser once so it can sign later requests.

A protected JSON request

[Diagram]

Each hop has its own AES key and encrypted response. The device proof binds the request details and encrypted body so changes are detected; the URL query itself remains visible in plaintext. The access token still controls authorization. Redis supports the web session and shared browser-hop nonce checks; Django uses its configured cache for backend nonce checks.

This is context for approving the current frontend design; the suggested mobile client would call Django directly and would not use the browser cookie or frontend Redis session.