secubox-deb/packages/secubox-billets

billets — micro-blog gateway inter-médias sociaux

Self-hosted micro-blog + social-media gateway. Author-published short posts; a public read feed with comments, emoji reactions and republish share-intents. It ingests links/embeds from social networks (SSRF-guarded oEmbed, sanitized) and lets each billet be re-shared back to them.

Built as a SecuBox module (secubox-billets): FastAPI + aiosqlite (WAL) + Jinja2, served on a Unix socket behind nginx.

Architecture

api/
  asgi.py        runtime entrypoint (uvicorn api.asgi:app) — lifespan opens the DB
  main.py        app factory + public feed / permalink / feeds / oEmbed
  db.py          aiosqlite WAL + numbered .sql migrations
  models.py      Pydantic v2 (strict, size-limited, https-only URLs)
  repo.py        billet/comment/reaction/author queries (keyset pagination)
  ids.py         ULID (time-sortable)
  routes/        admin.py (auth + CRUD + moderation), public.py (react/comment)
  services/      render, sanitize, ssrf, oembed, linkcard, eventlog, revisions,
                 antispam, security, feeds
  templates/  static/  migrations/
  manage.py      CLI: create-author / set-password / seed

Invariants. Every security-relevant action (publish/edit/delete, comment moderation, login) appends to an append-only BLAKE2b hash-chained event_log (services/eventlog, verify_chain). Every billet's content and style are versioned in a Gitea repo (services/revisions, one front-matter .md per billet, full git log --follow history).

Install

Debian package

dpkg -i secubox-billets_*.deb
# postinst creates the secubox user, /var/lib/secubox/billets, the signing
# secret, the venv (pip install requirements.txt), and the nginx vhost.
cd /usr/lib/secubox/billets
sudo -u secubox venv/bin/python -m api.manage create-author admin

Set the public origin so feeds/oEmbed emit absolute URLs — add to the unit: Environment=BILLETS_SITE_URL=https://billets.example.com.

Standalone

sudo deploy/install.sh (idempotent). In SecuBox, billets is fronted by HAProxy (TLS 1.3) → sbxwaf → nginx → the socket.

Configuration (environment)

Var	Default	Purpose
BILLETS_DB	/var/lib/secubox/billets/billets.db	SQLite WAL file
BILLETS_REVISIONS_DIR	/var/lib/secubox/billets/revisions	Gitea revision repo
BILLETS_SECRET_FILE	/etc/secubox/secrets/billets	signing secret (0600 secubox)
BILLETS_SECRET	—	secret override (takes precedence)
BILLETS_SITE_URL	derived from request	absolute origin for feeds/oEmbed
BILLETS_MEDIA_DIR	/var/lib/secubox/billets/media	re-encoded media + embed snapshots
BILLETS_SNAPSHOT_BROWSER	1	set 0 to disable the headless-Chromium capture

Communiqué style + embed snapshot

Each billet has a style: default (feed look) or communique (a poster/affiche layout — ROOT→MESH→MIND side-band, a framed "TRANSMISSION · CANAL PUBLIC" embed, stamp/kicker/slogans/footer). Pick it in the editor.

For communiqué billets with an embed, the module captures a still vignette of the embed (stored like any media file, shown in the poster frame as a click-to-load thumbnail and in the feed as a compact framed image):

1. Headless Chromium (a real full-page screenshot) — OPTIONAL. Enable it with pip install playwright && playwright install chromium (or install the snapshot extra). Any missing package / browser / timeout degrades silently.
2. og:image fallback — the page's og:image fetched through the same SSRF guard (https-only, must resolve to a public IP, redirects re-validated, size-capped). This is the default path when Chromium is not installed, so the feature works fully without a browser.

The capture runs OFF the shared event loop (asyncio.to_thread) and only re-captures when the embed_url changes.

GET /admin/billets/{id}/archive.html (JWT-gated) exports a portable, fully self-contained single .html of a billet in the communiqué layout: CSS inlined, system fonts (no network), media + the embed vignette inlined as data: URIs, and the embed rendered as its snapshot image linking to the original (no live iframe, so it opens offline). Button: "💾 Archive HTML".

To push revisions to Gitea, add an origin remote in the revisions repo as the secubox user (else commits stay local — still a full history).

Backup / restore

SQLite is the single source of truth. Take a consistent snapshot:

sudo -u secubox sqlite3 /var/lib/secubox/billets/billets.db ".backup '/var/backups/billets-$(date +%F).db'"

Restore: stop the service, copy the backup over billets.db (and the -wal/-shm are rebuilt), start again. The Gitea revision repo and /etc/secubox/secrets/billets should be backed up alongside.

Tests

PYTHONPATH=. python -m pytest -q     # from packages/secubox-billets

Covers data layer, feed/pagination, admin auth/CRUD, SSRF + XSS (the critical step), comments/anti-spam, reactions, feeds/oEmbed. pip-audit runs in CI.

Design decisions (documented per the brief)

• aiosqlite (async), not sync sqlite3. As a SecuBox module, billets shares the aggregator's event loop path; a blocking DB call would stall the box. All DB access is awaited off-loop.
• api/ layout + Unix socket, following SecuBox module conventions (rather than the standalone app/ layout).
• Own author auth (argon2id + optional TOTP) kept per spec; SecuBox-auth SSO is a possible v2.
• htmx replaced by a tiny vanilla shim (static/billets.js, CSP script-src 'self'). The reaction endpoint returns an htmx-compatible fragment, so dropping in a vendored htmx.min.js at deploy works unchanged — this avoids an un-fetchable CDN dependency while keeping graceful no-JS degradation.
• Emails hashed (BLAKE2b), not encrypted — never displayed, only used to detect a returning approved commenter (spec allows "chiffré au repos ou hashé").
• oEmbed discovery is same-origin only (Mastodon/PeerTube self-hosted); an unknown host with no same-origin oEmbed link falls back to a local OpenGraph card.