vnctalk-prosody/PATCHES_AND_MODULES.md

# VNCtalk Prosody Patches & Custom Modules Analysis

This document describes how the VNCtalk Prosody distribution deviates from upstream Prosody 0.11.6. The deviations are delivered as:
- **`patches/`** — direct replacements for upstream core files
- **`vnctalk/`** — additional custom modules

> **Note:** `patches.list` is stale and unused. The Dockerfile hard-copies each patch in a `RUN cp …` block.

---

## 1. Core Patches (`patches/`)

### 1.1 `mod_mam.lua` → `modules/mod_mam/mod_mam.lua`
**Purpose:** Message Archive Management (XEP-0313) for 1:1 chats.

**Key deviations from upstream:**
- **`vnc-rest-message` hook support:** Added `vnc_message_handler(event)` hooked on `vnc-rest-message` (priority 0). This allows the REST injection module (`mod_http_rest`) to archive messages that are injected via HTTP.
- **Store-user logic for REST:** When `vnc_rest` is true, `store_user` is derived from `orig_from` instead of `orig_to`, so injected stanzas are archived under the sender's archive.
- **`shall_store` always returns true:** The function `shall_store(user, who)` unconditionally returns `true`, bypassing any roster-based archive filtering.
- **Archives normal messages with body:** The condition `orig_type == "chat" or (orig_type == "normal" and stanza:get_child("body"))` is kept but the implementation now also processes `vnc-rest-message` events.

**Behavioural contract:**
- Any message injected via `/rest` (see `mod_http_rest`) must be archived under the sender's MAM archive.
- MAM queries must return `stanza-id` elements and support RSM pagination.

---

### 1.2 `mod_muc.lua` → `modules/muc/mod_muc.lua`
**Purpose:** MUC component loader and room lifecycle management.

**Key deviations from upstream:**
- **Custom unregister IQ hook:** Added `iq-set/bare/xmpp:vnctalk:unregister:query` → `handle_unregister_iq`. This exposes a VNCtalk-specific room-unregistration endpoint.
- **Debug helper:** Added `dumpTable(t, depth)` utility function.
- **Room defaults:** `muc_room_default_public` defaults to `false` (rooms are hidden by default).

---

### 1.3 `mod_muc_mam.lua` → `modules/mod_muc_mam.lua`
**Purpose:** MUC Message Archive Management.

**Key deviations from upstream:**
- **`with` filter hardcoded to `message<groupchat`:** The archive query and history loader both set `with = "message<groupchat"`, meaning only groupchat messages are stored/retrieved; presence stanzas are ignored unless `muc_log_presences` is enabled.
- **Presence archiving option:** If `muc_log_presences` is true, join/leave presences are archived with synthetic `with` values (`presence` / `presence<unavailable`).
- **MUC history from archive:** The `muc-get-history` hook loads history from the archive backend when the in-memory `_history` buffer is insufficient, respecting `max_history_messages`.
- **Stanza-id stripping before broadcast:** A `muc-broadcast-message` hook (priority 1) strips any `stanza-id` tags that claim to be from the room JID before the stanza is broadcast.
- **Occupant affiliation injection:** When `whois == "anyone"`, archived messages include an `<x xmlns="http://jabber.org/protocol/muc#user">` item with the sender's affiliation and role.

---

### 1.4 `mod_muc_unique.lua` → `modules/mod_muc_unique.lua`
**Purpose:** XEP-0307 Unique Room Names.

**Key deviations from upstream:**
- **Bare-JID request returns error:** Added `handle_iq_tobare` that replies with `item-not-found` for IQ-get requests sent to a bare JID, rather than generating a unique name. Unique names are only served for host-targeted requests.

---

### 1.5 `moduleapi.lua` → `core/moduleapi.lua`
**Purpose:** Module API base.

**Key deviations from upstream:**
- **Added `open_host_store`:** New method `api:open_host_store(host, name, store_type)` allows a module to open a data store on behalf of a different host. This is heavily used by MUC FCM modules to read user private data / vCards from the main virtual host while running inside the MUC component.

---

### 1.6 `muc.lib.lua` → `modules/muc/muc.lib.lua`
**Purpose:** MUC room implementation (the largest patch).

**Key deviations from upstream:**
- **Offline-affiliate broadcast (`broadcast` method):** After broadcasting to all online occupants, the method iterates over `_affiliations` and sends the stanza to any affiliated JIDs that are **not** currently in the room, **provided their domain is not hosted locally**. This enables federation/remote-user delivery.
- **`publicise_occupant_status` skip for unavailable:** When an occupant's role becomes `nil` (they left), the code logs `"skipping unavailable presence"` and does **not** route an unavailable presence to the leaving user themselves. This changes the standard XEP-0045 self-presence delivery.
- **Debug helpers:** Added `dumpTable` and `table_clone`.

---

### 1.7 `hidden.lib.lua` → `modules/muc/hidden.lib.lua`
**Purpose:** Room visibility (public/hidden).

**Key deviations from upstream:**
- **Restricted public rooms:** If `muc_room_allow_public` is `false` (default in VNCtalk config), the public-room config option is hidden from non-admins, and only admins may create public rooms.

---

### 1.8 `register.lib.lua` → `modules/muc/register.lib.lua`
**Purpose:** MUC room nickname registration.

**Key deviations from upstream:**
- **VNCtalk unregister handler (`handle_unregister_iq`):** Fires `vnc-muc-kick` event and unconditionally removes the user's affiliation from `_affiliations`, bypassing normal affiliation-change logic. This is used for VNCtalk-specific account deletion/room cleanup.

---

### 1.9 `mod_carbons.lua` → `modules/mod_carbons.lua`
**Purpose:** XEP-0280 Message Carbons.

**Key deviations from upstream:**
- **`vnc-rest-message` hook:** Added `module:hook("vnc-rest-message", c2s_message_handler, -0.5)`. Messages injected via the REST endpoint are carbon-copied to the user's other resources just like locally-sent messages.

---

### 1.10 `mod_admin_telnet.lua` → `modules/mod_admin_telnet.lua`
**Purpose:** Admin telnet console.

**Key deviations from upstream:**
- **Listens on all interfaces:** Changed `interface` from `"127.0.0.1"` to `"*"`. The healthcheck script (`healthcheck.sh`) relies on connecting to `127.0.0.1:5582`, but the console is now bound to `0.0.0.0`.

---

### 1.11 `portmanager.lua` → `core/portmanager.lua`
**Purpose:** Network port management.

**Key deviations from upstream:**
- **Respects `network_default_read_size` for socket mode:** `local default_mode = config.get("*", "network_default_read_size") or 4096;` instead of a hardcoded `4096`. The VNCtalk config sets this to `8192` to support larger stanzas (Jitsi/file transfers).

---

## 2. Custom Modules (`vnctalk/`)

### 2.1 Authentication

#### `mod_auth_http_async`
- **HTTP-based authentication.** Replaces Prosody's internal password database with an async HTTP call to `http_auth_url`.
- Sends a `Basic` auth header with `base64(username@host:password)`.
- If `util.async` is unavailable, falls back to synchronous `socket.http` / `ssl.https`.
- `user_exists` always returns `true`; `set_password` / `create_user` / `delete_user` are no-ops.

---

### 2.2 Push Notifications (FCM)

#### `mod_vnc_fcm`
- **FCM push for 1:1 messages.** Hooks on `message/bare`, `pre-message/bare/full`, and `vnc-rest-message`.
- Reads FCM tokens from private storage (`documents:stanza:io:json` → `fcm` element) and from a map store (`fcmtoken`).
- Supports iOS and Android tokens; iOS gets a notification payload with sound, Android gets data-only.
- Handles VNCtalk-specific extensions: `vncTalkConference`, `whiteboard`, `attachment`, `read` signals, Jitsi URL/room.
- Removes invalid FCM tokens (`NotRegistered`, `InvalidRegistration`, etc.) from user private data automatically.
- **Inactive-device tracking:** Uses `csi-client-active/inactive` hooks to avoid pushing to devices that are online but inactive.

#### `mod_vnc_fcm_hin`
- Variant of `mod_vnc_fcm` with HIN (German health network) specific modifications.

#### `mod_vnc_muc_fcm` / `mod_vnc_muc_fcm_hin`
- **FCM push for MUC messages.** Loaded on the MUC component.
- Opens stores against `storage_host` (the main virtual host) using `module:open_host_store`.
- On each groupchat message, iterates over room affiliations and pushes to offline/non-occupant members.

---

### 2.3 MUC Extensions

#### `mod_vnc_muc_automember`
- Automatically grants `member` affiliation to anyone who receives a MUC invite, if they were previously unaffiliated.

#### `mod_vnc_muc_hook`
- Sends a XMPP message notification (with `http://vnc.biz/xmpp/muc#hook` namespace) to online users who are affiliated with a room but not currently joined, when an "important" message (has non-empty body) is broadcast.
- Optionally sends a mediated invite instead of a plain notification (`muc_notification_invite`).

#### `mod_vnc_muc_data`
- Adds a `muc#roomconfig_vdata` config field and `muc#roominfo_vdata` disco info field.
- On config change, broadcasts a groupchat message with `<x xmlns='xmpp:vnctalk:update'/>` containing JSON-encoded affiliations and room data.

#### `mod_vnc_e2ehints`
- Adds a `muc#roomconfig_e2e` boolean field and `muc#roominfo_e2e` disco info field for end-to-end encryption hints.

#### `mod_vnc_remotemucstore`
- Archives groupchat messages from **remote** MUCs (federation) into a local archive (`muc_remote`) so users can query history even for rooms not hosted locally.
- Stores MUC presence metadata (real JID mapping, subject, nick) in a map store.
- Prevents further processing of messages addressed to bare JIDs from remote MUCs (so they don't create offline message spam).

#### `mod_vnc_remotemucinvite`
- Archives mediated MUC invitations sent to remote users in a store (`muc_remote_inv`).

#### `mod_vnc_track_kicks`
- Tracks kick/ban events in MUC rooms (lightweight event logger).

---

### 2.4 vCard & Avatar

#### `mod_vnc_vcard_avatar`
- On vCard update (IQ-set to self), extracts the PHOTO binval, decodes it, and uploads it via HTTP PUT to `avatar_upload_url`.
- Uses Basic auth if `avatar_upload_user` / `avatar_upload_pass` are configured.
- Stores an `avatarupdate` timestamp in a map store.

#### `mod_vnc_vcard_fallback`
- Intercepts vCard IQ-get requests.
- If the user has no vCard on file, auto-generates one from the username (dot-separated usernames become `FIRSTNAME LASTNAME`).
- Adds `ORGNAME` if `default_vcard_orgname` is configured.

---

### 2.5 Messaging Extensions

#### `mod_vnc_timestamp`
- Adds a custom `<stamp xmlns='xmpp:vnctalk:stamp'/>` tag to incoming chat/groupchat messages that have a body.
- Sends an IQ-result back to the sender containing the timestamp and original stanza ID.

#### `mod_vnc_receipts`
- Archives XEP-0184 delivery receipts (`<received xmlns='urn:xmpp:receipts'/>`) in an archive store (`receipts`).

#### `mod_vnc_lastactivity`
- Extends XEP-0012 last activity with avatar hash caching.
- Caches SHA1 of the user's vCard PHOTO in memory (`avt_hash_table`).
- Stores/retrieves remote user activity and avatar updates in map stores.

#### `mod_vnc_broadcast`
- Implements a `vnc_broadcast` component.
- Accepts messages with `<vncTalkBroadcast xmlns='xmpp:vnctalk'>` and fans them out to:
  - Explicit `to` JIDs
  - Roster groups (via `roster_manager.load_roster`)
  - MUC room affiliations (if a `to` JID is a MUC)

---

### 2.6 HTTP / REST

#### `mod_http_rest`
- Exposes `POST /rest` on the HTTP server.
- Accepts `Content-Type: text/xml` bodies, parses them as XMPP stanzas, and injects them into the server via `module:fire_event("vnc-rest-message", …)`.
- Returns `201` on success, `415` for wrong content type, `422` for unparseable body.

#### `mod_http_upload_external`
- Delegates HTTP file upload to an external PHP endpoint (`share.php`).
- Generates signed URLs using `http_upload_external_secret`.

---

### 2.7 Utility Modules

| Module | Purpose |
|--------|---------|
| `mod_alias` | Allows users to have alias JIDs |
| `mod_roster_command` | Ad-hoc commands for roster management |
| `mod_s2s_keepalive` | Keepalive pings for S2S connections (Jitsi compatibility) |
| `mod_smacks` / `mod_smacks_offline` | Stream Management (XEP-0198) with offline queue support |
| `mod_carbons_copies` | Helper for carbons routing |
| `mod_log_slow_events` | Logs events exceeding `log_slow_events_threshold` |
| `mod_discoitems` | Manual override of disco items for a host |
| `mod_filter_chatstates` | Drops chat-state notifications under certain conditions |
| `mod_idlecompat` | Compatibility shim for idle detection |
| `mod_http_altconnect` | Alternative connection methods discovery |
| `mod_http_index` | Static HTTP index page |
| `mod_webpresence` | Publish presence as web images/icons |
| `mod_auto_accept_subscriptions` | Auto-accept presence subscriptions |
| `mod_vcard_muc` | vCard support for MUC rooms |
| `mod_vnc_delfile` | File deletion command via XMPP |

---

## 3. Configuration-Driven Behaviour

Several behaviours are not hard-coded in Lua but emerge from `config/prosody.cfg.lua.template`:

| Config Option | Effect |
|---------------|--------|
| `authentication = "http_async"` | All client auth goes to `hybridaAuthUrl` |
| `default_archive_policy = "roster"` | MAM archives only roster contacts by default |
| `muc_log_by_default = true` / `muc_log_all_rooms = true` | All MUC messages archived |
| `c2s_require_encryption = true` | Plaintext C2S rejected |
| `keepalive_servers = { "${DEFAULT_JITSI_CONFERENCE}" }` | S2S keepalive pings sent to Jitsi |
| `component_secret = "…"` | Fixed MUC component secret (not randomly generated) |

---

## 4. Healthcheck & Runtime Quirks

- `healthcheck.sh` exits **2** (not 1) when the TLS cert in `/etc/tls-update/tls.crt` differs from the loaded one. Orchestrators must treat exit code 2 as a restart signal.
- `startup-sidecar.sh` runs a Node `http-server` on port 8080 for static files; this is **not** the XMPP server.
- `startup.sh` generates fallback certs from base64 defaults if `prosodySSLkey/cert` env vars are missing.