docs(vault): comprehensive update for v0.14.0 security hardening

bradleygauthier · bradleygauthier · commit aed486851183 · 2026-04-06T22:34:35.000-05:00
8 docs updated to cover all v0.14.0 changes:

- security.md: ReDoS protection, Unicode NFC, path traversal, CLI
  error sanitization, timeout cancellation, FastAPI validation bounds
- multi-tenancy.md: tenant lock enforcement behavior, atomic quota
  check mechanism (no TOCTOU)
- plugins.md: manifest.json now required by default, generation
  example, security rules for verification
- fastapi.md: limit/offset/content validation bounds, response
  caching section with TTL docs
- membrane.md: 500KB content limit for regex scanning
- api-reference.md: version bump, constructor behavior docs
- architecture.md: security architecture diagram, config field updates
- cli.md: error sanitization note with structured codes
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -1,6 +1,6 @@
 # API Reference
 
-Complete Python SDK for qp-vault v0.13.0.
+Complete Python SDK for qp-vault v0.14.0.
 
 ## Constructor
 
@@ -20,7 +20,11 @@ Vault(
 )
 ```
 
-<!-- VERIFIED: vault.py:132-145 -->
+When `tenant_id` is set, the vault enforces tenant isolation: operations auto-inject the locked tenant, and operations with a mismatched `tenant_id` raise `VaultError`.
+
+When `role` is set, all operations are checked against the RBAC permission matrix. Operations exceeding the role's permissions raise `VaultError` with code `VAULT_700`.
+
+<!-- VERIFIED: vault.py:132-145, 257-277 — constructor + _resolve_tenant -->
 
 ### Factory Methods
 
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -269,14 +269,34 @@ config = VaultConfig(
 vault = Vault("./knowledge", config=config)
 ```
 
-Additional config fields added in v0.6-v0.13:
+Additional config fields added in v0.6-v0.14:
 
 ```python
 config = VaultConfig(
-    max_resources_per_tenant=1000,    # Per-tenant quota (v0.11)
-    query_timeout_ms=30000,           # 30s query timeout (v0.13)
-    health_cache_ttl_seconds=30,      # Cache health responses (v0.13)
+    max_resources_per_tenant=1000,    # Per-tenant quota, atomic count enforcement (v0.11)
+    query_timeout_ms=30000,           # Query timeout with task cancellation (v0.14)
+    health_cache_ttl_seconds=30,      # TTL cache for health/status responses (v0.14)
 )
 ```
 
 <!-- VERIFIED: config.py:18-86 — VaultConfig fields and defaults -->
+
+## Security Architecture (v0.14.0)
+
+```
++-------------------------------------------------------------------+
+|  TENANT ISOLATION  _resolve_tenant: lock, auto-inject, reject     |
++-------------------------------------------------------------------+
+|  RBAC              _check_permission: 30+ operations gated        |
++-------------------------------------------------------------------+
+|  INPUT VALIDATION  Unicode NFC, path traversal, null bytes, limits|
++-------------------------------------------------------------------+
+|  MEMBRANE          Innate scan (500KB regex) + Release gate       |
++-------------------------------------------------------------------+
+|  TIMEOUT           _with_timeout: asyncio cancel + cleanup        |
++-------------------------------------------------------------------+
+|  AUDIT             VaultEvent for every mutation + Capsule chain   |
++-------------------------------------------------------------------+
+```
+
+<!-- VERIFIED: vault.py:215-277 — permission, tenant, timeout methods -->
diff --git a/docs/cli.md b/docs/cli.md
@@ -6,6 +6,10 @@ The `vault` CLI provides 15 commands for managing governed knowledge stores.
 pip install qp-vault[cli]
 ```
 
+Error messages display structured vault error codes (e.g., `[VAULT_300] Invalid lifecycle transition`) without exposing internal paths, SQL, or stack traces.
+
+<!-- VERIFIED: cli/main.py:28-35 — _safe_error_message -->
+
 ## Commands
 
 ### vault init
diff --git a/docs/fastapi.md b/docs/fastapi.md
@@ -82,14 +82,31 @@ app.include_router(router, prefix="/v1/vault")
 
 ## Input Validation
 
-| Field | Constraint |
-|-------|-----------|
-| `query` | Max 10,000 characters |
-| `top_k` | 1-1,000 |
-| `threshold` | 0.0-1.0 |
-| Batch sources | Max 100 items |
-
-<!-- VERIFIED: integrations/fastapi_routes.py:50-53 — SearchRequest validators -->
+All endpoints validate inputs at the API boundary before reaching vault logic.
+
+| Field | Constraint | Endpoint |
+|-------|-----------|----------|
+| `content` | Max 500MB | `POST /resources` |
+| `query` | Max 10,000 characters | `POST /search` |
+| `top_k` | 1-1,000 | `POST /search` |
+| `threshold` | 0.0-1.0 | `POST /search` |
+| `limit` | 1-1,000 | `GET /resources` |
+| `offset` | 0-1,000,000 | `GET /resources` |
+| Batch sources | Max 100 items | `POST /batch` |
+| `as_of` | Valid ISO date | `POST /search` |
+
+<!-- VERIFIED: integrations/fastapi_routes.py:40 — content max_length -->
+<!-- VERIFIED: integrations/fastapi_routes.py:51-53 — SearchRequest validators -->
+<!-- VERIFIED: integrations/fastapi_routes.py:140-141 — limit/offset Query validators -->
+
+## Response Caching
+
+`GET /health` and `GET /status` responses are cached with a configurable TTL (default 30 seconds). The cache is invalidated on any write operation (add, update, delete).
+
+Configure via `VaultConfig(health_cache_ttl_seconds=60)`.
+
+<!-- VERIFIED: vault.py:947-955 — health cache -->
+<!-- VERIFIED: vault.py:1026-1031 — status cache -->
 
 ## Error Codes
 
diff --git a/docs/membrane.md b/docs/membrane.md
@@ -38,7 +38,13 @@ Default patterns detect:
 - XSS: `<script>`, `javascript:`
 - Code injection: `eval()`, `exec()`, `__import__()`, `subprocess.`, `os.system()`
 
-<!-- VERIFIED: membrane/innate_scan.py:20-33 — DEFAULT_BLOCKLIST -->
+<!-- VERIFIED: membrane/innate_scan.py:20-35 — DEFAULT_BLOCKLIST -->
+
+## Security Limits
+
+Content is truncated to **500KB** before regex scanning to prevent catastrophic backtracking (ReDoS). Full content is still stored and indexed; only the scan input is bounded. Patterns are pre-compiled for validation before use.
+
+<!-- VERIFIED: membrane/innate_scan.py:69 — 500KB scan_content limit -->
 
 ## Custom Blocklist
 
diff --git a/docs/multi-tenancy.md b/docs/multi-tenancy.md
@@ -30,11 +30,21 @@ For stricter isolation, lock the vault to a single tenant at construction:
 
 ```python
 vault = Vault("./knowledge", tenant_id="site-123")
-# All operations are now scoped to site-123
-# No need to pass tenant_id on every call
+
+# All operations auto-inject tenant_id="site-123"
+vault.add("doc")              # tenant_id="site-123" applied automatically
+vault.search("query")         # scoped to site-123
+
+# Mismatched tenant_id is rejected
+vault.add("doc", tenant_id="site-456")  # Raises VaultError: tenant mismatch
 ```
 
-<!-- VERIFIED: vault.py:143-148 — _locked_tenant_id -->
+When a vault is tenant-locked:
+- Operations with no `tenant_id` auto-inject the locked tenant
+- Operations with a matching `tenant_id` proceed normally
+- Operations with a different `tenant_id` raise `VaultError`
+
+<!-- VERIFIED: vault.py:257-277 — _resolve_tenant enforcement -->
 
 ## Per-Tenant Quotas
 
@@ -47,9 +57,14 @@ config = VaultConfig(max_resources_per_tenant=1000)
 vault = Vault("./knowledge", config=config)
 
 vault.add("doc", tenant_id="site-123")  # OK until quota reached
+# After 1000 resources: raises VaultError("Tenant site-123 has reached the resource limit")
 ```
 
+Quotas are enforced with an atomic `COUNT(*)` query at the storage layer. No TOCTOU race condition window.
+
 <!-- VERIFIED: config.py:68 — max_resources_per_tenant -->
+<!-- VERIFIED: vault.py:406-416 — atomic count_resources check -->
+<!-- VERIFIED: storage/sqlite.py:595-601 — count_resources implementation -->
 
 ## Storage
 
diff --git a/docs/plugins.md b/docs/plugins.md
@@ -111,16 +111,37 @@ vault = Vault("./knowledge", plugins_dir="/opt/qp/plugins/")
 
 Drop `.py` files in the plugins directory. Any class decorated with `@embedder`, `@parser`, or `@policy` is auto-discovered.
 
+**A `manifest.json` is required.** This file maps each plugin filename to its SHA3-256 hash. Without it, the entire directory is skipped for security.
+
 ```
 /opt/qp/plugins/
+    manifest.json       # Required: SHA3-256 hashes for each .py file
     my_embedder.py      # Contains @embedder("local-model") class
     dicom_parser.py     # Contains @parser("dicom") class
     itar_policy.py      # Contains @policy("itar") class
 ```
 
-<!-- VERIFIED: plugins/registry.py:126-161 — discover_plugins_dir() loads .py files -->
+Generate the manifest:
+
+```python
+import hashlib, json, pathlib
+
+plugins_dir = pathlib.Path("/opt/qp/plugins")
+manifest = {}
+for f in sorted(plugins_dir.glob("*.py")):
+    if not f.name.startswith("_"):
+        manifest[f.name] = hashlib.sha3_256(f.read_bytes()).hexdigest()
+(plugins_dir / "manifest.json").write_text(json.dumps(manifest, indent=2))
+```
+
+Security rules:
+- Files not listed in the manifest are rejected
+- Hash mismatches are logged and the file is skipped
+- Files starting with `_` are always skipped
+- Broken files log a warning and are skipped
+- To disable hash verification: `discover_plugins_dir(path, verify_hashes=False)` (not recommended)
 
-Files starting with `_` are skipped. Broken files log a warning and are skipped.
+<!-- VERIFIED: plugins/registry.py:131-189 — manifest required, hash verification -->
 
 ## Discovery Order
 
diff --git a/docs/security.md b/docs/security.md
@@ -1,6 +1,6 @@
 # Security Model
 
-qp-vault's security architecture for v0.13.0.
+qp-vault's security architecture for v0.14.0.
 
 ## Cryptographic Inventory
 
@@ -44,7 +44,8 @@ Quarantined resources get `ResourceStatus.QUARANTINED` and are excluded from sea
 | Input | Validation |
 |-------|-----------|
 | Trust tier | Must be valid enum value |
-| Resource name | Path traversal stripped, null bytes removed, 255 char limit |
+| Resource name | Unicode NFC normalized, path traversal stripped, null bytes removed, 255 char limit |
+| Source path | Resolved and rejected if `..` detected (path traversal protection) |
 | Tags | Max 50 tags, 100 chars each, control chars stripped |
 | Metadata keys | Alphanumeric + dash/underscore/dot, max 100 keys |
 | Metadata values | Max 10,000 bytes per value |
@@ -60,7 +61,9 @@ All queries use parameterized placeholders (`?` for SQLite, `$N` for PostgreSQL)
 
 ## Plugin Security
 
-Plugins loaded from `plugins_dir` are verified against a `manifest.json` containing SHA3-256 hashes before execution. Hash mismatches are logged and the plugin is skipped.
+Plugins loaded from `plugins_dir` require a `manifest.json` (SHA3-256 hashes) by default. Without a manifest, the entire directory is skipped. Files not listed in the manifest are rejected. Hash mismatches are logged and the plugin is skipped.
+
+<!-- VERIFIED: plugins/registry.py:131-176 — manifest required, unlisted files rejected -->
 
 ## Key Management
 
@@ -98,14 +101,21 @@ Every chunk: SHA3-256 CID. Every resource: Merkle root over sorted chunk CIDs. E
 
 | Vector | Protection |
 |--------|------------|
-| Large upload | max_file_size_mb (default 500MB) |
+| Large upload | max_file_size_mb (default 500MB), content max_length 500MB |
 | Unbounded queries | Paginated with 50K hard cap |
 | Batch flooding | Max 100 items per request |
 | Search params | top_k max 1000, query max 10K chars |
+| List params | limit 1-1000, offset 0-1M (FastAPI validated) |
 | Chain cycles | Max 1000 links |
 | FTS5 complexity | Special operators stripped |
-| Tenant flooding | Per-tenant resource quotas |
-| Query timeout | Configurable query_timeout_ms (default 30s) |
+| Tenant flooding | Per-tenant quotas (atomic count, no TOCTOU) |
+| Query timeout | Configurable query_timeout_ms (default 30s), task cancelled on timeout |
+| Health/status abuse | TTL-cached responses (default 30s) |
+| Membrane ReDoS | Content truncated to 500KB for regex scanning |
+
+<!-- VERIFIED: vault.py:247-265 — _with_timeout with task cancellation -->
+<!-- VERIFIED: membrane/innate_scan.py:69 — 500KB scan limit -->
+<!-- VERIFIED: integrations/fastapi_routes.py:140-141 — limit/offset validation -->
 
 ## Threat Model
 
@@ -118,7 +128,9 @@ Every chunk: SHA3-256 CID. Every resource: Merkle root over sorted chunk CIDs. E
 | Data exfiltration | DataClassification blocks CONFIDENTIAL/RESTRICTED |
 | Prompt injection | Membrane innate scan + quarantine |
 | SQL injection | Parameterized queries only |
-| Path traversal | Name sanitization strips path components |
+| Path traversal | Name sanitization + source path resolve rejects `..` |
+| Unicode homographs | NFC normalization prevents visually identical collisions |
+| CLI information leakage | Structured error codes, no raw exception output |
 | FTS5 injection | Query sanitizer strips operators |
 | Audit manipulation | Capsule hash-chains are append-only |
 | Key compromise | ML-KEM-768 (quantum-resistant) + zeroization |
