Authentication & Security Model
Relevant source files
The following files were used as context for generating this wiki page:
Archivum employs a multi-layered security architecture designed for self-hosted environments. The model prioritizes data sovereignty and local-first operations while providing secure pathways for remote access, AI agent interaction, and public content sharing. It transitions from a single-user "Owner" model in v1 to a multi-tenant architecture by utilizing consistent wiki_id identifiers across all data layers.
Sources: archivum-prd-v1.0.md:521-525, README.md:167-175
Network & Access Layers
The security model utilizes a "Remote Access Model" that avoids direct public port exposure. Traffic is managed through three primary layers:
- LAN Direct: Full authenticated access for the owner on the local home network.
- Tailscale Network: A VPN layer providing full access to the UI, API, and MCP server for the owner and invited guests without port forwarding.
- Cloudflare Tunnel: Used specifically for public share links. This layer is read-only, token-gated, and restricted to a single subdomain.
Sources: archivum-prd-v1.0.md:468-475, README.md:124-130
Connection Flow
The following diagram illustrates how different users interact with Archivum layers:
Caddy acts as the central reverse proxy, handling TLS termination and routing traffic to the internal services.
Sources: archivum-prd-v1.0.md:470-485, README.md:144-150
Identity & Authentication
Archivum supports several authentication methods tailored to different access requirements.
Authentication Methods
| Method | Target Audience | Implementation |
|---|---|---|
| Password Login | Owner | Minimum 12 characters, hashed with bcrypt (cost factor 12). |
| Invite Token | Guests | Signed link allowing guests to set username/password. |
| Share Token | Public | 32-byte URL-safe base64 unguessable tokens. |
| API/MCP Key | Agents/CLI | Bearer token (MCP_API_KEY) for programmatic access. |
Sources: archivum-prd-v1.0.md:493-500, README.md:65-72, apps/backend/archivum/mcp/server.py:38-42
Session Management
User sessions are managed via JSON Web Tokens (JWT). These are stored in httpOnly, SameSite=Strict cookies to mitigate XSS-based token theft. Tokens follow a dual-lifecycle:
- Short-lived JWTs: 15-minute expiry.
- Refresh Tokens: 7-day expiry.
Sources: archivum-prd-v1.0.md:502-504
Authorization & Permissions
The system defines four distinct permission levels to control access to the wiki and management features.
| Role | Read | Write/Edit | Ingest | Admin/Settings |
|---|---|---|---|---|
| Owner | Yes | Yes | Yes | Yes |
| Collaborator | Yes | Yes | No | No |
| Viewer | Yes | No | No | No |
| Share Link | Target Only | No | No | No |
Sources: archivum-prd-v1.0.md:508-517
The backend enforces these roles using FastAPI dependencies such as require_writer for mutating operations.
Sources: apps/backend/archivum/api/pages.py:195-200
Content Security & Hardening
Markdown Sanitization
To prevent Cross-Site Scripting (XSS), Archivum implements strict markdown sanitization on both the server and client.
- Server-side: The
sanitize_markdownfunction is applied before storing user-submitted or LLM-generated content in the database or writing to disk. - Client-side: The frontend uses
DOMPurifyto sanitize HTML rendered from markdown, specifically allowing a restricted set of attributes (e.g.,class,href,target).
Sources: apps/backend/archivum/api/pages.py:237-238, apps/frontend/src/pages/PublicWikiPage.tsx:55-58, archivum-prd-v1.0.md:535-537
Service Hardening
The deployment environment is hardened through several infrastructure-level controls:
- Non-root Containers: All Docker services run as non-root users.
- Database Isolation: Qdrant and Neo4j/Kuzu ports are not exposed to the host by default; they are only reachable within the internal Docker bridge network.
- Read-only Volumes: The
/rawsource directory is mounted asread-onlyto all services except the ingest pipeline to prevent accidental overwrites. - CSRF Protection: Mutating requests require CSRF tokens alongside
SameSite=Strictcookies.
Sources: archivum-prd-v1.0.md:542-552, README.md:154-159
Public Sharing Implementation
Sharing is handled by a dedicated table in SQLite, generating unguessable tokens. Publicly shared pages are served by a lightweight read-only renderer that lacks access to editor or administrative endpoints.
Summary
Archivum's security model centers on the isolation of sensitive write-operations while enabling flexible read-access through Tailscale and tokenized sharing. By enforcing strict sanitization and local-first data storage, the system ensures that the knowledge base remains secure against both external threats and internal corruption during automated agent activities.