[FEAT] Double-Ratchet End-to-End Encrypted P2P Media & Chat Storage Engine

[jotel-dev]

telegram link : t.me/nullifiersystem

---

1. Summary & Core Promise

Velo's trade chat in apps/api/src/routes/chat.ts uses server-accessible message keys. This feature implements a Double-Ratchet End-to-End Encrypted (E2EE) Messaging & Media Subsystem. Users execute an Extended Triple Diffie-Hellman (X3DH) key agreement, encrypt messages and 64 KB cash receipt image chunks on-device with AES-256-GCM, and store encrypted blobs in S3/PostgreSQL with Perfect Forward Secrecy.

---

2. Background & Architectural Risks

• Server Eavesdropping: Plaintext server message access risks trade photo and receipt leakage.
• Key Compromise: Compromising a current message key must not expose historical chat logs.

---

3. Database Layer Specifications

Migration SQL (025_add_double_ratchet_e2ee.sql)

CREATE TABLE e2ee_identity_keys (
    user_id VARCHAR(64) PRIMARY KEY,
    identity_pubkey VARCHAR(64) NOT NULL,
    signed_prekey VARCHAR(64) NOT NULL
);

CREATE TABLE e2ee_ciphertext_messages (
    message_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    trade_id VARCHAR(64) NOT NULL,
    sender_id VARCHAR(64) NOT NULL,
    ciphertext TEXT NOT NULL,
    nonce VARCHAR(32) NOT NULL
);

---

4. Backend Route & Service Layer Specifications

Route: POST /api/v1/e2ee/keys/upload

1. Stores X3DH pre-key bundles in database.
2. Serves pre-key bundles to initiating chat participants.

---

5. Background Processors / Workers

(Client-side WASM chunk encryption + API Ciphertext Relay)

---

6. Frontend / UI Component Specifications

Component: mobile/frontend/src/components/EncryptedChatDrawer.tsx

• React E2EE chat UI supporting X3DH key establishment, encrypted image chunk previews, and security fingerprint verification modals.

---

7. Rigor & Test Plan

1. Ratchet Cryptographic Test (double-ratchet.test.ts): Verifies Perfect Forward Secrecy across 100 ratchet steps.
2. E2E Encrypted Media Test (e2ee_chat_media_e2e.test.ts).

---

8. Relevant Files Inventory (20 Files)

• apps/api/src/lib/crypto/x3dh.ts
• apps/api/src/lib/crypto/double-ratchet.ts
• apps/api/src/lib/crypto/prekey-vault.ts
• apps/api/src/db/migrations/025_add_double_ratchet_e2ee.sql
• apps/api/src/routes/e2ee-keys.ts
• apps/api/src/routes/chat.ts
• apps/api/src/lib/chat-store.ts
• apps/api/src/lib/chat-infrastructure-streams.ts
• apps/api/src/app.ts
• mobile/frontend/src/lib/crypto/ratchet-engine.ts
• mobile/frontend/src/lib/crypto/media-encryptor.ts
• mobile/frontend/src/hooks/useE2eeChat.ts
• mobile/frontend/src/components/EncryptedChatDrawer.tsx
• mobile/frontend/src/components/SecurityFingerprintModal.tsx
• mobile/frontend/src/components/EncryptedMediaViewer.tsx
• packages/shared/src/types/e2ee.ts
• packages/shared/src/index.ts
• apps/api/src/routes/__tests__/e2ee-keys.test.ts
• mobile/frontend/src/lib/crypto/__tests__/double-ratchet.test.ts
• tests/e2e/e2ee_chat_media_e2e.test.ts

---

9. Acceptance Criteria

• Chat messages and images encrypted on-device before transmission.
• Server operates strictly as an untrusted ciphertext relay.

---

10. Contributor Notes

• ⚠️ PFS Rule: NEVER store ratchet private keys on backend server storage.

[Peculiarr7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. I’ll prioritize this immediately and ensure a reliable solution is delivered as soon as possible. Thank you!

[BountySpaghetti]

Hi, I’m a full-stack Web2 & Web3 developer with open-source contribution experience, and I’d be glad to work on this issue.

[Hollujay]

I would like to work on this issue because I will get it done.

[extolkom]

Hi I am an experienced Full-Stack software engineer and I have read the specifications for this issue carefully I promise a very detailed and well implemented work making sure to solve your issue flawlessly

[grantfox-oss]

🦊 GrantFox — @extolkom has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #407)
2. Your PR will be reviewed by the Nullifier-Systems maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@extolkom's PR #430 was approved and merged by @jotel-dev.

🏆 @extolkom: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,588 total points). Track your full progress on GrantFox.

👏 Great work, @extolkom! Keep contributing to Nullifier-Systems.