feat: bitsocial-previewer

Multi-tenant link-preview + redirect server for Bitsocial clients.
Resolves a client profile by Host header (5chan -> s.5chan.app,
seedit -> s.seedit.app), renders OpenGraph/Twitter cards via
@pkcprotocol/pkc-js getComment over public IPFS gateways, then
redirects browsers into the app's hash route.

Author: tomcasaburi

.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+.git
+.env
+*.log
+test
+.github
+deploy
+README.md
+.DS_Store

.env.example

@@ -0,0 +1,21 @@
+# Copy to .env to run outside docker-compose. (The server deploy sets these
+# inline in docker-compose.yml.)
+
+PORT=3924
+BIND_HOST=127.0.0.1
+
+# Resolve shared comments from the public IPFS gateways the 5chan app uses —
+# these have broad content coverage. (A box's local IPFS node generally can NOT
+# resolve arbitrary shared comment cids: it's thinly peered and doesn't pin
+# individual comment blocks.) With none set, config.js falls back to a subset.
+IPFS_GATEWAY_URLS=https://gateway.forumindex.com,https://ipfsgateway.xyz,https://gateway.plebpubsub.xyz,https://ipfs.io
+
+# Max time to resolve a comment before serving a generic card. The fetch keeps
+# warming the cache in the background, so the retry is instant.
+GETCOMMENT_TIMEOUT_MS=10000
+
+DEBUG=bitsocial-previewer:*
+
+# Advanced / not recommended on the seeder box: delegate to a local pkc daemon
+# instead of gateways. Its node could not resolve arbitrary shared cids in tests.
+# PKC_RPC_URLS=ws://127.0.0.1:9138

.github/workflows/docker.yml

@@ -0,0 +1,38 @@
+name: build-and-push
+
+on:
+  push:
+    branches: [master, main]
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ghcr.io/bitsocialnet/bitsocial-previewer
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=ref,event=tag
+            type=sha,format=short
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.env
+*.log
+.DS_Store

Dockerfile

@@ -0,0 +1,17 @@
+# Debian-slim (not alpine): pkc-js pulls in heavy libp2p deps that are happiest
+# on glibc. Node 22+ is required: pkc-js depends on undici@8, which needs
+# node >=22.19 (on node 20 it crashes with "markAsUncloneable is not a function").
+FROM node:22-bookworm-slim
+
+WORKDIR /app
+
+# Install production deps first for better layer caching.
+COPY package.json ./
+RUN npm install --omit=dev --no-audit --no-fund
+
+COPY . .
+
+ENV NODE_ENV=production
+EXPOSE 3924
+
+CMD ["node", "start.js"]

LICENSE

@@ -0,0 +1,98 @@
+# bitsocial-previewer
+
+Link-preview + redirect server for Bitsocial clients. When someone shares a
+post link on Twitter/Telegram/Discord/etc., this server renders the
+OpenGraph/Twitter card for that post, then redirects real browsers into the app.
+
+It is **multi-tenant**: one running instance serves many clients and many mirror
+domains, picking the right profile from the request's `Host` header — so a single
+deployment (and a single TLS setup) covers every client and every mirror.
+
+```
+                      ┌──────────── s.5chan.app/biz/thread/<cid>
+ share link  ───────► │  bitsocial-previewer  ──► OG/Twitter card (for scrapers)
+ (no #/ hash)         └──────────── 302-ish JS redirect ──► 5chan.app/#/biz/thread/<cid>
+```
+
+## How it works
+
+1. 5chan 0.9.1 copies **path-based** share links (no `#/` hash) so the path
+   reaches the server: `https://s.5chan.app/<board>/thread/<cid>`.
+2. The server matches the path to a client profile + route, fetches the post by
+   cid via `@pkcprotocol/pkc-js` (`getComment`), and builds the card.
+3. Browsers get redirected into the app's hash route; scrapers read the tags.
+
+`<board>` is usually a short **directory code** (e.g. `biz`). We pass it straight
+through to the app (which resolves it); the cid is authoritative for the preview,
+so the previewer never needs to resolve codes itself.
+
+### Recognised share-link formats (5chan)
+
+| Incoming on `s.5chan.app` | Preview | Redirects to |
+|---|---|---|
+| `/<board>/thread/<cid>` | rich (title/text/image) | `5chan.app/#/<board>/thread/<cid>` |
+| `/<board>/catalog` | generic board card | `5chan.app/#/<board>/catalog` |
+| `/<board>` | generic board card | `5chan.app/#/<board>` |
+| `/p/<address>/c/<cid>` (legacy) | rich | `5chan.app/#/<address>/thread/<cid>` |
+
+Unresolvable cid → still redirects to the app with a generic card (short cache),
+so a share link never dead-ends.
+
+## Layout
+
+| File | Purpose |
+|---|---|
+| [`lib/clients.js`](lib/clients.js) | **The per-client design.** Profiles (hostnames, app URL, routes) + host→profile + route matching. |
+| [`lib/html.js`](lib/html.js) | OG/Twitter tag rendering + redirect (HTML-escaped, XSS-safe). Pure. |
+| [`lib/pkc.js`](lib/pkc.js) | `@pkcprotocol/pkc-js` init + cached `getComment`. |
+| [`lib/media.js`](lib/media.js) | Comment media URL + external-link `og:image` scraping. |
+| [`start.js`](start.js) | Express wiring. |
+| [`config.js`](config.js) | Env-driven config (port, bind host, pkc options). |
+
+## Run locally
+
+```bash
+npm install
+npm start            # listens on 127.0.0.1:3924, public-gateway fallback
+# in another shell:
+curl -s 'http://localhost:3924/biz/thread/<cid>' | grep -i og:
+```
+
+```bash
+npm test             # routing + HTML unit tests (no network/install needed for the pure logic)
+```
+
+## Deploy (Caddy)
+
+Deployed under `/opt/bitsocial-previewer` like the box's other services. Config
+(gateways, port) is inline in [`docker-compose.yml`](docker-compose.yml). The
+previewer resolves shared comments through the public IPFS gateways the 5chan app
+uses — a fetch is sub-second once a gateway has the content, and a hard timeout
+falls back to a generic card so a request never hangs. (A box's local IPFS node
+generally can't resolve arbitrary shared comment cids: thinly peered, and it
+doesn't pin individual comment blocks.)
+
+```bash
+# on the box, in /opt/bitsocial-previewer (source synced or git-cloned):
+docker compose up -d --build       # builds + runs on 127.0.0.1:3924
+docker compose logs -f --tail=50
+```
+
+CI also publishes `ghcr.io/bitsocialnet/bitsocial-previewer:latest`
+([workflow](.github/workflows/docker.yml)); once that package is made public you
+can `docker compose pull && docker compose up -d` instead of building on the box.
+
+Point the local Caddy at it with [`deploy/Caddyfile.snippet`](deploy/Caddyfile.snippet),
+then do the Cloudflare DNS change in [`deploy/cloudflare.md`](deploy/cloudflare.md).
+
+## Add a client or a mirror
+
+- **New mirror domain for 5chan:** add it to the `5chan` profile's `hostnames`
+  in [`lib/clients.js`](lib/clients.js), add a Caddy block + a DNS A record.
+- **New client (e.g. seedit):** fill in the `seedit` profile template
+  (hostnames, `appBaseUrl`, route formats) and enable it.
+
+## License
+
+[GPL-3.0-or-later](LICENSE) — matching the Bitsocial core stack it builds on
+(`@pkcprotocol/pkc-js`, `bitsocial-react-hooks`, 5chan, seedit).

README.md

@@ -0,0 +1,52 @@
+// Runtime config, driven entirely by environment variables so the same image
+// runs locally and on the server. See .env.example for the production values.
+
+const list = (value) =>
+  (value || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+
+// Build @pkcprotocol/pkc-js options. Two modes:
+//
+//   • RPC mode (recommended on VPS B): set PKC_RPC_URLS to the local daemon the
+//     seeder already runs (ws://127.0.0.1:9138). getComment is served by that
+//     warm, content-pinned node — no second IPFS node, fastest + most reliable.
+//
+//   • Standalone mode (default, runs anywhere): in-process pkc-js reading from
+//     IPFS gateways. On the server, point IPFS_GATEWAY_URLS at the local gateway
+//     (http://127.0.0.1:6473); with no env set it falls back to public gateways
+//     so `npm start` works on a laptop for review.
+const buildPkcOptions = () => {
+  const options = {}
+
+  const rpc = list(process.env.PKC_RPC_URLS)
+  if (rpc.length) options.pkcRpcClientsOptions = rpc
+
+  const kubo = list(process.env.KUBO_RPC_URLS)
+  if (kubo.length) options.kuboRpcClientsOptions = kubo
+
+  const pubsub = list(process.env.PUBSUB_KUBO_RPC_URLS)
+  if (pubsub.length) options.pubsubKuboRpcClientsOptions = pubsub
+
+  const gateways = list(process.env.IPFS_GATEWAY_URLS)
+  if (gateways.length) {
+    options.ipfsGatewayUrls = gateways
+  } else if (!rpc.length) {
+    // public fallback only when not delegating to a local daemon
+    options.ipfsGatewayUrls = ['https://ipfs.io', 'https://ipfsgateway.xyz', 'https://gateway.forumindex.com']
+  }
+
+  return options
+}
+
+export default {
+  port: Number(process.env.PORT || 3924),
+  // Bind to loopback by default: with host networking on the server, only the
+  // local Caddy reaches it (never the public internet). Set BIND_HOST=0.0.0.0
+  // when running in bridge networking with a published port.
+  bindHost: process.env.BIND_HOST || '127.0.0.1',
+  // Max time to resolve a comment before the request falls back to a generic card.
+  getCommentTimeoutMs: Number(process.env.GETCOMMENT_TIMEOUT_MS || 10_000),
+  pkcOptions: buildPkcOptions(),
+}

config.js

@@ -0,0 +1,16 @@
+# Add this to the server's Caddyfile. Caddy auto-provisions the Let's Encrypt
+# certificate the moment s.5chan.app resolves to this box (DNS-only A record).
+
+s.5chan.app {
+	encode zstd gzip
+	reverse_proxy 127.0.0.1:3924
+}
+
+# Mirror domains: list more hostnames on one block (they share the cert + the
+# same upstream), and add each to the 5chan profile's `hostnames` in
+# lib/clients.js so the server recognises them:
+#
+# s2.5chan.app, s.5chan.eth.limo {
+# 	encode zstd gzip
+# 	reverse_proxy 127.0.0.1:3924
+# }

deploy/Caddyfile.snippet

@@ -0,0 +1,38 @@
+# Cloudflare DNS for `s.5chan.app`
+
+Goal: stop redirecting `s.5chan.app` → `5chan.app`, and instead point it at the
+previewer on the VPS so Caddy can serve link previews.
+
+## Steps (DNS-only A record + Caddy)
+
+1. **Remove the old redirect.** In the `5chan.app` zone → **Rules**, delete the
+   Redirect Rule / Page Rule that sends `s.5chan.app` → `5chan.app`. Also delete
+   any placeholder DNS record for `s` that the redirect relied on.
+
+2. **Add the A record.** Zone → **DNS → Records → Add record**:
+   - Type: `A`
+   - Name: `s`
+   - IPv4 address: `<your VPS IP>`
+   - Proxy status: **DNS only** (grey cloud)
+   - TTL: Auto
+
+   Grey-cloud lets Caddy obtain a Let's Encrypt cert directly and lets social
+   scrapers (Twitter/Telegram/Discord/…) crawl the previews without challenges.
+
+3. **Wait for propagation**, then confirm TLS + a real preview:
+   ```bash
+   curl -sI https://s.5chan.app/health
+   curl -s  https://s.5chan.app/<board>/thread/<cid> | grep -i 'og:'
+   ```
+   The HTML should contain `og:title` / `og:description` and redirect a browser
+   into `https://5chan.app/#/<board>/thread/<cid>`.
+
+4. **Validate the card** with the Twitter/Telegram/Discord link-preview tools.
+
+## Later (optional): put Cloudflare in front
+
+To gain Cloudflare CDN/WAF, flip the A record to **Proxied** (orange) and set
+**SSL/TLS → Overview → Full (strict)**. Because proxied TLS-ALPN renewal is
+blocked, Caddy then needs either a **Cloudflare Origin Certificate** installed,
+or the **DNS-01** challenge via a Cloudflare API token. Keep bot-fight settings
+relaxed for `s.5chan.app` so OG scrapers aren't challenged.