Add Postgres signed authorization registry

Author: sl5-guy

Cargo.lock

@@ -29,6 +29,10 @@ opentelemetry = "0.31"
 opentelemetry_sdk = { version = "0.31", features = ["rt-tokio"] }
 opentelemetry-otlp = { version = "0.31", features = ["grpc-tonic"] }
 anyhow = "1"
+sqlx = { version = "0.8.6", default-features = false, features = ["runtime-tokio-rustls", "postgres", "chrono", "migrate", "macros", "derive"] }
+chrono = { version = "0.4.44", features = ["serde"] }
+sha2 = "0.11.0"
+p256 = { version = "0.13.2", features = ["ecdsa", "pkcs8"] }
 
 [dev-dependencies]
 rcgen = { version = "0.14", features = ["x509-parser"] }

Cargo.toml

@@ -2,7 +2,7 @@
 
 An mTLS HTTP/2 CONNECT proxy that authorizes connections based on custom X.509 certificate extensions.
 
-The proxy accepts incoming mTLS connections, extracts a custom extension value from the client certificate, and checks it against a TOML policy file to decide whether the client may connect to the requested destination. If allowed, it opens a raw TCP connection to the destination and tunnels data bidirectionally. The client is responsible for establishing its own TLS session to the destination through the tunnel.
+The proxy accepts incoming mTLS connections, extracts a custom extension value from the client certificate, and checks a PostgreSQL-backed signed permission registry to decide whether the client may connect to the requested destination. If allowed, it opens a raw TCP connection to the destination and tunnels data bidirectionally. The client is responsible for establishing its own TLS session to the destination through the tunnel.
 
 ## Building
 
@@ -22,6 +22,9 @@ sudo apt-get install libtss2-dev swtpm tpm2-tools pkg-config
 ```bash
 ./examples/generate-certs.sh          # server CA + gateway cert under certs/
 cp config.example.toml config.toml    # edit to taste
+docker compose -f docker-compose.postgres.yml up -d
+export AGENT_GATEWAY_DATABASE_URL=postgres://agent_gateway_admin:agent_gateway_dev@localhost:5432/agent_gateway
+cargo run -- --config config.toml migrate
 ```
 
 `generate-certs.sh` only creates **server** TLS material (`server-ca.pem`, `server.pem`, ...). Each agent platform enrolls with `./examples/connect.sh`, which starts a local `swtpm`, creates a persistent P-256 signing key in that simulated TPM, and issues `machine-client.pem` for the TPM public key. The gateway needs the generated `machine-client-ca.pem` in `certs/client-ca-bundle.pem` before it can trust that sidecar.
@@ -30,11 +33,12 @@ Typical first-time flow:
 
 1. `./examples/generate-certs.sh` and `cp config.example.toml config.toml`.
 2. `./examples/connect.sh --gateway 127.0.0.1:8443 --gateway-ca certs/server-ca.pem` creates `machine-client-ca.pem` under `~/.local/share/agent-gateway/` (or `$XDG_DATA_HOME`). Append that file to `client_ca_path` (for example, `cat ~/.local/share/agent-gateway/machine-client-ca.pem >> certs/client-ca-bundle.pem`).
-3. Start the gateway (`cargo run -- --config config.toml`), then return to the terminal running `connect.sh` and press Enter to start the sidecar and Claude.
+3. Insert a trusted principal signing key, its delegation scope, and signed permission rows into Postgres.
+4. Start the gateway (`cargo run -- --config config.toml`), then return to the terminal running `connect.sh` and press Enter to start the sidecar and Claude.
 
 On later runs, start the gateway first, run `connect.sh`, and press Enter after confirming the machine CA is still registered. If `connect.sh` finds an existing simulated TPM key but the saved `machine-client.pem` was issued for a different public key, it reissues `machine-client.pem` for the current TPM key using the existing machine client CA. `--regenerate-certs` creates a fresh simulated TPM state and machine client CA, so the new CA must be appended to `client_ca_path`.
 
-Pass a custom policy extension value: `connect.sh ... --extension-value agent-beta`.
+Pass a custom policy extension value: `connect.sh ... --extension-value agent-beta`. The extension value must match `permission_registry.subject_identity` in an active signed permission row.
 
 The simulated TPM state lives under `~/.local/share/agent-gateway/swtpm/` unless
 `XDG_DATA_HOME` is set. By default, the sidecar uses TCTI
@@ -56,13 +60,17 @@ Copy `config.example.toml` to `config.toml` and edit it. Key sections:
 | `tls_key_path` | yes | PEM private key for the server cert |
 | `client_ca_path` | yes | PEM bundle of per-machine client CAs (append each `machine-client-ca.pem`) |
 
-**`[policy]`** -- Maps certificate extension values to allowed destinations.
+**`[policy]`** -- Configures the certificate identity extension and Postgres registry access.
 
 | Field | Description |
 |---|---|
 | `client_ext_oid` | OID of the custom X.509 extension to extract (dotted notation) |
-| `rules[].extension_value` | Value to match in the extension |
-| `rules[].allowed_destinations` | List of `host` or `host:port` entries. Port defaults to `443` if omitted. |
+| `database_url` | Postgres URL for the authorization registry. Prefer `database_url_env` outside local development. |
+| `database_url_env` | Environment variable containing the Postgres URL. |
+| `max_connections` | Maximum Postgres pool connections. Defaults to `5`. |
+| `connect_timeout_ms` | Postgres connection timeout. Defaults to `5000`. |
+| `pool_acquire_timeout_ms` | Pool acquire timeout per authorization check. Defaults to `1000`. |
+| `query_timeout_ms` | Query timeout per registry lookup. Defaults to `500`. |
 
 **`[observability]`** -- Logging and tracing.
 
@@ -85,8 +93,60 @@ continues the same trace.
 agent_gateway --config config.toml
 ```
 
+Run migrations explicitly before starting the gateway:
+
+```bash
+agent_gateway --config config.toml migrate
+```
+
+Gateway startup verifies the authorization registry schema version and fails fast if the database is not migrated. The runtime gateway database role should be read-only for authorization tables; use a separate admin role for migrations and registry writes.
+
 Shut down cleanly with `Ctrl-C`.
 
+Register a demo principal signing key with:
+
+```bash
+./examples/register-principal-key.sh org-alice
+```
+
+The script creates a P-256 private key under `certs/principals/`, stores the public key in `principal_signing_keys`, and uses the friendly `key_id` (`org-alice`, `org-bob`, etc.) for the registry row.
+
+## Authorization Registry
+
+The gateway authorizes a CONNECT only when all of these checks pass:
+
+1. The mTLS client certificate has the configured UTF8String identity extension.
+2. The requested authority normalizes to a `host:port` destination.
+3. Postgres contains an active `permission_registry` row for that identity and destination.
+4. The row's `signature` verifies over the canonical permission row fields with the referenced active principal signing key.
+5. `principal_key_permissions` confirms that the signing key was allowed to delegate that identity/destination scope.
+
+### Database Structure
+
+The authorization registry has three main tables:
+
+| Table | Key Columns | Purpose |
+|---|---|---|
+| `principal_signing_keys` | `key_id`, `algorithm`, `public_key_spki_der`, `pubkey_sha256`, `not_before`, `not_after`, `revoked_at` | Stores trusted P-256 public keys that may sign permissions. |
+| `principal_key_permissions` | `signing_key_id`, `subject_identity`, `destination`, `not_before`, `not_after`, `revoked_at` | Defines what each signing key is allowed to delegate. |
+| `permission_registry` | `permission_id`, `signing_key_id`, `subject_identity`, `destination`, `not_before`, `not_after`, `revoked_at`, `signature` | Stores signed permissions that authorize a subject identity to reach a normalized destination. |
+
+`principal_key_permissions.signing_key_id` and `permission_registry.signing_key_id` both reference `principal_signing_keys.key_id`. A permission is usable only when the permission row is active, the signing key is active, the signature verifies over the canonical row fields, and the signing key has a matching delegation scope row.
+
+The signed bytes are the following UTF-8 text, with fields in this exact order and timestamps formatted as UTC RFC 3339 with six fractional digits:
+
+```text
+agent-gateway-permission-v1
+permission_id=perm-1
+signing_key_id=org-alice
+subject_identity=agent-alpha
+destination=api.example.com:443
+not_before=2026-05-01T00:00:00.000000Z
+not_after=2026-06-01T00:00:00.000000Z
+```
+
+Destination strings are normalized with the same rules used for CONNECT requests: hostnames are lowercased, omitted ports default to `443`, and IPv6 destinations use bracketed `host:port` form.
+
 ## Client requirements
 
 Clients must:
@@ -116,7 +176,7 @@ Clients must:
 
 ### Client certificate extension
 
-The extension value is matched exactly (case-sensitive) against policy rules. The extension must be an X.509 extension at the configured OID containing a single DER-encoded ASN.1 UTF8String.
+The extension value is matched exactly (case-sensitive) against signed permission rows. The extension must be an X.509 extension at the configured OID containing a single DER-encoded ASN.1 UTF8String.
 
 Example certificate generation with `rcgen`:
 
@@ -136,4 +196,4 @@ params.custom_extensions.push(
 cargo test
 ```
 
-38 integration tests cover policy evaluation, destination normalization (including IPv6 and default port), config validation, TLS PKI generation, and proxy request parsing.
+Database-backed policy and e2e tests require `TEST_DATABASE_URL` to point at a Postgres database that the test process can migrate and write to. The tests cover policy evaluation, signed-permission verification, signer delegation scope enforcement, destination normalization, config validation, TLS PKI generation, and proxy request parsing.

README.md

@@ -10,15 +10,13 @@ client_ca_path = "certs/client-ca-bundle.pem"
 log_level = "info"
 otlp_endpoint = "http://localhost:4317"
 
-# Custom extension OID to extract from client certs
 [policy]
+# Custom extension OID to extract from client certs.
 client_ext_oid = "1.3.6.1.4.1.57264.1.1"
-
-[[policy.rules]]
-extension_value = "agent-alpha"
-# Port defaults to 443 when omitted.
-allowed_destinations = ["api.example.com", "db.internal.com:5432", "api.anthropic.com:443"]
-
-[[policy.rules]]
-extension_value = "agent-beta"
-allowed_destinations = ["api.example.com:443"]  # explicit port also works
+# Use database_url_env for production so credentials are not stored in config.
+database_url_env = "AGENT_GATEWAY_DATABASE_URL"
+# database_url = "postgres://agent_gateway:change-me@localhost:5432/agent_gateway"
+max_connections = 5
+connect_timeout_ms = 5000
+pool_acquire_timeout_ms = 1000
+query_timeout_ms = 500

config.example.toml

@@ -0,0 +1,19 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: agent_gateway
+      POSTGRES_USER: agent_gateway_admin
+      POSTGRES_PASSWORD: agent_gateway_dev
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U agent_gateway_admin -d agent_gateway"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+    volumes:
+      - agent-gateway-postgres:/var/lib/postgresql/data
+
+volumes:
+  agent-gateway-postgres:

docker-compose.postgres.yml

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 KEY_ID [PRIVATE_KEY_PATH] [VALID_DAYS]" >&2
+  echo "Example: $0 org-alice certs/principals/org-alice.pem 365" >&2
+}
+
+if [[ $# -lt 1 || $# -gt 3 ]]; then
+  usage
+  exit 2
+fi
+
+KEY_ID="$1"
+PRIVATE_KEY="${2:-certs/principals/${KEY_ID}.pem}"
+VALID_DAYS="${3:-365}"
+DATABASE_URL="${AGENT_GATEWAY_DATABASE_URL:-${DATABASE_URL:-}}"
+
+if [[ -z "$DATABASE_URL" ]]; then
+  echo "Set AGENT_GATEWAY_DATABASE_URL or DATABASE_URL" >&2
+  exit 2
+fi
+
+command -v openssl >/dev/null || { echo "openssl is required" >&2; exit 1; }
+command -v psql >/dev/null || { echo "psql is required" >&2; exit 1; }
+
+mkdir -p "$(dirname "$PRIVATE_KEY")"
+if [[ ! -f "$PRIVATE_KEY" ]]; then
+  openssl ecparam -name prime256v1 -genkey -noout -out "$PRIVATE_KEY"
+  chmod 600 "$PRIVATE_KEY"
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+public_der="$tmpdir/public.der"
+pubkey_hash="$tmpdir/pubkey.sha256"
+openssl ec -in "$PRIVATE_KEY" -pubout -outform DER -out "$public_der" 2>/dev/null
+openssl dgst -sha256 -binary "$public_der" > "$pubkey_hash"
+
+hex_file() {
+  od -An -tx1 -v "$1" | tr -d ' \n'
+}
+
+PUBLIC_KEY_HEX="$(hex_file "$public_der")"
+PUBKEY_SHA256_HEX="$(hex_file "$pubkey_hash")"
+
+psql "$DATABASE_URL" \
+  --set=ON_ERROR_STOP=1 \
+  --set=key_id="$KEY_ID" \
+  --set=public_key_spki_der="$PUBLIC_KEY_HEX" \
+  --set=pubkey_sha256="$PUBKEY_SHA256_HEX" \
+  --set=valid_days="$VALID_DAYS" <<'SQL'
+WITH input AS (
+  SELECT
+    :'key_id'::text AS key_id,
+    decode(:'public_key_spki_der', 'hex') AS public_key_spki_der,
+    decode(:'pubkey_sha256', 'hex') AS pubkey_sha256,
+    :'valid_days'::int AS valid_days
+)
+INSERT INTO principal_signing_keys (
+  key_id, algorithm, public_key_spki_der, pubkey_sha256,
+  not_before, not_after, revoked_at
+)
+SELECT
+  key_id, 'ecdsa_p256_sha256', public_key_spki_der, pubkey_sha256,
+  now(), now() + make_interval(days => valid_days), NULL
+FROM input
+ON CONFLICT (key_id) DO UPDATE SET
+  public_key_spki_der = EXCLUDED.public_key_spki_der,
+  pubkey_sha256 = EXCLUDED.pubkey_sha256,
+  not_before = now(),
+  not_after = EXCLUDED.not_after,
+  revoked_at = NULL,
+  updated_at = now()
+RETURNING key_id, encode(pubkey_sha256, 'hex') AS pubkey_sha256, not_after;
+SQL
+
+echo "Private key: $PRIVATE_KEY"

examples/register-principal-key.sh

@@ -0,0 +1,56 @@
+CREATE TABLE agent_gateway_schema_version (
+    version INTEGER PRIMARY KEY,
+    applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+INSERT INTO agent_gateway_schema_version (version) VALUES (1);
+
+CREATE TABLE principal_signing_keys (
+    key_id TEXT PRIMARY KEY,
+    algorithm TEXT NOT NULL CHECK (algorithm = 'ecdsa_p256_sha256'),
+    public_key_spki_der BYTEA NOT NULL,
+    pubkey_sha256 BYTEA NOT NULL UNIQUE CHECK (length(pubkey_sha256) = 32),
+    not_before TIMESTAMPTZ NOT NULL,
+    not_after TIMESTAMPTZ NOT NULL,
+    revoked_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CHECK (key_id <> ''),
+    CHECK (not_before < not_after)
+);
+
+CREATE TABLE principal_key_permissions (
+    id BIGSERIAL PRIMARY KEY,
+    signing_key_id TEXT NOT NULL REFERENCES principal_signing_keys(key_id),
+    subject_identity TEXT NOT NULL CHECK (subject_identity <> ''),
+    destination TEXT NOT NULL CHECK (destination <> ''),
+    not_before TIMESTAMPTZ NOT NULL,
+    not_after TIMESTAMPTZ NOT NULL,
+    revoked_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CHECK (not_before < not_after)
+);
+
+CREATE TABLE permission_registry (
+    permission_id TEXT PRIMARY KEY,
+    signing_key_id TEXT NOT NULL REFERENCES principal_signing_keys(key_id),
+    subject_identity TEXT NOT NULL CHECK (subject_identity <> ''),
+    destination TEXT NOT NULL CHECK (destination <> ''),
+    not_before TIMESTAMPTZ NOT NULL,
+    not_after TIMESTAMPTZ NOT NULL,
+    revoked_at TIMESTAMPTZ,
+    signature BYTEA NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CHECK (permission_id <> ''),
+    CHECK (not_before < not_after)
+);
+
+CREATE INDEX permission_registry_active_lookup_idx
+    ON permission_registry (subject_identity, destination, not_after DESC)
+    WHERE revoked_at IS NULL;
+
+CREATE INDEX principal_key_permissions_active_scope_idx
+    ON principal_key_permissions (signing_key_id, subject_identity, destination)
+    WHERE revoked_at IS NULL;