Harden container packaging and document bridge operation

Keep local state and development artifacts out of the image, and generate configuration as the same configured user that runs the bridge. Document persistent state, configuration, login, media, and the native client API.

Author: Fizzadar

.dockerignore

@@ -4,5 +4,17 @@ logs
 start
 config.yaml
 registration.yaml
-*.db
+*.db*
+*.sqlite*
 *.pickle
+*.log
+.git
+.claude
+.DS_Store
+**/.DS_Store
+.env*
+*cookies*.json
+*storage-state*.json
+/reddit
+/evidence/
+/runtime/

.gitignore

@@ -8,3 +8,8 @@ logs/
 !.github/workflows/*.yml
 !.gitlab-ci.yml
 .idea
+.env*
+*cookies*.json
+*storage-state*.json
+/evidence/
+/runtime/

Dockerfile

@@ -2,9 +2,11 @@ FROM golang:1-alpine3.23 AS builder
 
 RUN apk add --no-cache git ca-certificates build-base su-exec olm-dev
 
+ARG CI_COMMIT_SHA=unknown
+ARG CI_COMMIT_TAG=
 COPY . /build
 WORKDIR /build
-RUN ./build.sh
+RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,target=/root/.cache/go-build CI=true ./build.sh
 
 FROM alpine:3.23
 
@@ -15,6 +17,9 @@ RUN apk add --no-cache ffmpeg su-exec ca-certificates olm bash jq yq curl
 
 COPY --from=builder /build/reddit /usr/bin/reddit
 COPY --from=builder /build/docker-run.sh /docker-run.sh
+ARG CI_COMMIT_SHA=unknown
+LABEL org.opencontainers.image.source="https://github.com/beeper/reddit" \
+    org.opencontainers.image.revision="${CI_COMMIT_SHA}"
 VOLUME /data
-
-CMD ["/docker-run.sh"]
+WORKDIR /data
+ENTRYPOINT ["/docker-run.sh"]

README.md

@@ -13,6 +13,24 @@ require bridge updates.
 - Text and media send and receive.
 - Replies, edits, reactions, read receipts, and typing notifications.
 
+## Configuration
+
+Direct media uses the standard top-level `direct_media` configuration: enable
+it with a reachable media server name/delegation and a persistent server signing
+key. Keep that name and key stable so existing signed URLs remain usable. The
+bridge must retain the originating Reddit login and Reddit must still serve the
+file. Downloads use bounded memory and sniff the actual image MIME type; they
+are proxied on demand, without a second media cache or an upload to Matrix.
+Reddit can transcode WebP to JPEG, so native event metadata may differ from the
+bytes served by the proxy. Existing reuploaded messages are unchanged.
+
+Ordinary Matrix leave events also require `bridge.bridge_matrix_leave: true`;
+Beeper membership state requests require `bridge.enable_send_state_requests: true`.
+The existing Delete/Ignore action remains available independently of
+the Matrix-leave switch. DMs are hidden for the owner, while groups are left.
+Group invite/kick capabilities remain rejected in DMs; Reddit enforces group
+permissions and invitation limits. Ban/unban and role changes are unsupported.
+
 ## Setup
 
 Install and log in to [`bbctl`](https://github.com/beeper/bridge-manager):
@@ -21,20 +39,42 @@ Install and log in to [`bbctl`](https://github.com/beeper/bridge-manager):
 bbctl login
 ```
 
-Register the bridge and generate its config:
+Build in the source checkout (Go 1.26+ and libolm are required):
 
 ```sh
-bbctl config --type bridgev2 -o config.yaml sh-reddit
-bbctl register -g -o registration.yaml sh-reddit
+./build.sh
 ```
 
-Run the bridge (requires Go 1.26+ and libolm — `brew install libolm` on
-macOS, `apt-get install libolm-dev` on Debian/Ubuntu):
+Install libolm with `brew install libolm` on macOS or
+`apt-get install libolm-dev` on Debian/Ubuntu.
+Generate credentials in a private runtime directory outside the source
+checkout. Use a dedicated bridge name for the first registration:
 
 ```sh
-go run ./cmd/reddit -c config.yaml -r registration.yaml
+install -d -m 700 "$HOME/.local/share/beeper-reddit"
+cd "$HOME/.local/share/beeper-reddit"
+umask 077
+bbctl config --type bridgev2 --param pickle_key=generate -o "$PWD/config.yaml" sh-reddit
+bbctl register -g -o "$PWD/registration.yaml" sh-reddit
 ```
 
+Enable Beeper's state-request path in `config.yaml` so group-name changes can
+reach the connector. Set this field under the `bridge` section:
+
+```yaml
+bridge:
+    enable_send_state_requests: true
+```
+
+Then start the bridge:
+
+```sh
+/absolute/path/to/reddit/reddit -c config.yaml -r registration.yaml
+```
+
+For updates, stop the bridge process and replace its binary while retaining
+the same runtime, registration, database and encryption key.
+
 Then open Beeper Desktop, go to Settings -> Bridges -> Self-hosted Bridges,
 find `sh-reddit`, add an account, and complete the Reddit login flow.
 

docker-run.sh

@@ -1,20 +1,30 @@
 #!/bin/sh
+set -eu
+umask 077
 
-if [[ -z "$GID" ]]; then
-	GID="$UID"
-fi
+bridge_uid="${UID:-1337}"
+bridge_gid="${GID:-$bridge_uid}"
+case "$bridge_uid:$bridge_gid" in
+	*[!0-9:]*|:*|*:) echo "UID and GID must be numeric" >&2; exit 1 ;;
+esac
+
+mkdir -p /data
+chmod 700 /data
+cd /data
 
-# Define functions.
-function fixperms {
-	chown -R $UID:$GID /data
+# Generate and upgrade files as the same numeric user that runs the bridge.
+# The previous launcher wrote the initial 0600 config as root, preventing the
+# host user from editing it even when UID/GID were explicitly supplied.
+if [ "$(id -u)" = 0 ] && [ "$bridge_uid" != 0 ]; then
+	chown -R "$bridge_uid:$bridge_gid" /data
+	exec su-exec "$bridge_uid:$bridge_gid" "$0" "$@"
+fi
 
-	# /opt/reddit is read-only, so disable file logging if it's pointing there.
-	if [[ "$(yq e '.logging.writers[1].filename' /data/config.yaml)" == "./logs/reddit.log" ]]; then
-		yq -I4 e -i 'del(.logging.writers[1])' /data/config.yaml
-	fi
-}
+if [ "$#" -gt 0 ]; then
+	exec /usr/bin/reddit "$@"
+fi
 
-if [[ ! -f /data/config.yaml ]]; then
+if [ ! -f /data/config.yaml ]; then
 	/usr/bin/reddit -c /data/config.yaml -e
 	echo "Didn't find a config file."
 	echo "Copied default config file to /data/config.yaml"
@@ -23,14 +33,13 @@ if [[ ! -f /data/config.yaml ]]; then
 	exit
 fi
 
-if [[ ! -f /data/registration.yaml ]]; then
+if [ ! -f /data/registration.yaml ]; then
 	/usr/bin/reddit -g -c /data/config.yaml -r /data/registration.yaml || exit $?
 	echo "Didn't find a registration file."
 	echo "Generated one for you."
 	echo "See https://docs.mau.fi/bridges/general/registering-appservices.html on how to use it."
 	exit
 fi
 
-cd /data
-fixperms
-exec su-exec $UID:$GID /usr/bin/reddit
+chmod 600 /data/config.yaml /data/registration.yaml
+exec /usr/bin/reddit -c /data/config.yaml -r /data/registration.yaml

pkg/redditchat/README.md

@@ -1,182 +1,33 @@
-# Reddit Chat Go
+# Reddit chat protocol client
 
-Go wrapper for Reddit's Matrix-backed chat service using mautrix-go.
+This package implements the Reddit endpoints used by the bridge. It uses
+`maunium.net/go/mautrix` for Reddit's Matrix-shaped chat protocol; bridgev2 owns
+local message delivery and mappings.
 
-Note: the GitHub project is `github.com/mautrix/go`, but its `go.mod` declares the canonical Go import path as `maunium.net/go/mautrix`. Importing `github.com/mautrix/go` directly fails module path validation, so this library uses the canonical mautrix-go import path.
+## Authentication
 
-## Auth
+The connector drives the native operations through bridgev2 login steps:
 
-Reddit chat stores Matrix credentials in `https://www.reddit.com` local storage after the chat app loads. The same credentials can also be minted directly from a logged-in Reddit web session by POSTing to `/svc/shreddit/token` with the `csrf_token` cookie.
+1. Create a `RedditSession` and call `PrepareLogin` with the username.
+2. Present `CaptchaRequest(CaptchaStepPassword)` in the framework's hidden
+   verification webview, then pass its result to `SubmitPassword`.
+3. If Reddit requires two-factor authentication, collect the user's code and
+   a fresh `CaptchaRequest(CaptchaStepOTP)`, then call `SubmitOTP` on the same
+   session. Do not repeat the password login.
+4. Call `CredentialsFromRedditSession` to mint chat credentials. The connector
+   persists the session cookies for renewal and validates the account on refresh.
 
-Supported extraction paths:
+Each operation accepts a context and performs only that step's HTTP requests.
+There is no background login worker or browser-debug connection. OTP codes are
+provided by the user; the bridge does not accept authenticator secrets.
 
-- `LoginReddit(ctx, opts)` implements Reddit's current web login flow and returns Reddit session cookies plus Matrix credentials.
-- `NewFromRedditLogin(ctx, opts)` logs in, mints Matrix credentials, and returns a ready chat client.
-- `CredentialsFromRedditSession(ctx, session)` POSTs `/svc/shreddit/token`, decodes the chat JWT into a Matrix user ID, calls Matrix `whoami` for the device ID, and returns `Credentials`.
-- `RedditSessionFromPlaywrightStorageState(path)` imports Reddit session cookies from a Playwright storage-state JSON file without using the old chat localStorage credentials.
-- `CredentialsFromPlaywrightStorageState(path)` reads a Playwright storage-state JSON file.
-- `CredentialsFromChromeDebugURL(ctx, url)` attaches to a live Chrome/Chromium debug endpoint, opens `https://www.reddit.com/chat/`, and reads the same local storage keys through CDP.
-- `SeedChromeFromPlaywrightStorageState(ctx, url, path)` seeds a live Chrome/Chromium debug endpoint from a Playwright storage-state JSON file, then the CDP extractor can read from the real browser session.
+## Chat protocol
 
-Chrome debug endpoints may be passed as `http://127.0.0.1:9222` or a browser websocket URL.
+Reddit uses `matrix.redditspace.com`, native `t2_` user IDs, opaque event IDs
+and provider pagination cursors. Its request previews also appear in
+`rooms.peek`. Media downloads use the native `/media/v3/download` endpoint;
+thread pages use Reddit's sequenced relations API. These differences are
+handled here and by the connector, without overriding bridgev2 delivery.
 
-Login API notes:
-
-- Reddit serves a deterministic JavaScript verification page before the login UI; the library follows that page transition.
-- The username/password step is `POST /svc/shreddit/account/login/check_is_oidc_required`, then `POST /svc/shreddit/account/login`.
-- Accounts with app-based 2FA receive HTTP 202 from the password step; the OTP step is `POST /svc/shreddit/account/login/otp`.
-- Reddit requires a reCAPTCHA Enterprise token for password and OTP submits. The library accepts a `CaptchaTokenProvider` callback and does not include CAPTCHA solving, media extraction, or bypass logic.
-- Reddit's current login flow does not POST an image/audio CAPTCHA answer to Reddit. Google reCAPTCHA runs in the browser and returns an opaque, short-lived `recaptcha_token`; that token is the value Reddit receives.
-- If no provider is configured, `LoginReddit` returns `CaptchaRequiredError` with the site key, action, and page URL needed by a caller-managed CAPTCHA flow.
-- `StaticCaptchaTokenProvider(tokens...)` can be used when the caller already has one or more fresh reCAPTCHA tokens. Accounts with 2FA need two tokens: one for the password step and one for the OTP step.
-- `CaptchaTokenProviderFromChromeDebugURL(url)` uses a real Chrome/Chromium debug session, opens the Reddit login page, runs Google reCAPTCHA Enterprise on Reddit's origin, and returns the resulting token. If Google presents an interactive challenge, the user handles it in that browser.
-- `CaptchaRequest.Step` is `password` or `otp`, so UI code can show why a token is being requested.
-- For an embedded WebView provider, load `CaptchaRequest.PageURL`, then evaluate `CaptchaRequest.EnterpriseExecuteJavaScript()` on that page and return the resulting token. Username, password, and 2FA do not need to be entered in the WebView.
-- TOTP generation is built in through `GenerateTOTP` and `RedditLoginOptions.TOTPSecret`.
-
-Minimal login shape:
-
-```go
-client, session, err := redditchat.NewFromRedditLogin(ctx, redditchat.RedditLoginOptions{
-    Username:   username,
-    Password:   password,
-    TOTPSecret: totpSecret,
-    CaptchaTokenProvider: redditchat.CaptchaTokenProviderFromChromeDebugURL("http://127.0.0.1:9222"),
-})
-_ = client
-_ = session
-```
-
-The Chrome-backed provider needs a running browser with remote debugging enabled, for example:
-
-```sh
-google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/reddit-login-captcha
-```
-
-The important detail is origin: the Reddit reCAPTCHA site key must be executed from `https://www.reddit.com/login/`. A local HTML page or unrelated WebView origin will usually produce an invalid token.
-
-WebView provider shape:
-
-```go
-CaptchaTokenProvider: func(ctx context.Context, req redditchat.CaptchaRequest) (string, error) {
-    webview.Navigate(req.PageURL)
-    token, err := webview.EvaluateJavaScript(ctx, req.EnterpriseExecuteJavaScript())
-    if err != nil {
-        return "", err
-    }
-    return token, nil
-}
-```
-
-The WebView is only for reCAPTCHA. `LoginReddit` still submits username, password, and TOTP through the reversed Reddit HTTP endpoints.
-
-## API Surface
-
-The package exposes mautrix-backed helpers for:
-
-- `LoginReddit`, `NewFromRedditLogin`, `CredentialsFromRedditSession`, `RedditSessionFromPlaywrightStorageState`
-- `CaptchaTokenProviderFromChromeDebugURL`, `CaptchaTokenFromChromeDebugURL`, `StaticCaptchaTokenProvider`
-- `Whoami`, `Capabilities`, `Sync`, `Messages`, `GetEvent`, `JoinedRooms`
-- `SearchUsers`, `RoomsWithUser`, `DirectRoomsWithUser`
-- `CreateDM`, `CreateOrGetDM`, `CreateGroup`, `Invite`, `AcceptInvite`, `Leave`
-- `SendText`, `SendNotice`, `SendMessage`
-- `SetTyping`, `MarkRead`
-- `MediaConfig`, `UploadMedia`, `SendFile`, `SendImage`, `SendVideo`, `SendAudio`, `SendMedia`
-- `SendMXCFile`, `SendMXCImage`, `SendMXCVideo`, `SendMXCAudio`, `SendMXCMedia`
-- `DownloadMedia`, `DownloadMediaBytes`
-
-Raw mautrix access is available through `Client.Mautrix()`.
-
-## Smoke Command
-
-Authenticate both saved test sessions and sync:
-
-```sh
-go run ./cmd/redditchat-smoke
-```
-
-Derive Matrix credentials from Reddit session cookies instead of chat localStorage:
-
-```sh
-go run ./cmd/redditchat-smoke -session-auth
-```
-
-Use Chrome debug protocol instead of saved storage state:
-
-```sh
-go run ./cmd/redditchat-smoke -cdp-a http://127.0.0.1:9222 -cdp-b http://127.0.0.1:9223
-```
-
-Seed real Chrome debug sessions from the saved test states, then authenticate through CDP:
-
-```sh
-go run ./cmd/redditchat-smoke \
-  -seed-cdp \
-  -cdp-a http://127.0.0.1:9222 \
-  -cdp-b http://127.0.0.1:9223
-```
-
-Send a text message through the verified DM room:
-
-```sh
-go run ./cmd/redditchat-smoke \
-  -room '!7qgWTmcqCdRXuLbvlk3ggseaFXdE5jltGuMrhpSbq6o:reddit.com' \
-  -message 'hello from mautrix'
-```
-
-Get or create a DM, or create a group room, then send the smoke message:
-
-```sh
-go run ./cmd/redditchat-smoke -create-dm
-go run ./cmd/redditchat-smoke -create-group
-```
-
-Send media through the Matrix media API:
-
-```sh
-go run ./cmd/redditchat-smoke \
-  -room '!7qgWTmcqCdRXuLbvlk3ggseaFXdE5jltGuMrhpSbq6o:reddit.com' \
-  -image /tmp/reddit-chat-smoke.png
-```
-
-Send an already-hosted Reddit MXC media event:
-
-```sh
-go run ./cmd/redditchat-smoke \
-  -room '!7qgWTmcqCdRXuLbvlk3ggseaFXdE5jltGuMrhpSbq6o:reddit.com' \
-  -image-url 'mxc://reddit.com/<media-id>' \
-  -media-name image.jpg \
-  -media-content-type image/jpeg
-```
-
-Print Reddit Matrix media limits:
-
-```sh
-go run ./cmd/redditchat-smoke -media-config
-```
-
-## Current Live Evidence
-
-- Both test accounts authenticate via Reddit's Matrix tokens.
-- Reddit login capture reversed the current web endpoints: password login uses `/svc/shreddit/account/login`; 2FA uses `/svc/shreddit/account/login/otp`; chat token refresh uses `POST /svc/shreddit/token`.
-- `-session-auth` was verified with a post-login state that had no chat localStorage bootstrap: account A minted fresh Matrix credentials as `@t2_2foi1of47y:reddit.com` device `63491a13e9d7e54e91096051125ff818`, and account B also minted fresh credentials from Reddit session cookies. Both synced successfully.
-- Both test accounts now have verified email addresses in Reddit settings.
-- `Sync` works for both accounts.
-- Reddit's web client uses `preset: "reddit_dm"` for direct chats and `preset: "private_chat"` for group rooms. The wrapper now matches those presets.
-- The web client checks `/_matrix/client/v3/rooms?with_user=...&type=direct&include=state,timeline` before creating a DM. `CreateOrGetDM` implements the same reuse flow.
-- `CreateDM` worked previously with a minimal mautrix `CreateRoom` request; repeated smoke runs now reuse the existing DM to avoid room-creation quota.
-- Account B accepted the invite via `JoinRoomByID`.
-- Account A sent a text message via mautrix in the verified DM room and account B observed it via `Sync`.
-- Real Chromium CDP sessions were launched on ports 9222 and 9223, seeded from the saved states, and used for auth/sync through `CredentialsFromChromeDebugURL`.
-- CDP-backed send/receive worked in room `!7qgWTmcqCdRXuLbvlk3ggseaFXdE5jltGuMrhpSbq6o:reddit.com`; sent event `$bY18t2ZghWQqGKKUy3K2nn52UcwTlatxDjPiNaTi6lA` was observed by account B.
-- The latest `CreateOrGetDM` smoke reused that room and sent event `$9Pie9l3KG8pohOoV_vQayz-7nHoVt058QYW5DnjSm1s`, observed by account B.
-- `SendMXCImage` with a `mxc://reddit.com/...` URI sent event `$KpRv0U9TGl_0hYbM9Rd9xHSzOXBvzD4Q-95o80OqZMU`, observed by account B.
-
-New-device note: a message send using a freshly minted session-auth Matrix device reached the existing DM room but Reddit returned `M_FORBIDDEN: User is flagged for spam`. The same accounts can still sync, and earlier established devices can send in the DM. This appears to be another Reddit account/device trust decision rather than a missing Matrix API call.
-
-Group note: `CreateGroup` is implemented as a non-direct Matrix room creation with invites. Live creation is currently blocked by Reddit rate limits/account-establishment gates on the test accounts:
-
-- After email verification and chat reload, account A receives `M_LIMIT_EXCEEDED: Limit exceeded for number of invites attempted` with `rate.score_invitation_limit`.
-- Earlier runs also hit `rate.score_room_creation_limit` on account A and `rate.score_invitation_limit_ln` when account B was used as the creator.
-
-Media note: Reddit currently returns `M_FORBIDDEN: Media upload forbidden` for standard Matrix media upload from these sessions, even after both accounts were email verified and the chat app was reloaded. `MediaConfig` reports `m.upload.size: 20971520` and `com.reddit.upload.size: {"image/gif":104857600}`, so the endpoint is present. A headed browser capture of the real Reddit chat UI selected `/tmp/reddit-chat-smoke.png` and the UI itself posted to `https://matrix.redditspace.com/_matrix/media/v3/upload?filename=reddit-chat-smoke.png`, the same endpoint mautrix uses. Reddit returned HTTP 403 and displayed "An error occurred while uploading the image. Please try again." Reddit also rejects HTTPS media URLs and foreign MXC origins in message content, but accepts `mxc://reddit.com/...` media events. A synthetic Reddit-origin MXC URI sends and renders as an image event; a fake media ID will not download actual bytes.
+Local protocol tests use synthetic responses and do not establish end-to-end
+acceptance.