ADR 0004: v1 Worker Security and Media Access
Status: proposed Date: 2026-05-10
Context
Memories uses worker processes for long-running media work such as preview generation, metadata extraction, face detection, clustering, OCR, and export. Workers may run on the same host or another operator-controlled machine, but the Core API remains authoritative for authorization, job leases, result acceptance, and metadata state.
Worker media access is privacy-sensitive because jobs may require reading original family media. v1 must support useful self-hosted operation without pretending to solve hostile public-internet or untrusted-compute security prematurely.
Options Considered
| Option | Summary | Benefits | Costs / Risks |
|---|---|---|---|
| A | Core API media download only | Strongest per-job enforcement and auditability | Less efficient for same-host preview/video workloads; more Core API bandwidth |
| B | Read-only filesystem mounts only | Simple and fast for Docker Compose | Not a hard per-job privacy boundary; actual file reads are not observable by Core API |
| C | Hybrid access modes with explicit trust boundary | Efficient local path plus enforceable remote path | Requires documenting the difference and modeling media grants |
Decision
Choose Option C: hybrid access modes with explicit trust boundary.
v1 supports private LAN, localhost, VPN, or private overlay self-hosted deployments. Reverse proxies may provide TLS/routing, but hostile public internet exposure is not the v1 security baseline.
Workers authenticate with registered, scoped, revocable Worker Credentials separate from user API/CLI credentials. Worker credentials are scoped by allowed job capabilities and media access modes. A worker credential alone does not allow arbitrary media downloads, library listing, metadata mutation, job creation, direct database access, or stored object mutation.
Worker media reads require:
- An active job lease.
- A job-scoped media access grant.
- A media input matching the job's media item, stored object, input version, worker credential, and expiration.
Same-host workers may use read-only library/stored-objects mounts as trusted infrastructure. The mount must not include library/ root or upload-staging, and workers never receive write access to stored original bytes. This mode is a performance optimization, not a hard per-job privacy boundary.
Remote workers, or deployments requiring enforceable per-job media access, use Core API worker media download endpoints bound to the active job lease.
Worker result and artifact handling is governed by ADR 0007: workers submit candidate results and job-scoped temporary artifacts through the Core API; Core API validates, accepts, and promotes final derived artifacts and authoritative records.
Consequences
- The Core API stays authoritative for job assignment, media grants, result acceptance, and visible failure state.
- Self-hosted Docker Compose workers remain efficient and simple.
- The privacy limitation of read-only mounts is explicit: Core API can audit issued grants, not actual operating-system file reads.
- Stronger per-job access is available through Core API download mode without requiring every local worker to stream through the API.
- Worker credentials become first-class operational objects that must be created, revoked, expired, backed up, and audited.
Audit And Processing Issues
Core API records audit events or equivalent inspectable records for worker credential lifecycle, job claim, heartbeat denial, media grant issuance, media download success/failure, result submission, result acceptance/rejection, unauthorized media access, repeated worker failures, and lease expiry.
Processing issues remain the user/operator-facing surface for actionable failures such as missing originals, checksum mismatch, unsupported codecs, invalid results, repeated worker crashes, and media access failures.
Deferred
v1 defers public-internet hardening as a baseline, untrusted third-party workers, public worker registration, per-owner/per-group worker allowlists, mTLS, OIDC/OAuth/2FA, advanced audit retention UI, SIEM export, object-storage signed URLs, GPU scheduling, Kubernetes orchestration, dynamic per-job bind mounts, and proof of actual file-read behavior for mounted workers.
Revisit Triggers
Revisit this decision when Memories supports public internet exposure, untrusted workers, object storage, remote GPU workers, multi-node orchestration, advanced audit/compliance requirements, per-owner worker policies, or public/guest sharing.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference