Authentication

The cache service supports PSK, bearer, and proxy-terminated mTLS patterns. For most first deployments, use PSK on a private network.

Recommended Choices

PSK

PSK uses one shared secret. Clients send the secret with each authenticated request. The server stores only a Blake3 hash of the secret.

Generate the server hash:

printf '%s' "your-shared-secret" | b3sum | cut -d' ' -f1

Server:

[auth]
mechanism = "psk"
psk_hash = "<64-character-blake3-hash>"

Client:

[cache]
service_auth = "psk"

export CRAB_CACHE_PSK="your-shared-secret"

PSK clients share one identity. Use separate cache services or mTLS when you need per-user or per-team identities.

Bearer

Bearer mode accepts a bearer token from the client:

[cache]
service_auth = "bearer"
service_token_path = "/var/run/crab/cache-token"

or:

export CRAB_CACHE_TOKEN="token-value"

Current bearer mode does not validate token signatures. Use it only on trusted networks or behind infrastructure that already authenticates requests.

Proxy-Terminated mTLS

For mTLS, validate client certificates at a trusted proxy, ingress, or service mesh. The proxy forwards the validated identity to the cache service.

Server:

[auth]
mechanism = "mtls"

Proxy requirement:

X-Client-CN: <validated-client-identity>

Do not allow untrusted clients to set this header directly.

Authorization Policy

Authentication identifies the client. A policy file controls what that client can do.

Example:

rules:
  - principal: "psk-client"
    repos: [".crab"]
    actions: ["read", "write", "dedup"]

  - principal: "ci-runner-prod"
    repos: ["my-org/*", ".crab"]
    actions: ["read", "dedup"]

  - principal: "deployer"
    repos: ["*"]
    actions: ["read", "write", "dedup", "admin"]

Policy fields:

Use separate cache services when dedup visibility itself must be isolated.

Rotation

For PSK rotation:

1. Generate a new secret and hash.
2. Update the server config.
3. Restart or roll the cache service.
4. Update client secrets.

For zero-downtime rotation, run two cache services during the cutover window and move clients gradually.