Skip to content

Security & privacy

Proton Faces is privacy-first by design: no telemetry, no cloud APIs, and the only network calls go to Proton's servers via the bridge container. The one opt-in exception is metrics export to a collector you run: operational numbers only, with no photo, person or user data. All ML runs locally through ONNX Runtime on CPU.

What's on disk

Path Content Sensitivity
DATA_DIR/thumbs/ 512px WebP thumbnails Low. These are downscaled previews; not full-res.
DATA_DIR/index.sqlite3 The local index (photos, faces, clips, people, users, tokens) Medium. Photo metadata + your local edits + bcrypt password hashes + bearer tokens (random hex).
DATA_DIR/crops/ Face-crop JPEGs ({face_id}.jpg) Low. Cached subset of the thumbs.
DATA_DIR/_backups/ index-<UTC-stamp>.sqlite3 snapshots Same as the live DB.
DATA_DIR/gps_sha1_cache.json sha1 → (lat, lng) map Low.
DATA_DIR/admin_config.json Auto-backup schedule None.
DATA_DIR/models/ InsightFace buffalo_l + CLIP ViT-B/32 None. Public ML model weights.
credentials/auth-session.json Your Proton session High. Treat like a password.

Nothing else is written to disk. No temporary caches, no logs of photo content, no analytics files.

What's NOT on disk

  • Full-resolution photos. The bridge downloads them on demand when you click View full resolution; the bytes stream through the FastAPI response and are discarded by the client. The fullres loop downloads HEIC / videos once, generates a 512px thumbnail, and discards the full-res bytes immediately.
  • Uploaded face-search images. The face-search-by-example endpoint reads the multipart upload into memory, embeds it, and discards it. The image is never written to disk or sent to Proton.
  • Telemetry, analytics, or any outbound calls other than Proton. There are no analytics SDKs, no Sentry/Datadog calls, no remote logs.

Network surface

From To What
Browser → app:8080 localhost / your reverse proxy HTTPS / JSON / static files
app:8080 → proton-bridge:8090 compose internal network timeline, timeline_ids, nodes, albums, thumbnails, photo/{uid}/full
app:8080 → indexer:8091 compose internal network (no host port mapping) /status (live state for the footer)
proton-bridge → Proton Drive HTTPS to drive-api.proton.me Auth + timeline + thumbnail fetch (read-only)

The bridge's only outbound destination is Proton's API. Nothing else leaves the host.

If you put a reverse proxy in front of :8080 (Traefik, Caddy, nginx), it's your responsibility to terminate TLS and gate the public side.

The bridge is read-only

proton-bridge is built inside the Proton Drive SDK monorepo and pins a specific release tag. It exposes only GET /timeline, POST /nodes, GET /albums, POST /thumbnails, GET /photo/{uid}/full, GET /health.

There is no POST/PUT/DELETE for write operations. There is no upload, no delete, no move. The session file is mounted writable (the SDK rewrites tokens on refresh) but only into the bridge container — the app and indexer containers have no path to it. The data dir is shared with the indexer for thumbnail caching only — not for write-back.

Multi-user auth

Proton doesn't publish an OAuth/OIDC provider, so each family member gets a local account:

  • Username + bcrypt password. Cost 12, ~250 ms per hash on a modern CPU.
  • Opaque bearer tokens — 32 random bytes, hex-encoded. Not JWT.
  • Access tokens — TTL AUTH_ACCESS_TTL (default 8 h).
  • Refresh tokens — TTL AUTH_REFRESH_TTL (default 30 d).
  • Refresh rotation with reuse detection. Every /api/auth/refresh retires the presented refresh token and issues a new pair. A retired token never works again. If one is presented more than 10 s after it was retired, every token from that login (access and refresh, on that device) is revoked: a stolen refresh token cannot be rotated forward quietly. Inside the 10 s window the request is simply refused, so two tabs refreshing at the same moment do not end each other's session. Other devices' logins are unaffected.
  • Signed media URLs can be revoked. The ?sig=&exp= links for thumbnails and full-size media are valid for up to an hour, but their signature also covers a server-side epoch. Disabling or deleting a user, any password change, or revoking a user's sessions bumps it, and every outstanding signed link stops working (each API worker notices within 15 s). Open pages show broken thumbnails until they reload. A plain logout does not bump the epoch.
  • Tokens are stored in auth_tokens (SQLite). The short-lived access token is kept in localStorage under pf.auth; the refresh token is held in the HttpOnly SameSite=Strict pf_refresh cookie (FP-1) so page-level XSS cannot exfiltrate it. The cookie's Secure flag is controlled by AUTH_COOKIE_SECURE.
  • Failed username probes run a dummy bcrypt hash to keep wall time comparable to a real failure (defense against username enumeration).
  • Optional per-user 2FA (TOTP, authenticator app). Each user can enroll from the account menu (click your username, bottom-left → Enable 2FA; QR code or manual secret); a 6-digit code is then required at every login. The TOTP secret is encrypted at rest (AES-256-GCM, key derived from SIGNING_SECRET), and the pending-login token expires after AUTH_2FA_PENDING_TTL (default 5 minutes). Recovery paths: an admin can force-disable 2FA for a user from the UI, or anyone with host access can run python main.py --disable-2fa <username> from the CLI (e.g. when the only admin is locked out).
  • Password reset (--reset-password) revokes every active token for that user.

Roles

Role Can browse Can edit metadata Admin area
read ✅ ❌ ❌
write ✅ ✅ ❌
admin ✅ ✅ ✅

A write user inherits everything a read user can do. An admin inherits everything a write user can do.

What can be edited by write+ users

  • Tag, untag, archive, unarchive, hide, unhide, favorite, unfavorite any photo.
  • Rename a person / merge two people.
  • Assign a face to a person / create a new named person.
  • Unassign a face.
  • Run face search by example.

What only admin can do

  • Create / edit / delete users.
  • Reset another user's password.
  • Sign another user out of every device.
  • Read the admin overview, run health checks.
  • Create / delete / prune backups, change the auto-backup schedule.

Bearer token validation

Every API request (except the auth-free ones listed in the API reference) requires Authorization: Bearer <token>. The server:

  1. Looks up the token in auth_tokens.
  2. Checks it's an access token (refresh tokens only work at /api/auth/refresh).
  3. Checks it's not expired.
  4. Checks the user isn't disabled.
  5. Returns a 401 otherwise — with a WWW-Authenticate: Bearer header.

Access tokens are not rotated; one stays valid until expiry or explicit revocation (POST /api/auth/logout, POST /api/admin/users/{id}/logout, a password change, or reuse detection on its refresh token — see above).

CORS / CSRF

There is no CORS layer in the app — the web UI is served from the same origin as the API. If you put a reverse proxy in front, configure it to not add CORS headers; the same-origin model is intentional.

Security headers

The app ships a SecurityHeadersMiddleware (app/src/security_headers.py) that adds defense-in-depth headers to every response (HTML, JSON and binary alike):

  • Content-Security-Policy — default-src 'self', with img-src allowing data:/blob: and OSM tiles, media-src allowing blob:, script-src/style-src allowing 'unsafe-inline' (the SPA is one inline-script file), connect-src 'self', object-src 'none', base-uri 'self', form-action 'self' and frame-ancestors 'none'. Leaflet is vendored under static/vendor, so no CDN origin is allow-listed. Tightening script-src to a nonce or external file is a follow-up.
  • X-Content-Type-Options: nosniff — no MIME sniffing.
  • X-Frame-Options: DENY — clickjacking protection (belt-and-braces with frame-ancestors).
  • Referrer-Policy: no-referrer — no referrer leakage anywhere.
  • Permissions-Policy — camera, microphone, geolocation, payment and USB are off.
  • Strict-Transport-Security (1 year, subdomains) — emitted only when AUTH_COOKIE_SECURE=1, i.e. when the operator declares the app is served over TLS.

If you run a reverse proxy in front, its own security headers (see SECURITY_HARDENING.md §9) are additive; the app-level headers are harmless duplicates.

Reverse-proxy checklist

The app never terminates TLS itself, so the proxy decides most of the transport posture. For a production install:

  • Route the app on the proxy's HTTPS entrypoint and redirect plain HTTP to it. Leaving the router on the :80 entrypoint (for example because ACME challenges use it) serves the login form and the refresh cookie in clear text to anyone who reaches port 80 with the right Host header.
  • Set AUTH_COOKIE_SECURE=1 so the refresh cookie is only ever sent over HTTPS and the app emits HSTS.
  • Set TRUSTED_PROXY_IPS to the proxy's network (e.g. the compose subnet) so X-Forwarded-For is honoured and the login limiter keys on the real client, not on the proxy. Without it every request looks like it comes from one address and the per-IP layer throttles everyone behind the proxy together.
  • The login limiter runs in-app (5 failures per user+IP, a per-IP budget, and a concurrency gate on bcrypt), so a proxy rate-limit middleware is optional defence-in-depth rather than a requirement.

Threat model — what you should worry about

Threat Mitigation
Someone reads your disk The DB has bcrypt password hashes + opaque bearer tokens. Photos aren't on disk; only thumbs. Revoke all tokens + change passwords if you suspect compromise.
Someone sniffs your network All traffic to Proton is TLS. The compose-internal traffic is plaintext HTTP but on a private network. Put a TLS-terminating reverse proxy in front of :8080 for remote access.
Someone accesses localhost:8080 while you're away Bearer tokens are required for every API endpoint — including the binary media endpoints (/thumb, /full, /cover, /crop), which additionally accept short-lived signed URLs from /api/sign. These are world-readable only when you explicitly set DEMO_ALLOW_PUBLIC_THUMBS=1. The ? overlay shows who's signed in. Sign out from another device via the admin Users tab.
Bug in the bridge The bridge is read-only by construction; even a bug can't write back to Proton. Pin the SDK tag in your fork if you're paranoid.
Malicious auth-session.json Only the bridge reads it. It authenticates to Proton and streams the encrypted timeline — it can't be used to delete or upload. Revoke the session on Proton's website to invalidate.
Compromised or broken image publish compose.yml defaults to :latest (highest release; :edge tracks main), which is mutable. Images are only published after the test suite passes on the built commit. Pin images to a versioned tag or a content digest (image@sha256:...) for an immutable deploy — see Pinning images to a version or digest.

What we don't do

  • We do not upload anything to Proton (read-only bridge).
  • We do not upload anything to any third party (no telemetry; optional metrics go only to the collector you configure).
  • We do not store full-resolution photos.
  • We do not log photo bytes to disk (the processed_at field is the only timestamp).
  • We do not require GPU access.
  • We do not require any cloud account other than your Proton Drive session.

Reporting a vulnerability

Open an issue on GitHub, or email the maintainer (see the GitHub profile). Please don't disclose security issues publicly until a fix is out.


Next: FAQ answers the common questions.