Govern Any Provider

Provider identities

chio-tool-call-fabric defines the shape a native adapter's lift produces, the verdict shape its lower consumes, and the streaming state machine. It holds no provider-specific logic and performs no I/O. Each ProviderId carries a Principal variant scoped to that provider's native identity boundary.

Lift and lower contract

A ToolInvocation is what each adapter's lift emits.

pub struct ToolInvocation {
    pub provider: ProviderId,
    pub tool_name: String,
    /// Canonical-JSON bytes (RFC 8785). Stored as raw bytes so the kernel can
    /// hash without re-serializing.
    pub arguments: Vec<u8>,
    pub provenance: ProvenanceStamp,
}

pub struct ProvenanceStamp {
    pub provider: ProviderId,
    pub request_id: String,
    pub api_version: String,
    pub principal: Principal,
    pub received_at: SystemTime,
}

arguments is a byte vector, so a serialized ToolInvocation shows it as an array of integers. This is the Anthropic single-tool fixture the crate pins its wire contract against; its seventeen bytes decode to {"ticker":"ANTH"}.

$ jq . crates/protocol/chio-tool-call-fabric/fixtures/lift_lower/anthropic/single_tool_use.json

{
  "arguments": [
    123,
    34,
    116,
    105,
    99,
    107,
    101,
    114,
    34,
    58,
    34,
    65,
    78,
    84,
    72,
    34,
    125
  ],
  "provenance": {
    "api_version": "anthropic.2023-06-01",
    "principal": {
      "kind": "anthropic_workspace",
      "workspace_id": "wks_chio_demo"
    },
    "provider": "anthropic",
    "received_at": {
      "nanos_since_epoch": 0,
      "secs_since_epoch": 1745452803
    },
    "request_id": "msg_01abcdEFGHJK1234567890mn"
  },
  "provider": "anthropic",
  "tool_name": "get_stock_price"
}

The keys are alphabetical because the file is canonical JSON, and api_version here is the fixture's own label rather than the adapter constant. The Bedrock fixtures carry the richer principal.

$ jq '.provenance.principal' \
  crates/protocol/chio-tool-call-fabric/fixtures/lift_lower/bedrock/assumed_role.json

{
  "account_id": "123456789012",
  "assumed_role_session_arn": "arn:aws:sts::123456789012:assumed-role/ChioAgentRole/session-1",
  "caller_arn": "arn:aws:iam::123456789012:role/ChioAgentRole",
  "kind": "bedrock_iam"
}

ToolInvocation::validate is the fail-closed check an adapter or replay consumer runs on a value that crossed a boundary. It enforces what the struct shape alone cannot:

• provider equals provenance.provider.
• The Principal variant matches the provider; a Bedrock invocation carrying an AnthropicWorkspace principal is rejected.
• tool_name, request_id, and api_version are non-empty, free of surrounding whitespace, and free of control characters.
• The same rules hold for the principal's fields: org_id, workspace_id, caller_arn, account_id, assumed_role_session_arn, project_id, and host.
• arguments re-canonicalizes to itself byte for byte. Bytes that are not JSON fail first with InvalidArgumentJson; JSON that is not canonical fails with NonCanonicalArguments.

On the way back, the kernel returns a VerdictResult, which the adapter lowers into the provider's tool-result shape.

pub enum VerdictResult {
    Allow {
        redactions: Vec<Redaction>,
        receipt_id: ReceiptId,
    },
    Deny {
        reason: DenyReason,
        receipt_id: ReceiptId,
    },
}

pub enum DenyReason {
    PolicyDeny { rule_id: String },
    GuardDeny { guard_id: String, detail: String },
    CapabilityExpired,
    PrincipalUnknown,
    BudgetExceeded,
}

A Redaction is a JSON Pointer path plus a replacement string, applied to the tool result on the allow path; a path that does not start with / is refused. The kernel-side conversion always returns an empty redaction list, so redactions come from an adapter or a caller. Three opaque byte wrappers keep wire handling in the adapter: ProviderRequest (upstream request bytes an adapter lifts), ProviderResponse (bytes lower hands back to the transport), and ToolResult (canonical-JSON tool output for consistent downstream verification).

Anthropic native tool gate

The adapter recognizes the native names computer_use, bash, and text_editor, plus their date-suffixed forms, and fails closed on them unless both gates are open: the computer-use cargo feature is compiled in (it also adds the anthropic-beta: computer-use-2025-01-24 header), and the manifest's server_tools list names the matching stable entry. Only tools named in server_tools pass ensure_tool_allowed.

Any 8-digit date suffix folds onto the bare name, so a wire bump from bash_20241022 to a later date stays behind the same entry. Build the gate from a validated manifest with AnthropicAdapter::new_with_manifest; AnthropicAdapter::new denies every recognized native-tool call, even with the feature compiled. Other names skip this gate, and their kernel capability checks still apply. Match support for a new provider toolset to the adapter's pinned beta contract, never to a date suffix alone.

The field name server_tools refers to the Chio manifest. Computer, Bash, and text-editor calls are client-executed tools, which Anthropic's tool reference distinguishes from provider-hosted server tools.

Bedrock IAM caller

new_with_signed_iam_principals_config_from_sts resolves STS GetCallerIdentity once per process, loads config/iam_principals.toml, checks the Sigstore bundle beside it (the TOML path with .sigstore-bundle.json appended, per sigstore_bundle_path) through the chio-attest-verify verifier, and maps the caller ARN to Principal::BedrockIam.

# iam_principals.toml
# Default signed-config path for Bedrock IAM principal mapping.
# Replace these sample mappings with operator-owned values and publish a
# matching Sigstore bundle at iam_principals.toml.sigstore-bundle.json.

default_action = "deny"
config_version = 1

[[mapping]]
match = "arn:aws:iam::123456789012:role/ChioAgentRole"
owner = "team-alpha"
notes = "sample exact role mapping"

[[mapping]]
match = "arn:aws:sts::123456789012:assumed-role/ChioAgentRole/*"
owner = "team-alpha"
notes = "sample assumed-role session mapping"

The mapping list is ordered and the first match wins; each match is an exact ARN or a * wildcard pattern. Loading rejects a config_version other than 1, a default_action other than deny, an empty mapping list, and any entry with a blank match or owner (crates/protocol/chio-bedrock-converse-adapter/src/iam_principals.rs:272-300). The shipped file is a sample: replace its mappings with operator-owned values and publish a matching Sigstore bundle beside it.

Resolution fails closed on a missing config file, a missing Sigstore bundle, a rejected signature, invalid TOML, an unsupported config_version, or a caller ARN with no matching entry. The bundle is checked before the TOML is parsed, so a signature problem masks any content problem behind it. For an STS assumed-role caller, the adapter keeps the session ARN in assumed_role_session_arn and the canonical role ARN in caller_arn. principal_owner() and matched_iam_principal_pattern() return the resolved owner and the matched pattern. The mapping is one case of binding an execution environment to a Chio principal, which Workload Identity covers.

Provider errors

Both adapters map upstream failures to the ProviderError taxonomy: seven named classes plus Other. Other wraps an anyhow::Error, and neither adapter crate depends on anyhow, so neither produces it. Anything an adapter cannot place lands in Malformed and fails closed.

pub enum ProviderError {
    #[error("rate limited by upstream: retry after {retry_after_ms}ms")]
    RateLimited { retry_after_ms: u64 },
    #[error("upstream content policy denied request: {0}")]
    ContentPolicy(String),
    #[error("tool arguments failed schema validation: {0}")]
    BadToolArgs(String),
    #[error("upstream 5xx ({status}): {body}")]
    Upstream5xx { status: u16, body: String },
    #[error("transport timeout after {ms}ms")]
    TransportTimeout { ms: u64 },
    #[error("verdict latency budget exceeded ({observed_ms}ms > {budget_ms}ms); fail-closed")]
    VerdictBudgetExceeded { observed_ms: u64, budget_ms: u64 },
    #[error("malformed upstream payload: {0}")]
    Malformed(String),
    #[error(transparent)]
    Other(#[from] anyhow::Error),
}

• RateLimited. HTTP 429 on the Anthropic path, ThrottlingException on Bedrock. retry_after_ms is a constant, 0 for Anthropic and 1000 for Bedrock; neither adapter reads a provider retry hint, and the Anthropic transport surfaces no response headers.
• ContentPolicy. HTTP 403 from the provider, on the Anthropic path only. A refusal inside a 200 response is not parsed into it, and a Bedrock guardrail intervention arrives as another class.
• BadToolArgs. A tool_use.input or toolUse.input that cannot become canonical JSON object arguments; also any non-403 4xx on the HTTP path, and a malformed tool result on the Bedrock lower path.
• Upstream5xx. Any status in the 500 range, which is where an overload response lands. Bedrock also routes ModelTimeoutException here, with status 408.
• TransportTimeout. A local per-call timeout, classified apart from upstream timeout envelopes.
• VerdictBudgetExceeded. Your evaluator reported missing its own budget. The adapter preserves observed_ms and budget_ms and fails the stream closed.
• Malformed. Impossible or out-of-order native payloads; the fail-closed default.

Detached provenance

A kernel receipt signs its own fields, and the basic invocation-to-request builder leaves the full stamp out of the kernel request. When an auditor needs the upstream identity (provider, request ID, principal) as asserted by a trusted adapter, sign the stamp separately. sign_provenance serializes it to RFC 8785 canonical JSON, signs those bytes, and returns a SignedProvenance envelope carrying the stamp, the signed bytes, the algorithm, the public key, and the detached signature.

use chio_tool_call_fabric::{sign_provenance, verify_signed_provenance};

// Sign the stamp with the adapter's signing backend.
let envelope = sign_provenance(&invocation.provenance, &backend)?;

// verify_signed_provenance runs three checks in order:
//   1. envelope.algorithm matches the signature algorithm,
//   2. envelope.signed_bytes re-canonicalize from stamp byte-for-byte,
//   3. the signature verifies against public_key over signed_bytes.
// On success it returns the public key that signed the stamp.
let signer = verify_signed_provenance(&envelope)?;

Compare the returned signer with a configured trusted authority before accepting the claim: the signature check uses the key inside the envelope, which by itself names neither your expected adapter nor a provider-authenticated principal. The envelope is canonical-JSON serializable, so it fits an audit log line, a receipt attachment, or a standalone attestation. Its cryptography is the same used for capability tokens and receipts; the adapter adds no key handling.

Pinned contracts and offline replay

Byte-stable canonical-JSON fixtures pin the lift and lower contract under crates/protocol/chio-tool-call-fabric/fixtures/lift_lower/{openai,anthropic,bedrock}/, three files each, and a test asserts each re-serializes to the same bytes; the two fixture transcripts above read them. chio-provider-conformance keeps its own NDJSON capture corpus under crates/protocol/chio-provider-conformance/fixtures/ and replays it through each adapter behind per-provider cargo features.

chio replay traffic reads a chio-tee-frame.v1 NDJSON stream and deserializes a ToolInvocation from each frame. With no other flags it validates.

$ chio replay traffic \
  --from ./capture.ndjson

chio replay traffic: validating <chio-source>/crates/products/chio-cli/tests/replay_traffic/fixtures/clean_match.ndjson (schema=chio-tee-frame.v1)
  line    1: ok (01H7ZZZZZZZZZZZZZZZZZZZZZA)
chio replay traffic: 1/1 frames passed

--against <policy-path> re-executes each captured call in an ephemeral kernel and compares the recomputed verdict with the captured one. The policy is the one you name, so a replay answers what that policy would have done. That path refuses a policy carrying post-output guards or concrete-server grants, which a pre-output replay cannot honor.

A frame's upstream.system is one of six: openai, anthropic, aws.bedrock, mcp, a2a, and acp; the five vocabulary-only providers have no frame system. A capture goes wrong in two ways: a frame that does not parse, and a schema name that does not match.

$ chio replay traffic \
  --from ./malformed.ndjson

chio replay traffic: validating <chio-source>/crates/products/chio-cli/tests/replay_traffic/fixtures/parse_error.ndjson (schema=chio-tee-frame.v1)
  line    1: FAIL exit=30 ndjson parse error on line 1: key must be a string at line 1 column 2
chio replay traffic: 0/1 frames passed

$ chio replay traffic \
  --from ./capture.ndjson --schema chio-tee-frame.v2

chio replay traffic: validating <chio-source>/crates/products/chio-cli/tests/replay_traffic/fixtures/clean_match.ndjson (schema=chio-tee-frame.v2)
  line    1: FAIL exit=40 schema-version gate failed: expected schema name "chio-tee-frame.v1", got "chio-tee-frame.v2"
chio replay traffic: 0/1 frames passed

Symptoms and fixes

• NonCanonicalArguments on a value you serialized. The bytes are JSON but not RFC 8785 canonical, most often unsorted keys. Re-serialize canonically. Bytes that are not JSON raise InvalidArgumentJson, a different bug.
• A validation failure names the principal. The Principal variant differs from provenance.provider, or one of its fields is empty, padded with whitespace, or carries a control character.
• Bedrock construction refuses before any traffic. The region or API version is not the pinned pair. The transport re-checks the region on every call, so a later override fails too.
• IAM principal resolution fails at startup. One of the six fail-closed conditions under Bedrock IAM caller holds, or the mapping list is empty.
• A recognized native tool fails closed with the feature compiled. The manifest is the second and authoritative gate. Build with new_with_manifest and name the stable entry in server_tools.
• A stream fails instead of forwarding an allowed block. The block exceeded the buffer caps, or the allow carried redactions.
• A Bedrock tool name comes back Malformed. The response carried a toolConfig that does not declare the lifted name: the lift refuses a tool the turn never offered.
• An approval-gated call reads as a plain deny. The kernel-to-fabric conversion maps PendingApproval to Deny with rule_id kernel.pending_approval. Read that reason or the receipt to tell them apart.