visus-mcp 0.9.0 → 0.10.0

package/.claude/settings.local.json

@@ -69,7 +69,15 @@
       "Bash(/tmp/mcp-publisher login:*)",
       "Bash(/tmp/mcp-publisher publish:*)",
       "WebFetch(domain:airc.nist.gov)",
-      "WebFetch(domain:csf.tools)"
+      "WebFetch(domain:csf.tools)",
+      "Bash(npx ts-node:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm --version:*)",
+      "Bash(env)",
+      "Bash(.gitignore)",
+      "Bash(npm whoami:*)",
+      "Bash(npm login:*)",
+      "Bash(~/.npmrc)"
     ],
     "deny": [],
     "ask": []

package/.env.example

@@ -0,0 +1,55 @@
+# Visus-MCP Environment Configuration
+# Copy this file to .env and fill in your values
+
+# =======================================
+# Cryptographic Configuration
+# =======================================
+
+# REQUIRED for production proof signatures.
+# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# Minimum length: 32 bytes (64 hex chars recommended)
+# Rotate: on compromise, on personnel change, on annual audit cycle
+VISUS_HMAC_SECRET=
+
+# =======================================
+# Audit Configuration
+# =======================================
+
+# DynamoDB audit table name
+VISUS_AUDIT_TABLE=visus-audit-log
+
+# AWS region for DynamoDB
+AWS_REGION=us-east-1
+
+# Set to "true" to make audit write failures propagate (fail-closed)
+# Default "false" = fail-open (audit failure does not break tool call)
+AUDIT_FAIL_CLOSED=false
+
+# Set to "false" to disable audit logging (dev/test only)
+VISUS_AUDIT_ENABLED=true
+
+# =======================================
+# Browser Configuration (optional)
+# =======================================
+
+# Fetch timeout in milliseconds
+VISUS_TIMEOUT_MS=10000
+
+# Max content size before truncation (in KB)
+VISUS_MAX_CONTENT_KB=512
+
+# =======================================
+# Lambda Configuration (Hosted tier only)
+# =======================================
+
+# Lambda function ARN (set by CDK)
+# LAMBDA_FUNCTION_ARN=
+
+# API Gateway endpoint (set by CDK)
+# API_GATEWAY_ENDPOINT=
+
+# Cognito User Pool ID (set by CDK)
+# COGNITO_USER_POOL_ID=
+
+# Cognito App Client ID (set by CDK)
+# COGNITO_APP_CLIENT_ID=

package/CRYPTO-PROOF-SPEC.md

@@ -0,0 +1,244 @@
+# Visus-MCP Cryptographic Proof Specification
+
+Version: 1.0.0
+Status: Normative
+Regulatory basis: EU AI Act Art. 9, 11, 13, 15 | GDPR Art. 5(2), 32
+
+---
+
+## Purpose
+
+This document specifies the cryptographic proof scheme used by Visus-MCP to
+provide verifiable, tamper-evident evidence that its prompt injection
+sanitization pipeline executed before any web content was forwarded to a
+large language model.
+
+Any third party — regulator, DPA, conformity assessment body, or security
+researcher — can independently verify any Visus-MCP proof record using only
+this specification and standard SHA-256 / HMAC-SHA-256 implementations.
+
+---
+
+## Proof Fields
+
+Every Visus-MCP tool response includes a `visus_proof` object with these fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `request_id` | hex string (32 chars) | Unique identifier for this tool call |
+| `proof_hash` | hex string (64 chars) | SHA-256 commitment over all proof fields |
+| `chain_hash` | hex string (64 chars) | Links this proof to previous proof |
+| `injection_detected` | boolean | Whether any injection pattern fired |
+| `patterns_evaluated` | integer | Total patterns checked |
+| `patterns_triggered` | integer | Patterns that fired |
+| `redactions` | integer | Number of redactions applied |
+| `sanitization_applied` | boolean | Whether content was modified |
+| `timestamp_utc` | ISO 8601 string | When sanitization completed |
+| `pipeline_version` | semver string | Sanitization library version |
+| `schema_version` | semver string | Proof schema version |
+
+The `proof_signature` (HMAC) is stored in the audit log but **not** returned
+in tool responses. It is disclosed only to authorised auditors.
+
+---
+
+## Proof Hash Computation
+
+The `proof_hash` is computed as:
+
+```
+proof_hash = SHA-256(canonical_string)
+
+canonical_string = join([
+    request_id,
+    input_hash,
+    output_hash,
+    sorted(triggered_pattern_ids).join(","),
+    str(patterns_evaluated),
+    timestamp_utc,
+    pipeline_version,
+], separator="\x00|\x00")
+```
+
+Where:
+
+- `input_hash  = SHA-256(raw_content_utf8)`   — hash of content BEFORE sanitization
+- `output_hash = SHA-256(sanitized_content_utf8)` — hash of content AFTER sanitization
+- `triggered_pattern_ids` = sorted lexicographically before joining
+- All string encoding is UTF-8
+- The field separator `\x00|\x00` (null-pipe-null) prevents field boundary ambiguity
+
+---
+
+## Proof Signature Computation
+
+```
+proof_signature = HMAC-SHA-256(proof_hash, VISUS_HMAC_SECRET)
+```
+
+The signature is disclosed to authorised auditors under NDA. It proves the
+proof was issued by a pipeline instance holding the secret key, not forged
+by an external observer.
+
+---
+
+## Chain Hash Computation
+
+```
+chain_hash = SHA-256(previous_proof_hash + "\x00|\x00" + current_proof_hash)
+```
+
+- First record: `previous_proof_hash = "GENESIS"`
+- The chain allows auditors to detect gaps (deleted records) or reordering.
+
+---
+
+## Verification Procedure
+
+### Hash-only verification (no signing key required)
+
+1. Obtain `request_id`, `timestamp_utc`, `pipeline_version`, `patterns_evaluated`, `patterns_triggered` from the `visus_proof` object
+2. Obtain `input_hash` and `output_hash` from the audit log record
+3. Obtain `triggered_pattern_ids` (list) from the audit log record
+4. Recompute `canonical_string` using the formula above
+5. Compute `SHA-256(canonical_string)`
+6. Compare against `proof_hash` — must match byte-for-byte
+
+### Full cryptographic verification (requires signing key)
+
+1. Perform hash-only verification first
+2. Compute `HMAC-SHA-256(recomputed_proof_hash, VISUS_HMAC_SECRET)`
+3. Compare against `proof_signature` from audit log — must match byte-for-byte
+
+### Using the `visus_verify` MCP tool
+
+```json
+{
+  "tool": "visus_verify",
+  "input": {
+    "proof": { "<paste the visus_proof object here>" },
+    "signingKey": "<VISUS_HMAC_SECRET — omit for hash-only>"
+  }
+}
+```
+
+### Using the CLI verifier
+
+```bash
+# TypeScript
+echo '{"proof": {...}, "signingKey": "..."}' | \
+  node dist/crypto/verifier.js
+
+# Exit code 0 = valid, 1 = invalid, 2 = parse error
+```
+
+---
+
+## Regulatory Mapping
+
+| Proof Component | EU AI Act | GDPR |
+|---|---|---|
+| `input_hash` + `output_hash` | Art. 15 Robustness — proves pipeline ran | Art. 32 Security — cryptographic evidence |
+| `proof_hash` | Art. 9 Risk Management — tamper-evident record | Art. 5(2) Accountability — verifiable |
+| `proof_signature` (audit-only) | Art. 11 Technical Documentation | Art. 32(1)(d) Regular testing evidence |
+| `chain_hash` | Art. 9 Risk Management — deletion detection | Art. 5(2) Accountability |
+| `visus_verify` tool | Art. 13 Transparency — callable verification | Art. 30 Records — machine-readable |
+| `patterns_evaluated` / `patterns_triggered` | Art. 9(4) Risk Management documentation | Art. 32 — evidence of controls |
+
+### Presumption of Conformity Path
+
+Deployers can reference this specification as part of the technical
+documentation required under EU AI Act Annex IV. The `visus_verify` tool
+constitutes the "testing, validation and verification procedures" required
+by Annex IV §2(f).
+
+---
+
+## Security Properties
+
+| Property | Mechanism | Guarantee |
+|---|---|---|
+| **Tamper evidence** | SHA-256 over all fields | Any field change invalidates proof_hash |
+| **Authenticity** | HMAC-SHA-256 with secret key | Proves pipeline issued the proof |
+| **Non-repudiation** | Audit log + chain_hash | Deletion of records is detectable |
+| **Privacy preservation** | Hashes only, no raw content | Verification without data exposure |
+| **Timing safety** | `timingSafeEqual` / `hmac.compare_digest` | No timing oracle on verification |
+| **Ordering proof** | Chain hash | Record sequence is tamper-evident |
+
+---
+
+## Reference Implementation Test Vectors
+
+Use these to verify your implementation is correct:
+
+### Input:
+```
+request_id         = "test-request-id-0000"
+input_hash         = SHA-256("raw content")
+                   = "a6e5d15bf571ca7a23fd704caad6c4c071210ba8d38ea0296dc58c3ce0a0e514"
+output_hash        = SHA-256("clean content")
+                   = "573b1d8589d0623b86749785dae7a299483d140d551299578f0fcb30bdcece28"
+triggered_pattern_ids = ["PI-001", "PI-007"]  (sort → ["PI-001","PI-007"])
+patterns_evaluated = 43
+timestamp_utc      = "2026-03-26T00:00:00.000Z"
+pipeline_version   = "1.0.0"
+
+canonical_string = "test-request-id-0000\x00|\x00a6e5d15bf571ca7a23fd704caad6c4c071210ba8d38ea0296dc58c3ce0a0e514\x00|\x00573b1d8589d0623b86749785dae7a299483d140d551299578f0fcb30bdcece28\x00|\x00PI-001,PI-007\x00|\x0043\x00|\x002026-03-26T00:00:00.000Z\x00|\x001.0.0"
+```
+
+### Expected Output:
+```
+proof_hash = "9cda5595b2f9865e1f1f50ac366a79daa488bd85db02551c20c3de22a65c902d"
+
+signing_key = "test-signing-key-for-spec-vectors-only-000000"
+proof_signature = "0d7a6102117ed1c6d5ceb8dcc132000f96ddf3d1c4a97bf18328063dded959b5"
+```
+
+### Verification:
+
+Recompute the `proof_hash` from the inputs above. It must match exactly. Then compute the HMAC signature using the test signing key. It must also match exactly.
+
+If either hash does not match, your implementation is incorrect. Common causes:
+- Field ordering wrong in canonical string
+- Separator string incorrect (must be `\x00|\x00`)
+- Pattern IDs not sorted lexicographically
+- Encoding not UTF-8
+- Extra whitespace or newlines in canonical string
+
+---
+
+## Compliance Checklist
+
+For deployers preparing for conformity assessment under EU AI Act:
+
+- [ ] `VISUS_HMAC_SECRET` configured in production (minimum 32 bytes)
+- [ ] Audit logging enabled (`VISUS_AUDIT_ENABLED=true`)
+- [ ] Audit records retained for 90 days minimum
+- [ ] `visus_verify` tool accessible to auditors
+- [ ] Test vectors verified against your deployment
+- [ ] Chain tip persisted across server restarts (if applicable)
+- [ ] HMAC key rotation procedure documented
+- [ ] Incident response plan for key compromise
+- [ ] Data sharing agreement covers proof signature disclosure to DPAs
+- [ ] Technical documentation references this specification
+
+---
+
+## Changelog
+
+| Version | Date | Changes |
+|---|---|---|
+| 1.0.0 | 2026-03-28 | Initial release — comprehensive cryptographic proof system |
+
+---
+
+## Contact
+
+For questions about this specification or security disclosures:
+
+- Email: security@lateos.ai
+- GitHub: https://github.com/visus-mcp/visus-mcp/security
+
+---
+
+**End of Specification**

package/README.md

@@ -1,12 +1,13 @@
 # Visus — Secure Web Access for Claude
 
 [![npm version](https://img.shields.io/npm/v/visus-mcp?color=crimson&label=npm)](https://www.npmjs.com/package/visus-mcp)
-[![tests](https://img.shields.io/badge/tests-294%20passing-brightgreen)](https://github.com/visus-mcp/visus-mcp)
-[![tools](https://img.shields.io/badge/MCP%20tools-4-blue)](https://github.com/visus-mcp/visus-mcp)
+[![tests](https://img.shields.io/badge/tests-323%20passing-brightgreen)](https://github.com/visus-mcp/visus-mcp)
+[![tools](https://img.shields.io/badge/MCP%20tools-5-blue)](https://github.com/visus-mcp/visus-mcp)
 [![mcp](https://img.shields.io/badge/MCP-compatible-brightgreen)](https://modelcontextprotocol.io)
 [![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/visus-mcp/visus-mcp/blob/main/LICENSE)
 [![security](https://img.shields.io/badge/frameworks-NIST%20AI%20RMF%20%7C%20CSF%202.0%20%7C%20OWASP%20%7C%20MITRE%20%7C%20ISO42001-orange)](https://github.com/visus-mcp/visus-mcp/blob/main/SECURITY.md)
 [![iso42001](https://img.shields.io/badge/ISO%2FIEC-42001%3A2023-blueviolet)](https://www.iso.org/standard/81230.html)
+[![euaiact](https://img.shields.io/badge/EU%20AI%20Act-Art.%209%2F13%2F15-blue)](https://github.com/visus-mcp/visus-mcp/blob/main/CRYPTO-PROOF-SPEC.md)
 
 > **Your AI agent shouldn't have to read garbage.**
 > **visus-mcp makes sure it doesn't.**
@@ -19,7 +20,7 @@ Claude handles most of it. But it still has to read all of it first. You still p
 
 Built as infrastructure, not a replacement for Claude's own safety training. The two layers together are stronger than either alone.
 ```bash
-npx visus-mcp@0.9.0
+npx visus-mcp@0.10.0
 ```
 
 *"What the web shows you, Lateos reads safely."*
@@ -50,7 +51,8 @@ visus-mcp fetches the same page and delivers:
 URL → Playwright Render → Content-Type Detection
 → Specialized Handlers (PDF/JSON/SVG) OR HTML Pipeline
 → Injection Sanitizer (43 patterns) → PII Redactor
-→ Token Ceiling (24k cap) → Clean Content → Claude
+→ Cryptographic Proof Generation → Token Ceiling (24k cap)
+→ Clean Content + Proof → Claude
 ```
 
 ### Security Pipeline
@@ -63,9 +65,10 @@ URL → Playwright Render → Content-Type Detection
    - **HTML/XML/RSS** — Uses existing conversion and reader extraction pipeline
 3. **Injection Detection**: 43 pattern categories scan for prompt injection attempts
 4. **PII Redaction**: Emails, phone numbers, SSNs, credit cards, and IP addresses are redacted
-5. **Clean Delivery**: Stripped, formatted, token-efficient content reaches your LLM — with a compliance report attached if anything was flagged
+5. **Cryptographic Proof**: SHA-256 + HMAC-SHA-256 proof that sanitization ran (EU AI Act Art. 9/13/15 compliance)
+6. **Clean Delivery**: Stripped, formatted, token-efficient content reaches your LLM — with a `visus_proof` header and compliance report attached if anything was flagged
 
-**This pipeline runs before content enters Claude's context window** — reducing token consumption, keeping PII out of conversation history, and generating audit logs when injection patterns are detected.
+**This pipeline runs before content enters Claude's context window** — reducing token consumption, keeping PII out of conversation history, generating audit logs when injection patterns are detected, and producing tamper-evident cryptographic proofs that sanitization executed.
 
 ---
 
@@ -300,6 +303,114 @@ Extract structured data from a web page according to a schema. Includes NIST AI
 
 All extracted fields are individually sanitized.
 
+### `visus_verify`
+
+**NEW in v0.10.0:** Verify a Visus-MCP sanitization proof record. Confirms that a specific request was processed by the Visus injection detection pipeline before content reached the LLM. Produces a compliance statement suitable for EU AI Act Art. 9/13 documentation and GDPR Art. 32 security evidence.
+
+**Input:**
+```json
+{
+  "proof": {
+    "request_id": "abc123...",
+    "proof_hash": "9cda5595...",
+    "chain_hash": "977f5566...",
+    "injection_detected": false,
+    "patterns_evaluated": 43,
+    "patterns_triggered": 0,
+    "timestamp_utc": "2026-03-28T12:00:00Z",
+    "pipeline_version": "1.0.0",
+    "schema_version": "1.0.0"
+  },
+  "signingKey": "optional-for-full-verification"
+}
+```
+
+**Output:**
+```json
+{
+  "valid": true,
+  "checks": {
+    "proofHashMatch": true,
+    "signatureMatch": true,
+    "schemaVersionMatch": true
+  },
+  "complianceStatement": "VERIFIED: Request abc123 was processed by Visus-MCP sanitization pipeline v1.0.0 at 2026-03-28T12:00:00Z. Proof hash 9cda5595... recomputed and confirmed. 43 injection patterns evaluated, 0 triggered, 0 redactions applied. Sanitized content reached LLM only after this processing completed. Verified at 2026-03-28T12:30:00Z. EU AI Act Art. 9/13/15 controls confirmed active for this request.",
+  "recomputedProofHash": "9cda5595...",
+  "verifiedAt": "2026-03-28T12:30:00Z",
+  "requestId": "abc123...",
+  "issues": []
+}
+```
+
+**Use Cases:**
+- Regulatory audit responses (DPA, conformity assessment)
+- Internal compliance verification
+- Third-party security assessments
+- Incident investigation and forensics
+
+See [CRYPTO-PROOF-SPEC.md](./CRYPTO-PROOF-SPEC.md) for the complete technical specification.
+
+---
+
+## Cryptographic Proof System
+
+**NEW in v0.10.0:** Every Visus tool response now includes a `visus_proof` object providing tamper-evident cryptographic evidence that sanitization executed. This satisfies EU AI Act Art. 9 (Risk Management), Art. 13 (Transparency), and Art. 15 (Robustness) requirements.
+
+### What's in a Proof?
+
+```json
+{
+  "visus_proof": {
+    "request_id": "0b9564ea943c3909...",
+    "proof_hash": "a7cbc0e4a158dc4e...",
+    "chain_hash": "977f55664549b4b2...",
+    "injection_detected": false,
+    "patterns_evaluated": 43,
+    "patterns_triggered": 0,
+    "redactions": 0,
+    "sanitization_applied": false,
+    "timestamp_utc": "2026-03-28T12:00:00.000Z",
+    "pipeline_version": "1.0.0",
+    "schema_version": "1.0.0",
+    "verify_instruction": "Recompute proof_hash from disclosed fields per visus-mcp/CRYPTO-PROOF-SPEC.md"
+  }
+}
+```
+
+### How It Works
+
+1. **Before sanitization**: Generate unique request ID and timestamp
+2. **During sanitization**: Run full injection detection + PII redaction pipeline
+3. **After sanitization**: Compute cryptographic proof:
+   - `proof_hash` = SHA-256(request_id + input_hash + output_hash + patterns + timestamp + version)
+   - `proof_signature` = HMAC-SHA-256(proof_hash, VISUS_HMAC_SECRET) — stored in audit log only
+   - `chain_hash` = SHA-256(previous_proof_hash + current_proof_hash) — detects deleted records
+
+4. **Verification**: Anyone can verify the proof by recomputing the proof_hash from the disclosed fields
+
+### Security Properties
+
+| Property | Mechanism | Guarantee |
+|----------|-----------|-----------|
+| **Tamper evidence** | SHA-256 over all fields | Any field change invalidates proof_hash |
+| **Authenticity** | HMAC-SHA-256 with secret key | Proves pipeline issued the proof |
+| **Non-repudiation** | Audit log + chain_hash | Deletion of records is detectable |
+| **Privacy preservation** | Hashes only, no raw content | Verification without data exposure |
+
+### For Regulators and Auditors
+
+- **Hash-only verification**: Recompute `proof_hash` from disclosed fields (no key required)
+- **Full cryptographic verification**: Verify `proof_signature` with `VISUS_HMAC_SECRET` (shared under NDA)
+- **Independent verification**: Use the `visus_verify` tool or CLI verifier
+- **Compliance statements**: Automatically generated for DPA submissions
+
+See [CRYPTO-PROOF-SPEC.md](./CRYPTO-PROOF-SPEC.md) for:
+- Complete technical specification
+- Verification procedures
+- Reference implementation test vectors
+- Regulatory mapping (EU AI Act / GDPR)
+- Deployer compliance checklist
+
 ---
 
 ## Threat Reporting
@@ -884,4 +995,49 @@ A: Yes! Open-source tier is free forever. Phase 2 will introduce a hosted tier w
 
 ---
 
+## EU Regulatory Compliance
+
+Visus-MCP is designed with EU AI Act and GDPR principles as first-class architectural constraints, not afterthoughts. This section provides a mapping between Visus features and the specific regulatory articles they address, enabling integrators to build toward **presumption of conformity** via the EU AI Act Code of Practice and harmonised standards under CEN/CENELEC JTC 21.
+
+### Feature → Regulation Mapping
+
+| Visus-MCP Feature | EU AI Act Article | GDPR Article | Regulatory Rationale |
+|---|---|---|---|
+| Prompt injection sanitization (43 validated patterns) | Art. 9 — Risk Management System | Art. 32 — Security of Processing | Mandatory technical measures to prevent adversarial manipulation of AI outputs |
+| Untrusted-by-default web content model | Art. 9 — Risk Management System | Art. 5(1)(f) — Integrity & Confidentiality | Treats all external input as hostile; maps to adversarial robustness requirement in Code of Practice Measure 2.5 |
+| No raw external content forwarded to LLM | Art. 15 — Robustness, Accuracy & Cybersecurity | Art. 5(1)(c) — Data Minimisation | Only sanitized, stripped content reaches the model; reduces attack surface and unnecessary data exposure |
+| Content sanitization before AI processing | Art. 15 — Robustness, Accuracy & Cybersecurity | Art. 25 — Data Protection by Design | Sanitization is enforced at ingestion, not as an optional post-processing step |
+| Stateless fetch architecture (no session persistence) | Art. 10 — Data & Data Governance | Art. 5(1)(e) — Storage Limitation | No user browsing data retained beyond the immediate request |
+| Open-source, auditable codebase | Art. 13 — Transparency & Provision of Information | Art. 5(2) — Accountability | Full auditability for conformity assessment bodies and data protection authorities |
+| SECURITY-AUDIT-v1.md (planned red team disclosure) | Art. 9 — Risk Management + Code of Practice §4 Adversarial Testing | Art. 32(1)(d) — Regular Testing | Aligns with EDPS guidance on AI risk management: document threats, test mitigations, publish findings |
+| MCP endpoint scoped permissions | Art. 9 — Risk Management System | Art. 25 — Data Protection by Design | Least-privilege access model; each tool call scoped to minimum required capability |
+
+### EU AI Act Code of Practice Alignment
+
+The EU AI Act Code of Practice (General-Purpose AI, published 2025) identifies adversarial testing and mitigation documentation as key obligations for AI system providers. Visus-MCP addresses these through:
+
+- **Measure 2.5 (Adversarial Robustness):** Prompt injection defense is the primary threat model. The 43-pattern detection library directly addresses adversarial input manipulation.
+- **Measure 4.1 (Incident Reporting Preparedness):** The planned `SECURITY-AUDIT-v1.md` constitutes a pre-emptive disclosure document that regulators can use to assess risk management maturity.
+- **Measure 1.2 (Capability Transparency):** The open-source architecture and this compliance mapping serve as the transparency artifact required under Art. 13.
+
+### EDPS Guidance on AI Risk Management
+
+The European Data Protection Supervisor's *Guidelines on AI and Data Protection* (2022, updated 2024) require that AI systems processing content on behalf of users implement:
+
+1. **Risk identification at ingestion** — Visus sanitizes at the fetch layer before any data reaches the AI model.
+2. **Technical measures proportionate to risk** — Stateless architecture and data minimisation limit blast radius of any breach.
+3. **Accountability documentation** — This mapping table, combined with `SECURITY.md` and `STATUS.md`, constitutes the technical documentation required under GDPR Art. 30 (Records of Processing) for AI-assisted data handling.
+
+### Presumption of Conformity Path
+
+Integrators deploying Visus-MCP in EU contexts can reference this mapping to support conformity claims under:
+
+- **EN ISO/IEC 42001** (AI Management Systems) — risk management and data governance controls
+- **ETSI EN 303 645** (Cyber Security for Consumer IoT, applicable by analogy to AI agents)
+- **EU AI Act Annex IV** (Technical Documentation) — this section, `SECURITY.md`, and `STATUS.md` together form a substantive portion of the required technical file
+
+> **Note:** Visus-MCP is an open-source tool. Conformity assessment obligations apply to the deploying organisation, not to the upstream open-source component. This documentation is provided to assist deployers in meeting their obligations.
+
+---
+
 **Built with by Lateos**

package/SECURITY.md

@@ -357,6 +357,99 @@ We take security seriously. If you discover a vulnerability in Visus:
 
 ---
 
+## EU AI Act & GDPR Compliance Mapping
+
+### Threat Model → Regulatory Mapping
+
+The Visus-MCP security architecture is explicitly mapped to EU AI Act and GDPR obligations. The following table cross-references each security control with its regulatory basis.
+
+| Security Control | Threat Mitigated | EU AI Act Article | GDPR Article |
+|---|---|---|---|
+| Prompt injection sanitization | Adversarial manipulation of AI reasoning | Art. 9 — Risk Management | Art. 32 — Security of Processing |
+| Untrusted-by-default content model | Supply chain / web content injection | Art. 15 — Robustness & Cybersecurity | Art. 5(1)(f) — Integrity & Confidentiality |
+| Stateless fetch (no session storage) | Persistent tracking / data leakage | Art. 10 — Data Governance | Art. 5(1)(e) — Storage Limitation |
+| Minimal data forwarding to LLM | Unnecessary PII exposure to AI model | Art. 15 — Accuracy & Data Quality | Art. 5(1)(c) — Data Minimisation |
+| Open audit trail (this document) | Opacity / unverifiable security claims | Art. 13 — Transparency | Art. 5(2) — Accountability |
+| Scoped MCP permissions | Privilege escalation via tool calls | Art. 9 — Risk Management | Art. 25 — Data Protection by Design |
+
+### EU AI Act Code of Practice: Adversarial Testing Requirements
+
+Under the EU AI Act Code of Practice for General-Purpose AI Models (2025), providers are expected to conduct and document adversarial testing. For Visus-MCP this means:
+
+**What we test:**
+- Prompt injection via crafted web page content (direct and indirect)
+- Instruction smuggling via HTML comments, meta tags, and hidden DOM elements
+- Encoding-based evasion (Base64, Unicode normalization attacks, homoglyph substitution)
+- Multi-turn injection via session context manipulation
+
+**How we document it:**
+- `SECURITY-AUDIT-v1.md` (planned): A public red team disclosure document covering methodology, findings, and mitigations. This directly satisfies Code of Practice Measure 4.1 (incident and vulnerability disclosure preparedness).
+
+**EDPS AI Risk Management Guidance:**
+The European Data Protection Supervisor recommends that AI systems document the following for each data processing operation:
+1. The AI capability being exercised (fetch + sanitize + forward)
+2. The data flows involved (external URL → sanitization layer → LLM context)
+3. The risk mitigations applied (stateless, no persistence, injection filtering)
+4. The residual risk and monitoring approach (open-source auditability, community disclosure)
+
+Visus-MCP addresses all four points through this document, `README.md`, and `STATUS.md`.
+
+### Reporting Security Issues
+
+See the main [Vulnerability Disclosure](#vulnerability-disclosure) section above for responsible disclosure procedures. For EU-specific regulatory concerns (e.g., potential GDPR Art. 33 notification obligations arising from a Visus-MCP vulnerability), please include "EU-REGULATORY" in the subject line of your disclosure.
+
+---
+
+## HMAC Signing Key Management (VISUS_HMAC_SECRET)
+
+The `VISUS_HMAC_SECRET` is used to sign all sanitization proof records.
+It must be treated as a high-value secret.
+
+### Generation
+
+```bash
+# Node.js
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+# Python (if applicable)
+python3 -c "import secrets; print(secrets.token_hex(32))"
+```
+
+### Storage
+
+Use AWS Secrets Manager, not .env files in production.
+
+### Rotation triggers
+
+- Personnel change with access to the secret
+- Suspected compromise
+- Annual audit cycle (recommended)
+- Any infrastructure credential rotation event
+
+### On rotation
+
+Old proof_signatures will no longer verify against the new key.
+Retain the old key (in Secrets Manager, versioned) for audit purposes during
+the 90-day record retention window.
+
+### Disclosure to auditors
+
+Share under NDA with conformity assessment bodies
+or DPAs requiring full cryptographic verification of proof records.
+GDPR Art. 32 requires "appropriate technical measures" — the HMAC key is
+a controlled measure and its disclosure is governed by your data sharing agreements.
+
+### Compromise response
+
+If the HMAC key is compromised:
+1. Immediately rotate to a new key
+2. Audit all proof records signed with the compromised key
+3. Determine if any proofs were forged (check against original audit logs)
+4. Notify affected parties if required under GDPR Art. 33 / 34
+5. Document incident in security log
+
+---
+
 **Built with by Lateos**
 
 For questions: **security@lateos.ai**