Threat model
What humpyard protects, from whom, and where the protections live. It is meant to be short enough to read in
ten minutes and to be updated whenever a trust boundary moves; a change that touches authentication, a network
listener, secrets, or the parsing of untrusted data carries its own threat model in its design.md and updates this
page when it lands. The rules that must keep holding are in Architecture invariants; this page says
which threats they answer and which threats nothing answers yet. Performance has the same kind of register in
Fitness functions.
The system in one paragraph
Clients send LLM requests with a bearer key to the gateway. The gateway authenticates the key, applies the key's
route and budget limits, picks a target, calls the provider with the gateway's own provider key, and records a
usage row and a decision in a local ledger. Operators configure it through a file (and secrets through the
environment), read it through the admin API (/admin/v1, its own credentials), humpyard ctl, and /metrics.
Optional commands read public price and model lists (prices, models). Release artifacts are built in CI.
Assets
| Asset |
Why it matters |
| Provider API keys |
They spend the operator's money and carry the operator's identity at each provider |
| Client keys (stored as SHA-256 hashes) |
They authorise spend through the gateway, within route and budget limits |
| Admin credentials (hashes in the file) |
They can create overrides and revoke credentials; one with the config scope can ask for configuration patches, which write nothing |
| Prompts and responses |
They may contain anything the user sent; the gateway does not store them |
| The ledger (SQLite) |
Key ids, models, token counts, costs, decisions with scrubbed provider error text |
| The configuration and generated target file |
They decide where prompts go; a poisoned one sends them elsewhere |
| Release artifacts and the container image |
What operators run |
Actors
The operator; a legitimate client; a malicious or compromised client key; a provider (trusted to answer, not
trusted for what it returns); a compromised provider or an attacker in the path to one; a public data source
(models.dev, a provider's model list); anyone who can reach a listener; a local user or process on the gateway's
host; a dependency or build-tool maintainer.
Trust boundaries
flowchart LR
C[Client] -->|B1 bearer key| G[Gateway]
G -->|B2 provider key, https| P[Providers]
O[Operator] -->|B3 admin credential| G
F[Config file + env secrets] -->|B4| G
G -->|B5| L[(Ledger)]
S[models.dev, provider model lists] -->|B6 untrusted data, commands only| G
B[CI and registry] -->|B7 release artifacts| G
M[Prometheus] -->|B8 scrape credential| G
Threats and what answers them
"Enforced by" names the invariant, test or ADR that keeps the mitigation true. Gap marks a threat with no
sufficient answer today; they are collected at the end.
B1: client to gateway
| Threat |
Mitigation |
Enforced by |
| Spend or use without a valid key |
Bearer keys, stored only as SHA-256 hashes; authentication, route allow-list and budget are checked before any upstream call |
Invariants 5 and 8; tests/auth.rs, tests/budget.rs |
| A key leaks through logs or the ledger |
Logs name the key id and never the key or its hash; the ledger holds key ids, never hashes |
Invariants 8 and 10; tests/auth.rs (logs_name_the_key_id_but_never_the_key_or_its_hash) |
| Guessing a key |
Keys are random 256-bit values from keygen; a lookup is by the hash of the presented key, so timing reveals nothing usable about the key |
tests/cli.rs (keygen) |
| One key hammering the gateway, or holding many slow streams open |
Optional per-key max_requests_per_minute and max_concurrent, checked after authentication and before the budget and any upstream call; the concurrency permit is released by Drop however the response ends |
Invariant 5; tests/key_rate_limit.rs, tests/key_concurrency.rs, tests/key_limits_reload.rs. Residual: counters are per process (reset on restart, multiplied by replicas) and a holder of several keys has several allowances |
| A key is given more authority than intended, or a profile edit widens keys silently |
A key inherits its profile's settings and can only narrow them: a wider value, an unknown profile, or a privilege in a profile is refused when the file loads, and a reload that would do so is refused as a whole |
src/config/tests.rs (per setting), tests/key_limits_reload.rs (a refused reload keeps the old limits), ADR 0025. Residual: each key has its own counters, so many keys on one profile multiply its allowance (max_active_keys comes with database-managed keys) |
| Many failed authentication attempts |
None |
Gap: failed authentication is not throttled (a limit keyed by source address is inert behind a proxy and would lock out everyone); keys from keygen are 256 random bits, so guessing is not feasible, and a weak hand-chosen secret is the operator's error (ADR 0025 lists limits for database-managed keys) |
| An oversized request exhausts memory |
A request body above 2 MB is refused with 413 |
Gap: this is the web framework's default, not a setting or a tested invariant; it also refuses large multimodal requests, which may not be wanted |
| A client routes around a strict (private-only) route |
The policy narrows targets by class before any algorithm runs |
Invariant 6; tests/policy.rs; ADR 0017 |
A client reaches a route its key may not use by asking for it under an alias, or learns of one from /v1/models |
An alias is resolved to its real name before authorization, so the allow-list is checked on the real name; the list shows an alias only when the key may use its target; aliases cannot collide with a real name or point at another alias |
ADR 0033; tests/model_aliases.rs (the_allowlist_is_checked_on_the_real_name, models_lists_the_aliases_a_key_may_use_with_their_labels); src/config/tests.rs (alias validation) |
| A client key learns the prices of endpoints it may not use, by asking the statistics for a baseline |
The baseline parameter exists only on the administrative statistics; the client statistics refuse it as an unknown parameter, and a baseline is matched exactly against the configured endpoint names, never reaching the query |
tests/baseline_stats.rs (the_client_statistics_do_not_accept_a_baseline, a_hostile_baseline_is_only_ever_text_in_a_refusal); the API guide |
| One key overspends |
Per-key and per-request budgets, integer micro-USD accounting |
Invariant 9; tests/budget.rs |
| Strings a client chooses (model name, session id) reach an operator's screen or a metric label |
Metrics never use client strings as labels; the planned GUI renders every string as text |
ADR 0016; tests/metrics_registry.rs (a_clients_strings_never_become_labels) |
| Prompts or responses are disclosed from storage |
Nothing of the content is stored; decisions keep one scrubbed, bounded line of provider error text |
ADR 0013, ADR 0028; Gap: no test asserts that no ledger column can hold content |
B2: gateway to providers
| Threat |
Mitigation |
Enforced by |
| A provider key reaches the wrong host |
A provider key is sent only to that provider's own origin; quota polling and the model-list fetches send it only over https and do not follow redirects |
Invariant 4b; tests/quota.rs; tests/models_retired.rs (the_key_goes_only_to_the_providers_own_host_and_redirects_are_not_followed); Gap: for chat calls this relies on the HTTP client's defaults, with no test |
| A provider returns hostile or malformed data (tool-call arguments, error text, endless streams) |
Tool-call arguments are repaired within bounds, error text is scrubbed and bounded, the response judge keeps bounded memory, a stream's idle time is bounded |
ADR 0029, ADR 0028, ADR 0030, ADR 0031; src/signals.rs limits |
| Prompts go to a third party the operator did not intend |
private routes are strict: only targets of the allowed classes are eligible |
ADR 0017; the operator's route configuration |
| A slow or failing provider denies service |
Timeouts, failover and endpoint health; health never denies service |
Invariant 14; tests/health.rs |
B3: operator to gateway (admin API, ctl)
| Threat |
Mitigation |
Enforced by |
| A client key reaches the admin API |
The admin and client authenticators never consult each other's credentials; admin authority lives only in the file |
ADR 0027; admin API tests |
| An admin credential leaks |
Hashed, scoped, optionally expiring, and revocable as an expiring override without a deploy |
ADR 0027; Gap: no rate limit on failed admin authentication |
| The admin credential or API is exposed in cleartext |
The admin API can have its own listener |
Gap: the gateway speaks plain HTTP and expects TLS from a reverse proxy; the deployment guide does not say so plainly |
| An admin action is not attributable |
Admin actions are audited as admin:<id> |
ADR 0027 |
A config credential is used to edit authority: a new admin credential, a changed key hash, a new key |
Only named sections are editable; the admin table is not; under keys only set and remove, never sha256, never adding or removing a key; a rejected edit applies nothing |
ADR 0034; invariant 23; tests/config_patch.rs (edits_outside_the_editable_sections_are_refused_naming_the_edit) and the config::patch unit tests |
| A patch answer shows a key hash, a credential hash or a provider header value |
The diff is computed on texts masked by walking the parsed document; loader and parser messages have the file lines they quote removed |
config_patch.rs (removing_a_provider_shows_its_header_without_the_value, a_hash_near_an_edit_is_masked_in_the_context, a_loader_error_never_echoes_a_line_of_the_file); the config::patch diff tests |
| A patch changes the file, reloads or alters the running gateway |
The endpoint has no write path and no reload trigger; every outcome is checked to leave the file, fingerprint and reload status as they were |
invariant 23; config_patch.rs (no_outcome_writes_the_file_reloads_or_changes_the_running_configuration) |
A config credential reads the file's structure by probing diffs |
Gap, accepted: a diff shows the lines around an edit (secrets masked); config is a separate scope, so read alone cannot, and the docs say to give it only to someone who may see the file |
residual; API reference |
A read credential is used, stolen or shared, to read the statistics (now with a series, which adds time resolution) as fast as it likes |
Bounded cost per call (interval, buckets, groups, the row cap), one heavy read at a time and a ten-second shared result |
Gap: the admin API has no per-credential rate limit, for this or any read; the GUI's own refresh timer is client behaviour and does not change it |
The admin GUI (humpyard ui) |
Host, Origin and fetch-site rules, a per-run token when it holds the credential, a strict CSP, text-only rendering |
The admin GUI |
B4: configuration and secrets
| Threat |
Mitigation |
Enforced by |
| Secrets in files or in the repository |
Provider keys come from the environment; the loader rejects plaintext secrets; a maintainer-side pre-commit check blocks key-shaped strings and private names (local, not enforced in CI) |
Invariant 8; ADR 0004; the config tests |
| A poisoned generated target file |
A strict loader accepts it whole or ignores it whole, forces the class, requires zero prices and refuses duplicates |
ADR 0022; tests/discovery_loader.rs |
| A stale or unvalidated change proposed for the file |
A patch names the file's current fingerprint (a stale base is refused with the current one) and passes the check a reload makes before a diff is offered |
ADR 0034; config_patch.rs (a_stale_fingerprint_is_refused_with_the_current_one_even_before_a_reload); server::tests (the shared check) |
| An unreviewed change to the running configuration |
The configuration fingerprint is exposed, so drift is detectable |
ADR 0025; humpyard ctl config --fingerprint |
B5: the ledger
| Threat |
Mitigation |
Enforced by |
| SQL injection |
All SQL is in one module and parameterised |
Invariant 3; tests/architecture.rs |
| Tampering or disclosure of the file |
It holds no secrets and no content; admin authority is never stored in it |
ADR 0027; Gap: not encrypted at rest, and access is the deployment's file permissions |
B6: public data sources (commands only)
| Threat |
Mitigation |
Enforced by |
| A poisoned price or model list changes what is served |
The serving process never fetches them; prices reach it only through the reviewed config; fetched data is untrusted, https-only, size- and time-bounded |
Invariant 4a; ADR 0014, ADR 0022 |
B7: build and release
| Threat |
Mitigation |
Enforced by |
| A vulnerable or malicious dependency |
Advisories, licences and sources are checked on every build; every commit is signed off |
Invariants 11 and 13; the deny and dco jobs; the image runs distroless as non-root |
| Tampered release artifacts or images |
None |
Gap: no signed artifacts, build provenance or SBOM; CI actions are pinned by tag, not by commit; no automated dependency updates |
B8: metrics
| Threat |
Mitigation |
Enforced by |
| Metrics disclose or are abused |
Own credential, optional own listener, bounded label vocabulary that never carries client strings |
ADR 0016; tests/metrics.rs |
Administrative and statistics reads share the process, the runtime, the ledger and the CPU allowance with the request
path (ADR 0036). The threats are to
availability and to the record, so they are checked by tests and measurements; the checks are in
Fitness functions.
| Threat |
Mitigation |
Enforced by |
| A heavy read holds a runtime worker and stalls every request |
The row fold runs on the blocking pool |
Invariant 24; the isolation test (tests/isolation.rs, one worker) |
| Reads take the writer's connections and usage entries are dropped |
A read pool of its own; none dropped in the isolation test |
tests/ledger_read_pool.rs; the isolation test |
| A flood of distinct heavy reads exhausts CPU and memory |
One heavy read per surface, the rest answered 503 and never queued; the shared result is bounded in entries and size |
tests/heavy_reads.rs; the cache bound tests in server::heavy |
| A client's statistics loop shuts the operator out, or one key reads another's cached result, or a caller without the scope takes the gate |
Separate gates per surface; the key is part of the cache key; the scope is checked before the gate |
tests/heavy_reads.rs (a client cannot hold the administrative gate; two keys get their own results; a refused credential does not take the gate) |
| A cached number is read as current |
computed_at_ms in the answer; at most ten seconds old |
tests/heavy_reads.rs; the OpenAPI contract |
| A long prune holds the write lock and an override write fails |
Prunes delete in batches of 10,000 on a task of their own |
tests/ledger_prune.rs; the contention isolation test (slowest override write under 500 ms) |
| A read waits for a connection and holds its gate |
Read pool acquire timeout 2 s, busy timeout 1 s; the handlers answer such a timeout 503 with Retry-After |
tests/ledger_read_pool.rs (the pool timeout is busy); the handlers map it by LedgerError::is_busy |
| A change that can move performance is not tested because the path map missed it |
Every module is classed; every request or shared module is covered by a blocking check; the weekly and release runs catch the rest |
tests/architecture.rs; tests/select_checks.rs |
| The gate is skipped or not required, or the thresholds are loosened to pass a change |
The gate always runs and is a required status check; the thresholds are in docs/performance.md and the spec |
The gate on every pull request; review |
| A failed weekly run goes unnoticed |
An issue labelled performance-regression is opened or commented on, never closed automatically |
Shown on the repository with the rehearse failure dispatch |
| A CPU limit of one core or less lets heavy reads raise request latency |
None yet |
Gap: measured in Run 9 (0.5 CPU: 10.5 to 91 ms p99); the cluster gives the gateway 500m. Raising the limit or the separate-process escalation in the ADR closes it |
GET /admin/v1/decisions?request_id= scans without using the index |
Limit-bounded; not a fold |
Gap: recorded as an open finding in Performance and scale |
B10: who a key is for (actors)
An actor says who a key is for: a person or an agent, with the person an agent acts for as its owner
(ADR 0037). (These are not the threat actors listed
above.) An actor is a label, so the threats are to authority and to the record: a label that quietly becomes a
permission, a caller who chooses who they are, and a leaked key that cannot be retired quickly.
| Threat |
Mitigation |
Enforced by |
| A label becomes a permission: a policy, limiter or route rule starts reading an actor or owner |
An actor grants and removes nothing; a key's authority comes only from the key and its profile; no module outside the attribution code may name one |
Invariant 25; tests/architecture.rs (no_module_reads_an_actor_or_an_owner_to_decide_anything, with samples that break it); tests/actors.rs (an_actor_changes_nothing_a_key_may_do) |
| A caller chooses its own actor or owner, or has its usage attributed to someone else |
The actor comes only from the key's entry in the file; no header, field or user tag in a request is read for it |
The architecture rule above (no request-path code reads one); tests/actors.rs |
| A key names an actor that does not exist, or an owner that is not a person |
Refused when the configuration loads, naming the table and field |
config::tests (the actor tests) |
| A leaked client key stays usable until the next deploy |
POST /admin/v1/keys/{id}/revoke in the credentials scope: an audited, expiring record that only removes access, effective on the next request; deleting the key from the file is the permanent step |
tests/key_revoke.rs |
| A refusal tells a thief whether a key exists or was revoked |
A revoked key is refused with the same 401 and body as an unknown one |
tests/key_revoke.rs (a_revoked_key_is_refused_byte_for_byte_like_a_key_the_gateway_never_knew) |
A client key, or a credential with only the overrides scope, revokes keys or ends a revocation |
The scope is credentials; a client key never reaches the admin API; a revocation is not an override and the override endpoints cannot end it |
tests/key_revoke.rs; tests/architecture.rs (only_the_override_store_the_admin_api_and_the_scrape_touch_revocations) |
| An owner change rewrites history, or a client key reads other keys' usage by actor |
Decisions record the ids as they were when the request was made; the client statistics do not accept group_by=actor or owner |
tests/actors.rs, tests/actor_attribution.rs |
| A key's secret or hash leaves in a view |
The effective configuration, key info and decisions show ids only |
tests/actors.rs, tests/key_revoke.rs |
| A key revoked for a long time is forgotten |
An expiry no later than the overrides maximum, so it ends by itself |
Gap: there is no alert for a key revoked for hours, as HumpyardAdminRevoked is for an admin credential |
B11: settings the operator adds to a client's request (endpoint request defaults)
An endpoint can declare request fields the gateway adds to a request that lacks them
(ADR 0038). The
boundary is the operator's reviewed file writing into a request a client wrote.
| Threat |
Mitigation |
Enforced by |
| A default replaces what the client asked for |
Defaults go through the HTTP client's non-replacing merge, so a field the request carries is never changed, including a value of 0 |
tests/request_defaults.rs (the_clients_own_value_wins_and_only_the_missing_fields_are_filled, a_client_value_equal_to_zero_is_still_the_clients, and the same for the Anthropic format) |
| A client learns the operator's settings, or sets them |
The client sees only its response; the defaults are in the effective configuration, which needs read_config or an admin credential |
tests/request_defaults.rs (defaults_are_not_shown_to_a_client), tests/effective_config.rs |
| A typo or an unsupported field makes a provider reject every request |
An allow-list per protocol, each field typed and ranged, refused at load and by check-config; a refused reload keeps the previous configuration |
config::tests (the request-default tests), tests/request_defaults.rs (the reload test) |
| A default raises cost or changes routing |
max_tokens is not allowed; defaults are merged into the outbound body after planning, budgeting and limits, so none of those sees them |
tests/request_defaults.rs (defaults_do_not_change_which_endpoint_is_chosen_or_how_the_request_is_judged), the allow-list test |
| A default is applied to the wrong model after a failover |
The setting belongs to the endpoint, and each attempt builds its own body |
tests/request_defaults.rs (a_failover_sends_each_endpoint_its_own_defaults) |
| A default hides a thinking request a client made |
Gap: Claude Code's thinking object is not translated to OpenAI-compatible endpoints, so a default reasoning_effort = "none" cannot be overridden by it; only an effort field (reasoning_effort, or output_config.effort) wins. Stated in the configuration guide; the fix belongs in the translation layer or the native Anthropic upstream |
Providers |
Gaps, in the order I would close them
- Report channel. A security policy and private reporting (SECURITY.md). Done with this page.
- Failed-authentication limits, for clients and for the admin API. (Per-key rate and concurrency limits are done.)
- An explicit, configurable request-body limit with a test, replacing the framework default.
- Say plainly that the gateway speaks HTTP and that TLS, in front of it, is required wherever a bearer key or an admin credential crosses a network.
- Release provenance and repository hygiene: artifact attestations and an SBOM for the binaries and the image; pin CI actions by commit; automated dependency updates for cargo, npm and the actions; secret scanning with push protection on the repository (the pre-commit check is not in CI).
- A test that provider keys are not forwarded on a redirect in chat calls, and a schema test that no ledger column can hold content.
- ~~The admin GUI lands with its own threat model and re-checks it against what was built.~~ Done: the admin GUI page records the check.
- Heavy reads under a CPU limit of one core or less. Raise the gateway container's CPU limit to 2, or move heavy reads to a separate process working from a local snapshot of the ledger (ADR 0036). Until then the isolation test passes on the host and fails in a container limited to 1 CPU or less.
- The decisions lookup by request id uses a filter pattern that stops SQLite using its index (308 ms at 1M rows); rewrite the optional filters.
- A per-credential rate limit on the admin API. The heavy-read gate bounds how much work reads can do, but a
read credential can still ask as fast as it likes, and the series (a heavier read) and the GUI's refreshing pages make repeated reads normal. Many visible GUI tabs add up on the gateway; there is no server-side limit.
- An alert for a client key that stays revoked.
humpyard_admin_revocations_active and the HumpyardAdminRevoked rule cover admin credentials only; a key revocation has neither, so a key revoked and forgotten is quiet. Add a gauge and a rule like the admin ones.
- A client's request for thinking cannot reach an OpenAI-compatible endpoint that has a
reasoning_effort default. The translation drops the Anthropic thinking object; map it to an effort in the translation layer, or serve those endpoints through a native Anthropic upstream (roadmap).