mTLS / cert auth

Mutual TLS authenticates both sides of an HTTPS handshake: the server presents its certificate as usual, and the client also presents one signed by a CA the server trusts. The connection only completes if both certs validate. There is no bearer token or OAuth flow on top — the cryptographic handshake itself is the credential.

CodeSpar's cert auth_type is the catalog shape for any provider that requires this pattern. It sits alongside api_key, path_secret, oauth, hmac_signed, and none in the six-type taxonomy — the dashboard wizard knows to render a file-upload UX when a server's catalog row declares auth_type: "cert", and the proxy executor knows to mount the PEM blob into an undici.Agent for outbound calls.

When you'll use it

Brazilian open-banking corporate APIs are the canonical case. They mandate mTLS for any B2B integration and do not offer an API-key or OAuth alternative.

• Banco do Brasil — production pilot. Live rails: cobranca_create, cobranca_status.
• Itaú, Santander, Bradesco, Caixa — next batch. Each is a mechanical drop: a catalog row plus a META_TOOL_CATALOG entry; the runtime is the same.
• Future LATAM corporate-banking integrations (Mexico's SPEI corporate APIs, Chile's CMF-supervised APIs, etc.) will land on the same cert runtime.

Files the operator uploads

All three are stored as PEM blobs in the CodeSpar vault, encrypted at rest. The cert + key pair stays bonded — re-uploading one without the other invalidates the connection.

Connect flow walkthrough

1. Operator opens /dashboard/auth-configs (or /dashboard/connections when scoping per project).
2. Picks the cert-auth-typed server — for example, banco-do-brasil.
3. The Provider Connect modal renders three file inputs (cert, key, optional ca), each accepting .pem, .crt, or .key.
4. Operator uploads the PEM blobs the bank issued. The dashboard does a client-side sanity check (file is non-empty, looks like a PEM header) before submitting.
5. Backend writes the PEM blobs to the vault, then runs cert-parser.ts to extract metadata via node:crypto's X509Certificate:
   • subject CN
   • issuer
   • validFrom / validTo
   • SHA-256 fingerprint
6. Migration 0065_cert_metadata.sql adds a cert_metadata jsonb column on connected_accounts; the parsed metadata lands there. The dashboard's CertExpiryBadge reads that column to surface expiry warnings — green default, amber at 30 days, red at 7 days, critical when expired.

What happens at runtime

The proxy executor caches an undici.Agent per (orgId × serverId × envFingerprint) tuple. The first outbound call materializes the agent (parses PEM, builds the TLS context, opens the keepalive pool); every subsequent call within the same tuple reuses it. The TLS handshake is paid once, not per request.

session.execute("banco-do-brasil/cobranca_create", { ... })
  │
  ▼
proxy-executor.ts
  │
  ├─ resolve connection → cert + key + ca PEM blobs
  ├─ envFingerprint = hash(orgId, serverId, env, fingerprint)
  ├─ undici.Agent cache hit? → reuse
  │                           ↓ miss
  │                    new Agent({ connect: { cert, key, ca } })
  ▼
HTTPS request — TLS handshake reuses the cached pool
  │
  ▼
provider returns response → normalized → idempotency-keyed → returned to caller

Idempotency, retries, and the meta-tool transform layer behave identically to every other auth_type. The only thing that changes is which credential the proxy presents to the bank.

Companion API-key header (Bradesco style)

A subset of BR banks layer a developer key alongside the mTLS handshake — the cert proves "you are this corporate entity," the dev key identifies which application within that entity is calling. Bradesco is the canonical example.

The catalog spec captures this with two extra fields:

{
  "auth_type": "cert",
  "secrets": [
    { "name": "cert", "kind": "cert" },
    { "name": "key",  "kind": "cert" },
    { "name": "ca",   "kind": "cert", "optional": true }
  ],
  "path_secret_header_ref": "developer_key",
  "auth_header_name": "X-Bradesco-Developer-Key"
}

The dashboard reads those two extra fields and renders an additional non-cert input below the file uploaders. The proxy executor stamps the header on every call after the TLS connection is established. From the agent's perspective, nothing changes — the catalog row absorbs the wiring.

Catalog snippet

A minimal cert-auth provider declaration looks like this:

{
  "id": "banco-do-brasil",
  "name": "Banco do Brasil — Cobrança",
  "auth_type": "cert",
  "secrets": [
    { "name": "cert", "kind": "cert", "label": "Client certificate (PEM)" },
    { "name": "key",  "kind": "cert", "label": "Private key (PEM)" },
    { "name": "ca",   "kind": "cert", "label": "CA bundle (PEM)", "optional": true }
  ],
  "tools": ["cobranca_create", "cobranca_status"]
}

The kind: "cert" marker is what tells the dashboard to render a file uploader instead of a text input, and what tells the vault layer to treat the value as a multi-line PEM blob rather than a single-line secret.

Cert rotation + revocation

Banks rotate corporate certs annually. The flow is:

1. Bank issues a renewed cert (and possibly a new CA chain) to the CNPJ during their renewal window.
2. Operator opens the connection in the dashboard and re-uploads the new PEM blobs.
3. Backend re-parses, writes new cert_metadata (new fingerprint, new validTo), and rewrites the vault entry.
4. The envFingerprint changes (because the cert fingerprint changed), which invalidates the cached undici.Agent automatically. The next outbound call materializes a fresh agent against the new cert.

For revocation — say a cert was leaked — the operator deletes the connection in the dashboard. The vault entry is wiped, the cached agent is dropped, and any in-flight calls fail closed with a clear error.

Troubleshooting

Next steps