{ "openapi": "3.1.0", "info": { "title": "SQLPermit", "version": "0.1.0", "summary": "Deterministic PostgreSQL statement policy checks with a signed, statement-bound execution permit.", "description": "SQLPermit parses a candidate statement with PostgreSQL's own grammar (libpg-query, PG 18), walks the syntax tree, and reports whether it complies with the policy you supply — read-only, schema and table allowlists, row ceilings, a function allowlist, single-statement enforcement. Detection is structural, so comments, dollar quoting, Unicode escapes, and stacked statements cannot hide a construct from it. On a compliant statement it can issue a signed Ed25519 permit, valid for seconds, bound to the sha256 of the deparsed canonical statement so it cannot be moved onto a different one. An offline reference verifier is published for your executor. What it cannot do: it never connects to your database, so it cannot see your schema, cannot resolve search_path, and cannot know the role a statement will run as. It is defence in depth alongside a least-privilege database role, not a replacement for one.", "contact": { "email": "security@schemasure.com" }, "x-policy-version": "sqlpermit-policy-1.0.0" }, "servers": [ { "url": "https://sqlpermit.schemasure.com" } ], "paths": { "/v1/guard/sql": { "post": { "operationId": "sqlpermit_v1_guard_sql", "summary": "Check a PostgreSQL statement against an execution policy and optionally issue a signed permit", "description": "Decide whether an agent-authored PostgreSQL statement complies with an execution policy, using PostgreSQL's own parser rather than pattern matching. Detects statement stacking, data-modifying CTEs, COPY PROGRAM, privilege changes, and dangerous functions that read as ordinary SELECTs. Returns reason codes and an optional short-lived signed permit bound to the exact normalized statement. Never connects to your database.", "x-payment-info": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amountAtomic": "10000", "priceUsd": 0.01, "payTo": "0x9876af0F6D8Ed5155Cd02d1ca56D128601612690", "policy": "charge only on a successful, usable result" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dialect", "target_pg_major", "sql" ], "additionalProperties": false, "properties": { "dialect": { "type": "string", "enum": [ "postgresql" ] }, "target_pg_major": { "type": "integer", "enum": [ 18 ], "description": "Required. The PostgreSQL major the statement will run on. Only 18 is supported in v1: a permit issued under one grammar and verified against another is a parser differential." }, "sql": { "type": "string", "minLength": 1, "maxLength": 100000 }, "policy": { "type": "object", "additionalProperties": false, "properties": { "read_only": { "type": "boolean", "description": "Reject anything that can change data or schema, including writes reached through a CTE." }, "allowed_schemas": { "type": "array", "items": { "type": "string" }, "description": "Schemas the statement may reference." }, "allowed_tables": { "type": "array", "items": { "type": "string" }, "description": "Permitted relations as schema.table, or a bare name to match an unqualified reference." }, "max_rows": { "type": "integer", "minimum": 1, "description": "Row ceiling. Becomes a permit obligation the executor enforces." }, "allowed_functions": { "type": "array", "items": { "type": "string" }, "description": "Added to the built-in allowlist. Bare name, or schema.function to admit one of your own." }, "allow_multi_statement": { "type": "boolean", "description": "Permit more than one statement in the input. Defaults to false." }, "allowed_languages": { "type": "array", "items": { "type": "string" }, "description": "Permitted CREATE FUNCTION languages. Defaults to none." }, "allow_row_locks": { "type": "boolean", "description": "Accept SELECT ... FOR UPDATE without a warning." }, "allow_returning": { "type": "boolean", "description": "Accept RETURNING on a permitted write without a warning." }, "statement_timeout_ms": { "type": "integer", "minimum": 1, "description": "Timeout written into the permit obligations. Defaults to 30000." } } }, "audience": { "type": "string", "description": "Identity of the ONE executor the permit is for. Required when issue_permit is true. Wildcards are rejected." }, "issue_permit": { "type": "boolean" }, "subject": { "type": "string", "description": "Opaque caller label recorded as the permit subject." } } }, "example": { "dialect": "postgresql", "target_pg_major": 18, "sql": "SELECT id, total FROM analytics.orders ORDER BY created_at DESC LIMIT 100", "policy": { "read_only": true, "allowed_schemas": [ "analytics" ], "allowed_tables": [ "analytics.orders" ], "max_rows": 1000, "allowed_functions": [ "count", "sum", "avg" ], "allow_multi_statement": false }, "audience": "executor:acme-prod-01", "issue_permit": true } } } }, "responses": { "200": { "description": "Successful result envelope", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verdict", "confidence", "risk_codes", "evidence", "result", "policy_version", "request_hash", "data_versions", "warnings" ], "properties": { "ok": { "type": "boolean" }, "verdict": { "type": "string", "enum": [ "pass", "warn", "block" ] }, "confidence": { "type": "number" }, "risk_codes": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "object", "required": [ "code", "severity", "detail", "disposition" ], "properties": { "code": { "type": "string", "description": "Stable reason code, e.g. DATA_MODIFYING_CTE." }, "severity": { "type": "string", "enum": [ "info", "low", "medium", "high", "critical" ] }, "disposition": { "type": "string", "enum": [ "block", "warn", "info" ] }, "detail": { "type": "string" }, "source": { "type": "string" }, "span": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } }, "data": { "type": "object" } } } }, "policy_version": { "type": "string" }, "request_hash": { "type": "string" }, "data_versions": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "required": [ "statement_count", "statement_types", "referenced_schemas", "referenced_tables", "referenced_functions", "classification", "findings", "normalized_sql", "stmt_hash", "stmt_fingerprint", "policy_hash", "grammar", "target_pg_major", "obligations" ], "properties": { "statement_count": { "type": "integer" }, "statement_types": { "type": "array", "items": { "type": "string" } }, "referenced_schemas": { "type": "array", "items": { "type": "string" } }, "referenced_tables": { "type": "array", "items": { "type": "string" } }, "referenced_functions": { "type": "array", "items": { "type": "string" } }, "classification": { "type": "string", "enum": [ "read_only", "write", "ddl", "mixed" ] }, "findings": { "type": "array", "items": { "type": "object", "required": [ "code", "severity", "detail", "disposition" ], "properties": { "code": { "type": "string", "description": "Stable reason code, e.g. DATA_MODIFYING_CTE." }, "severity": { "type": "string", "enum": [ "info", "low", "medium", "high", "critical" ] }, "disposition": { "type": "string", "enum": [ "block", "warn", "info" ] }, "detail": { "type": "string" }, "source": { "type": "string" }, "span": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } }, "data": { "type": "object" } } } }, "normalized_sql": { "type": "string", "description": "Deparsed canonical statement. This, not your original text, is what a permit binds." }, "stmt_hash": { "type": "string", "description": "BINDING. sha256 of normalized_sql. The executor recomputes this from the statement it is about to run." }, "stmt_fingerprint": { "type": "string", "description": "ADVISORY ONLY — never authorize on this. libpg-query fingerprints discard literal constants, so 'WHERE id = 1' and 'WHERE id = 999999' share one fingerprint." }, "policy_hash": { "type": "string" }, "grammar": { "type": "string" }, "target_pg_major": { "type": "integer" }, "obligations": { "type": "object", "required": [ "max_rows", "statement_timeout_ms", "require_read_only_tx" ], "properties": { "max_rows": { "type": [ "integer", "null" ] }, "statement_timeout_ms": { "type": "integer" }, "require_read_only_tx": { "type": "boolean" } } }, "permit": { "type": "string", "description": "Compact JWS. Present only when requested and the verdict is not block." }, "permit_expires_at": { "type": "string" }, "permit_kid": { "type": "string" } } } } }, "example": { "ok": true, "verdict": "pass", "confidence": 1, "risk_codes": [], "evidence": [], "result": { "statement_count": 1, "statement_types": [ "SelectStmt" ], "referenced_schemas": [ "analytics" ], "referenced_tables": [ "analytics.orders" ], "referenced_functions": [], "classification": "read_only", "findings": [], "normalized_sql": "SELECT id, total FROM analytics.orders ORDER BY created_at DESC LIMIT 100", "stmt_hash": "sha256:0f4c1d8e2b7a9c5d3e6f8a1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d", "stmt_fingerprint": "a1b2c3d4e5f60718", "policy_hash": "sha256:2b7a9c5d3e6f8a1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d0f4c1d8e", "grammar": "pg18/libpg-query@18.1.4", "target_pg_major": 18, "obligations": { "max_rows": 1000, "statement_timeout_ms": 30000, "require_read_only_tx": true }, "permit": "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoi…", "permit_expires_at": "2026-08-03T12:00:45.000Z", "permit_kid": "uGzLTTwi4LTsOiBLgwf2wMU7ILTecj18Y_71Y37bVD8" }, "policy_version": "sqlpermit-policy-1.0.0", "request_hash": "sha256:1c2d0f4c1d8e2b7a9c5d3e6f8a1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b", "data_versions": { "grammar": "pg18/libpg-query@18.1.4", "parser": "libpg-query@18.1.4", "pg_parse_version": "180004" }, "warnings": [ "stmt_fingerprint is ADVISORY and must not be used for authorization: libpg-query fingerprints discard literal constants, so two statements differing only in a value share one fingerprint. stmt_hash is the binding value." ] } } } }, "400": { "description": "INPUT_INVALID", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "402": { "description": "Payment required. Body carries the x402 challenge; see PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "422": { "description": "UNSUPPORTED or INDETERMINATE. Not charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "502": { "description": "Upstream or facilitator unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "504": { "description": "UPSTREAM_TIMEOUT", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }