[DavidCockerill]

⊙ Problem

The Admin → API Token page is one "Generate token" button: a one-hour token acting as the signed-in admin, never listed, never revoked. Central manager now mints staff tokens for a named owner with a role and a role-capped lifetime, and lists and revokes them (HarperFast/central-manager#973, PR HarperFast/central-manager#975). The page had to catch up.

🤔 Is a whole page warranted, or would the button do?

Yes: the owner, the role and the lifetime are the point of HarperFast/central-manager#973, and a token nobody can see or revoke is what it replaces. The page is the Studio half of that issue (#1985) and ships with it; the old empty-body mint still works on the server, so nothing here is urgent on its own.

💡 Solution

• A mint form: owner (email search over Admin/User, "Me" shortcut), role (least privilege first), name, and a lifetime in hours bounded by the role's cap mirrored from central manager.
• The show-once card keeps the same cache hygiene; another mint waits until the card is dismissed.
• A token table shows owner, role, minter, dates and status, with confirmed Revoke for active tokens.
• The page shows to apiToken:self (every staff role), the form only to apiToken:create: staff who cannot mint still see and revoke their own tokens.

🤔 Why does the role picker offer every role when the server refuses one wider than the owner's?

Nothing central manager exposes says which staff role another account holds; exposing it on Admin/User is a central manager follow-up. So the picker offers every role, defaults to read-only, and the server's refusal, which names the owner's role, is shown under the Role field. One field on the user record reverses this.

🤔 Which review findings were accepted rather than fixed?

Sign-out mid-mint can leave an unheld token live until it expires or idles 5 days: the clean-up revoke has no session; the token stays listed and revocable. Labels cost one cached lookup per other staff id. post-review delta: the 404 revoke wording, comment trims and the starts_with query, not re-reviewed — narrow fixes inside code every full pass read.

⚖️ Alternatives

• Reusing the organization service-account token pieces: they live on the unmerged david/576-org-api-tokens branch, not on stage; fold together once both land.
• A modal instead of an inline form: the page has nothing else on it.
• Lifetime in days: the admin cap is 12 hours.
• Let the server default the role to the owner's: then the lifetime field has no cap to show, and the default is the owner's widest role, not the narrowest useful one.

🔧 Changes

Product and architecture tour

Product and architecture tour

What the page does now

Before	After
One "Generate token" button: a one-hour token acting as the signed-in admin, never listed, never revoked.	An admin mints a token for a named staff owner with a role and a role-capped lifetime; every staff member sees their tokens with a status and can revoke them; admins see everyone's.

A token acts as its owner with the role it was minted with, for at most the role's lifetime, and is refused after 5 days unused; the secret is shown once; the form moves it into page state and clears the mutation cache in the same step.
The page shows only to an API that sends apiToken:self, the permission that ships with the endpoints it drives.

The mint, from form to list

From Mint to the show-once card

The secret goes to the page's state before the mutation forgets it; a token minted after the page was left gets a revoke attempt, and the admin is told when that attempt fails.

sequenceDiagram
    participant Admin
    participant Form as MintStaffApiTokenForm
    participant CM as central manager
    participant Page as ApiTokenIndex
    Admin->>Form: owner, role, name, lifetime
    Form->>CM: POST /Admin/ApiToken/
    alt 403 role wider than the owner holds
        CM-->>Form: refusal naming the owner's role
        Form->>Admin: message under the Role field
    else minted
        CM-->>Form: token with its secret
        Form->>Page: onMinted (page state)
        Form->>Form: reset() the mutation
        Page->>Admin: show-once card
        Form->>CM: GET /Admin/ApiToken/ (list refresh)
    else minted after the page was left
        Form->>CM: DELETE /Admin/ApiToken/:id
        Form->>Admin: warning toast
    end

Loading

Lifetime caps mirror central manager's STAFF_API_TOKEN_LIFETIMES: fabric_readonly up to 14 days (default 14), fabric_support and fabric_staff up to 7 days (default 7), fabric_admin up to 12 hours (default 1). The server refuses longer lifetimes; the form caps the input.

Choosing an owner

The user table holds customers and staff and offers no "ends with" match. The picker reads GET /Admin/User/?email=starts_with=<prefix> page by page until it finds staff, keeps only the staff domain, and asks for more typing when it runs out of pages or hits its limit. Results match the settled prefix; Enter never reaches the mint form; closing cancels the search.

Central manager does not expose another account's staff role. The role list offers every staff role; the server's refusal names the owner's role and appears under the Role field.

The list

Statuses: Active authenticates and can be revoked here; Idle went unused for 5 days before its expiry and is refused; Expired reached its expiry; Revoked was revoked here and stays listed for 30 days. Owner and minter ids are rendered as addresses through GET /Admin/User/:id, one cached lookup per distinct id other than the signed-in account; a failed lookup shows the id.

Files

• index.tsx — the page: the form gated on apiToken:create and held while a card is showing, the show-once card, the filterable table, whose filter matches the shown id and the owner's and minter's address and which keeps the last known rows, with a Retry, through a failed refresh.
• MintStaffApiTokenForm.tsx — react-hook-form + zod form; changing the role resets the lifetime to that role's default; the server's role refusal lands under the role field and clears when the owner changes, other failures toast; a second mint waits while a secret is on screen; a second submit cannot race the first; a token minted after the page was left is revoked, with a refusal, a lost answer and a 404 each worded for what they mean, a 404 being an unconfirmed clean-up that names the token and owner.
• StaffUserPicker.tsx — debounced email-prefix search with a keyboard-navigable listbox; matches belong to the settled prefix only, it searches only while open and closing cancels the search, Enter never reaches the form, and a search that ran out of pages says to type more beside whatever it found.
• StaffApiTokenTable.tsx — the table, laid out like the console: token name over its masked id, a status badge per row, columns that leave as the viewport narrows instead of scrolling sideways, and a row menu at the end; StaffUserCell.tsx shows a user as an initial, name and address (a removed account says so over its id, any other failed lookup shows the id, the signed-in account needs none); StaffApiTokenRowMenu.tsx copies the id or revokes a live token behind the confirm; StaffUserLabel.tsx names the owner inline on the card; MintedTokenCard.tsx is the show-once card with a Done that drops the secret.
• staffTokenRoles.ts — the role list and the lifetime caps mirrored from central manager; mintTokenSchema.ts — the form schema whose lifetime cap follows the role.
• getStaffApiTokens.ts — the list query; staffUsers.ts — the staff search that pages past customers, keeps the staff domain and reports a cut at the limit, and the user lookup that reports a removed account or falls back to the id.
• useGenerateApiToken.ts — the mint: typed payload, gcTime: 0, opts out of the global toast, refreshes the list on any outcome; useRevokeApiToken.ts — the revoke that marks the cached row revoked at once, then refetches.
• AdminShell.tsx — the rail item is "API Tokens", shown on apiToken:self and never through the role-name fallback for an API without staffPermissions; routes.ts — the page title.
• api.patch.d.ts — StaffApiToken, MintedStaffApiToken, StaffApiTokenStatus; apiToken:self added to StaffPermission.
• DESIGN.md — the secret-hygiene invariant, the mirrored caps, the owner-role gap, the permission gating.

✅ Verification

• End-to-end route, run: Studio from this branch against the local Fabric rig's central manager on david/staff-api-tokens; every step below passed, and it caught the *-vs-starts_with query bug fixed here.

Live smoke steps

• As a fabric_admin: minted a read-only token for a fabric_readonly colleague picked by email; the card named the owner and role, the row appeared Active, and a second mint was held until Done.
• Asked for a fabric_admin token for the same owner: "A fabric_admin token would exceed the owner's fabric_readonly role" appeared under the Role field.
• Revoked the token through the confirm: DELETE /Admin/ApiToken/:id answered 200 and the row flipped to Revoked.
• As the fabric_readonly account: the rail shows the page, the list is "Your tokens" with only that token, and there is no mint form.
• The deployed Harper line (5.3) read a trailing * as a literal, so the owner search matched nobody; it now sends email=starts_with=<prefix>, which also works on main.

- `tsc -p tsconfig.app.json`, `oxlint`, and `dprint check` clean; full `vitest run` passes except for 6 failures in `LogsFiltersForm.test.tsx` and `beforeSend.sdk.test.ts` that reproduce on untouched `origin/stage` (2b0b41c).

Unit tests

• staffTokenRoles.test.ts — caps pinned to central manager's numbers.
• mintTokenSchema.test.ts — the lifetime cap follows the role.
• getStaffApiTokens.test.ts, staffUsers.test.ts — request shapes, staff-domain filter, paging past customers, truncation, silent lookup fallback.
• useGenerateApiToken.test.ts — payload, cache hygiene, list refresh on any outcome.
• index.test.tsx — cached rows and a Retry survive a failed refresh; the filter matches the owner address and the masked id.
• StaffApiTokenRowMenu.test.tsx — Revoke only for a live token, copy the id, one revoke for two quick confirms.
• StaffUserCell.test.ts — initials from the name, else the address.
• StaffApiTokenTable.test.ts — the relative-time reading picks days, hours or minutes, never seconds; the id mask keeps head and tail.
• useRevokeApiToken.test.ts — cached row marked revoked at once.
• StaffUserPicker.test.tsx — debounce, pick by click / Enter / Me, no stale matches, Enter never submits, no search once closed, cancellation, the type-more hint.
• MintStaffApiTokenForm.test.tsx — default payload, page-then-reset order, refusal under the role field and cleared on owner change, unseen token revoked with each failure worded, one mint for two racing submits, no mint while a secret is on screen, empty name refused.
• adminShellVisibility.test.ts — who sees the page.

Related PRs: #1780 overlaps (StaffPermission union), #1975 overlaps (StaffPermission union, admin visibility fixture), #1988 overlaps (StaffPermission union, admin visibility fixture), #1989 overlaps (admin visibility fixture)

🤖 Generated with Claude Code

Complexity: medium

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; blocked=cursor-grok(lost); declined=cursor-composer,cursor-kimi,cursor-muse,muse; rounds=9; full=5 @ a064a1e}

_{Review-Attention: study ~20m (critical: mintTokenSchema.ts; decisions: do-less-alternative, auto-revoke-unseen-token, client-side-staff-filter, legacy-api-hides-token-page, role-refusal-via-403) @ a064a1e}

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive management interface for Admin/Staff API tokens, replacing the previous simple token generation mechanism. It adds features to mint tokens with specific roles, owners, and lifetimes, as well as capabilities to list, filter, and revoke active tokens. Key additions include the MintStaffApiTokenForm, StaffUserPicker, and StaffApiTokenTable components, along with corresponding React Query hooks, Zod validation schemas, design documentation, and extensive unit tests. I have no review comments or feedback to provide as no issues were identified.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	80.65%	15526 / 19250
🔵	Statements	80.58%	16488 / 20461
🔵	Functions	76.1%	4179 / 5491
🔵	Branches	75.01%	12046 / 16059

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/admin/routes.ts	69.23%	100%	55.55%	69.23%	33-34, 40-41, 47-48, 54-55
src/features/admin/apiToken/index.tsx	95.23%	60.97%	92.85%	96.96%	68, 89
src/features/admin/apiToken/mintTokenSchema.ts	100%	100%	100%	100%
src/features/admin/apiToken/staffTokenRoles.ts	100%	100%	100%	100%
src/features/admin/apiToken/components/MintStaffApiTokenForm.tsx	93.93%	91.42%	86.66%	93.65%	115-118, 248
src/features/admin/apiToken/components/MintedTokenCard.tsx	0%	100%	0%	0%	17-43
src/features/admin/apiToken/components/StaffApiTokenRowMenu.tsx	86.66%	100%	83.33%	85.71%	30-31
src/features/admin/apiToken/components/StaffApiTokenTable.tsx	100%	84.21%	100%	100%
src/features/admin/apiToken/components/StaffUserCell.tsx	100%	78.04%	100%	100%
src/features/admin/apiToken/components/StaffUserLabel.tsx	0%	0%	0%	0%	10-17
src/features/admin/apiToken/components/StaffUserPicker.tsx	91.66%	88.09%	84.21%	92.59%	68-69, 132, 147
src/features/admin/apiToken/mutations/useGenerateApiToken.ts	100%	100%	100%	100%
src/features/admin/apiToken/mutations/useRevokeApiToken.ts	100%	100%	100%	100%
src/features/admin/apiToken/queries/getStaffApiTokens.ts	100%	100%	100%	100%
src/features/admin/apiToken/queries/staffUsers.ts	100%	100%	100%	100%
src/features/admin/components/AdminShell.tsx	33.33%	61.9%	60%	42.85%	51-73

Generated in workflow #2433 for commit a064a1e by the Vitest Coverage Report Action

[dawsontoth]

Bye bye, conflicts!

[kriszyp]

Yay!

_{🤖 Reviewed with Codex}

[DavidCockerill]

Addressed both review findings in bb63d30: a synchronous submit lock on the mint form (with a racing-double-submit test that fails without it), and a 404 on the post-unmount revoke now reported as an unconfirmed clean-up naming the token and owner rather than "already gone". Gates are green; re-requesting review.

_{🤖 Generated by Anthropic Claude (Fable 5.1) with Claude Code; posted via @DavidCockerill.}

[kriszyp]

_{🤖 Reviewed with Cursor-grok}

[DavidCockerill]

Addressed the two remaining review findings in a064a1e: a failed background refresh keeps the last known tokens (and their menus) on the page with a Retry, and the filter box matches the shown id and the owner's and minter's address. Gates are green; re-requesting review.

_{🤖 Generated by Anthropic Claude (Fable 5.1) with Claude Code; posted via @DavidCockerill.}