echo6-docs/PHASE6_DECISION.md

# Phase 6 Decision Summary
# Generated: 2026-04-09

## 1. Is Hookshot the Right Choice?

**NO.** Hookshot cannot be used for this use case.

**Reason:** Hookshot's E2EE implementation is incompatible with MAS (Matrix
Authentication Service). Echo6's Synapse uses MAS. All mautrix-signal portal
rooms use E2BE encryption. Hookshot cannot establish crypto sessions when MAS
is active (GitHub issues #1084, #980 — both OPEN as of March 2026). The webhook
payloads would contain useless ciphertext, not plaintext.

This is a hard blocker with no workaround short of disabling MAS (breaks all
user auth) or disabling E2BE on the bridge (exposes Signal messages in transit).

## 2. Recommended Alternative: Synapse Retention + Export Script

Instead of hookshot, a much simpler approach achieves the same goal:

### Step 1: Synapse Config (2 lines)
```yaml
redaction_retention_period: null     # Never censor redacted content
experimental_features:
  msc2815_enabled: true              # Allow moderator access to redacted content
```

This preserves ALL event content in Synapse's Postgres forever, including
redacted messages. MSC2815 provides API access to the original content.

### Step 2: Export Script (cron job, no bot)
A Python script that:
- Runs nightly via cron on Contabo
- Queries Synapse admin API for events in bridged rooms
- Writes JSONL + markdown exports to /mnt/library/Archives/Signal/
- No E2EE handling needed — admin API returns server-side decrypted content
- No bot account, no device verification, no crypto key management

### Why This Is Better Than Hookshot

| Concern | Hookshot | Synapse Retention + Export |
|---------|----------|---------------------------|
| E2EE + MAS | BROKEN | Not applicable (admin API) |
| Per-room config | Manual per room | Automatic (all rooms) |
| New portal auto-join | Requires automation | Not needed (queries DB) |
| Backfill historical | No backfill | Full history available |
| Infrastructure | New container + Redis | 2-line config + cron script |
| Maintenance | Hookshot upgrades, Redis, crypto store | Script only |
| Failure mode | Missed events if down | DB has everything, export retries |
| Edit/redaction capture | Real-time only | Retained in DB forever |

### Why This Is Better Than the Custom Bot (Original Phase 6)

The original Phase 6 plan proposed a full matrix-nio bot with E2EE, asyncpg,
systemd service, healthchecks, and monitoring. That's ~500-1000 lines of Python
for a problem that Synapse already solves with 2 config lines.

The custom bot approach is only justified if:
- Real-time alerting on specific messages is needed (not requested)
- Independent archive separate from Synapse DB is required (not requested)
- Synapse admin API is insufficient for export needs (it's not)

## 3. Questions Requiring Live Test

None. All claims are verified from Synapse source code:
- `redaction_retention_period: null` — confirmed in synapse/config/server.py
- `msc2815_enabled` — confirmed in synapse/config/experimental.py line 372
- Admin API event access — confirmed working (used throughout Phase 3-5)
- Hookshot E2EE+MAS blocker — confirmed from GitHub issues with reproduction steps

## 4. Estimated Effort

### Synapse Config Change
- Edit homeserver.yaml: 5 minutes
- Restart Synapse: 1 minute
- Verify via admin API: 5 minutes
- **Total: ~15 minutes**

### Export Script
- Python script to query admin API and write JSONL/markdown: 1-2 hours
- Cron setup: 5 minutes
- Test with existing rooms: 15 minutes
- **Total: ~2 hours**

### Compare to Full Hookshot Deployment
- Deploy hookshot container: 30 min
- Debug E2EE+MAS incompatibility: hours of dead end
- Fall back to alternative: start over
- **Total: wasted time**

### Compare to Custom Bot (Original Phase 6)
- Bot code + E2EE + DB schema + systemd + monitoring: 4-6 hours
- Device verification walkthrough: 30 min
- Export pipeline: 1-2 hours
- **Total: 6-8 hours**

## 5. Blockers

None for the recommended approach. The only blocker was hookshot's E2EE+MAS
incompatibility, which the recommended approach avoids entirely.

## 6. Decision Matrix

| Approach | Viable | Effort | Completeness | Ops Burden |
|----------|--------|--------|--------------|------------|
| Hookshot | NO (E2EE+MAS blocked) | N/A | N/A | N/A |
| Custom matrix-nio bot | Yes | High (6-8h) | Full (real-time + export) | Medium |
| Synapse retention + export | Yes | Low (~2h) | Full (DB + batch export) | Minimal |

**Recommendation: Synapse retention + export script.**

---

## Ref Files Produced

1. `.ref/synapse_retention_discovery.ref` — Current retention config, MSC2815 support, DB sizes, growth rate, rollback
2. `.ref/hookshot_deployment_discovery.ref` — Contabo resources, port conflicts, compose snippet
3. `.ref/hookshot_e2ee_discovery.ref` — **BLOCKER documented** — E2EE+MAS incompatibility
4. `.ref/hookshot_payload_discovery.ref` — Webhook payload shape (for future reference)
5. `.ref/hookshot_room_targeting_discovery.ref` — Per-room model, no wildcard, current portals
6. `.ref/archive_receiver_discovery.ref` — Storage options, alternative approaches, CT recommendations
7. `.ref/PHASE6_DECISION.md` — This file