Security & Operations
Relevant source files
The following files were used as context for generating this wiki page:PRKS is a single-user, local-first research application. It operates without a built-in authentication layer and relies on host-level isolation for security. The system prioritizes data durability and privacy through metadata-only logging and controlled filesystem access.
Sources: README.md:65-68, SECURITY.md:54-58
Authentication and Network Security
PRKS does not include application-level authentication. You must not expose the server to untrusted networks or the public internet without an external access-control layer.
Sources: README.md:65-68, SECURITY.md:54-58
Deployment Boundaries
The server binds to the loopback address 127.0.0.1 by default. This configuration limits access to the local machine. Docker Compose publishes the container port to the host loopback only (127.0.0.1:8080:8080). You must pass an explicit host via --host 0.0.0.0 to listen on other local interfaces.
Sources: README.md:51-63, README.md:83-88
Admission and Validation
The system validates the Host and Origin headers for all incoming requests. It refuses requests that bypass documented deployment boundaries or attempt server-side request forgery (SSRF).
Sources: SECURITY.md:38-42, backend/AGENTS.md:144-149
The request admission flow enforces deployment boundaries before reaching application logic.
Sources: backend/AGENTS.md:144-149, SECURITY.md:38-42
Data Privacy and Logging
PRKS enforces a metadata-only logging policy to prevent the exposure of private research content.
Logging Restrictions
Logs never contain user content, request bodies, or library metadata. The system uses backend/log_safety.py to normalize routes and identifiers.
| Data Category | Log Status | Description |
|---|---|---|
| User Content | Banned | Research notes, titles, and annotations. |
| Filesystem Paths | Banned | Absolute paths and specific filenames. |
| Request Details | Banned | Query strings, bodies, and user URLs. |
| Tracebacks | Restricted | Must use privacy-safe formatters. |
| API Metadata | Allowed | Normalized route names and status codes. |
Sources: backend/AGENTS.md:46-51, SECURITY.md:47-49
Input Sanitization and Safety
PRKS processes untrusted input, such as Markdown and remote images, through restricted boundaries.
Markdown Sanitization
The frontend uses DOMPurify to sanitize Markdown previews. It strips active content, including <script>, <iframe>, and event handlers like onclick. It also enforces a strict link policy, allowing only safe protocols like http, https, mailto, and internal hashes.
Sources: tests/browser/markdown_security.html:105-156
Remote Resource Handling
Person profile images must use direct public HTTP/HTTPS URLs. The server does not follow redirects. It refuses private, local, or link-local targets to prevent SSRF. The download process is size-bounded and time-bounded.
Sources: README.md:131-137, SECURITY.md:41
Storage Operations and Durability
The system maintains an exclusive lock on the storage root to prevent data corruption from concurrent processes.
Sources: README.md:125-129
Storage Root Validation
Every storage root contains a prks-root.json marker. The server process holds an OS-level lock on .prks-maintenance/root.lock. A second process attempting to open the same root exits with an error.
Sources: README.md:118-129, backend/AGENTS.md:58-64
Post-Delete Cleanup Recovery
Deleting a work commits the database row first and cleans the filesystem afterward. This process uses a durable claim record to prevent orphaned files if a crash occurs.
The cleanup recovery model ensures managed bytes are eventually deleted even after process failures.
Sources: backend/AGENTS.md:100-120
Filesystem Containment
The system uses safe_pdf_path_under_dir() to ensure all file operations stay within the designated storage root. It refuses path traversal attempts and symlinks inside the root.
Sources: README.md:121-124, backend/AGENTS.md:130-131
Backup and Restore Operations
Backups contain canonical library data and are verifiable. Derived data like search indexes and thumbnails are excluded from archives.
Restore Process
- Validation: The system completes restore validation before modifying live state.
- Atomicity: Restore operations use a journal. A crash before the final commit restores the previous library.
- Durability: The system uses
fsyncfor renames and file replacements during the restore phase.
Sources: backend/AGENTS.md:73-88
Summary
PRKS secures research data by defaulting to loopback networking and enforcing metadata-only logging. Exclusive storage locks and durable cleanup recovery prevent data corruption and orphaned files. All untrusted inputs undergo strict sanitization to protect the user environment from script injection and SSRF.