# SQLGuard Executor — cert-gated Postgres writes

x402 funds **certificate issuance**. Authorization is enforced here **when enabled**.

**Public host default: OFF.** Check `GET /health` → `executor.enabled`. If false, `POST /v1/execute` returns **503** `EXECUTOR_DISABLED` — run verified SQL yourself after `/v1/verify`.

## Topology (when enabled)

```
agent ──► SQLGuard /v1/cert (pay Exact) ──► PASS Ed25519 cert
agent ──► SQLGuard /v1/execute (cert + sql) ──► Postgres
                                                    ▲
                         only executor holds DB URL ┘
```

1. Agents **must not** receive the production DB connection string.
2. Network / `pg_hba.conf` should allow the write role **only from the executor host**.
3. Use a least-privilege Postgres role (DML on needed tables only; no SUPERUSER).

## Enable

```bash
SQLGUARD_EXECUTOR_ENABLED=1
SQLGUARD_EXECUTOR_DATABASE_URL=postgres://writer:...@db/app
```

If `SQLGUARD_EXECUTOR_DATABASE_URL` is empty, executor falls back to `DATABASE_URL` when enabled.

`GET /health` reports `{ executor: { enabled, database_configured } }`.

## API

`POST /v1/execute`

```json
{
  "schema_ddl": "CREATE TABLE users (id int primary key, email text);",
  "sql": "INSERT INTO users (id, email) VALUES (1, 'a@b.co');",
  "certificate": { "...PASS cert from /v1/cert..." },
  "signature": "<ed25519>"
}
```

Checks (fail closed):

- Ed25519 signature + `status=PASS` + not expired + not demo
- `sql_hash` / `schema_hash` bind to the exact payload
- Single statement only (no multi-statement / transaction control)
- `cert_id` consumed once (replay → 409)

## Curl (after Instant Cert settle)

```bash
curl -sS -X POST "$BASE/v1/execute" \
  -H 'content-type: application/json' \
  -d @certified-write.json
```

## Security note for reviewers

Payment ≠ authorization. `/v1/execute` refuses any mutation without a verified, unused, hash-bound PASS certificate. Direct DB access outside this path voids the control — isolate the port.