Regulatory & Audit APIs

API Surface

The endpoint is implemented as a framework-agnostic handler in chio-http-core/src/regulatory_api.rs. It does not embed an HTTP server: framework adapters wire the handler into their framework's router (Axum, Actix, Fastly Compute@Edge, whatever) and forward query-string fields throughRegulatoryReceiptsQuery.

The query shape:

pub struct RegulatoryReceiptsQuery {
    /// Filter by agent subject (hex-encoded Ed25519 public key).
    pub agent: Option<String>,
    /// Include only receipts with timestamp >= after.
    pub after: Option<u64>,
    /// Include only receipts with timestamp <= before.
    pub before: Option<u64>,
    /// Maximum rows to return (capped at 200).
    pub limit: Option<usize>,
}

And the response body, wrapped in a SignedExportEnvelope:

pub const REGULATORY_RECEIPT_EXPORT_SCHEMA: &str =
    "chio.regulatory.receipt-export.v1";
pub const MAX_REGULATORY_EXPORT_LIMIT: usize = 200;

pub struct RegulatoryReceiptExport {
    pub schema: String,
    pub agent_id: Option<String>,
    pub after: Option<u64>,
    pub before: Option<u64>,
    pub matching_receipts: u64,
    pub generated_at: u64,
    pub receipts: Vec<ChioReceipt>,
}

The envelope is signed with the kernel's receipt-signing keypair. Regulators verify against ChioKernel::public_key() using verify_regulatory_export.matching_receipts is the full count pre-limit; receipts contains up to limit_or_default() rows for paging.

Errors

Four error variants, mapped onto stable HTTP statuses:

Authorization

The handler requires the framework adapter to validate the caller and provide an authorized RegulatorIdentity:

pub struct RegulatorIdentity {
    /// Stable identifier for audit logging
    /// (e.g. regulator name, agency id).
    pub id: String,
}

Operators typically validate a long-lived X-Regulatory-Token header against a small allowlist (each entry mapped to a RegulatorIdentity) and log every successful query. The kernel does not impose a token format; that is left to the framework adapter so operators can use whatever auth mechanism their security review demands.

Tax and Billing Hooks

Receipt-driven tax reporting is a downstream consumer of the same billing pipeline that powers ordinary reconciliation. The regulatory export gives auditors the canonical receipts; the billing export (chio.billing-export.v1 from chio-metering) gives finance the per-receipt cost rollup. Each is signed; each is independently verifiable.

For tax reporting specifically, the typical pattern is:

1. Run the billing export at jurisdiction-relevant cadence (monthly for VAT, annually for income, quarterly for sales tax).
2. Filter records by agent, tool, or jurisdiction tag carried in the receipt's rail metadata.
3. Cross-reference against the regulatory export for any periods under audit; the receipt ids appear in both, so the tax filing is backed by signed receipts and matching billing records.

See Reconciliation & Watchdog for the cycle that produces these records and Export Billing Records for the operator workflow.

Compliance Framework Mappings

Chio receipts and policy elements map onto external compliance frameworks at well-defined points. The mappings are documented per framework on dedicated pages:

• NIST AI RMF: control-id mapping for the GOVERN, MAP, MEASURE, MANAGE functions.
• EU AI Act: mapping for automatic logging and traceability (Article 19), technical documentation and retention (Annex IV), human oversight (Article 14), and monetary risk-management accountability (Article 9).
• ISO 42001: clause-level mapping for AI Management System requirements.
• Compliance Frameworks, the synthesis page with SOC 2 trust-service-criteria mappings and cross-framework references.

Code-Level Claim Labels

Each Chio component that participates in a control has a stable identifier the framework page can reference. Examples:

The framework pages carry the full mappings. This page describes the API, each export's contents, and its use.

HIPAA, PCI, GDPR Considerations

HIPAA

Protected Health Information (PHI) must never appear in an unredacted receipt. Operators handling PHI use Chio's data guards (see Data Layer) to redact prompts and responses before the receipt is sealed. The regulatory export contains the redacted form. Operators should keep unredacted PHI out of signed envelopes; the export does not itself provide HIPAA compliance.

PCI DSS

When a payment rail settles a receipt, the receipt carries only the rail's opaque payment_reference, never the PAN. The shipped adapters are X402PaymentAdapter (an x402 payment reference) and AcpPaymentAdapter (an ACP-Commerce shared-payment-token id); a card-network bridge such as the planned StripePaymentAdapter follows the same rule, retaining only the rail's charge or authorization id. The regulator cross-references the rail's own logs through the operator's PCI-scoped systems; Chio is out of PCI scope by design because it does not handle cardholder data directly.

GDPR

Three GDPR-relevant facts about the regulatory API:

• Data minimization. The export filters by agent, time window, and limit. There is no“return everything” call; even an authorized regulator can only pull the slice their query targets.
• Audit trail. Every export carries generated_at and the regulator id is logged by the framework adapter. The export is a discoverable record for the data subject's right of access.
• Right to erasure. Receipts are append-only and signed; there is no per-record deletion or in-place erasure path. The log is governed by time- and size-based retention (RetentionConfig on KernelConfig: retention_days default 90, max_size_bytes default 10 GB). Aged receipts rotate into a separate archive database instead of being deleted, and remain verifiable against the Merkle checkpoint roots preserved in that archive. Chio ships no Article 17 erasure mechanism; operators keep a data subject's identifying data out of the sealed receipt at write time through the data guards, so the signed log never has to be rewritten.

For breach notification (Article 33 GDPR), the operator joins the receipt log against access logs to establish whose data was affected; the regulatory API is the read-side that auditors use to verify the operator's claim post-incident.

Auditor Workflow

An auditor can use the API as follows:

1. Receive credentials. The operator provisions a regulator token bound to a RegulatorIdentity.
2. Issue a query. GET /regulatory/receipts?after=…&before=…&agent=…&limit=… with the token in the configured header.
3. Verify the envelope. The response is a SignedExportEnvelope. Run verify_regulatory_export (or its framework-adapter equivalent) against the operator's published kernel public key. Verification covers schema, signer key, and canonical-JSON integrity.
4. Request inclusion evidence. Inclusion proofs are not attached to the receipts this API returns. A ChioReceipt carries its signature, content hash, and policy hash, but no Merkle path. To prove a receipt was committed to a checkpoint, the auditor requests a separate evidence-export bundle (EvidenceExportBundle), which pairs the receipts with the signed KernelCheckpoint batch and an inclusion_proofs list of ReceiptInclusionProof records (checkpoint_seq, leaf_index, merkle_root, proof). Each proof verifies the receipt's canonical bytes against the checkpoint's Merkle root. For a receipt anchored on a Web3 rail, the on-chain form is an AnchorInclusionProof (chio.anchor-inclusion-proof.v1), built with the anchoring tooling: it bundles the receipt, a Web3ReceiptInclusion, the signed Web3CheckpointStatement, and an optional chain-anchor record tying the checkpoint root to the root published in the on-chain ChioRootRegistry. verify_anchor_inclusion_proof checks the receipt signature, the checkpoint statement signature, and the Merkle inclusion path in one pass.
5. Cross-reference billing. Pull the billing export over the same window. Receipt ids appear in both; the rolled-up cost in the billing export must reconcile to the per-receipt amounts in the regulatory export.

Worked Example: 90-Day EU AI Act Audit

An EU regulator issues a request for all high-risk decisions issued by a deployed agent over the last 90 days. The agent's subject key is a1b2c3...; the window is after=1740000000 through before=1747776000.

Step 1: Query

curl -s 'https://kernel.example.com/regulatory/receipts?\
agent=a1b2c3...&after=1740000000&before=1747776000&limit=200' \
  -H 'X-Regulatory-Token: <regulator-token>' \
  > export.json

The response body (saved to export.json) is a SignedExportEnvelope:

{
  "schema": "chio.regulatory.receipt-export.v1",
  "agent_id": "a1b2c3...",
  "after": 1740000000,
  "before": 1747776000,
  "matching_receipts": 142,
  "generated_at": 1747776123,
  "receipts": [/* up to 200 ChioReceipt records */],
  "signature": "<ed25519-hex>"
}

Step 2: Verify

use chio_http_core::regulatory_api::{
    verify_regulatory_export, SignedRegulatoryReceiptExport,
};

let envelope: SignedRegulatoryReceiptExport =
    serde_json::from_reader(File::open("export.json")?)?;

let kernel_public_key = load_kernel_public_key();
let verified = verify_regulatory_export(&envelope, &kernel_public_key)?;
assert!(verified, "envelope signature did not match kernel key");

Step 3: Page If Needed

matching_receipts in the envelope identifies whether the response is complete. MAX_REGULATORY_EXPORT_LIMIT = 200; if the matching count exceeds 200, the auditor narrows the time window or filters by tool to page through.

Step 4: Filter by Decision Class

The query does not natively filter by decision class; that is a client-side filter against the receipt stream. For each returned receipt, the auditor inspects the decision field on the receipt body and retains only the variants matching the audit scope (e.g. high-risk classifications, denials, or human-overridden approvals).

Step 5: Archive

The signed envelope is the primary audit record. The auditor retains it alongside the kernel public key fingerprint that was used to verify it; future re-verification works from the same envelope without needing the live kernel to remain online.

Limits

Three limits operators should be explicit about when they expose this API:

• Read-only. The handler cannot mutate, supersede, or amend a receipt. The backing store is append-only; retention rotates aged receipts into a separate archive instead of deleting them. This API only reads: it never creates, archives, or erases receipt state.
• Jurisdiction-scoped. The operator's authorization rules decide which regulators see which slices of the receipt log. Chio does not enforce jurisdiction at the kernel level; that policy belongs in the framework adapter (the same way capability scoping handles cross-tenant isolation elsewhere).
• Pagination is via window narrowing. There is no cursor. The 200-row cap forces regulators with large queries to either narrow the time window or filter by agent. This is intentional: it keeps the API stateless and the export deterministic.

See Also

• Compliance Certificates for the per-deployment certification record that participates in regulatory exports.
• Bilateral Receipts for cross-operator receipt sharing under federation peering.
• Compliance Frameworks for the framework-by-framework mappings.
• Query Audit Receipts for the operator-side query patterns that mirror the regulator API.
• Reconciliation & Watchdog for how receipts get to a state worth exporting.