feat(mtls): add certificate lifecycle API and DB schema (#146)

[Subhajitdas99]

Summary

• Problem: Bindu agents have no mechanism to authenticate each other cryptographically — any agent can claim any identity over the wire.
• Why it matters: Enterprise deployments and zero-trust architectures require mutual TLS so every agent connection is verified by certificate, not just token.
• What changed: Added the Certificate Lifecycle API (issue / renew / revoke), DB schema for certificate storage and audit logging, protocol TypedDicts, and route registration — all opt-in via mtls_enabled setting.
• What did NOT change: Default developer experience is untouched. pip install bindu + zero-config agent still works with zero TLS configuration. This is the infrastructure layer only — the ASGI/Uvicorn SSL context (Standalone Mode) is being handled separately by @Subhajitdas99 in a companion PR.

Change Type

• Feature
• Security hardening

Scope

• Server / API endpoints
• Storage backends
• Authentication / authorization

Linked Issue/PR

• Related [Feature]: mTLS Support - Secure Agent Communication #146

User-Visible / Behavior Changes

None by default. mTLS is disabled (mtls_enabled = False) unless explicitly enabled in settings. When enabled, three new endpoints become available:

• POST /api/v1/certificates/issue
• POST /api/v1/certificates/renew
• POST /api/v1/certificates/revoke

On first run with mTLS enabled, a local Root CA is auto-generated at ~/.bindu/certs/ with no external dependencies.

Security Impact

• New permissions/capabilities? Yes
• Secrets/credentials handling changed? Yes
• New/changed network calls? Yes
• Database schema/migration changes? Yes
• Authentication/authorization changes? Yes

Explanation:

• The local CA private key is written to ~/.bindu/certs/ca.key with no passphrase — acceptable for local dev, operators should replace with Vault PKI or AWS Private CA in production (documented in ADR).
• Certificate fingerprints are bound to Hydra OAuth2 clients via RFC 8705 x5t#S256 claim — a PUT to the Hydra Admin API is made on every issue/renew/revoke.
• DB migration 20260322_0001 adds agent_certificates and certificate_audit_log tables — no changes to existing tables, fully backward compatible.
• All certificate events are written to an immutable audit log for SIEM ingestion.

Verification

Environment

• OS: Windows 11
• Python version: 3.12.9
• Storage backend: InMemoryStorage (local dev)
• Scheduler backend: InMemoryScheduler (local dev)

Steps to Test

1. Run uv run alembic history — confirm 20260322_0001 appears as the single head
2. Run python examples/beginner/beginner_zero_config_agent.py — confirm agent starts normally with no mTLS errors (opt-out default)
3. Run uv run pytest — confirm existing tests unaffected
4. With Postgres + mtls_enabled = True: run uv run alembic upgrade head, then POST /api/v1/certificates/issue with a valid CSR — expect 201 + PEM certificate in response
5. Revoke the certificate via POST /api/v1/certificates/revoke — confirm status revoked in agent_certificates table and Hydra binding cleared

Expected Behavior

• Zero-config agent starts cleanly with no changes to existing behavior
• alembic history shows a single clean migration head
• /issue returns a signed PEM certificate with SHA-256 fingerprint
• /revoke marks cert as revoked in DB and removes Hydra binding immediately

Actual Behavior

• Zero-config agent confirmed running at http://localhost:3773 ✅
• alembic history shows single head 20260322_0001 ✅
• Postgres + Hydra integration untested locally (no Hydra instance in dev env)

Evidence

• Test output / logs — zero-config agent runs cleanly after changes
• alembic history output confirms clean migration chain

Human Verification

• Verified scenarios: Zero-config agent unaffected by changes. Alembic migration chain valid. Pre-commit hooks pass on all files touched by this PR.
• Edge cases checked: mtls_enabled guard uses getattr with fallback — safe if security section missing from settings entirely.
• What you did NOT verify: Live Hydra OAuth2 binding (no Hydra instance in local dev). Full E2E mTLS handshake — depends on Subhajit's Standalone Mode PR for the ASGI SSL layer.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? Yes — new optional security.mtls_enabled flag, defaults to False
• Database migration needed? Yes
• Upgrade steps: Run uv run alembic upgrade head to create agent_certificates and certificate_audit_log tables. No existing tables modified.

Failure Recovery

• How to disable quickly: Set security.mtls_enabled = False (already the default) — certificate routes simply won't register
• Files to restore: bindu/server/applications.py — remove _register_certificate_endpoints() call and method
• Known bad symptoms: If Hydra Admin API is unreachable, /issue and /revoke will return 500 — this is expected and logged

Risks and Mitigations

• Risk: Local CA key stored unencrypted at ~/.bindu/certs/ca.key
  • Mitigation: Dev-only. ADR documents pluggable CA backends (Vault PKI, AWS Private CA) for production. Key is never transmitted or logged.
• Risk: Hydra binding PUT fails silently if Hydra is down during certificate operations
  • Mitigation: All Hydra calls raise ValueError on failure — the endpoint returns 500 and logs the error. No partial state is committed.

Checklist

• Tests pass (uv run pytest) — pytest hook fails with uv: command not found in pre-commit environment (Windows path issue, unrelated to this PR)
• Pre-commit hooks pass on files touched by this PR
• Security impact assessed
• Human verification completed
• Backward compatibility confirmed — opt-in only, zero default behaviour change