Skip to content

feat(caller): accept an account caller from the website - #320

Open
sefk wants to merge 2 commits into
devfrom
feat/keyed-caller
Open

sefk wants to merge 2 commits into
devfrom
feat/keyed-caller

Conversation

@sefk

@sefk sefk commented Nov 16, 2026 •

Copy link
Copy Markdown

Summary

Part of DevelopmentFinanceObservatory/website#142, API keys on the website's platform proxy. Limits are per account, so the website names a call made with an API key to the backends as x-dfo-caller: user:<32 hex>. The hex is an HMAC digest of the account id, the same shape as today's ip: form.

  • resolve_caller accepts user:<32 lowercase hex> beside a vouched x-dfo-caller-principal, as a new caller kind, account.
    • ip: callers are unchanged.
    • A user: header without the principal is ignored, and the X-Forwarded-For path names the caller.
    • Anything else beside the principal still answers 400.
  • datasets_api/maintenance.py: the deploy-time settle treated any principal that was not secret-sha256: or ip: as a raw pin secret and rewrote it to a hash label. A user: pin principal would have been rewritten, which breaks the account's repeat-pin match. _LABELLED now accepts (ip|user):. Migration 0026 is unchanged; it is immutable.
  • No code branches on Caller.kind. The allowance ledger, pins, shares, cards and exports key on caller.key alone, so they count per account as they stand.
  • Docstrings, datasets_api/README.md and the deploy workflow comment now name both forms.

Test plan

  • just lint and just typecheck.
  • tests/platform/test_caller.py:
    • user: is accepted when vouched, with kind account, and is the same caller from any address.
    • 11 malformed forms answer 400.
    • user: without the principal falls back to the address.
    • A wrong principal still answers 500.
  • tests/datasets_api/test_allowance.py: an account's count is kept apart from addresses, and refunds work.
  • tests/datasets_api/test_pin_door.py: a vouched user: pin is keyed and spent per account, and a malformed one answers 400.
  • tests/datasets_api/test_maintenance.py: the settle statements use the (ip|user) pattern.
  • tests/dataset_store/test_live.py: the live settle seeds a user: key and checks it survives two runs. This needs live Postgres, so it runs in CI only.
  • Locally, the full suite was blocked by a stale sibling spec-kit checkout. After updating it, the touched tests pass. Two test_store_budget tests fail identically on a clean dev.
  • Codex review: no findings.

Coordination

Ship this first. dfo-ai then forwards user: callers (dfo-ai feat/keyed-caller), and the website starts sending them last (website #143).

Docs: docs/guide/quickstart.md now says an API key is optional, linking the hub's new "Use an API key" page. Merge DevelopmentFinanceObservatory/docs#26 first, or the docs build's link check reports that link as broken.

🤖 Generated with Claude Code

https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf

The website is gaining API keys (website#142), and limits are per account, so a
keyed call will name its caller to the backends as `x-dfo-caller:
user:<32 lowercase hex digits>` (an HMAC digest of the account id, the same shape
as the `ip:` form) in place of `ip:<digest>`.

`resolve_caller` now accepts either form beside a vouched
`x-dfo-caller-principal`: `ip:` stays `kind="address"` and `user:` is the new
`kind="account"`. A `user:` caller is accepted only with the principal, so a direct
request cannot claim an account, and the X-Forwarded-For path is unchanged. Shares,
presentation cards and pins therefore count per account. Anything else still
refuses 400 `request_invalid`, and the message names both forms.

`datasets-maintenance settle` told caller keys from raw secrets by the `ip:`
prefix, so it would have rewritten a `user:` pin principal to a `secret-sha256:`
label. Its pattern now admits `user:` keys as well.

This ships ahead of dfo-ai and the website sending `user:` callers.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
The quickstart said the API accepts requests without a key. Anonymous
calls still work, but a key now raises the per-caller limit. Say so, name
the two headers, and link the API keys page.

Refs DevelopmentFinanceObservatory/website#142

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant