Repository navigation
feat(usage): add opt-in signed usage receipts - #68
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configuration
You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
multillm-proxy | ec0f357 | Oct 09 2026, 05:52 AM |
Summary
Adds opt-in signed usage receipts. Each settled usage event can get an Ed25519-signed, hash-chained receipt per principal, which its owner can fetch and verify. Receipts prove that the gateway signed a usage record. They don't prove what the provider billed. With
USAGE_RECEIPTS_ENABLEDunset oroff(the default), the usage ledger, its storage and every response are byte-for-byte unchanged.USAGE_RECEIPTS_ENABLED: empty means off; a malformed value is off with one warning that leaves the value out.USAGE_RECEIPTS_KEY_IDnames the active key.USAGE_RECEIPTS_SIGNING_KEY_REFnames the environment variable or Worker secret binding that holds the base64 PKCS#8 Ed25519 private key; it never holds the key itself.usage_receipt_keyswithreviewed=1. Unreviewed or mismatched keys don't sign. Rotated-out keys stay published so old receipts remain verifiable.{record, canonical_bytes_base64, signature_ed25519, key_id, previous_hash, record_hash, sequence}.null, and writes numbers as exact IEEE-754 decimals. The signed bytes are domain-separated and bind the key ID, principal, event, sequence and previous hash.cost_usd: null,usage_basis: "unknown").GET /v1/usage/receipts/<id>is owner-only and returns 404 otherwise, including for administrators.GET /v1/usage/receipt-keysreturns reviewed public keys only.modelsscope and sendCache-Control: no-store.cryptographypackage and the Worker with WebCrypto Ed25519. Both test files check the same published RFC 8032 vector and canonical bytes.Details are in
docs/usage-receipts.md.Wiring
services/usage_ledger.py: after a successful flush, the ledger callsusage_receipts.record_flushed_usage(batch_id, rows). This is a no-op while off and absorbs its own errors while on. Event IDs are<batch-id>:<row-index>.worker/usage-ledger-d1.mjsmakes the same call after a stored batch. A D1 deployment where both runtimes see the batch produces one receipt per event, because event IDs are unique per principal.worker/managed-state-dispatch.mjsroutes the private/v1/managed-state/usage-receiptsoperation (append/get/keys). It returns 404 while off, accepts onlyintelligence.internal, and caps requests at 128 KiB.routes/usage_receipts.pyexposesregister_usage_receipt_routes. Mounting it inapp.py, the public Worker routes, the Flask D1 store endpoint and the reservation reconciliation hook come with the Wave 6 integration.Shared registrations
tests/test_usage_receipts_worker.mjsintest:worker.worker/usage-receipts.mjsin the edge module inventory, and both receipt routes in the Flask route inventory.USAGE_RECEIPTS_ENABLED,USAGE_RECEIPTS_KEY_IDandUSAGE_RECEIPTS_SIGNING_KEY_REFin the Container env keys.usage_receipt_keys,usage_receipt_headsandusage_receiptsinREQUIRED_D1_TABLES.No browser-readable headers.
Stacked on #67
Migration numbers must be contiguous in each PR, so this branch merges
feat/learned-cooldown(#67, migration 0031), which stacks on #66 (0030) and #62 (0029). Merge those first.Tests
tests/test_usage_receipts.pyandtests/test_usage_receipts_worker.mjscover:npm run test:worker: 1,684 passed.npm run test:integration: 7 passed.cf:migrations:checkreports 32 contiguous, additive migrations.test:deploy, free routes, client headers and thewrangler deploy --dry-runbundle all pass.tests/test_frontend_build.mjsfails locally because@tailwindcss/cliis not installed. It fails the same way on main.Apply the migration before enabling receipts:
npx wrangler d1 migrations apply multillm-intelligence --remote.CI notes
python/nodejobs: the dependency-audit steps fail on every branch, including main. fix(deps): clear the CI dependency audit advisories #42 fixes that.AdmissionCoordinatorDurable Object migration, whichwrangler versions uploadcannot apply. This is expected untilwrangler deployruns on main.This is part of Wave 6. The README line comes with the Wave 6 integration PR.