echo6-docs/PLAN.md

# mautrix-signal Bridge Deployment Plan

## 1. Deployment Target

**Same Contabo host**, same Docker Compose stack at `/opt/matrix/docker-compose.yml`.

Rationale: Synapse runs as Docker on Contabo (ref: `synapse.ref` — "Docker Compose at /opt/matrix/docker-compose.yml"). The bridge container joins the existing `matrix-net` network so it can reach both `matrix-synapse` and `matrix-postgres` by container name without exposing any new ports externally.

## 2. Bridge Version

- **Image:** `dock.mau.dev/mautrix/signal:v0.2603.0`
- **Released:** 2026-03-16 (latest stable as of 2026-04-09)
- **Type:** Go rewrite (NOT the deprecated Python mautrix-signal)

Pin to the exact tag `v0.2603.0`, not `:latest`, so upgrades are intentional.

## 3. Database Plan

Create a new Postgres database and role inside the existing `matrix-postgres` container. The role gets **minimal grants** — `LOGIN` only, no `SUPERUSER`, no `CREATEDB`, no `CREATEROLE`. Ownership of the new database is the sole privilege.

```sql
-- Connect as the synapse superuser to create the role and database
CREATE ROLE mautrix_signal WITH LOGIN PASSWORD '<generated-64-char-password>'
  NOSUPERUSER NOCREATEDB NOCREATEROLE;
CREATE DATABASE mautrix_signal
  OWNER mautrix_signal
  ENCODING 'UTF8'
  LC_COLLATE 'C'
  LC_CTYPE 'C';
-- No additional GRANT needed — OWNER on the database gives full DDL/DML
-- within mautrix_signal only. The role has zero access to synapse or mas databases.
```

Verification after creation:

```sql
-- Confirm no superuser, no createdb
SELECT rolname, rolsuper, rolcreatedb, rolcreaterole FROM pg_roles WHERE rolname = 'mautrix_signal';
-- Expected: rolsuper=f, rolcreatedb=f, rolcreaterole=f

-- Confirm cannot access synapse DB
SET ROLE mautrix_signal;
SELECT 1 FROM synapse.public.users LIMIT 1;  -- should fail with permission denied
RESET ROLE;
```

- Collation matches Synapse's DB settings (ref: `synapse.ref` — POSTGRES_INITDB_ARGS uses `--lc-collate=C --lc-ctype=C`)
- No shared schema with Synapse or MAS
- The `synapse` user has Superuser privileges so can create the role/DB (ref: `synapse.ref` — "synapse (Superuser, Create role, Create DB)")
- Bridge config URI: `postgres://mautrix_signal:<password>@matrix-postgres:5432/mautrix_signal?sslmode=disable`

## 4. Networking

- **Appservice port:** 29328 (mautrix-signal default)
- **Bind:** 0.0.0.0:29328 inside container (Docker internal only, NOT exposed to host)
- **Appservice address in config:** `http://mautrix-signal:29328` (container name on matrix-net)
- **Verified unused:** No ports in 29xxx range are in use (ref: `appservices.ref` — "Full 29000-29999 range — AVAILABLE")
- **No Caddy changes needed** — bridge communicates with Synapse over the internal Docker network
- **No firewall changes needed** — no host port mapping

The bridge container joins `matrix-net` in docker-compose.yml:

```yaml
  mautrix-signal:
    image: dock.mau.dev/mautrix/signal:v0.2603.0
    container_name: mautrix-signal
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - ./mautrix-signal:/data
    networks:
      - matrix-net
```

No `ports:` section — the container is only reachable from within `matrix-net`.

## 5. Encryption Config

Enable end-to-bridge encryption with MSC4190 (required for MAS compatibility).

### 5a. Bridge config (`config.yaml`)

```yaml
encryption:
  allow: true
  default: true
  require: true
  appservice: false
  msc4190: true       # REQUIRED when MAS is in use
  allow_key_sharing: true
  pickle_key: generate
  self_sign: true
```

**MSC4190 requirement:** The mautrix docs state: "The `encryption` -> `msc4190` config option must be set to true for encryption to work if you use MAS."
Source: https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html

### 5b. Synapse `homeserver.yaml` diff

The exact flag names are confirmed from Synapse 1.147.1 source code at `synapse/config/experimental.py`:
- `msc3202_transaction_extensions` — parsed at line ~167, default `False`
- `msc2409_to_device_messages_enabled` — parsed at line ~163, default `False`

Source: `synapse.config.experimental.ExperimentalConfig` in Synapse v1.147.1 (`docker exec matrix-synapse python3 -c "import synapse.config.appservice"` — inspected live).

The current `homeserver.yaml` has no `experimental_features` block. The exact diff:

```diff
--- a/homeserver.yaml
+++ b/homeserver.yaml
@@ -end of file
+
+experimental_features:
+  msc3202_transaction_extensions: true
+  msc2409_to_device_messages_enabled: true
```

These flags enable:
- `msc3202_transaction_extensions`: Allows Synapse to send to-device messages, device list changes, and OTK counts in appservice transaction pushes (required for E2BE)
- `msc2409_to_device_messages_enabled`: Allows appservices to receive to-device messages (required for encryption key exchange)

**Note:** MSC4190 is NOT an `experimental_features` flag. It is parsed from the appservice registration YAML file as `io.element.msc4190: true` (confirmed from Synapse 1.147.1 source: `synapse/config/appservice.py` line 190: `msc4190_enabled = as_info.get("io.element.msc4190", False)`).

### 5c. Appservice registration (`registration.yaml`)

The bridge auto-generates `registration.yaml` when `encryption.msc4190: true` is set in `config.yaml`. The generated file will include these flags:

```yaml
io.element.msc4190: true
de.sorunome.msc2409.push_ephemeral: true
push_ephemeral: true
```

Synapse 1.147.1 supports MSC4190 (merged in Synapse 1.121.0 via PR #17705).
Source: https://github.com/element-hq/synapse/pull/17705

### 5d. Trust boundary

The bridge process holds plaintext message content in memory after decryption. The trust boundary extends from the Matrix client to the bridge container. Signal transport encryption remains intact on the Signal side.

## 6. MAS Interaction

### Claim: Appservice registration bypasses MAS

**Status: ASSUMPTION — verify during Phase 3 with stop-and-check.**

The evidence supporting this claim:
1. Appservices authenticate to Synapse via `as_token`/`hs_token` in the registration YAML, which is a Synapse-native mechanism predating MAS.
2. GitHub issue element-hq/matrix-authentication-service#3206 shows a user successfully registering and running a mautrix-signal appservice alongside MAS — basic appservice connectivity (GET `/versions`, GET `/account/whoami`, appservice ping) all returned 200 before encryption was attempted.
3. A commenter on that issue confirmed: "Can confirm it works with mautrix-signal and mautrix-whatsapp."
4. The Matrix Application Service spec defines its own auth mechanism independent of the C-S API auth layer.

Source: https://github.com/element-hq/matrix-authentication-service/issues/3206

**However**, no official MAS documentation explicitly states "appservices bypass MAS." The MAS docs (element-hq.github.io/matrix-authentication-service/) have no dedicated appservice compatibility page.

**Phase 3 stop-and-check procedure:**
1. After adding the registration to `homeserver.yaml` and restarting Synapse, check Synapse logs for appservice registration errors
2. Before starting the bridge container, run a manual appservice ping test:
   ```bash
   curl -sv http://127.0.0.1:8008/_matrix/client/v3/account/whoami \
     -H "Authorization: Bearer <as_token>" \
     -H "Content-Type: application/json" 2>&1
   ```

**PASS criteria (ALL must be true):**
- HTTP status code is `200`
- Response body contains `"user_id":"@signalbot:echo6.co"`
- Response body contains `"appservice_id":"signal"` (confirms Synapse recognized the as_token as appservice auth)

**FAIL criteria (ANY triggers STOP):**
- HTTP status `401` or `403` → MAS or Synapse rejected the as_token
- HTTP `3xx` redirect to MAS (`Location:` header pointing to `matrix-mas:8080` or `matrix.echo6.co` auth endpoints)
- Response contains MAS-specific indicators: HTML login page, `matrix-authentication-service` in headers/body, or `errcode: M_UNKNOWN_TOKEN` with MAS introspection trace in Synapse logs
- `user_id` in response does NOT match `@signalbot:echo6.co`

**On FAIL:** Do NOT start the bridge container. Do NOT proceed to step 16. Capture the full `curl -sv` output (headers + body) and the last 50 lines of Synapse logs (`docker logs matrix-synapse --tail 50`). Report both for triage.

### Registration steps

1. Generate the registration file by running the bridge container once with config in place
2. Copy `registration.yaml` into the Synapse data volume (`/opt/matrix/synapse/`)
3. Add to `homeserver.yaml`:
   ```yaml
   app_service_config_files:
     - /data/registration.yaml
     - /data/doublepuppet.yaml
   ```
   Both files are listed — Synapse reads all entries on startup. A single restart covers both registrations.
4. Restart Synapse (`docker compose restart synapse`) to pick up both appservice registrations

## 7. Permissions

```yaml
bridge:
  permissions:
    "*": relay
    "echo6.co": user
    "@matt:echo6.co": admin
```

- `*: relay` — external users can interact via relay (relay disabled by default, so effectively no access)
- `echo6.co: user` — all echo6.co users can use the bridge
- `@matt:echo6.co: admin` — full admin access for matt

Single-user deployment — only matt will link a Signal account.

## 8. Double Puppeting

Use the **appservice-based automatic double puppeting** method:

1. Generate a dedicated double-puppet appservice registration (`doublepuppet.yaml`) with a null URL and an `as_token`:
   ```yaml
   id: doublepuppet
   url:
   as_token: <generated-token>
   hs_token: <generated-token>
   sender_localpart: _doublepuppet
   rate_limited: false
   namespaces:
     users:
       - regex: '@.*:echo6\.co'
         exclusive: false
   ```
2. Register it with Synapse alongside the bridge registration in `app_service_config_files` (see section 6)
3. Configure the bridge:
   ```yaml
   double_puppet:
     secrets:
       echo6.co: "as_token:<the-as-token-from-doublepuppet.yaml>"
   ```

This ensures messages matt sends from Signal Desktop appear as `@matt:echo6.co` in Matrix rooms rather than as the Signal ghost user.

**MAS compatibility:** The appservice-based double puppeting method uses the appservice `as_token` to impersonate the user, which works independently of MAS. MAS handles human user auth; appservice tokens are Synapse-native. (Same assumption as section 6 — covered by the stop-and-check.)

## 9. Backup Impact

The existing backup script (`/opt/matrix/scripts/pg_backup.sh`) only backs up the `synapse` database (ref: `synapse.ref` — "Backs up synapse DB only (NOT mas DB)").

**Action required — BEFORE bridge goes live:**

1. Update `pg_backup.sh` to dump `mautrix_signal` and `mas`:
   ```bash
   # Add to pg_backup.sh after the synapse dump:

   # mautrix-signal bridge database
   SIGNAL_BACKUP="${BACKUP_DIR}/mautrix_signal_${TIMESTAMP}.sql.gz"
   docker exec matrix-postgres pg_dump -U mautrix_signal -d mautrix_signal | gzip > "${SIGNAL_BACKUP}"
   if [ $? -eq 0 ] && [ -s "${SIGNAL_BACKUP}" ]; then
       echo "$(date): Backup created: ${SIGNAL_BACKUP} ($(du -h "${SIGNAL_BACKUP}" | cut -f1))"
   else
       echo "$(date): WARNING: mautrix_signal backup failed"
   fi

   # MAS database (was missing from backups)
   MAS_BACKUP="${BACKUP_DIR}/mas_${TIMESTAMP}.sql.gz"
   docker exec matrix-postgres pg_dump -U mas -d mas | gzip > "${MAS_BACKUP}"
   if [ $? -eq 0 ] && [ -s "${MAS_BACKUP}" ]; then
       echo "$(date): Backup created: ${MAS_BACKUP} ($(du -h "${MAS_BACKUP}" | cut -f1))"
   else
       echo "$(date): WARNING: mas backup failed"
   fi
   ```

2. Update the cleanup `find` to also cover `mautrix_signal_*.sql.gz` and `mas_*.sql.gz`

3. **Test the backup** by running `pg_backup.sh` manually after DB creation but before starting the bridge. Verify:
   - `mautrix_signal` dump succeeds (even if empty, it should produce a valid .sql.gz)
   - `mas` dump succeeds
   - Retention cleanup patterns match the new filenames

4. Apply the same 14-day retention policy.

## 10. Rollback Plan

If the bridge needs to be removed:

```bash
# 1. Stop and remove the bridge container
cd /opt/matrix
docker compose stop mautrix-signal
docker compose rm -f mautrix-signal

# 2. Remove mautrix-signal service block from docker-compose.yml

# 3. Remove appservice registrations from Synapse homeserver.yaml:
#    - Remove /data/registration.yaml from app_service_config_files
#    - Remove /data/doublepuppet.yaml from app_service_config_files
#    - If app_service_config_files is now empty, remove the key entirely

# 4. Revert experimental_features from homeserver.yaml:
#    - Remove the entire experimental_features block:
#        experimental_features:
#          msc3202_transaction_extensions: true
#          msc2409_to_device_messages_enabled: true
#    - Only safe to remove if no other bridges depend on these flags.
#      As of this plan, no other appservices exist (ref: appservices.ref),
#      so removal is safe.

# 5. Remove registration files from Synapse volume
rm /opt/matrix/synapse/registration.yaml
rm /opt/matrix/synapse/doublepuppet.yaml

# 6. Restart Synapse to apply config changes
docker compose restart synapse

# 7. Drop the database and role
docker exec matrix-postgres psql -U synapse -c "DROP DATABASE mautrix_signal;"
docker exec matrix-postgres psql -U synapse -c "DROP ROLE mautrix_signal;"

# 8. Remove bridge data directory
rm -rf /opt/matrix/mautrix-signal

# 9. Revert backup script
# Edit pg_backup.sh: remove the mautrix_signal and mas dump sections
# (Keep mas dump if desired — it was missing before this plan anyway)

# 10. Clean up docker image
docker rmi dock.mau.dev/mautrix/signal:v0.2603.0
```

---

## Implementation Order (Phase 3 — requires approval)

1. Generate password for `mautrix_signal` DB role
2. Create DB role (with `NOSUPERUSER NOCREATEDB NOCREATEROLE`) and database in matrix-postgres
3. Verify role privileges are minimal (query `pg_roles`)
4. **Update backup script** to include `mautrix_signal` and `mas` dumps
5. **Test backup** — run `pg_backup.sh` manually, verify all three dumps succeed
6. Create `/opt/matrix/mautrix-signal/` directory
7. Generate initial config with `docker run --rm`
8. Edit `config.yaml` with all settings from this plan
9. Run container again to generate `registration.yaml`
10. Create `doublepuppet.yaml` registration
11. Copy both registration files to Synapse volume (`/opt/matrix/synapse/`)
12. Add `experimental_features` block to `homeserver.yaml`
13. Add `app_service_config_files` with both registration paths to `homeserver.yaml`
14. Restart Synapse
15. **STOP-AND-CHECK:** Verify appservice auth works alongside MAS (see section 6 procedure)
16. Add mautrix-signal service to `docker-compose.yml`
17. `docker compose up -d mautrix-signal`
18. Verify bridge bot appears in Matrix
19. Link Signal account via `!signal link` in bridge bot DM
20. Update docs (services.md, MEMORY.md)