lock family docs GitHub

Locks · locksql

Path to 1.0

locksql is pre-release (v0.x): any release may change the config files, the MCP tools or the CLI. 1.0 is the promise that they stop changing without notice. This page lists what has to be true first. Each item is checked off in the pull request that completes it.

Criteria #

Security work #

  • [ ] The parser and analyzer are fuzzed. Fuzz targets for sqlast.Parse and sqlast.Analyze run nightly in CI, and a metamorphic suite checks that rewrites that keep a statement's meaning (aliases, parentheses, CTE wrapping, derived tables, case) keep its masking, in every dialect.
  • [ ] A PII canary test runs on real engines. Known canary values seeded in MariaDB, MySQL and PostgreSQL (every version CI tests) never come back unmasked through any statement the console accepts, under go test -tags integration.
  • [ ] TLS is passed to the driver. Every engine forwards the tls settings with the driver's semantics and enforces nothing else; integration tests cover verify-full success and failure with a self-signed CA, and a plaintext connection gets its one warning.
  • [ ] Refusals are actionable. Every refusal carries a code, a test enumerates them, and the agent instructions written by locksql init say how to retry for each code.
  • [ ] An external review is published. Someone other than the maintainers has reviewed the threat model and internal/sqlast, and the report is linked from SECURITY.md, with the fixes it led to.
  • [ ] A second reviewer. At least one person besides the maintainer has merge rights, and is a code owner of internal/sqlast, internal/pii and internal/console in .github/CODEOWNERS.

Frozen contracts #

  • [ ] Config schema. The keys, types and defaults of .locksql/config.toml, .locksql/pii.toml and /etc/locksql/system.toml are listed in one reference and frozen for 1.x.
  • [ ] MCP tool schema. The tool names (locksql_status, locksql_list_tables, locksql_describe, locksql_plan, locksql_run, locksql_pii_list, locksql_pii_add, locksql_request_change), their input fields and their result shapes are frozen for 1.x, with a test that fails when one changes.
  • [ ] CLI and exit codes. Command names, flags, --json output and the exit codes (0, 1, 2, 3) are frozen for 1.x.
  • [ ] Socket protocol. ProtocolMajor (now 1) and the methods it covers are frozen for 1.x.
  • [ ] Upgrade notes. Each release lists, under "Upgrading", what a user must do, and a 0.x → 1.0 note covers every change since the last 0.x.

Versioning policy from 1.0 #

Semantic versioning, applied to the contracts above:

  • Patch (1.0.x): fixes. A fix may refuse a statement that was accepted before, when accepting it was a leak or a bypass: refusing more is how a security tool fails closed, and is not a breaking change.
  • Minor (1.x): additions. New config keys with defaults that keep the previous behaviour, new MCP tools, new optional tool fields, new result fields, new CLI flags, new refusal codes. A new default may only tighten (for example a stricter TLS default), and the release notes say so under "Upgrading".
  • Major (2.0): removing or renaming a config key, an MCP tool, a tool field or a CLI flag; changing a field's type or meaning; loosening a default. A key that is going away is first deprecated in a minor release, with a warning on the console and in locksql doctor, and works until the next major.
  • The console and its clients come from the same release. A client and a console with different socket protocol majors refuse to talk; the protocol major changes only with a major release.
  • Unknown config keys stay errors, so a typo never silently loosens a policy. A config written for 1.y therefore loads in 1.z only when z ≥ y.

What is not covered: the console's screen, the wording of messages and refusal reasons (agents must use the codes), the audit log's field order (its field names are covered), and the Go packages under internal/.

Upgrade notes #

Until 1.0, breaking changes are announced in the release notes and in the README where they apply (for example the tls default in v0.4). The 0.x → 1.0 notes will be collected here when 1.0 is cut.