SPIFFE / SPIRE

Long-lived API keys for agents are a liability. SPIFFE/SPIRE replaces them with short-lived, cryptographically-rotated mTLS certificates (SVIDs) anchored to workload identity.

Use this when:

• Agents run on Kubernetes and you have a SPIRE deployment.
• Agents need to authenticate to TapPass and to each other in a zero-trust mesh.
• You want offboarding to happen by revoking a workload, not by key rotation.

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  SPIRE       │     │  Agent       │     │  TapPass     │
│  Server      │     │  (workload)  │     │              │
│              │     │              │     │              │
│  ① issues    │────▶│  ② holds     │────▶│  ③ verifies  │
│  SVID        │     │  SVID        │     │  SVID chain  │
└──────────────┘     └──────────────┘     └──────────────┘

1. Configure SPIRE trust domain

TapPass validates SVIDs against a known trust domain.

spiffe:
  enabled: true
  trust_domain: spiffe://prod.example.com
  spire_server_socket: /run/spire/sockets/api.sock
  # or trust-bundle file:
  trust_bundle_file: /etc/spire/trust-bundle.pem

2. Allowlist workload SPIFFE IDs

spiffe:
  allowed_ids:
    - spiffe://prod.example.com/ns/agents/sa/chat-bot
    - spiffe://prod.example.com/ns/agents/sa/research-crew

Or use a prefix match:

spiffe:
  allowed_prefixes:
    - spiffe://prod.example.com/ns/agents/

3. Agent config

Agents mount the SPIRE agent socket and use it to obtain SVIDs:

# Kubernetes manifest
volumeMounts:
  - name: spire-agent-socket
    mountPath: /run/spire/sockets
    readOnly: true
volumes:
  - name: spire-agent-socket
    hostPath:
      path: /run/spire/sockets
      type: Directory

Then in Python:

from tappass import Agent
from tappass.identity.spiffe import SPIFFECredentialProvider

creds = SPIFFECredentialProvider(
    socket_path="/run/spire/sockets/api.sock",
)

agent = Agent(
    "https://tappass.example.com",
    credentials=creds,  # no tp_ key needed
)

response = agent.chat("Hello")

The SDK renews SVIDs automatically before expiry.

4. TapPass verifies on every request

On each incoming request, TapPass:

1. Extracts the client cert from the mTLS handshake
2. Validates the cert chain against the trust bundle
3. Extracts the SPIFFE ID from the SAN
4. Checks the ID against allowed_ids / allowed_prefixes
5. Maps the SPIFFE ID to an internal agent identity for audit

Example SPIRE registration

spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/agents/sa/chat-bot \
    -parentID spiffe://prod.example.com/spire/agent/k8s_sat/prod/<node-id> \
    -selector k8s:ns:agents \
    -selector k8s:sa:chat-bot

Why this matters

• No long-lived secrets. SVIDs rotate every hour by default.
• Offboard by deleting a workload. No key revocation dance.
• Audit maps to identity, not to a key. The audit trail records the SPIFFE ID, so you always know which workload called.