feat(backend): Phase-1 to Signal migration path

[Olorunfemi20]

closes #364

Summary

Defines how existing Phase-1 sealed-box conversations transition to Signal without losing history. Clients update at their own pace, so a conversation contains devices on both sides of the line for as long as the slowest one takes.

This has been reworked onto the devices.capabilities model that landed on main while the PR was open — see "Rebased onto the capability model" below for what was dropped and why.

What this builds on

main already has capability advertisement: devices.capabilities lists the protocols a device can decrypt, and selectProtocol (src/lib/capabilities.ts) picks the strongest one two devices share, falling back to the sealed_box baseline. GET /conversations/:id/devices already returns each device's capabilities and the negotiated protocol.

This PR adds the two things negotiation alone does not provide.

1. A record of what actually encrypted each envelope

message_envelopes.protocol — e2ee_protocol NOT NULL DEFAULT 'sealed_box' (enum mirroring KNOWN_PROTOCOLS). Adding it with that default backfills every existing row in the same statement.

This is the no-history-loss guarantee. Capabilities describe what a device can do now, which says nothing about what encrypted a message last month — so capability alone cannot be used to pick a decryption path for old data. Recording the construction per envelope is what keeps pre-cutover history decryptable forever.

Every read path reports it (GET /sync, message_envelope socket events, conversation history), so a client catching up across the cutover receives a mix of sealed_box and signal envelopes in one page and decrypts each with the matching routine. Nothing is migrated or re-encrypted.

2. Enforcement on the way in

A sender can claim any protocol on an envelope. Both send paths (REST POST /messages and socket send_message) now reject two things:

Status	Reason	Meaning
400	unsupported_by_recipient	The envelope names a protocol the recipient does not advertise. It would be undecryptable on arrival, which the recipient cannot distinguish from tampering.
409	downgrade	Both devices can do better. Without this a patched client could quietly keep a peer on the sealed box forever and nobody would notice.

Both list every offending envelope with declared, expected and reason, so the client re-fetches the device set and rebuilds rather than retrying blind. When a batch contains both kinds, the undecryptable one decides the status code — it is the more specific failure.

MLS group messages carry a single group ciphertext and no per-device envelopes (#372), so the check does not run for them.

Rebased onto the capability model

Dropped from the original version of this PR, because main now covers them:

• devices.supports_signal. A bespoke boolean alongside capabilities.protocols would be two sources of truth for "can this device do Signal" — exactly the divergence the repo already fixed once when user_devices was merged into devices.
• PATCH /devices/:id/capabilities. POST /auth/verify already treats a newer capabilities document as the upgrade path.
• GET /conversations/:id/e2ee-protocol. GET /conversations/:id/devices already answers this per device.

Changed:

• Negotiation is now per device pair, not per conversation. My original version held the whole conversation on sealed box until every device was ready. Since each recipient device already gets its own envelope, that was strictly worse: an upgraded pair can use Signal immediately instead of waiting for the slowest device in the group, which in a large group may be never. main's pairwise selectProtocol is the better primitive and this now enforces exactly what it returns.

Net effect: the PR is smaller and composes with what shipped, instead of competing with it.

Migration

Renumbered to drizzle/0004_envelope_protocol.sql (0001–0003 are taken on main). Existing _journal.json entries are left byte-identical — only a new entry is appended.

Separate problem, flagged not fixed: drizzle/meta/_journal.json on main has one entry packing three when/tag pairs as duplicate keys, so 0001_mls_group_state and 0001_mls_key_packages are silently dropped when it is parsed, and nine of the twelve migration files are unjournaled entirely. Repairing that means asserting an apply order for other people's migrations, which is a maintainer call and does not belong in this PR.

Merge repairs

Several files this branch touches do not compile on main after earlier merges — duplicated blocks and lost declarations from conflict resolutions. They are fixed here because the branch cannot build otherwise:

• schemas/message.schemas.ts — SendMessageSchema declared twice
• routes/messages.ts — the request body destructured twice
• socket/messaging.ts — sibling-coverage check duplicated with an unbalanced brace; send_file_message lost its payload destructuring
• db/schema.ts — mlsKeyPackages and deviceKeyHistory spliced into one another
• services/deliveryPipeline.ts — welcomeTransport referenced without being declared

Each repair preserves both merged features; nothing from main is dropped. The removals in the socket/messaging.ts diff are exactly the duplicated and now-dead code.

main is also broken in routes/users.ts, routes/conversations.ts, routes/files.ts, routes/uploads.ts and routes/devices.ts, which this branch does not touch. Those are left alone deliberately — users.ts in particular has a PATCH /me handler fused with a bogus duplicate route referencing undefined variables, and involves privacy-settings work I was not part of. That needs its own PR; I'm happy to open one.

Refactor

routes/messages.ts now uses the shared insertMessageEnvelopes helper that the socket paths already use, instead of its own copy of the resolve-devices-and-insert logic. The per-envelope protocol default lives in one place, so the two implementations cannot drift apart again — which is what produced the duplication above.

Tests

• e2eeProtocol.test.ts — 13 cases: sealed box accepted for a Phase-1 recipient, Signal accepted when both advertise it, Signal-to-Phase-1 rejected, post-cutover downgrade rejected, a mixed batch where one pair uses Signal and another stays on sealed box (the per-pair property), undecryptable reported ahead of downgrade, and null/absent capability documents treated as baseline at both ends.
• signalMigration.routes.test.ts — 8 cases over POST /messages: protocol defaulting, persistence, both rejection codes with their violations, unknown protocol rejected at the schema layer, membership checked first, and the check skipped for envelope-free MLS messages.

75 tests pass across my four suites. tsc and eslint are clean on every file this branch touches.

Docs

apps/backend/docs/signal-migration.md rewritten for the capability model: what it builds on, the three rules, why negotiation is per-pair, the data model, advertising support via re-verify, both rejection codes, the read contract, a per-pair cutover diagram, and the rollout order — including that dual-path decryption must ship before Signal encryption.

[drips-wave]

@Olorunfemi20 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[codebestia]

Please resolve the conflicts.