Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.codezero.io/llms.txt

Use this file to discover all available pages before exploring further.

Cordon can inject credentials into database connections, not just HTTP APIs. For PostgreSQL, cordon intercepts the wire protocol handshake and injects the password before the connection reaches the upstream database. Your application connects to a local port with no password and cordon handles authentication transparently.

​
How it works

  1. Cordon listens on a local port (e.g., 15432)
  2. Your app connects to localhost:15432 with no password
  3. Cordon intercepts the PostgreSQL authentication handshake
  4. The real password, resolved when Cordon starts, is injected into the authentication handshake
  5. The authenticated connection is forwarded to the upstream database
Your application never sees or handles database credentials.
PostgreSQL listeners currently resolve credentials at startup, not per connection. If you rotate the underlying secret, restart Cordon to pick up the new value.

​
Configuration

Database connections are configured as [[listeners]] entries in cordon.toml, alongside HTTP routes. See Listeners for the full configuration reference. 
listen = 6790

[tls]
enabled = true
# Substitute paths from your real `cordon.toml` (typically under ~/.config/cordon/projects/<namespace>/certs/).
ca_cert_path = "/path/to/ca-cert.pem"
ca_key_path = "/path/to/ca-key.pem"

# ... your HTTP routes ...

[[listeners]]
name = "prod-db"
port = 15432
upstream = "db.prod.example.com:5432"
client_tls = "accept"

[listeners.auth]
type = "password"
username = "app_user"

[listeners.auth.secret]
source = "1password"
vault = "Engineering"
item = "Postgres Prod"
field = "password"
FieldTypeRequiredDescription
namestringYesIdentifier for the listener (used in logs)
portintegerYesLocal port to listen on
upstreamstringYesUpstream database host and port
client_tlsstringNoClient-to-Cordon TLS mode: accept (default), require, or disable.
auth.typestringYesAuth type. Currently password.
auth.usernamestringYesUsername to authenticate as
auth.secretobjectYesSecret source reference. See Secret Sources.
PostgreSQL listener upstreams are configured trust decisions in v1, matching configured HTTP credential routes. Cordon resolves the configured upstream once at listener startup and connects to the selected SocketAddr, which pins DNS and avoids a second lookup before connecting. Private, loopback, and link-local upstream policy will be revisited post-v1 in #531.

​
Client TLS

PostgreSQL clients can request TLS from the local Cordon listener by sending a PostgreSQL SSLRequest before the startup packet. Configure client_tls on each listener:
ModeBehavior
acceptDefault. Accepts TLS when Cordon can load valid tls.ca_cert_path and tls.ca_key_path; plaintext clients still work. If no usable CA is configured, Cordon declines SSL requests to preserve sslmode=prefer and plaintext behavior.
requireRequires clients to request and complete TLS before the PostgreSQL startup packet. This mode requires tls.ca_cert_path and tls.ca_key_path.
disableDeclines PostgreSQL SSL requests and continues only with clients that fall back to plaintext.
Cordon uses the same local CA configured under [tls] for PostgreSQL client TLS. Clients using sslmode=verify-ca or sslmode=verify-full must trust that CA, for example by running cordon trust or by configuring the client trust store directly. Cordon presents a loopback certificate valid for localhost, 127.0.0.1, and ::1. For sslmode=verify-full, connect to the local listener with one of those host identities.
Cordon always requires TLS on the Cordon-to-upstream PostgreSQL leg. It sends a PostgreSQL SSLRequest to the upstream server and completes TLS before sending startup or authentication data. If the upstream declines TLS or certificate verification fails, Cordon fails closed and does not send credentials.

​
Connecting your application

Point your application at the local port instead of the upstream database: 
postgresql://app_user@localhost:15432/mydb
No password in the connection string. Cordon injects it.

​
Multiple databases

Configure multiple PostgreSQL listeners for different databases, each on its own local port: 
[[listeners]]
name = "prod-db"
port = 15432
upstream = "db.prod.example.com:5432"
client_tls = "accept"

[listeners.auth]
type = "password"
username = "app_user"

[listeners.auth.secret]
source = "1password"
vault = "Engineering"
item = "Postgres Prod"
field = "password"

[[listeners]]
name = "staging-db"
port = 15433
upstream = "db.staging.example.com:5432"
client_tls = "accept"

[listeners.auth]
type = "password"
username = "staging_user"

[listeners.auth.secret]
source = "keyring"
account = "staging-pg-pass"