@carllee1983/dbcli 11.0.0 → 12.1.0

package/assets/reference.md

@@ -157,7 +157,7 @@ Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `
 
 New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
 
-**Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
+**Key options:** `--sql-tls verify-full`, `--sql-tls-ca <path>`, `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
@@ -193,6 +193,57 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
 
+#### Verified TLS for PostgreSQL, MySQL and MariaDB
+
+Use both SQL TLS flags when creating a named PostgreSQL, MySQL or MariaDB profile. This example prompts for the password and tests the connection before saving:
+
+```bash
+dbcli init --conn-name verified-pg --system postgresql \
+  --host db.example.com --port 5432 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/root-ca.pem
+dbcli --use verified-pg blacklist list
+dbcli --use verified-pg schema public.events --format json
+dbcli --use verified-pg query "SELECT id FROM public.events LIMIT 10" --format json
+```
+
+MySQL and MariaDB use the same flags, with separate named profiles and CA paths. Select the corresponding profile, then check blacklist and schema before an authorized query:
+
+```bash
+dbcli init --conn-name verified-mysql --system mysql \
+  --host mysql.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mysql-ca.pem
+dbcli init --conn-name verified-mariadb --system mariadb \
+  --host mariadb.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mariadb-ca.pem
+```
+
+Replace the host, database and table with your authorized target; confirm real columns through schema before querying. The saved connection includes this dedicated SQL object (shown as a connection fragment):
+
+```json
+{
+  "sqlTls": {
+    "mode": "verify-full",
+    "caPath": "/absolute/path/to/certs/root-ca.pem"
+  }
+}
+```
+
+`--sql-tls verify-full` and `--sql-tls-ca <path>` are required together. Empty values, other modes and unsupported engines fail explicitly. PostgreSQL, MySQL and MariaDB support this SQL TLS contract; all other engines reject an explicit request. MongoDB's `tls` and Elasticsearch's TLS settings remain separate. Existing profiles without `sqlTls` keep their previous behavior; no global TLS policy is added. V1 directory and v2 profile reads, normal `init` import from a V1 directory to v2, and the public `migrateV1ToV2` helper preserve the TLS object. A legacy V1 single-file TLS profile remains readable and usable in human mode, but automatic `init` import explicitly refuses it before connecting or writing and leaves the original untouched. For that case, create a verified named profile in a separate configuration directory, verify it, then select it; preserve `sqlTls` throughout migration.
+
+`init` resolves a relative CA path against its current working directory before saving. Saved `caPath` must be a nonempty absolute literal path to a PEM CA bundle; it accepts no environment-variable reference. Existing environment references in host/user and other supported fields remain usable. Explicit TLS uses only the selected profile’s CA and identity settings; ambient TLS settings cannot weaken verification or supply another profile’s trust. Each new connection reads the CA bundle again; an unreadable, empty or invalid bundle stops before connecting. `--skip-test` skips only the initialization test, not verification on subsequent use.
+
+`verify-full` requires encryption, a trusted certificate chain, valid certificate dates and certificate identity matching the configured DNS name or IP address. Unix sockets are refused for explicit SQL TLS. Untrusted, expired or mismatched certificates and servers without TLS fail before the user query; there is no plaintext retry or verification downgrade. Correct the CA, target hostname or certificate validity before retrying. A cipher alone does not prove identity verification.
+
+For TLS error recovery, keep TLS configured and repair the CA, hostname or certificate first. Then deliberately select the configuration with `--config <path>` (or `--global`) and, for v2, the named profile with `--use <name>` (`DBCLI_CONNECTION` is also accepted). The selected profile must still have `sqlTls.mode: verify-full`; missing, ambiguous or plaintext selections block live recovery steps instead of falling back to a default plaintext connection. Saved recovery envelopes redact the original selectors: your current selection is deliberate targeting, not proof of the original target. Recovery apply and verification use the current CLI binary, avoiding an older `dbcli` on PATH. For the MySQL example above:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+Permitted reads through an already configured profile remain usable in agent mode; `init` and other configuration mutations remain refused under `DBCLI_AGENT_MODE=1`. TLS does not bypass explicit production selection, native database authorization, permission, blacklist, write-gate or audit controls.
+
+For binary rollback, stop workflows that require verified TLS or keep a supporting version. Older binaries may strip `sqlTls`; retaining the profile after downgrading does not preserve the guarantee. Removing TLS settings or retrying in plaintext cannot restore compliance. Local isolated PostgreSQL, MySQL and MariaDB fixture results are not evidence of real RDS acceptance; RDS remains unverified.
+
 ### use
 
 Set, clear, or display the default database connection (v2 multi-connection config).
@@ -1731,6 +1782,8 @@ Every actionable block carries machine-readable next steps so an agent can move
 
 ### capabilities
 
+`connection.tls` reports PostgreSQL, MySQL and MariaDB support from the engine capability matrix and maps to the existing connection command surfaces; it adds no TLS subcommand. Check with `dbcli --use verified-pg capabilities check --require connection.tls --format json`. `available` means tool support only: it does not prove that this profile configures TLS, the CA is readable, the handshake succeeds, or the operation is authorized. Catalog/check remain offline, read no CA bundle, perform no handshake and change no configuration. Other engines do not report this capability as available; older binaries without the ID return `unknown`. Configuration mutation still requires its own authorization.
+
 Discovery. Lists the static dbcli capability catalog — what this tool can do,
 described in a versioned shape an external Skill can parse before it starts
 working. It never opens a database connection and never writes anything.
@@ -1868,8 +1921,11 @@ at execution time, and no human has agreed to anything. `admin` in a config file
 is a permission level, not a DBA sign-off.
 
 `schema.read` is available under `DBCLI_AGENT_MODE=1`, and `dbcli schema` runs
-there: storing the schema cache is not a configuration change. Agent mode still
-refuses every change to connection identity, permission and credentials.
+there: storing the schema cache is not a configuration change. `blacklist.read`
+(`blacklist list`) is available there too, so read-only Task Packs that inspect
+the blacklist can plan; `blacklist.manage`, which adds and removes rules, is
+refused. Agent mode still refuses every change to connection identity,
+permission and credentials.
 
 **Permission:** query-only+ (no connection is made)
 

package/assets/tasks/README.md

@@ -33,4 +33,4 @@ The markdown body below the frontmatter is `Agent Notes` and is shown in
 
 Use `postgresql` for PostgreSQL. The legacy `postgres` engine spelling is read
 as `postgresql`; legacy requirement names `blacklist-list` and `schema-check`
-are rejected with their replacements, `blacklist.manage` and `schema.read`.
+are rejected with their replacements, `blacklist.read` and `schema.read`.

package/assets/tasks/analyze-table-perf.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/audit-permissions.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
 steps:
   - type: command
     command: status

package/assets/tasks/connection-health.md

@@ -12,8 +12,7 @@ params:
     enum: [health, capacity, perf]
 safety:
   mode: plan-only
-  requires:
-    - blacklist.manage
+  requires: []
 steps:
   - type: command
     command: status

package/assets/tasks/design-review.md

@@ -6,7 +6,7 @@ engines: [postgresql, mysql]
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/diagnose-slow-query.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/migration-review.md

@@ -15,7 +15,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command
@@ -37,5 +37,7 @@ Use this task before applying a schema migration. It only PLANS — it never run
 Save the pre-change `schema {{table}} --format json` output as the baseline. After the
 migration is applied (out of band, via your migration tool), re-run
 `schema {{table}} --format json` and diff the two to confirm the change matches intent.
-Always prepare and record an explicit rollback statement before applying. Requires
-data-admin permission to actually run DDL — this task does not grant it.
+Always prepare and record an explicit rollback statement before applying.
+Read-only planning and review need no elevated permission beyond this task's existing
+requirements. Running DDL out of band requires `admin` permission — this task neither
+grants that permission nor runs DDL.

package/assets/tasks/mongo-safe-backfill.md

@@ -19,7 +19,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/mongo-schema-drift-review.md

@@ -15,7 +15,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/orm-drift-review.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/pr-database-review.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/safe-backfill-verify.md

@@ -23,7 +23,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/safe-backfill.md

@@ -15,7 +15,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command
@@ -34,9 +34,15 @@ steps:
 # Agent Notes
 
 Use this task when a user wants to backfill or correct existing rows. This task only
-PLANS — it never writes. After reviewing the plan, run the real backfill manually in
-two steps: first `dbcli update ... --dry-run` (or `dbcli query "<sql>" --dry-run`) to
-preview the generated SQL, then re-run with `--execute` only once the dry-run looks
-correct. Prefer a narrow `WHERE` clause and verify the affected row count with a
-read-only `SELECT count(*)` before writing. Requires read-write (or higher) permission
-to actually execute.
+PLANS — it never writes. After reviewing the plan, run the real backfill manually:
+
+1. Confirm a narrow `WHERE` clause and capture its scope with a read-only
+   `SELECT count(*)` before writing.
+2. Preview the structured write with
+   `dbcli update <table> --where "<predicate>" --set '<json>' --dry-run`.
+   Keep raw SQL writes in `dbcli plan "<sql>"`; `query` does not dry-run arbitrary writes.
+3. Once the preview looks correct, re-run the write command without `--dry-run`
+   and with the required confirmation/force flag for your environment. The existing
+   write gate still applies; execution requires read-write (or higher) permission.
+4. Read the rows back afterwards to confirm the backfill achieved its goal. If the
+   result does not match, stop and investigate before attempting another write.

package/assets/tasks/schema-drift-review.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/slow-endpoint-investigation.md

@@ -15,7 +15,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
 steps:
   - type: command
     command: blacklist list