# v1.1.0 — Security, Structured Errors & Developer Experience

## Highlights

- **🧪 Exhaustive E2E Test Suite** — 12 Playwright specs + 6 gap-closing spec files covering dual-adapter (WASM + Native) and dual-transport (SSE + Streamable HTTP) scenarios. Total E2E coverage now exceeds 300 tests.
- **🔒 Deterministic Structured Errors** — Every tool across all 9 groups now returns `{success: false, error, code, category, suggestion, recoverable}` on failure instead of raw MCP `-32602` frames. ~108 handler catch blocks migrated.
- **🧩 Introspection & Migration Tool Groups** — 12 new tools for read-only schema analysis (dependency graphs, topological sorts, cascade simulation, schema snapshots) and opt-in migration lifecycle management with SHA-256 deduplication.
- **💻 Code Mode (Sandboxed Execution)** — `sqlite_execute_code` lets agents write JavaScript against `sqlite.*` API for 70–90% token reduction. Dual sandbox modes (worker_threads / vm), security validation, rate limiting.
- **🔐 OAuth 2.1 Foundation** — Full scope hierarchy (`read ⊂ write ⊂ admin ⊂ full`), transport-agnostic auth, AsyncLocalStorage context threading, and 8 new auth unit test files.

---

## Added

- **Introspection Tool Group** — 6 read-only tools: `dependency_graph`, `topological_sort`, `cascade_simulator`, `schema_snapshot`, `constraint_analysis`, `migration_risks`
- **Migration Tool Group** — 6 tools: `migration_init`, `migration_record`, `migration_apply`, `migration_rollback`, `migration_history`, `migration_status`
- **Code Mode** — `sqlite_execute_code` sandboxed JavaScript execution with `sqlite.*` API bridge, help(), aliases, and positional params
- **`sqlite_drop_index`** — New core tool with existence pre-validation
- **Dual HTTP Transport** — Simultaneous Streamable HTTP (MCP 2025-03-26) + Legacy SSE (MCP 2024-11-05) with cross-protocol session guards
- **Tool Icons** — All tools, resources, and prompts include Material Design Icons via MCP 2025-11-25 spec
- **Help Resources** — `sqlite://help` and `sqlite://help/{group}` pull-based reference docs (9 groups)
- **Performance Benchmark Suite** — 9 benchmark files measuring framework overhead on critical hot paths
- **OAuth Enhancements** — `full` scope, `TOOL_GROUP_SCOPES` mapping, scope utilities, scope-map, auth-context, transport-agnostic auth
- **Transport Features** — `trustProxy`, opt-in HSTS, wildcard subdomain CORS, server host binding
- **Security Headers** — 7 headers on all HTTP responses (CSP, X-Frame-Options, HSTS, etc.)
- **Rate Limiting** — Per-IP sliding-window (100 req/min), health exempt
- **Body Size Enforcement** — 1 MB JSON limit with 413 response

## Security

- Removed `.strict()` from all Zod input schemas (prevented structured error handling)
- SQL injection guard on savepoint names
- DNS rebinding protection via `localhostHostValidation()` middleware
- SHA-pinned all GitHub Actions across 4 CI workflows
- Bumped Actions to latest major versions (Node 24 runtime)
- WHERE clause validation added to 15 previously unguarded JSON tool SQL interpolation points
- Table name regex guard added to native adapter's `describeTable` fallback
- HTTP server timeouts (120s request, 65s keep-alive, 66s headers) against slowloris DoS
- Docker Scout gate hardened to fail-fast on scan errors
- Fixed transitive vulnerabilities: `minimatch` ReDoS, `hono` multiple CVEs, `express-rate-limit` IPv6 bypass

## Changed

- **Error Handling Overhaul** — All ~115 output schemas include `ErrorFieldsMixin`; ~108 catch blocks migrated to `formatHandlerError()`
- **File Modularity** — Split 8+ oversized files (500–986 lines) into directory modules with barrel exports
- **File Naming** — Renamed 19 PascalCase/camelCase files to kebab-case
- **Help Architecture** — Replaced `--instruction-level` with pull-based `sqlite://help` resources
- **Code Quality** — 35+ generic `Error` → `DbMcpError`, shared WAL/JSONB/PRAGMA/extension helpers, logger module split, types file split, dead code removal
- **Deterministic Error Handling** — Structured responses across all tools with specific error codes (`TABLE_NOT_FOUND`, `COLUMN_NOT_FOUND`, `DIMENSION_MISMATCH`, etc.)
- **Column Existence Validation** — All text, stats, and geo tools validate columns before query execution
- **Parameter Aliases** — `resolveAliases()` for backward compatibility (`tableName`→`table`, `sql`→`query`)
- **Dockerfile** — Removed builder `apk upgrade`, fixed tool count label (124→139)

## Fixed

- **200+ bug fixes** including: output schema leaks, validation refinement leaks, enum coercion, dimension validation, FTS5 WASM crashes, Code Mode positional params, restore/backup path resolution, migration dedup scope, window function annotations, and more
- **Error Code Refinement** — `DbMcpError` subclasses auto-refine generic codes to specific ones (`DB_QUERY_FAILED` → `TABLE_NOT_FOUND`)
- **Input Coercion** — 50+ parameters now use `z.preprocess()` so wrong-type inputs fall to defaults instead of raw MCP errors
- **Payload Optimization** — System tables excluded by default in `list_tables`, `get_indexes`, `schema_snapshot`, `storage_analysis`, `dependency_graph`, `topological_sort`
- **Post-Review Hardening** — CTE write support, semicolon normalization before LIMIT injection, SQL injection hardening via parameterized queries in `get_indexes`/`index_stats`, N+1 column validation batch optimization, structured savepoint errors, WASM capability accuracy

## Performance

- Compact JSON serialization (~15-20% reduction on large payloads)
- Incremental TypeScript builds
- Vitest thread pool parallelism
- SchemaManager TTL-based caching for native adapter
- Logger regex pre-compilation and taint-breaking optimization
- SQL validation regex hoisted to module scope
- CI `node_modules` caching (20-30s savings per run)

## Dependencies

- Bumped `@eslint/js` 9.39.2→10.0.1, `eslint` 9.39.2→10.0.3 (major)
- Bumped `@modelcontextprotocol/sdk` 1.25.3→1.27.1
- Bumped `better-sqlite3` 12.6.2→12.8.0
- Bumped `sql.js` 1.13.0→1.14.1, `jose` 6.1.3→6.2.1
- Bumped `vitest`/`@vitest/coverage-v8` 4.0.18→4.1.0
- Removed unused `pg`, `@types/pg`, `dotenv`

---

**Full Changelog**: [v1.0.2...v1.1.0](https://github.com/neverinfamous/db-mcp/compare/v1.0.2...v1.1.0)

**Install**:

```bash
npm install @neverinfamous/db-mcp@1.1.0
```

```bash
docker pull neverinfamous/db-mcp:1.1.0
```
