Security & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
The Security & Authentication system in KnowledgeVault is a multi-layered framework designed to protect the RAG (Retrieval-Augmented Generation) pipeline, user data, and system configurations. It employs JWT-based authentication with httpOnly refresh cookies, Cross-Site Request Forgery (CSRF) protection, and Role-Based Access Control (RBAC) to manage multi-tenant organization and vault permissions.
Beyond standard authentication, the system implements specialized security boundaries for LLM interactions. This includes structural isolation of untrusted user content using XML tags to prevent prompt injection attacks and strict enforcement of message roles at the API layer.
Sources: README.md:14-25, specs/security-ux-hardening/SPEC.md:7-14
Authentication Architecture
KnowledgeVault utilizes a dual-token JWT system for session management. Access tokens are short-lived and used for authorizing API requests, while refresh tokens are stored in httpOnly cookies to provide secure, persistent sessions without exposing long-term credentials to client-side scripts.
Token Lifecycle & Refresh
When a user logs in, the server issues an access token and sets a refresh token in a secure cookie. The frontend apiClient automatically attaches the JWT to the Authorization header. If an access token expires (returning a 401 status), the frontend interceptor attempts a silent refresh.
The system ensures that only one refresh call is in flight at a time to prevent race conditions during token rotation.
Sources: frontend/src/lib/api.ts:13-25, frontend/src/lib/api.ts:122-155, qa-report.md:45-55
Cross-Site Request Forgery (CSRF) Protection
The system implements a robust CSRF defense mechanism for all mutating requests (POST, PUT, PATCH, DELETE).
CSRF Implementation Details
- Token Storage: The server sets a non-httpOnly cookie (
X-CSRF-Token). - Validation: Mutating requests must include the
X-CSRF-Tokenheader. - Frontend Interceptor: The
attachCsrfInterceptorin the frontend API library automatically extracts the token from cookies and injects it into request headers. - Error Recovery: If a 403 CSRF error occurs, the client clears the cached token and retries the request once after fetching a fresh token.
Sources: frontend/src/lib/api.ts:27-55, frontend/src/lib/api.ts:88-115
Role-Based Access Control (RBAC)
KnowledgeVault defines four primary roles with hierarchical permissions. Access is governed by these roles and specific vault-level permissions.
| Role | Description | Permissions |
|---|---|---|
| Superadmin | System Owner | Full access, user management, organization CRUD, vault deletion. |
| Admin | Manager | User role management (activate/deactivate), organization oversight. |
| Member | Standard User | Document management, RAG chat, search, and memory operations within assigned vaults. |
| Viewer | Read-only User | Restricted to chat and search; cannot upload or modify data. |
Sources: README.md:465-475, backend/app/api/routes/wiki.py:55-65
Security Policies
Access to resources like Vaults or Wiki pages is gated by policy evaluators:
_require_vault_read: Ensures the user has at least "read" permissions for a specific vault._require_vault_write: Required for mutating actions like document uploads or wiki edits.
Sources: backend/app/api/routes/wiki.py:68-76, qa-report.md:145-155
Prompt Injection Defense (CWE-1333)
To prevent users or malicious documents from overriding LLM system instructions, the project implements "Structural Isolation."
XML Content Boundaries
All untrusted data is wrapped in specific XML tags before being injected into the LLM prompt. This establishes a boundary that the system prompt instructs the LLM to treat as data only.
| Tag | Content Type | Location of Injection |
|---|---|---|
<document> | Retrieved document text | PromptBuilderService.format_chunk() |
<memory> | User memory records | PromptBuilderService.build_messages() |
<user_query> | Raw search queries | QueryTransformer.transform() |
<user_message> | Chat history | chat.py title generation |
Security Boundary Directive
The system prompt includes a dedicated SECURITY BOUNDARY section. This directive explicitly lists the trusted XML tags and commands the LLM to ignore any instructions found within those tags.
Sources: specs/security-ux-hardening/SPEC.md:35-55, specs/security-ux-hardening/SPEC.md:65-75
File Upload Security
The system employs magic byte validation to prevent file extension spoofing during document ingestion.
Text-based formats like .txt, .md, and .csv are exempt from magic byte checks as they lack fixed binary headers.
Sources: specs/security-ux-hardening/SPEC.md:82-95
Known Security Hardening Targets
Based on the recent QA audit, several security gaps are identified for remediation:
- Dependency Management: Critical missing auth dependencies (PyJWT, bcrypt, passlib) in
requirements.txt. - Infrastructure Security: Docker containers currently run as root; needs migration to a non-privileged user.
- Granular Authorization: Settings endpoints and internal connection tests lack strict admin-only guards.
- Data Persistence: Access tokens are currently persisted in
localStorage, which is a target for XSS exfiltration.
Sources: qa-report.md:15-40, qa-report.md:75-85
Conclusion
The Security & Authentication system provides a robust baseline using modern JWT and CSRF patterns, complemented by innovative prompt injection defenses. While the application establishes strong boundaries between user data and LLM logic, ongoing hardening is required to address infrastructure-level risks and further tighten the granularity of administrative authorization.