62 lines
4.4 KiB
Markdown
62 lines
4.4 KiB
Markdown
# mysql-readonly-tool Specification
|
|
|
|
## Purpose
|
|
|
|
Define a fail-closed, parameterized, read-only MySQL evidence Tool that reuses ToolBoundary and exposes only bounded ACI results.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: SQL validation SHALL fail closed on a conservative SELECT subset
|
|
|
|
The Tool SHALL parse exactly one SQL statement with JSqlParser and SHALL accept only a single `SELECT` with explicit projection columns, supported predicates/grouping/ordering, `INNER JOIN` or `LEFT JOIN`, parameter placeholders and allowlisted functions. It SHALL reject writes, CTEs, subqueries, set operations, wildcard projections except `COUNT(*)`, metadata discovery, unsupported joins/functions, `FOR UPDATE`, multiple statements and unknown/ambiguous AST structures.
|
|
|
|
#### Scenario: Reject unsupported SQL before execution
|
|
|
|
- **WHEN** an agent submits a write statement, a second statement, a subquery, or an unallowlisted function
|
|
- **THEN** validation fails closed and no JDBC execution is attempted
|
|
|
|
### Requirement: Data-source and identifier authorization SHALL use exact independent allowlists
|
|
|
|
The Tool SHALL accept only a logical `data_source` ID and SHALL authorize every schema, table and column used in projection, join, predicate, grouping and ordering against the configured exact allowlist. It SHALL reject unknown data sources, schemas, tables, columns, aliases and ambiguous unqualified columns. Agent input SHALL NOT provide JDBC coordinates or authorization controls.
|
|
|
|
#### Scenario: Reject an identifier outside the configured allowlist
|
|
|
|
- **WHEN** a valid-looking query references an unknown data source, table, column, alias, or ambiguous unqualified column
|
|
- **THEN** authorization fails before connection creation and agent-provided JDBC coordinates are ignored
|
|
|
|
### Requirement: Parameter binding and JDBC execution SHALL be read-only and bounded
|
|
|
|
The executor SHALL use a configured logical datasource, a read-only JDBC connection, `PreparedStatement` parameter binding, query timeout, max rows and Run cancellation/deadline checks. Placeholder count SHALL exactly match `params`. The executor SHALL not expose connection details or raw JDBC failures to the Agent.
|
|
|
|
#### Scenario: Execute an authorized query within read-only bounds
|
|
|
|
- **WHEN** an authorized query has exactly matching parameters and an active Run
|
|
- **THEN** it executes through a read-only prepared statement with timeout and row limits, while cancellation or a deadline stops execution and raw JDBC details remain hidden
|
|
|
|
### Requirement: MySQL projection SHALL be bounded and evidence-aware
|
|
|
|
The projector SHALL expose only ordered columns, bounded JSON-safe rows, returned count and truncation. It SHALL enforce row, cell and total UTF-8 limits, redact sensitive column values, return `NO_EVIDENCE` for a successful empty result, and never expose raw JDBC metadata or credentials.
|
|
|
|
#### Scenario: Project bounded rows and empty evidence safely
|
|
|
|
- **WHEN** JDBC returns rows containing oversized or sensitive values, or returns a successful empty result
|
|
- **THEN** the projection redacts and bounds values, reports truncation when data is removed, and returns `NO_EVIDENCE` for the empty result without exposing metadata or credentials
|
|
|
|
### Requirement: MySQL Tool SHALL reuse canonical Harness ownership
|
|
|
|
The adapter SHALL pass the exact framework `tool_call_id` and RunContext through the existing ToolBoundary and canonical invocation store. It SHALL not create a second ID, use a parallel store, return raw SQL results, or modify legacy audit/public runtime paths.
|
|
|
|
#### Scenario: Preserve framework invocation identity
|
|
|
|
- **WHEN** the adapter invokes an authorized MySQL query
|
|
- **THEN** ToolBoundary and the canonical invocation store receive the exact framework `tool_call_id` and RunContext, with no second identifier or parallel raw-result path
|
|
|
|
### Requirement: The query helper script SHALL be read-only and secret-free by default
|
|
|
|
The repository query helper SHALL require connection values from environment variables, reject non-SELECT and metadata discovery SQL before connection, and SHALL NOT commit writes or expose hardcoded external connection defaults.
|
|
|
|
#### Scenario: Reject unsafe helper SQL without connecting
|
|
|
|
- **WHEN** the helper receives a non-`SELECT` or metadata-discovery statement, or missing environment connection values
|
|
- **THEN** it exits before opening a connection and does not reveal or invent credentials or external connection defaults
|