feat: initial bitsocial-previewer

Multi-tenant link-preview + redirect server for Bitsocial clients,
replacing the archived plebbit-previewer. Resolves a client profile by
Host header (5chan -> s.5chan.app, seedit -> s.seedit.app), renders
OpenGraph/Twitter cards via @pkcprotocol/pkc-js getComment, 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,20 @@
+# Copy to .env and adjust for the host.
+
+# Port Caddy proxies s.5chan.app to. Loopback bind keeps it off the public net.
+PORT=3924
+BIND_HOST=127.0.0.1
+
+# ── Protocol (pkc-js) connection — pick ONE approach ─────────────────────────
+#
+# A) Recommended on VPS B: reuse the warm local pkc daemon the seeder runs.
+PKC_RPC_URLS=ws://127.0.0.1:9138
+#
+# B) Or run standalone over the local IPFS node (leave PKC_RPC_URLS empty):
+# IPFS_GATEWAY_URLS=http://127.0.0.1:6473
+# KUBO_RPC_URLS=http://127.0.0.1:50019/api/v0
+# PUBSUB_KUBO_RPC_URLS=http://127.0.0.1:50019/api/v0
+#
+# With neither set, it falls back to public gateways (fine for laptop review,
+# not for production).
+
+DEBUG=bitsocial-previewer:*

.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,16 @@
+# Debian-slim (not alpine): pkc-js pulls in heavy libp2p/native deps that are
+# happiest on glibc, matching the old previewer's node:20 base.
+FROM node:20-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"]

README.md

@@ -0,0 +1,91 @@
+# 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 the successor to the old [`plebbit-previewer`](https://github.com/plebbit/plebbit-previewer)
+(archived). Unlike that one — which forced every link to a single domain — this
+is **multi-tenant**: one running instance serves many clients and many mirror
+domains, picking the right profile from the request's `Host` header.
+
+```
+                      ┌──────────── 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
+(protocol endpoints, port) is inline in [`docker-compose.yml`](docker-compose.yml),
+which uses `network_mode: host` so the previewer reaches the same warm local node
+the seeder uses (`getComment` resolves instantly from pinned 5chan content).
+
+```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.

config.js

@@ -0,0 +1,50 @@
+// 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',
+  pkcOptions: buildPkcOptions(),
+}

deploy/Caddyfile.snippet

@@ -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/cloudflare.md

@@ -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.

docker-compose.yml

@@ -0,0 +1,31 @@
+services:
+  bitsocial-previewer:
+    image: ghcr.io/bitsocialnet/bitsocial-previewer:latest
+    build:
+      context: .
+    container_name: bitsocial-previewer
+    restart: unless-stopped
+
+    # Host networking so the previewer reaches the local node the seeder uses
+    # (127.0.0.1:9138 / :50019 / :6473). BIND_HOST=127.0.0.1 keeps the preview
+    # port private to the host, so only the local Caddy can proxy to it.
+    network_mode: host
+
+    environment:
+      NODE_ENV: production
+      PORT: "3924"
+      BIND_HOST: 127.0.0.1
+      DEBUG: bitsocial-previewer:*
+
+      # Protocol fetch: reuse the warm local pkc daemon (same as the seeder).
+      PKC_RPC_URLS: ws://127.0.0.1:9138
+      # Decoupled alternative — comment out PKC_RPC_URLS and use the local node:
+      # IPFS_GATEWAY_URLS: http://127.0.0.1:6473
+      # KUBO_RPC_URLS: http://127.0.0.1:50019/api/v0
+      # PUBSUB_KUBO_RPC_URLS: http://127.0.0.1:50019/api/v0
+
+    logging:
+      driver: json-file
+      options:
+        max-size: 10m
+        max-file: "5"