echo6-docs/hookshot_e2ee_discovery.md

Hookshot E2EE Discovery

Generated: 2026-04-09 (Phase 6.0, Question 3)

!! BLOCKER: Hookshot E2EE + MAS is BROKEN !!

The Problem

Hookshot v7.3.2 CANNOT establish E2EE crypto sessions when Synapse uses MAS (Matrix Authentication Service). This is confirmed in two open GitHub issues:

• Issue #1084: "MAS + hookshot can't login for encryption" https://github.com/matrix-org/matrix-hookshot/issues/1084
• Issue #980: "Encryption + MAS unable to start" https://github.com/matrix-org/matrix-hookshot/issues/980

Both issues remain OPEN as of March 2026.

Root Cause

When encryption is enabled, hookshot needs to establish a device and crypto session. It does this via a login call that MAS intercepts and rejects with M_UNRECOGNIZED: Invalid login type. The mautrix bridges solved this via MSC4190 (encryption.msc4190: true), but hookshot's bot-sdk does NOT implement MSC4190 for device management — only for user registration (fixed in v7.2.0).

Compatibility Matrix

Scenario	Status	Source
Hookshot + MAS, no encryption	WORKS (since v7.2.0)	PR #1092
Hookshot + MAS, with encryption	BROKEN	Issue #1084, #980
Hookshot + no MAS, with encryption	WORKS	Docs confirm
Hookshot + no MAS, no encryption	WORKS	Trivial case

Echo6 Impact

Echo6 Synapse uses MAS (matrix_authentication_service.enabled: true). All mautrix-signal portal rooms use E2BE encryption (encryption.require: true).

This means:

1. Hookshot CANNOT decrypt events in bridged Signal rooms
2. Outbound webhooks from encrypted rooms would contain CIPHERTEXT, not plaintext
3. The entire archive would be "Unable to decrypt" — USELESS

Encryption Library (for reference)

Hookshot uses:

• @vector-im/matrix-bot-sdk → @matrix-org/matrix-sdk-crypto-nodejs → vodozemac (Rust)
• NOT libolm (deprecated)
• Crypto store: SQLite format
• Redis: REQUIRED when encryption is enabled

Config Keys (for reference, cannot be used with MAS)

# hookshot config.yml
encryption:
  storagePath: ./cryptostore   # persistent volume required

# Redis required for encryption
cache:
  redisUri: redis://localhost:6379

# registration.yml additions for encryption
de.sorunome.msc2409.push_ephemeral: true
push_ephemeral: true
org.matrix.msc3202: true

Device Verification

IF encryption worked (which it doesn't with MAS), hookshot would:

• Auto-generate a device on first crypto login
• Need manual verification from a trusted device
• Support key sharing via MSC3202 transaction extensions

Workaround Options

1. Wait for upstream fix — Issue #1084 is open but no timeline
2. Disable MAS — Not viable, MAS handles all user auth for echo6.co
3. Disable E2BE on bridge — Would expose Signal messages in plaintext on Synapse wire, defeating the purpose of E2BE. Not recommended.
4. Use a different tool — A custom matrix-nio bot (Python) with native MSC4190 support could work. matrix-nio has vodozemac bindings and can be configured for MAS-compatible device login. This is the Phase 6 original plan's approach.
5. Skip hookshot entirely — Use Synapse-level retention (redaction_retention_period: null
   • MSC2815) for the DB-level archive, and build a lightweight custom worker for real-time export. No hookshot needed.

Recommendation

Hookshot is NOT viable for archiving E2BE-encrypted Signal bridge rooms on a MAS-enabled Synapse. The E2EE + MAS incompatibility is a hard blocker with no workaround short of disabling MAS or E2BE.

The original Phase 6 plan's custom bot approach (matrix-nio + asyncpg) avoids this entirely because matrix-nio supports MSC4190 natively and can be configured for MAS-compatible appservice login.

Alternatively, the Synapse-level approach (retention null + MSC2815) requires NO additional bot for the archival function — the data stays in Synapse's DB and is queryable via admin API. A simple export script can pull events from the Synapse DB directly.