MetaAppStore/Apps/MetaReadShared/rationale.md

MetaRead (shared backend) — Rationale

What deviation / exception is being requested

1. metaread-app is publicly routed with no AppShield sidecar. It carries the caddy_* labels itself.
2. metaread-search runs user: 0:0 and publishes host port 4006/tcp (libp2p).
3. The compose top-level name: is metaread, the same project id as the self-contained MetaRead app in this store.

Why it is necessary

1. meta-read has its own authentication: a secp256k1 keypair proven by signing a challenge, with invite-only signup. Its router gates deny-by-default: a route not in open_routes() answers 401. The open set is /health, /api/config, the challenge/token pair, /api/invite/check/:token and /api/image/:cid. That is the "app's own built-in auth" alternative the security checklist accepts. AppShield in front added a second login and an OIDC redirect on every cover fetch, because <img src> cannot carry an Authorization header. It also left the service worker's offline cache at the mercy of a session cookie.
2. libp2p is not HTTP. Caddy cannot proxy it, and remote peers dial the advertised multiaddr directly, so the port must be published and reachable inbound. The app carries the reserved needs-public-ip tag.
3. The two MetaRead variants are alternatives, not companions. They share the project id and the same /DATA/AppData/metaread/ paths, so installing one over the other reuses the same data. Only one may be installed at a time.

Security mitigations in place

• meta-read's signature-challenge login is on by default, and signup is invite-only, so a stranger reaching the public hostname cannot create an account.
• The metaread-search dashboard is behind an AppShield sidecar (ghcr.io/yundera/appshield:2.0.9) with Authelia SSO; only the reader itself uses its own gate.
• metaread-app runs unprivileged as 1000:1000 with a 512 MB hard memory cap and swap disabled.
• The only published port is raw libp2p TCP; no HTTP port is published to the host.
• No user directories are mounted: no /DATA/Documents, /DATA/Downloads, /DATA/Media or /DATA/Gallery.
• cpu_shares on every service; image tags pinned.

Alternatives considered and rejected

• AppShield in front of metaread-app. Two identities for one user, plus the cover and service-worker costs above.
• Bundle a private MetaCore/MetaShare. That is the self-contained MetaRead app. On a box that already runs them, it doubles the memory footprint. It also gives the reader an identity, a User Data Layer and a catalogue separate from MetaWatch's on the same box.
• A distinct project id so both variants coexist. They would fight over the same public hostnames, the same /DATA/AppData/metaread/ paths and host port 4006.

Data protection

My List, Continue Reading, the session key and the invite book persist in /DATA/AppData/metaread/data. The recovered cover blockstore and language prefs persist in /DATA/AppData/metaread/search-data. Both are declared in x-compose-app.folders and archived by Maison on uninstall. Because both MetaRead variants use those paths, switching between them keeps the user's data. The MetaCore and MetaShare state this variant reads belongs to those apps and is archived with them.