visus-mcp 0.8.0 → 0.10.0

package/.claude/settings.local.json

@@ -60,7 +60,24 @@
       "Bash(unzip:*)",
       "Bash(mkdir:*)",
       "Bash(comm -13:*)",
-      "Bash(comm -23:*)"
+      "Bash(comm -23:*)",
+      "Bash(npx @modelcontextprotocol/registry-cli:*)",
+      "Bash(make:*)",
+      "Bash(tar:*)",
+      "Bash(./mcp-publisher:*)",
+      "Bash(/tmp/mcp-publisher auth login:*)",
+      "Bash(/tmp/mcp-publisher login:*)",
+      "Bash(/tmp/mcp-publisher publish:*)",
+      "WebFetch(domain:airc.nist.gov)",
+      "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/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-03-26
+
+### Added
+
+- **NIST AI RMF Framework Mappings** (`src/sanitizer/framework-mapper.ts`)
+  - Added NIST AI Risk Management Framework (AI 100-1) mappings for all 43 injection patterns
+  - Maps threats to four core functions: GOVERN, MAP, MEASURE, and MANAGE
+  - Examples: GOVERN-1.1 (Legal Requirements), MEASURE-2.7 (AI System Security), MANAGE-2.3 (Respond to Unknown Risks)
+  - Provides comprehensive risk management alignment for federal/government users
+
+- **NIST CSF 2.0 Framework Mappings** (`src/sanitizer/framework-mapper.ts`)
+  - Added NIST Cybersecurity Framework 2.0 mappings for all 43 injection patterns
+  - Maps threats to six core functions: IDENTIFY, PROTECT, DETECT, RESPOND, RECOVER, and GOVERN
+  - Examples: DE.CM-01 (Network Monitoring), PR.DS-01 (Data at Rest Protection), PR.AC-04 (Access Control)
+  - Widely adopted enterprise cybersecurity framework for compliance and audit requirements
+
+- **Enhanced Threat Reporting** (`src/sanitizer/threat-reporter.ts`)
+  - Expanded framework coverage from 4 to 6 compliance frameworks
+  - Updated TOON format from 10 fields to 12 fields (added nist_ai_rmf, nist_csf_2_0)
+  - Enhanced Markdown threat report table with new AI-RMF and CSF 2.0 columns
+  - All threat reports now include comprehensive 6-framework alignment
+
+### Changed
+
+- **Framework Badge** (README.md) - Updated security badge to highlight NIST AI RMF and CSF 2.0
+- **Tool Descriptions** (README.md) - All 4 MCP tools now reference 6 frameworks in their descriptions
+- **Framework Alignments Section** (README.md) - Expanded to document all 6 frameworks with descriptions
+- **Test Coverage** (tests/threat-reporter.test.ts) - Updated to verify 6 frameworks and 12 TOON fields
+
+### Fixed
+
+- **server.json Version Sync** - Ensured server.json version matches package.json per MCP Registry requirements
+
+## [0.8.1] - 2026-03-25
+
 ### Added
 
 - **PDF Content Handler** (`src/content-handlers/pdf-handler.ts`)
@@ -56,9 +91,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Tests for error handling (corrupt/invalid content)
   - Tests for edge cases (nested structures, arrays, malformed input)
 
+### Fixed
+
+- **PDF Text Extraction** - Fixed critical bug where PDF content was passed as corrupted UTF-8 strings instead of binary data
+  - Root cause: `response.text()` in `playwright-renderer.ts` converted all response bodies to strings, mangling binary PDFs
+  - Fix: Use `response.arrayBuffer()` for binary content types (`application/pdf`, `image/*`, `application/octet-stream`)
+  - Impact: PDF handler now receives proper binary data, text extraction works correctly
+  - Files modified: `src/types.ts`, `src/browser/playwright-renderer.ts`, `src/tools/fetch.ts`, `src/tools/read.ts`, `src/tools/fetch-structured.ts`
+  - Note: Some complex PDFs may fail with "Invalid Root reference" error - this is a limitation of the pdf-parse library, not Visus
+
 ### Changed
 
 - Added `pdf-parse` dependency (v2.4.5) for PDF text extraction
+- Updated `BrowserRenderResult.html` type to `string | Buffer` to support binary content
 
 ## [0.6.2] - 2026-03-14
 

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**