Skip to main content

PKI, mTLS, and certificate lifecycle

Identity proof​

Backend agent identity is the common name of the leaf certificate in a verified chain. A request-body agent ID or proxy header cannot replace it. The allowed agent ID shape is enforced by internal/agentidentity. Backend TLS listeners use TLS 1.3. Agent-side network transport is still planned.

Endpoint keys are generated locally by the implemented P-256 filesystem provider. Callers receive a crypto.Signer and key identifier, not an API for exporting a private key. The underlying unencrypted key file remains readable by root, the owning account, or someone holding a disk copy; the signer interface alone is not hardware protection.

Renewal​

The backend control process has a separate agent-authenticated renewal listener. It derives identity from the presented certificate and checks registry admissibility before signing. The agent repository does not yet contain a live renewal client or scheduled rotation loop.

A superseded certificate remains valid until expiry or agent-level revocation. The gateway admits by agent ID, not the latest certificate fingerprint. Renewal must not be described as immediate old-key invalidation. CRL and OCSP infrastructure is not provided; agent admission state is the implemented denial mechanism.

CA rotation ordering​

ADR 25 defines the server-side trust-bundle mechanism:

  1. Widen trusted authority bundles to contain the next authority before signing with it.
  2. Distribute that widened trust to endpoints through authenticated issuance/renewal workflows.
  3. Switch signing authority and restart the control process that holds the signing key.
  4. Remove the former authority after compatible credentials are deployed; existing connections need to drain.

The backend reloads changed listener material and reads the published trust bundle at issuance. It refuses to publish a trust bundle that does not trust the signing authority. These mechanisms are implemented; fleet automation and the V2 endpoint renewal loop are not. Do not execute a fleet rotation assuming that step 2 happens automatically today.

Recovery and residual risk​

Certificate validity depends on endpoint/server clocks. Expired credentials cannot authenticate themselves into renewal. Use an authorized recovery workflow instead of disabling TLS verification. Compromise of the signing key affects the entire agent trust domain; protect its storage and access more strongly than ordinary runtime configuration.

Source evidence​

Reviewed against the source baseline. Seagull-backend-v2/docs/decisions/0002-identity-comes-from-the-certificate.md · Seagull-backend-v2/docs/decisions/0025-the-platform-signs-the-identity-it-binds.md · Seagull-backend-v2/internal/platform/tlsx/material.go · Seagull-agent-v2/internal/pki/keyfiles.go.