documentation: add ADR 0002 and rescope MSSQL extension to read-only credentials #341

Merged

david merged 1 commit from documentation/2026-11-11/mssql-read-only-credentials-adr into main

2026-11-10 23:31:43 +00:00

david commented

2026-11-10 23:30:29 +00:00

Owner

Summary

The MSSQL Stage 1 spike ended in a STOP: neither parser candidate reached zero false accepts (node-sql-parser 3, ANTLR4 T-SQL grammar 2). This PR records the owner's follow-up decision and rescopes the extension docs to match. Docs only; no code changes.

Decision (ADR 0002): read-only database credentials are the write control. The extension adds a minimal, dependency-free guard that catches accidents (not a security boundary), and a startup check that warns, and never blocks, when the login appears to have write access.

Files

docs/adr/0002-mssql-read-only-credentials-with-minimal-guard.md (new): context from the spike, the decision, options considered, and residual risks ([SECURITY RISK], [COMPLIANCE RISK], [BEST PRACTICE]).
extensions/mssql/docs/IMPLEMENTATION_PLAN.md: Stages 0 and 1 marked done (Stage 1 as STOP). Stage 2 no longer uses a parser. Task 2.7 is now the minimal guard, with the spike corpora reused as regression tests plus a known-gaps list. New tasks 2.7a/2.7b cover the permission check and warning. The README checklist and done criteria are updated.
extensions/mssql/docs/DESIGN.md: replaces the "parser is the only write block" section with a write-protection section, adds a spike outcome section, and updates the risk table, rollout and open items so the design no longer contradicts the ADR.

Notes for review

The write-access check covers sysadmin, db_owner/db_datawriter/db_ddladmin, and database-level INSERT/UPDATE/DELETE/ALTER/EXECUTE. It does not detect table-level grants or ownership chaining, so a clean result does not prove the login is read-only.
The guard's keyword denylist is broader than the original must-reject list (adds INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, CREATE, TRUNCATE). It will reject an unbracketed column named update. Worth a view on whether to trim it.
The spike directory is kept as a record. Removing its generated grammar output is listed as an open item.

## Summary The MSSQL Stage 1 spike ended in a STOP: neither parser candidate reached zero false accepts (`node-sql-parser` 3, ANTLR4 T-SQL grammar 2). This PR records the owner's follow-up decision and rescopes the extension docs to match. Docs only; no code changes. **Decision (ADR 0002):** read-only database credentials are the write control. The extension adds a minimal, dependency-free guard that catches accidents (not a security boundary), and a startup check that **warns, and never blocks**, when the login appears to have write access. ## Files - `docs/adr/0002-mssql-read-only-credentials-with-minimal-guard.md` (new): context from the spike, the decision, options considered, and residual risks ([SECURITY RISK], [COMPLIANCE RISK], [BEST PRACTICE]). - `extensions/mssql/docs/IMPLEMENTATION_PLAN.md`: Stages 0 and 1 marked done (Stage 1 as STOP). Stage 2 no longer uses a parser. Task 2.7 is now the minimal guard, with the spike corpora reused as regression tests plus a known-gaps list. New tasks 2.7a/2.7b cover the permission check and warning. The README checklist and done criteria are updated. - `extensions/mssql/docs/DESIGN.md`: replaces the "parser is the only write block" section with a write-protection section, adds a spike outcome section, and updates the risk table, rollout and open items so the design no longer contradicts the ADR. ## Notes for review - The write-access check covers `sysadmin`, `db_owner`/`db_datawriter`/`db_ddladmin`, and database-level `INSERT`/`UPDATE`/`DELETE`/`ALTER`/`EXECUTE`. It does not detect table-level grants or ownership chaining, so a clean result does not prove the login is read-only. - The guard's keyword denylist is broader than the original must-reject list (adds `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `DROP`, `ALTER`, `CREATE`, `TRUNCATE`). It will reject an unbracketed column named `update`. Worth a view on whether to trim it. - The spike directory is kept as a record. Removing its generated grammar output is listed as an open item.

david added 1 commit

2026-11-10 23:30:29 +00:00