Sharing & Public Publishing
Relevant source files
The following files were used as context for generating this wiki page:
Archivum provides a multi-layered system for distributing knowledge outside of the private home network. This includes granular token-gated share links for individual pages and query results, as well as a global "Public Wiki" mode for world-readable access. The system is designed to provide secure, read-only access to external parties while shielding the administrative and editing interfaces behind authentication and network layers. Sources: archivum-prd-v1.0.md:522-540, README.md:162-171
The architecture distinguishes between local authenticated access (via direct LAN or Tailscale) and external public access. External sharing is typically facilitated through a Cloudflare Tunnel that exposes a specific share subdomain, ensuring that only read-only endpoints are reachable by the general public. Sources: archivum-prd-v1.0.md:526-532, README.md:118-132
Share Link Mechanisms
Archivum supports two primary types of token-gated sharing: Page Share Links and Query Result Permalinks. These links use unguessable 32-byte URL-safe base64 tokens stored in a dedicated database table. Sources: archivum-prd-v1.0.md:542-550, apps/backend/archivum/db/sqlite.py:102-111
Page Share Links
A user can generate a unique URL for a specific wiki page. This link renders the page content in a read-only environment without the full application UI. The system supports optional expiry (24h, 7d, 30d, or never) and manual revocation. Sources: archivum-prd-v1.0.md:562-564, apps/frontend/src/api.ts:168-175
Query Result Links
This feature allows users to share the result of an AI-powered query. Unlike page links, query shares capture a "frozen" snapshot of the question, answer, and citations at the time of creation. This ensures that the shared content remains consistent even if the underlying wiki pages are modified later. Sources: archivum-prd-v1.0.md:565-566, apps/frontend/src/api.ts:177-184
Share Link Data Model
The share_links table in SQLite manages the lifecycle of these external links.
| Field | Type | Description |
|---|---|---|
id | INTEGER | Primary key |
wiki_id | TEXT | Identifier for multi-tenant support |
token | TEXT | Unique 32-byte URL-safe base64 token |
type | TEXT | The type of shared content: page or query |
target_id | TEXT | The slug of the page or the identifier for the query |
created_at | TEXT | Timestamp of link generation |
expires_at | TEXT | Optional ISO8601 expiry timestamp |
revoked | INTEGER | Boolean flag (0/1) for manual invalidation |
Sources: apps/backend/archivum/db/sqlite.py:102-111, archivum-prd-v1.0.md:577-582
Public Wiki Mode
The Public Wiki mode allows the owner to make the entire knowledge base world-readable. This is toggled via the PUBLIC_WIKI_ENABLED environment variable. When active, all pages are indexed and accessible at the /public path and via the /api/public/pages endpoint. Sources: README.md:92-92, apps/frontend/src/api.ts:208-219
Read-Only Rendering
The PublicWikiPage.tsx component handles the display of public pages. It utilizes a custom markdown renderer and enforces security through DOMPurify to prevent XSS attacks in the rendered output. Sources: apps/frontend/src/pages/PublicWikiPage.tsx:5-24, apps/frontend/src/pages/PublicWikiPage.tsx:61-68
The diagram shows the logic flow for determining how content is served to external, unauthenticated users. Sources: archivum-prd-v1.0.md:586-588, apps/frontend/src/pages/PublicWikiPage.tsx:40-68
Collaborative Sharing (Wiki Invites)
Beyond public links, Archivum supports inviting specific users with defined roles. This is managed through the invite_tokens system. Sources: archivum-prd-v1.0.md:567-570, apps/backend/archivum/db/sqlite.py:133-142
- Viewer Invite: Grants a guest user read-only access to the entire wiki after they set a password.
- Collaborator Invite: Grants a guest user read-write access (editing pages) but restricts administrative functions like ingest or system settings.
Sources: archivum-prd-v1.0.md:567-570, apps/backend/archivum/db/sqlite.py:596-621
Invite Token Lifecycle
The following sequence illustrates the process of inviting a collaborator:
Content Export
For distribution outside the web platform, Archivum provides export functionality for individual pages or collections. Sources: archivum-prd-v1.0.md:567-575, apps/backend/archivum/api/pages.py:204-210
- PDF Export: Server-side rendering of markdown content via WeasyPrint. Accessible via
GET /api/export?slug=...&format=pdf. - HTML Export: Generates a self-contained HTML bundle with internal wikilinks resolved to anchors. Accessible via
GET /api/export?slug=...&format=html.
Sources: archivum-prd-v1.0.md:567-575, apps/frontend/src/pages/WikiPage.tsx:244-250
Security Infrastructure
The sharing system relies on a "Remote Access Model" to ensure the main application remains secure while allowing public visibility. Sources: archivum-prd-v1.0.md:526-532
- Network Layering: The primary UI and API are served over LAN or encrypted Tailscale networks. Public links are routed through a Cloudflare Tunnel.
- Scope Limitation: The Cloudflare Tunnel subdomain (e.g.,
share.archivumapp.com) only routes traffic to specific read-only endpoints (/share/*,/public/*,/api/share/*). All other administrative paths return a 404 on this subdomain. - Markdown Sanitization: Both server-side (
bleach) and client-side (DOMPurify) sanitization are employed to prevent stored XSS from malicious or agent-generated content. - Token Format: Uses 32-byte URL-safe base64 tokens to prevent brute-forcing of share links.
Sources: archivum-prd-v1.0.md:535-540, README.md:162-171, apps/frontend/src/pages/PublicWikiPage.tsx:61-68, apps/backend/archivum/db/sqlite.py:105
Conclusion
The "Sharing & Public Publishing" feature set transforms Archivum from a private repository into a versatile knowledge distribution platform. By leveraging tokenized URLs for specific pages, a toggleable public wiki mode, and professional export formats, it allows users to share synthesized knowledge while maintaining the security of the underlying home-server infrastructure. The combination of read-only renderers and Cloudflare Tunnel integration ensures that shared content is accessible without compromising the integrity of the private wiki. Sources: archivum-prd-v1.0.md:522-540, README.md:162-171