Skip to content

feat(api-keys): pause and resume a key instead of only revoking it - #445

Merged
argszero merged 1 commit into
mainfrom
feat/api-key-pause-resume
Nov 12, 2026
Merged

argszero merged 1 commit into
mainfrom
feat/api-key-pause-resume

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

A distribution key could only be active or revoked. Revoking is terminal and drops the row out of the list, so there was no way to stop a key temporarily and bring it back — the settings page could not even show a key that was not active.

This adds the third state, paused:

  • active / paused / revoked, where revoked is still terminal and still delete-only. dao::LIVE_KEY_STATUSES is the single source for the two switchable values; the list, rename, enable/disable and revoke guards derive their SQL from it instead of each spelling the set.
  • PATCH /api/api-keys/:id now takes status: active|paused alongside name (both optional, at least one required). An invalid value is a 400 whose message names every accepted one. Non-owner, missing and already-revoked are all the same 404, as before.
  • GET /api/api-keys lists active and paused rows and marks the caller's own key with current. The revoked display semantics are unchanged.
  • Authentication is untouched: find_api_key_user_and_id still requires active, so a paused key stops working for both the gateway and the platform API the moment it is paused.

The one thing this PR deliberately does not do

Pausing the key the request is authenticated with is refused (400). The reason is architectural rather than cautious: an API key here is also the session credential (AuthUser extracts through the same find_api_key_user_and_id), so pausing your own key ends the session — and on the next login get_or_create_api_key finds no active row and mints a fresh key, which makes that pause cosmetic (that is exactly the hole the work order asked to close). The alternative — never mint while a paused row exists — would let a user pause their last key and then be unable to sign in at all, so the row could never be resumed.

Both of those exits are broken, so the endpoint takes the third one: it refuses, and the UI disables that single button with the reason attached ("this is the key you are signed in with"). get_or_create_api_key is left exactly as it was, and the hole closes structurally instead: the key that get_or_create_api_key will find can never be paused, so a login can never mint a second key over a pause. api_key_cannot_pause_the_key_it_is_signed_in_with pins that (it asserts the re-login returns the very same key).

The consequence to be aware of: the oldest active key — the one login returns — cannot be paused from a browser session, while every key created afterwards can. If that trade is not what you want, the real fix is separating the session credential from the distribution key, which is a much larger change than this PR and is not attempted here.

UI

Badge and action come from one three-state map, the same shape the sharing page already uses for its three states (C2153) — never a two-value ternary, which is how "relisted" once got reported as "resumed". Both the pill text and the button label go through i18n keys in zh and en; no literal strings in JS. The "non-active" pill branch that existed in renderSettings was unreachable before (the backend filtered those rows out) and is reachable now.

Related Issue

No tracked issue: this implements the host's work order filed as rant 2026-11-12T14:13:23 (agent=aitokenpool), item ①.

Item ② of the same rant (a per-key usage comparison on the transactions page) is not in this PR — it follows separately, branched from the tip this one lands on.

Changes

  • src/dao.rs — the status set, set_api_key_status, and the widened guards
  • src/routes/api_keys.rs — PATCH takes status, current marking, the session-key guard
  • src/routes/mod.rs — route registration + three endpoint tests
  • ui/js/app.js + ui/js/i18n.js — pause/resume button, three-state map, zh & en keys
  • docs/architecture.md, ui/README.md — the endpoint list and the settings-page description
  • Positive-control constants in src/i18n_pack.rs moved to the values the gates report (key counts, T() literal counts, backend message count, ERR_MAP entries) — these exist to prove the scanners are not blind, so they are updated rather than loosened
  • No billing arithmetic, no pricing precedence (that is admin model editor: price edits and added models are silently reverted at the next startup #440, untouched), no database migration needed (status already exists with DEFAULT 'active')

Tests

  • cargo test — 610 passed, 0 failed
  • cargo fmt --check — clean
  • cargo clippy --all-targets -- -D warnings — clean
  • New tests added

New tests, and the direction each was measured in:

Test What it pins
api_key_pause_stops_the_key_and_resume_brings_it_back pause → the key's own Bearer is 401, the row is still listed as paused, it can still be renamed, resume → the same key works again, and a paused row can still be revoked
api_key_cannot_pause_the_key_it_is_signed_in_with the session key is refused, stays active, and a re-login returns the same key (no second key minted)
api_key_status_rejects_values_outside_the_live_pair revoked / off / on / ACTIVE / "" are 400, an empty body is 400, and a revoked key cannot be revived
the_status_400_names_every_accepted_value the 400 text names every value in LIVE_KEY_STATUSES, read from the source so the two cannot drift

Mutation evidence (the failure was actually measured, not assumed). The three endpoint tests were also run against the unmodified 05716b9 tree, in a separate worktree of upstream/main with only the tests added: all three fail there, for the behaviour and not for a missing symbol —

baseline_pause_stops_the_key_and_resume_brings_it_back  left: 422, right: 200
  "Failed to deserialize the JSON body into the target type: missing field `name`"
baseline_pausing_the_session_key_is_refused             left: 422, right: 400
baseline_status_values_are_the_live_pair                left: 422, right: 400  (status="revoked")

— i.e. the old endpoint could not express a status change at all (RenameKeyReq required name). The session-key guard's own test was measured the other way, with the guard switched off in this tree: it then fails on 暂停自己应被拒绝 with left: 200, right: 400.

Checklist

  • Branch name follows the convention (feat/…)
  • Commit message follows Conventional Commits
  • Single responsibility — item ② of the rant is deliberately left out
  • Shared layer: the only src/routes/mod.rs edit outside tests is the one-identifier registration (api_keys::rename → api_keys::patch), the same step every sibling endpoint takes

A key used to be `active` or `revoked`, and revoking is terminal and drops
the row from the list, so there was no way to stop a key temporarily and
bring it back. Add `paused` (rant 2026-11-12T14:13:23, item 1).

- dao: `LIVE_KEY_STATUSES` is the single source for the two switchable
  values; list / rename / revoke guards derive their SQL from it instead of
  each spelling the set. `revoked` stays terminal: no path writes it back.
- PATCH /api/api-keys/:id accepts `status: active|paused` next to `name`.
  Invalid values are 400, and the message names every accepted one.
- GET /api/api-keys marks the caller's own key with `current`.
- Pausing the key the request is authenticated with is refused (400). That
  key is also the session credential, so pausing it would sign the caller
  out, and the next login would mint a fresh key over the pause — the pause
  would undo itself. Refusing is the only exit that is neither a lockout
  nor a no-op; the UI disables that one button and says why.
- UI: badge + action come from one three-state map (the shape the sharing
  page already uses, C2153), and each row gets a pause/resume button. The
  previously unreachable non-active pill branch is now reachable.
- docs/architecture.md and ui/README.md are updated with the new endpoint
  behaviour and the session-key restriction.
@argszero
argszero merged commit 59bb0c6 into main Nov 12, 2026
2 checks passed
argszero added a commit that referenced this pull request Nov 12, 2026
Two commits since v0.7.34, no schema change (still 18):

- #445 lets an API key be paused and resumed instead of only revoked.
- #446 breaks the transactions summary down by API key.

The version string moves in the five carriers deploy_gate guards: Cargo.toml,
Cargo.lock, Dockerfile (three places), docker-compose.yml (two) and the new
CHANGELOG heading.

Co-authored-by: argszero <argszero@argszerodeMac-mini.local>
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