Audit APIs

Route and query

chio-http-core embeds no HTTP server. A framework adapter wires handle_regulatory_receipts_signed into its own router and forwards query-string fields through RegulatoryReceiptsQuery. The route constant is REGULATORY_RECEIPTS_PATH, /regulatory/receipts, registered as a GET.

#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct RegulatoryReceiptsQuery {
    /// Filter by agent subject (hex-encoded Ed25519 public key).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub agent: Option<String>,
    /// Include only receipts with `timestamp >= after`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub after: Option<u64>,
    /// Include only receipts with `timestamp <= before`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub before: Option<u64>,
    /// Maximum rows to return (capped at
    /// [`MAX_REGULATORY_EXPORT_LIMIT`]).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limit: Option<usize>,
}

limit_or_default() clamps the caller's limit to the range 1 through 200 and defaults to 200. Filters are optional: an unfiltered query returns the whole authorized source when it has at most 200 matches.

Handler order

The handler runs four steps in order:

1. It refuses a caller with no RegulatorIdentity.
2. It refuses a window whose after is greater than its before, with the message "after must be <= before".
3. It queries the store under ReceiptReadContext::admin_service().
4. It signs the body.

The handler is read-only by construction. The store trait it consumes, RegulatoryReceiptSource, exposes one method, query_receipts, and the backing store is append-only. The API never creates, supersedes, archives, or erases receipt state; retention rotates aged receipts into a separate archive.

Export body and envelope

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

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RegulatoryReceiptExport {
    pub schema: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub agent_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub after: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub before: Option<u64>,
    pub matching_receipts: u64,
    pub generated_at: u64,
    pub receipts: Vec<ChioReceipt>,
}

pub type SignedRegulatoryReceiptExport = SignedExportEnvelope<RegulatoryReceiptExport>;

SignedExportEnvelope is rename_all = "camelCase" and deny_unknown_fields over exactly three keys: body, signerKey, and signature. The signature covers the canonical JSON of body, which is camelCase too. matching_receipts is the full count before the limit; receipts holds up to limit_or_default() rows.

An absent value is omitted, never sent as null: agentId, after, and before carry skip_serializing_if, so an unfiltered export body has four keys: schema, matchingReceipts, generatedAt, and receipts.

Errors

RegulatoryApiError has four variants. Each carries a status, a stable code, and a message, and body() renders them as {"error": <code>, "message": <message>}.

Authorization

The framework adapter validates the caller and passes an authorized RegulatorIdentity to the handler:

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RegulatorIdentity {
    /// Stable identifier for audit logging (e.g. regulator name,
    /// agency id).
    pub id: String,
}

The header has its own constant, REGULATORY_TOKEN_HEADER, X-Regulatory-Token. Its doc comment states the adapter's rule: an adapter must not expose /regulatory/* without requiring that header, and the handler fails closed when the caller identity is missing. Map each token to one RegulatorIdentity and log every successful query. The kernel imposes no token format, so the adapter uses whatever mechanism a security review requires.

Jurisdiction is the operator's rule. The adapter decides which regulators see which slices of the receipt log, the same way capability scoping handles cross-tenant isolation elsewhere.

Compliance score route

The same route group registers POST /compliance/score (COMPLIANCE_SCORE_PATH, handler in crates/platform/chio-http-core/src/compliance.rs). It takes an agent subject and a time window and returns a ComplianceScore on a 0..=1000 scale, computed by compliance_score in chio-kernel. It is a compute-only rollup: the receipt export is the evidence, the score summarizes it, and as_underwriting_evidence projects the score into underwriting.

Tax and billing records

Receipt-driven tax reporting consumes the same billing pipeline as 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. The regulatory envelope is signed. The billing export is an unsigned projection, so retain its source receipts and the export procedure for independent comparison.

1. Select the reporting window your finance process requires, export the intended receipt set, and retain its selection criteria.
2. Apply the agent and tool filters your integration supports. A jurisdiction annotation is application metadata; retain its meaning and source.
3. Cross-reference the regulatory export for any period under audit. Receipt ids appear in both, and the rolled-up cost in the billing export must reconcile to the per-receipt amounts in the regulatory export.

Reconciliation covers the cycle that produces these records, and Export Billing Records the operator workflow.

HIPAA

Configure which Protected Health Information (PHI) may enter the recorded evidence. Chio's data guards (Data Layer) redact configured content before the receipt is sealed; verify the resulting receipt. The regulatory export returns the stored form and performs no redaction of its own, so keep unredacted PHI out of signed envelopes. HIPAA compliance remains the operator's program.

PCI DSS

Keep cardholder data out of receipt contents and adapter metadata. For payment linkage, use the rail's opaque payment_reference, which is the transaction_id the adapter returned. Payment rails plug in as optional modules, and three adapters ship: X402PaymentAdapter (an x402 payment reference), AcpPaymentAdapter (an ACP-Commerce shared-payment-token id), and SimPaymentAdapter (a deterministic id that performs no HTTP and moves no funds).

A card-network bridge is an adapter the operator writes against the PaymentAdapter trait, and that integration enforces the data boundary: identifiers and metadata accept arbitrary strings, and the trait leaves cardholder-data screening to the integration. The regulator cross-references the rail's own logs through the operator's PCI-scoped systems.

GDPR

• Data minimization. The export supports agent and time filters plus a 200-row cap. Filters are optional, so enforce the permitted scope in the adapter and receipt source; a row limit authorizes nothing.
• Audit trail. Every export carries generated_at, and the framework adapter logs the regulator id. The export is a discoverable record for the data subject's right of access.
• Right to erasure. Receipts are append-only and signed, with no per-record deletion or in-place erasure path. Time- and size-based retention governs the log (RetentionConfig on KernelConfig: retention_days default 90, max_size_bytes default 10 GB). Aged receipts rotate into a separate archive database and stay verifiable against the Merkle checkpoint roots preserved there. Chio ships no Article 17 erasure mechanism, and archive rotation is not erasure: the operator defines retention and deletion procedures for the deployment and verifies any configured redaction before sealing.

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

Anchored inclusion proofs

Where the optional web3 anchoring module publishes checkpoint roots on chain, the inclusion proof takes the form of an AnchorInclusionProof (chio.anchor-inclusion-proof.v1). 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 ChioRootRegistry contract. verify_anchor_inclusion_proof checks the receipt signature, the checkpoint statement signature, and the Merkle inclusion path in one pass.