Skip to content
Capsem

Credential Broker Plugin

Plugin id: credential_broker

Version: supplied by the plugin registry descriptor and emitted in profile plugin lists, VM info/status, logs, and benchmark output.

Stage: preprocess. CEL rules do not invoke the credential broker.

Stages:

  • preprocess: capture observed credentials, attach broker refs, and resolve broker refs for runtime/upstream materialization.

Config:

[plugins.credential_broker]
mode = "rewrite"
detection_level = "informational"

Inputs: outbound HTTP boundaries, remote MCP auth boundaries, plus plugin-owned broker state. Raw credentials remain private to the broker and are not exposed as CEL fields.

Mutation: stores observed credentials through the broker and writes the brokered credential:blake3:* reference back onto the event. The broker does not sanitize durable logs; the log_sanitizer logging plugin owns ledger-safe materialization.

MCP contract: remote MCP server config may carry only brokered auth metadata in profile-owned mcp.json:

{
  "servers": [
    {
      "id": "remote",
      "name": "Remote MCP",
      "transport": "sse",
      "url": "https://mcp.example.invalid/sse",
      "auth": {
        "kind": "oauth",
        "credential_ref": "credential:blake3:..."
      }
    }
  ]
}

The broker owns OAuth/API-key material and resolution. MCP config must not store raw bearer_token, bearerToken, Authorization, X-Api-Key, refresh tokens, or access tokens.

Decision: plugin policy can request allow, ask, block, or rewrite; rewrite keeps the effective decision at allow while recording mutation intent.

Status contract: credential state is opaque and VM-scoped. The UI must not infer credential state from AI/provider config. Profile plugin configuration is read through /profiles/{profile_id}/plugins/list and /profiles/{profile_id}/plugins/credential_broker/info; VM info and status carry the active descriptor, version, stage health, and last in-memory status snapshot without reading session.db.

Benchmark contract: the plugin descriptor owns a stable benchmark spec for capture, substitution, failed materialization, and status snapshot overhead. Benchmarks must report plugin id, version, stage, event count, latency, and mutation count.

Detection contract: enabled executions append one SecurityDetectionEvent to SecurityEvent.detections with source = "plugin", the configured detection_level, plugin id, plugin mode, and reason.

Failure: broker storage errors abort runtime materialization and the event is not emitted by the security engine.

Tests must prove capture, BLAKE3 reference logging, rewrite mutation, VM-scoped status/stats, and failure without raw credential leakage.