Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 141 additions & 0 deletions docs/usage-receipts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
# Signed usage receipts

Usage receipts prove that the gateway signed a particular usage record. They do
not prove provider-billed truth, correct pricing, complete metering, payment,
invoicing, or external anchoring. Unknown costs and token counts remain `null`;
estimated and unknown evidence remains explicitly labelled. Records contain
usage metadata only. They do not contain prompts, completions, or credentials.

## Configuration and storage

`USAGE_RECEIPTS_ENABLED` is off by default. An empty value is off. Accepted true
values are `true`, `1`, `yes`, and `on`; false values are `false`, `0`, `no`, and
`off`, case-insensitively. An invalid value disables receipts with one warning
that does not print the value. While off, usage rows, storage and responses keep
their existing shape, and receipt routes return 404.

For example, an enabled configuration names a key and a secret reference:

```text
USAGE_RECEIPTS_ENABLED=true
USAGE_RECEIPTS_KEY_ID=usage-2026-10
USAGE_RECEIPTS_SIGNING_KEY_REF=USAGE_RECEIPT_PRIVATE
```

The referenced environment variable or Worker secret binding contains a
base64-encoded DER PKCS#8 Ed25519 private key. The reference setting contains only
its binding name. Provision private material through the deployment's secret
mechanism. Neither responses nor errors expose it. Python uses `cryptography`;
the Worker uses WebCrypto Ed25519. Unsupported signing runtimes return 503.

Apply `0032_usage_receipts.sql` to the usage database before enabling receipts.
It creates `usage_receipt_heads`, `usage_receipts`, and `usage_receipt_keys`.
Local SQL uses the ledger's database path. D1 uses the private managed-state
authority. Schema application and public-key review are explicit operator steps.
The migration is additive and does not rewrite existing usage rows.

Independently review the public key, then insert its unique key ID, raw 32-byte
public key encoded as base64, and `reviewed=1` into `usage_receipt_keys`. An
unreviewed key is not published or used to sign. A reviewed active public key
must match the private key. Never reuse an existing key ID for different material.
To rotate, add a newly reviewed public key and change the active key ID/reference.
Keep the old reviewed public keys so old receipts remain verifiable.

With receipts enabled, missing tables, missing or unusable private material,
or an unreviewed/mismatched active key makes receipt reads and writes unavailable
with a JSON 503 error. Usage recording continues. Receipt failures produce only
a fixed warning; they never authorize another provider request.

## Reads and immutable corrections

`GET /v1/usage/receipts/<id>` requires authenticated model-read scope and returns
only a receipt owned by the caller. Its ID is the hexadecimal `record_hash`.
A missing receipt or another principal's receipt returns 404, including for an
administrator. `GET /v1/usage/receipt-keys` requires the same scope and returns
`{"keys":[{"key_id":"...","public_key_base64":"..."}]}`, with reviewed keys
only. Responses use `Cache-Control: no-store`.

A receipt has exactly these fields:

```json
{
"record": {"cost_usd": null, "cost_basis": "unknown"},
"canonical_bytes_base64": "...",
"signature_ed25519": "...",
"key_id": "usage-2026-10",
"previous_hash": null,
"record_hash": "...",
"sequence": 1
}
```

Sequences start at 1 for each principal. Atomic compare-and-swap advances the
head and stores the receipt in one transaction. A stable event ID is unique
within its principal: repeating the same event and metadata returns the same
receipt, while changing that metadata under the same ID returns 409. Ledger
flush events use `<batch-id>:<row-index>`, distinct from a provider request ID.
Use a new event ID for a settlement correction and include the old receipt's
hash as metadata such as `corrects`. The correction appends to the chain; it
never replaces the original record. Reservation reconciliation uses that same
settled-event interface with its immutable settlement/transition identity.

## Canonical bytes and verification

The decoded `canonical_bytes_base64` is the UTF-8 canonical JSON object containing
`version=1`, `principal`, `event_id`, `key_id`, `record`, `sequence`, and
`previous_hash`. Every unknown metadata field and every exact JSON null is kept.
Object keys sort by Unicode codepoint; arrays keep their order. Strings use JSON
escaping with scalar Unicode encoded directly in UTF-8. Lone surrogates are
rejected. Booleans remain distinct from numbers.

Finite floating-point numbers use the exact decimal expansion of their IEEE-754
value, without exponent notation. Negative zero becomes `0`. Integer values
must fit in the JavaScript safe-integer range. This is a versioned gateway
canonical format, rather than the shortest-number encoding used by JSON JCS.
For example, `0.1` becomes
`0.1000000000000000055511151231257827021181583404541015625`.

Signed bytes are the ASCII prefix `MultiLLM usage receipt v1` followed by the
two literal characters backslash and lowercase `n`, followed by canonical JSON
bytes. `signature_ed25519` is the base64-encoded Ed25519 signature of those bytes;
`record_hash` is their SHA-256 digest in lowercase hexadecimal. The signed
context binds the key ID, principal, event, sequence and previous hash.

Verify the signature with a trusted reviewed public key, recompute canonical
bytes and the hash, and compare all displayed fields with the signed payload.
For a complete chain, require sequence 1 and a null previous hash, followed by
consecutive sequence numbers and matching previous hashes. To verify a suffix,
supply an independently trusted starting sequence and hash. Reordering, missing
records and modified metadata fail verification. A chain cannot prove that a
tail was not truncated without an independently trusted latest head. Public key
delivery still depends on trusting the gateway or separately distributing keys.

Both runtime test files check this public RFC 8032 test vector:

```text
public_key_base64: 11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=
key_id: test-1
canonical UTF-8:
{"event_id":"settlement-1","key_id":"test-1","previous_hash":null,"principal":"alice","record":{"cost_basis":"unknown","cost_usd":null,"extra":{"fraction":0.5,"nullable":null,"text":"é","zero":0}},"sequence":1,"version":1}
signature_ed25519: bj6tfJIYOfMT4NdUChDUckhAsA4PLn+ZRTkFoMgFkJ688dug9EXuyw01kUt39d17bJJ+qAP7rzhdROvEgJ9ADg==
record_hash: 500716026bf9836219938f4e6bba0cb435e940bcf6db76910f1ee9f6279ad256
```

## Operational bounds and retention

Canonical documents are limited to 64 KiB, 32 nested levels, and 4,096 visited
values/keys. The private request body is limited to 128 KiB. Content-bearing or
credential-bearing field names are rejected recursively; unknown fields must
still be content-free metadata. Event IDs and key IDs are limited to 128 safe
ASCII characters, principals to 256 Unicode characters. The Worker makes at
most 16 metadata CAS attempts before returning 409 on contention.

Receipts are separate from usage rollups and raw-ledger pruning. There is no
automatic receipt or public-key deletion. Plan storage growth and access with
your retention policy; this feature does not create an immutable external
archive or override a legal deletion requirement. Receipts are written after
successful ledger storage, so a crash or unavailable signing authority can
leave a stored usage event without a receipt. Replaying its stable metadata
event ID can fill that gap without double metering or calling a provider.
Historic ledger rows are not automatically backfilled. Raw/passthrough request
or response bodies are never rewritten.
22 changes: 22 additions & 0 deletions intelligence-migrations/0032_usage_receipts.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
CREATE TABLE IF NOT EXISTS usage_receipt_keys (
key_id TEXT PRIMARY KEY,
public_key_base64 TEXT NOT NULL,
reviewed INTEGER NOT NULL DEFAULT 0 CHECK (reviewed IN (0, 1))
);
CREATE TABLE IF NOT EXISTS usage_receipt_heads (
principal TEXT PRIMARY KEY,
sequence INTEGER NOT NULL DEFAULT 0 CHECK (sequence >= 0),
record_hash TEXT
);
CREATE TABLE IF NOT EXISTS usage_receipts (
id TEXT PRIMARY KEY,
principal TEXT NOT NULL,
event_id TEXT NOT NULL,
sequence INTEGER NOT NULL CHECK (sequence > 0),
previous_hash TEXT,
key_id TEXT NOT NULL REFERENCES usage_receipt_keys(key_id),
receipt_json TEXT NOT NULL,
UNIQUE (principal, sequence),
UNIQUE (principal, event_id)
);
CREATE INDEX IF NOT EXISTS idx_usage_receipts_principal ON usage_receipts(principal, sequence);
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"lint": "ruff check . --select E9,F63,F7,F82",
"typecheck": "mypy --ignore-missing-imports --follow-imports=skip --disable-error-code import-untyped --disable-error-code var-annotated --disable-error-code arg-type --disable-error-code assignment --disable-error-code operator app.py routes services providers streaming",
"test": "python -m pytest -q",
"test:worker": "node --test tests/test_cloudflare_worker.mjs tests/test_cascades_worker.mjs tests/test_cascades_dashboard.mjs tests/test_image_quality_worker.mjs tests/test_secret_scan_worker.mjs tests/test_secret_firewall_worker.mjs tests/test_secret_firewall_coverage_worker.mjs tests/test_roleplay_compaction_budget_worker.mjs tests/test_roleplay_compaction_model_worker.mjs tests/test_roleplay_stream_validation_worker.mjs tests/test_aihubmix_worker.mjs tests/test_gpt_image_moderation_worker.mjs tests/test_dashboard_scripts.mjs tests/test_operations_dashboard.mjs tests/test_opencode_reasoning_worker.mjs tests/test_opencode_thinking_worker.mjs tests/test_nanogpt_reasoning_worker.mjs tests/test_nanogpt_speed_routing_worker.mjs tests/test_sse_heartbeat_worker.mjs tests/test_roleplay_worker.mjs tests/test_roleplay_config_worker.mjs tests/test_roleplay_glm_failover_worker.mjs tests/test_roleplay_intelligence_worker.mjs tests/test_roleplay_memory_worker.mjs tests/test_roleplay_compatibility_worker.mjs tests/test_roleplay_history_reconciliation_worker.mjs tests/test_roleplay_output_contract_analysis.mjs tests/test_roleplay_output_contract_cleanup_worker.mjs tests/test_roleplay_output_contract_nonstream_worker.mjs tests/test_roleplay_output_contract_worker.mjs tests/test_roleplay_performance_worker.mjs tests/test_roleplay_quality_routing_worker.mjs tests/test_roleplay_reasoning_worker.mjs tests/test_roleplay_session_storage_worker.mjs tests/test_roleplay_transport_failure_worker.mjs tests/test_roleplay_unlimited_worker.mjs tests/test_roleplay_workbench_worker.mjs tests/test_roleplay_candidate_context_worker.mjs tests/test_roleplay_operator_worker.mjs tests/test_workbench_stream.mjs tests/test_intelligence_worker.mjs tests/test_intelligence_d1_worker.mjs tests/test_intelligence_auth_worker.mjs tests/test_intelligence_outbound_worker.mjs tests/test_intelligence_operator.mjs tests/test_control_users_worker.mjs tests/test_control_audit_worker.mjs tests/test_access_sso_worker.mjs tests/test_d1_schema_worker.mjs tests/test_shadow_eval_worker.mjs tests/test_auto_routes_worker.mjs tests/test_ai_outbound_worker.mjs tests/test_knowledge_*.mjs tests/test_control_state_worker.mjs tests/test_route_health_worker.mjs tests/test_gateway_mcp_worker.mjs tests/test_usage_ledger_worker.mjs tests/test_media_outbound_worker.mjs tests/test_media_files_worker.mjs tests/test_media_jobs_worker.mjs tests/test_tool_repair_worker.mjs tests/test_prometheus_worker.mjs tests/test_evaluation_noise_floor_worker.mjs tests/test_prompt_templates_worker.mjs tests/test_config_snapshots_worker.mjs tests/test_managed_idempotency_worker.mjs tests/test_wave3_hub_worker.mjs tests/test_wave3_transport_worker.mjs tests/test_admission_leases_worker.mjs tests/test_edge_request_metrics_worker.mjs tests/test_request_cancellation_worker.mjs tests/test_mcp_contract_drift_worker.mjs tests/test_zero_content_retention_worker.mjs tests/test_prompt_cache_cost_worker.mjs tests/test_config_revision_sync_worker.mjs tests/test_gateway_alerts_worker.mjs tests/test_session_tiers_worker.mjs tests/test_usage_reservations_worker.mjs tests/test_shared_generation_cache_worker.mjs tests/test_deferred_tools_worker.mjs tests/test_generation_deadline_worker.mjs tests/test_wave4_worker.mjs tests/test_responses_state_worker.mjs tests/test_gateway_batches_worker.mjs tests/test_semantic_generation_cache_worker.mjs tests/test_canary_traffic_worker.mjs tests/test_context_pages_worker.mjs tests/test_observability_exports_worker.mjs tests/test_prompt_injection_worker.mjs tests/test_pii_rehydration_worker.mjs tests/test_wave5_worker.mjs tests/test_learned_cooldown_worker.mjs tests/test_stream_cost_breaker_worker.mjs tests/test_realtime_worker.mjs",
"test:worker": "node --test tests/test_cloudflare_worker.mjs tests/test_cascades_worker.mjs tests/test_cascades_dashboard.mjs tests/test_image_quality_worker.mjs tests/test_secret_scan_worker.mjs tests/test_secret_firewall_worker.mjs tests/test_secret_firewall_coverage_worker.mjs tests/test_roleplay_compaction_budget_worker.mjs tests/test_roleplay_compaction_model_worker.mjs tests/test_roleplay_stream_validation_worker.mjs tests/test_aihubmix_worker.mjs tests/test_gpt_image_moderation_worker.mjs tests/test_dashboard_scripts.mjs tests/test_operations_dashboard.mjs tests/test_opencode_reasoning_worker.mjs tests/test_opencode_thinking_worker.mjs tests/test_nanogpt_reasoning_worker.mjs tests/test_nanogpt_speed_routing_worker.mjs tests/test_sse_heartbeat_worker.mjs tests/test_roleplay_worker.mjs tests/test_roleplay_config_worker.mjs tests/test_roleplay_glm_failover_worker.mjs tests/test_roleplay_intelligence_worker.mjs tests/test_roleplay_memory_worker.mjs tests/test_roleplay_compatibility_worker.mjs tests/test_roleplay_history_reconciliation_worker.mjs tests/test_roleplay_output_contract_analysis.mjs tests/test_roleplay_output_contract_cleanup_worker.mjs tests/test_roleplay_output_contract_nonstream_worker.mjs tests/test_roleplay_output_contract_worker.mjs tests/test_roleplay_performance_worker.mjs tests/test_roleplay_quality_routing_worker.mjs tests/test_roleplay_reasoning_worker.mjs tests/test_roleplay_session_storage_worker.mjs tests/test_roleplay_transport_failure_worker.mjs tests/test_roleplay_unlimited_worker.mjs tests/test_roleplay_workbench_worker.mjs tests/test_roleplay_candidate_context_worker.mjs tests/test_roleplay_operator_worker.mjs tests/test_workbench_stream.mjs tests/test_intelligence_worker.mjs tests/test_intelligence_d1_worker.mjs tests/test_intelligence_auth_worker.mjs tests/test_intelligence_outbound_worker.mjs tests/test_intelligence_operator.mjs tests/test_control_users_worker.mjs tests/test_control_audit_worker.mjs tests/test_access_sso_worker.mjs tests/test_d1_schema_worker.mjs tests/test_shadow_eval_worker.mjs tests/test_auto_routes_worker.mjs tests/test_ai_outbound_worker.mjs tests/test_knowledge_*.mjs tests/test_control_state_worker.mjs tests/test_route_health_worker.mjs tests/test_gateway_mcp_worker.mjs tests/test_usage_ledger_worker.mjs tests/test_media_outbound_worker.mjs tests/test_media_files_worker.mjs tests/test_media_jobs_worker.mjs tests/test_tool_repair_worker.mjs tests/test_prometheus_worker.mjs tests/test_evaluation_noise_floor_worker.mjs tests/test_prompt_templates_worker.mjs tests/test_config_snapshots_worker.mjs tests/test_managed_idempotency_worker.mjs tests/test_wave3_hub_worker.mjs tests/test_wave3_transport_worker.mjs tests/test_admission_leases_worker.mjs tests/test_edge_request_metrics_worker.mjs tests/test_request_cancellation_worker.mjs tests/test_mcp_contract_drift_worker.mjs tests/test_zero_content_retention_worker.mjs tests/test_prompt_cache_cost_worker.mjs tests/test_config_revision_sync_worker.mjs tests/test_gateway_alerts_worker.mjs tests/test_session_tiers_worker.mjs tests/test_usage_reservations_worker.mjs tests/test_shared_generation_cache_worker.mjs tests/test_deferred_tools_worker.mjs tests/test_generation_deadline_worker.mjs tests/test_wave4_worker.mjs tests/test_responses_state_worker.mjs tests/test_gateway_batches_worker.mjs tests/test_semantic_generation_cache_worker.mjs tests/test_canary_traffic_worker.mjs tests/test_context_pages_worker.mjs tests/test_observability_exports_worker.mjs tests/test_prompt_injection_worker.mjs tests/test_pii_rehydration_worker.mjs tests/test_wave5_worker.mjs tests/test_usage_receipts_worker.mjs tests/test_learned_cooldown_worker.mjs tests/test_stream_cost_breaker_worker.mjs tests/test_realtime_worker.mjs",
"db:migrate": "python scripts/validate_sqlite_schema.py --apply",
"db:validate": "python scripts/validate_sqlite_schema.py",
"security:secrets": "python scripts/check_static_secrets.py",
Expand Down
42 changes: 42 additions & 0 deletions routes/usage_receipts.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
"""Authenticated reads of immutable usage receipts and reviewed public keys."""
from flask import g, jsonify

from route_helpers import api_authenticate_only
from services import usage_receipts


def register_usage_receipt_routes(app, csrf, *, store=None):
def authority():
if not usage_receipts.enabled():
raise usage_receipts.ReceiptError("not_found", 404)
return store or usage_receipts.open_store()

def failed(error):
return jsonify({"error": {"code": error.code, "message": "Usage receipt operation unavailable."}}), error.status

@app.route("/v1/usage/receipts/<id>", methods=["GET", "OPTIONS"])
@csrf.exempt
@api_authenticate_only(required_scope="models")
def usage_receipt(id):
try:
user = g.authenticated_user
principal = str(user.get("username") or user.get("id") or "")
receipt = authority().get(principal, id)
if receipt is None:
raise usage_receipts.ReceiptError("not_found", 404)
response = jsonify(receipt)
response.headers["Cache-Control"] = "no-store"
return response
except usage_receipts.ReceiptError as error:
return failed(error)

@app.route("/v1/usage/receipt-keys", methods=["GET", "OPTIONS"])
@csrf.exempt
@api_authenticate_only(required_scope="models")
def usage_receipt_keys():
try:
response = jsonify({"keys": authority().keys()})
response.headers["Cache-Control"] = "no-store"
return response
except usage_receipts.ReceiptError as error:
return failed(error)
3 changes: 2 additions & 1 deletion services/usage_ledger.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
from datetime import datetime, timedelta, timezone
from typing import Any, Callable, Optional

from services import usage_store
from services import usage_store, usage_receipts

logger = logging.getLogger(__name__)

Expand Down Expand Up @@ -189,6 +189,7 @@ def flush_once(self) -> int:
self._stats["recorded"] += len(batch["rows"])
self._stats["last_flush_at"] = utc_timestamp()
self._notify(0, batch["rows"])
usage_receipts.record_flushed_usage(batch["id"], batch["rows"])
return len(batch["rows"])

def flush(self, timeout: float = 5.0) -> bool:
Expand Down
Loading
Loading