diff --git a/docs/superpowers/plans/2026-09-08-api-keys-redesign-mockup.html b/docs/superpowers/plans/2026-09-08-api-keys-redesign-mockup.html new file mode 100644 index 0000000..0e0701c --- /dev/null +++ b/docs/superpowers/plans/2026-09-08-api-keys-redesign-mockup.html @@ -0,0 +1,439 @@ +Vantage Key Ledger + + +
+ +
+
+

API keys

+
+ +
+ +
+
6keys in this instance
+
2expire within 7 days
+
1never expires
+
2unused since issue
+
+ +
+
+ + +
+
+ Instance policy caps new keys at 90 days. +
+ +
+
+ key / holderscopeslifetimelast call +
+ +
+
+ gitea-ci-deploy + vt_9f2c… + joe@hostxtra.co.uk · admin +
+
+ serversrw + workflowsrw + secretsr +
+
+
+ 64 days left · 12 Nov +
+ 4 minutes ago +
+
+ +
+
+ eso-cluster-prod + vt_41ab… + joe@hostxtra.co.uk · member +
+
+ secretsr +
+
+
+ 5 days left · 13 Sep +
+ 22 minutes ago +
+
+ +
+
+ status-page-embed + vt_c70e… + priya@hostxtra.co.uk · member +
+
+ statusr + monitorsr +
+
+
+ 318 days left · 23 Jul 2027 +
+ 3 days ago +
+
+ +
+
+ patch-tuesday-runner + vt_2d55… + ops@hostxtra.co.uk · owner +
+
+ vulnsrw + workloadsrw + serversrw + keysr +
+
+
+ No expiry · issued before the 90-day cap +
+ Yesterday +
+
+ +
+
+ laptop-scratch + vt_86f1… + priya@hostxtra.co.uk · member +
+
no scopes granted
+
+
+ Expired 2 Sep +
+ Never used +
+
+ +
+
+ terraform-plan-readonly + vt_0b3d… + joe@hostxtra.co.uk · member +
+
+ serversr + keysr +
+
+
+ 2 days left · 10 Sep +
+ Never used +
+
+
+ + +
+

Create key

+

One dialog, three decisions in the order that matters: who the key is, what it may call, how long it lives. The preview line is the key read back as a sentence before it exists.

+ +
+ +
+
+ + +
+

After it is created

+

The secret is unrecoverable once this closes, so Copy is the primary action and the summary confirms what was granted without a second trip to the ledger.

+ +
+ +
+
+ + +
+

When there are no keys

+
+
+ vt_ · nothing issued yet + You have no API keys. +

Create one to call the REST API from a script or a CI job. It is scoped to what you grant it and never outranks your own role.

+ +
+
+
+ +
diff --git a/docs/superpowers/plans/2026-09-08-api-keys-redesign.md b/docs/superpowers/plans/2026-09-08-api-keys-redesign.md new file mode 100644 index 0000000..a20bde3 --- /dev/null +++ b/docs/superpowers/plans/2026-09-08-api-keys-redesign.md @@ -0,0 +1,378 @@ +# API Keys Page Redesign Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Rebuild `/tokens` — the API keys page and its create dialog — around what an operator actually needs to decide: which credentials are about to expire, what each one can reach, and whether a new one is over-granted. The current page is a seven-column table where every column is a bare string. + +**Reference mockup:** `docs/superpowers/plans/2026-09-08-api-keys-redesign-mockup.html`. Open it in a browser. It is the visual contract for this plan: the posture strip, the record layout, the lifetime bar, the scope matrix and both dialog states are all drawn there, in the app's own tokens and font stacks. Where this plan and the mockup disagree, the plan wins — the mockup carries example data and static markup, not logic. + +**Tech Stack:** Next.js 16 App Router, React 18, Tailwind 3 (tokens only, no hex), TanStack Query. No new dependencies. + +**Existing code:** the whole page is one 487-line file, `web/components/apikeys/ApiKeysPanel.tsx`, rendered by `web/app/(app)/tokens/page.tsx`. + +## Global Constraints + +- **No component may carry a hex value.** Every colour comes from the Tailwind token map (`accent`, `danger`, `warning`, `success`, `text-primary/secondary/tertiary`, `surface`, `surface-2`, `well`, `border`). This is a repository-wide rule, not a preference for this page — see the Frontend section of `CLAUDE.md`. +- **`web/` is dark only.** Do not add a light variant or a theme toggle. +- **State never reads by colour alone.** Every coloured element in the mockup also carries a text label — an amber lifetime bar always sits above the words "5 days left". +- **There is no test runner in `web/`.** Verification for each task is `npm run lint` and `npm run build` from `vantage-app/web`, plus a stated browser check. Pure logic goes in `web/lib/` so it is at least readable in isolation. +- **The API is the boundary; the UI is the courtesy.** Nothing here may be the only thing enforcing a rule. Disabled expiry options, hidden MCP scopes and the role cap are all mirrors of server behaviour that already exists. +- Conventional commits (`feat:`, `refactor:`, `fix:`), one per task. +- Branch: this work is UI-only and independent of the MCP server tasks, but it **collides with them in one file** — read the next section before starting. + +## Relationship to the MCP server plan + +`docs/superpowers/plans/2026-09-08-mcp-server.md` is in progress on branch `feat/mcp-server`. Tasks 1–5 are committed: the `mcp` scope resource exists, and `api_tokens.tag_selector` is modelled, accepted at creation (`POST /api/tokens`) and enforced at the server-resolution chokepoints. Tasks 6–15 are not started. + +**That plan's Task 12 rewrites the same file this plan rewrites**, and its file list is stale — it names `web/app/(app)/settings/`, but the page moved to `web/app/(app)/tokens/` with its body in `web/components/apikeys/ApiKeysPanel.tsx`. Two plans editing one 500-line component from opposite ends is a guaranteed conflict. + +Resolution, and it is a decision this plan makes deliberately: **this plan absorbs MCP Task 12 steps 2, 3, 4 and 5** — the tag selector field, the MCP scope gating, the tag chip in the list, and the agent access panel. They are built here, on the redesigned surfaces, because a tag selector is a field in the create dialog and a tag chip is a column in the ledger, and both are cheaper to design once than to design and then redesign. + +What stays with MCP Task 12: **step 1 only**, the `Agent Access (MCP)` row on `settings/license/page.tsx`, which is a different file and a different page. + +Sequencing: + +- Run this plan **on `feat/mcp-server`, after MCP Task 11**, so `license.features.mcp` and the `mcp:*` scopes exist when Tasks 6 and 7 below need them; or +- run it on its own branch **stopping after Task 5**, and land Tasks 6 and 7 later once MCP merges. + +Tasks 6 and 7 are written to be skippable and are marked so. Nothing in Tasks 1–5 depends on MCP. + +Whichever route is taken, **strike steps 2–5 from MCP Task 12 and leave a pointer to this plan**, so the next worker through does not build the tag picker twice. + +--- + +### Task 1: The lifetime model + +The redesign's one visual idea is that a key's expiry is a bar, not a date — how much of its issued life is left, coloured by urgency. That calculation is the only real logic on the page, so it goes in a module of its own rather than inline in a cell. + +**Files:** +- Create: `web/lib/keyLifetime.ts` +- Modify: none yet + +**Interfaces:** +- Produces: `keyLifetime(token, now)` returning `{ state, remainingPct, label, outsidePolicy }`, consumed by Tasks 2 and 3. + +- [ ] **Step 1: Write the module** + +Create `web/lib/keyLifetime.ts`. It takes an `ApiToken` and returns everything a lifetime cell needs, with no JSX and no date formatting spread across components: + +```ts +import type { ApiToken } from "@/lib/api"; + +export type LifetimeState = "healthy" | "soon" | "expired" | "eternal"; + +export type Lifetime = { + state: LifetimeState; + /** 0–100, the share of the token's issued life still to run. `eternal` is 100. */ + remainingPct: number; + /** e.g. "64 days left · 12 Nov", "Expired 2 Sep", "No expiry". */ + label: string; + /** True when the instance cap has tightened since this token was issued. */ + outsidePolicy: boolean; +}; +``` + +Rules the implementation must honour: + +- `soon` is seven days or fewer remaining — the same `SEVEN_DAYS_MS` threshold the current file already uses. Keep the constant here and delete it there. +- `remainingPct` is measured against the token's **own** issued span (`created_at` → `expires_at`), not against the instance cap. A 30-day key at day 15 is half gone; a 365-day key at day 15 is barely started. Clamp to 0–100, and guard the zero-length span (`created_at === expires_at`) so it cannot divide by zero. +- A token with no `expires_at` is `eternal`, drawn full-width and grey. It is not `healthy` — "runs forever" is the state the posture strip counts as a risk. +- `outsidePolicy` keeps the existing rule verbatim: with a cap set, a token that never expires, or that expires further out than the cap allows, is outside it. **The cap is not applied retroactively** — this is a prompt to rotate, never an error, and the copy must not imply the key has stopped working. +- Accept `now` as an argument with a `Date.now()` default. A function that reads the clock itself cannot be reasoned about. + +- [ ] **Step 2: Verify it compiles** + +From `vantage-app/web`: `npx tsc --noEmit` +Expected: no output. + +- [ ] **Step 3: Commit** + +```bash +git add web/lib/keyLifetime.ts +git commit -m "feat: model an api key's remaining lifetime as a single value" +``` + +--- + +### Task 2: Split the panel into components + +`ApiKeysPanel.tsx` is 487 lines holding a page, a table, two dialogs and a form. Every later task in this plan edits it. Split first, or each of them edits the same file and the diffs stop being reviewable. + +**Files:** +- Create: `web/components/apikeys/ScopeChips.tsx`, `web/components/apikeys/LifetimeBar.tsx`, `web/components/apikeys/KeyLedger.tsx`, `web/components/apikeys/CreateKeyDialog.tsx` +- Modify: `web/components/apikeys/ApiKeysPanel.tsx` + +**Interfaces:** +- Produces: the four components above. `ApiKeysPanel` keeps the queries, the mutations and the dialog open/closed state; the children stay presentational, taking props and calling handlers. + +- [ ] **Step 1: Move the existing pieces out, unchanged** + +This step is a pure refactor — **no visual change, no behaviour change.** Move `summariseScopes` and `ScopeChips` into `ScopeChips.tsx` verbatim, exporting both. Move `ExpiryCell` into `LifetimeBar.tsx` as-is for now (Task 3 rewrites its body). Move the `` block into `KeyLedger.tsx`, the `` block into `CreateKeyDialog.tsx`. + +Keep every explanatory comment with the code it explains. Those comments are the record of why `write` implies `rw` in a chip and why Copy outranks Done, and they are worth more than the lines they sit above. + +`ApiKeysPanel` keeps: both `useQuery` calls, both `useMutation` calls, `showAll`, `createOpen`, `revoking`, the form state, `closeCreate`, `copyToken`, `resetForm` and the expiry-default effect. + +- [ ] **Step 2: Verify nothing moved on screen** + +```bash +npm run lint && npm run build +``` + +Then run the app and compare `/tokens` against the page before the split — key list, create dialog, revoke dialog, empty state. It must be pixel-identical. Any difference is a mistake made during the move, and it is far cheaper to find now than under the redesign. + +- [ ] **Step 3: Commit** + +```bash +git add web/components/apikeys/ +git commit -m "refactor: split the api keys panel into ledger, chips, lifetime and dialog" +``` + +--- + +### Task 3: The ledger + +Replace the seven-column table with the record layout from the mockup: identity (name, `vt_` hint, holder, role) in one column, then scopes, lifetime and last call. + +**Files:** +- Modify: `web/components/apikeys/KeyLedger.tsx`, `web/components/apikeys/LifetimeBar.tsx`, `web/components/apikeys/ScopeChips.tsx` + +**Interfaces:** +- Consumes: `keyLifetime` (Task 1). + +- [ ] **Step 1: Rewrite `LifetimeBar`** + +It renders a 4px track with a filled portion at `remainingPct`, the label beneath it in mono with `tabular-nums`, and the policy note when `outsidePolicy` is set. Colour by state: `bg-success`, `bg-warning`, `bg-danger`, and `bg-text-tertiary` for `eternal`. The label takes the matching text colour. + +Give the track `role="img"` with an `aria-label` carrying the same text as the visible label. A bar with no accessible name is decoration to a screen reader, and this one is the primary signal in the row. + +- [ ] **Step 2: Rewrite the row as a grid, not a `
`** + +The mockup's row is a CSS grid, because the identity column stacks four things and the existing `Table`/`Td` primitives assume one value per cell. Columns: `minmax(220px,1.5fr) minmax(180px,1.3fr) minmax(150px,1fr) 150px auto`, `gap-5`, rows separated by `border-border/60` — reach for the `rule-soft` token if a softer divider is wanted; do not invent a colour. + +Keep the header row as a mono, tracked-out strip on `surface-2`. Keep the hover fill. Keep the owner column conditional on `showAll` — but fold it **into** the identity column as a third line rather than adding a fifth grid column, exactly as the mockup does. `showAll` then changes what a record says, not how the page is laid out. + +Keep the role `Badge` inline in that identity column, and keep `roleVariant` as-is: `owner` accent, `admin` warning, `member` neutral. + +- [ ] **Step 3: Make the scope chips two-part** + +Each chip becomes resource plus a tinted access half — `rw` on `accent/18`, `r` on a neutral wash — as in the mockup. `summariseScopes` already produces exactly this shape and does not change. A token with no scopes keeps its dashed "no scopes granted" chip rather than an em dash; an em dash reads as "unknown", and "this key can call nothing" is a fact worth stating. + +- [ ] **Step 4: Rewrite the mobile layout** + +Below `900px` the grid collapses to a stacked record. Hide the header row and give each cell its own label via `data-label` and a `::before` rule, as the mockup does — an unlabelled date sitting under an unlabelled chip list is unreadable once the columns are gone. The scope list scrolls horizontally in its own track instead of wrapping to four lines. Revoke pins to the top-right of the record and gains a border so it is a real tap target. + +Below `520px`: the posture strip goes single-column, the filter segment goes full width with its hint on its own line, and the dialog footer stacks with the primary button on top. + +Copy these breakpoints from the mockup rather than re-deriving them; they were tuned against a real narrow viewport. + +- [ ] **Step 5: Keep `AsyncBoundary`, the skeleton and the empty state working** + +`TableSkeleton` assumes a table. Either keep it for the loading state and accept a one-frame shape change, or add a small ledger-shaped skeleton beside it. Do not leave the loading state as an empty box. + +The empty state keeps both existing copy variants — instance-wide versus personal — and the "Create your first key" action. + +- [ ] **Step 6: Verify** + +```bash +npm run lint && npm run build +``` + +In a browser at `/tokens`: a healthy key, a key expiring inside seven days, an expired key, a never-expiring key and a key with no scopes all render distinctly. Resize to 375px wide and confirm every cell is labelled and nothing clips. Tab through the page and confirm Revoke is reachable and its focus ring is visible. + +- [ ] **Step 7: Commit** + +```bash +git add web/components/apikeys/ +git commit -m "feat: redesign the api key list as a ledger with lifetime bars" +``` + +--- + +### Task 4: The posture strip + +Four counts above the list, answering "is anything wrong here" before the operator reads a single row. + +**Files:** +- Create: `web/components/apikeys/KeyPosture.tsx` +- Modify: `web/components/apikeys/ApiKeysPanel.tsx` + +- [ ] **Step 1: Build it** + +Four cells in a bordered grid: total keys, expiring within seven days (warning), never expiring (danger), and never used (muted). Derive all four from the `tokens` array already in hand with `keyLifetime` — **no new request, and no new endpoint.** + +"Never used" is `last_used_at == null`. It is muted rather than coloured: an unused key is a cleanup candidate, not an incident. + +The counts describe the list as filtered, so the strip sits below the `My keys` / `All keys` toggle in the DOM order the mockup shows, and re-renders with it. + +- [ ] **Step 2: Delete the old subtitle** + +The `{count} key{s} · {scope}` line under the heading goes; the strip says it better. The masthead is left as the heading and the Create key button, vertically centred. + +The descriptive paragraph about what API keys are for is **not** to be added — it was in an earlier draft of the mockup and was cut deliberately. The `sha256` and role-cap facts appear in the create dialog and the reveal panel, where they are actionable. + +- [ ] **Step 3: Verify** + +Browser check: with the fixtures from Task 3 present, the four counts are correct, and switching `My keys` / `All keys` changes them. + +- [ ] **Step 4: Commit** + +```bash +git add web/components/apikeys/ +git commit -m "feat: summarise key posture above the ledger" +``` + +--- + +### Task 5: The create dialog + +Name and role side by side, scopes as one matrix instead of nine mini-cards, an expiry select that names the resolved date, and a preview line that reads the key back as a sentence before it exists. + +**Files:** +- Modify: `web/components/apikeys/CreateKeyDialog.tsx` +- Create: `web/components/apikeys/ScopeMatrix.tsx` + +- [ ] **Step 1: Build the scope matrix** + +One bordered grid: a resource per row, `read` and `write` checkbox columns, a mono header row. Resources come from `GET /api/tokens/scopes` exactly as now — **do not hardcode the nine resources**, the endpoint is the source of truth and MCP is about to add a tenth. + +Each row carries a one-line description under the resource name ("fleet list, inventory, agent updates"). Those strings are UI copy with no server counterpart, so keep them in one exported record in this file, keyed by resource, and fall back to no description for an unknown key rather than rendering `undefined`. + +The footer carries the running count ("3 of 9 resources · 5 scopes") and two bulk actions: **Read-only everywhere** and **Clear all**. + +Checking `write` must also check `read` in the UI. The server treats write as satisfying read on the same resource, so a `:write`-only token works — but a matrix that lets you tick write while read sits empty invites the reader to conclude the key cannot read. + +- [ ] **Step 2: Name the date in the expiry options** + +Each option renders as "90 days — 7 December 2026", computed from `Date.now()`. Options beyond the cap, and Never, stay `disabled` with the existing hint, and the existing effect that defaults to the shortest allowed option stays as it is. + +- [ ] **Step 3: Add the preview line** + +One mono line in a `well` box, assembled from the current form state: the name, the role, the resources it may read and write, and the date it stops working. It is the over-granting check — reading "may read and write servers, workflows, secrets and keys" out loud is what makes someone go back and untick two boxes. + +Handle the empty states honestly: no name yet, no scopes granted, no expiry. + +- [ ] **Step 4: Rework the reveal panel** + +Keep the warning bar, keep the `sha256` sentence, keep Copy as the primary action with Done as the ghost — all three are existing decisions and all three were right. Add the `curl` example line from the mockup so nobody leaves the dialog to find out how to use what they just made. Put the plaintext key beside its Copy button, stacking below `520px` so Copy is reachable without scrolling 64 characters of hex sideways. + +- [ ] **Step 5: Verify** + +```bash +npm run lint && npm run build +``` + +In a browser: create a key with two resources ticked; the preview names them and the resolved date; the created key's summary matches what the preview said. Confirm the cap still disables the long options, and that closing the dialog after a reveal still invalidates the list. + +- [ ] **Step 6: Commit** + +```bash +git add web/components/apikeys/ +git commit -m "feat: rebuild the create key dialog around a scope matrix and a preview" +``` + +--- + +### Task 6: Tag restriction — absorbs MCP Task 12 steps 2 and 4 + +**Requires MCP Tasks 3–5, which are already committed on `feat/mcp-server`.** Skip this task entirely on a branch that does not have them; `tag_selector` will be rejected by a server without them. + +**Files:** +- Modify: `web/lib/api.ts` (the `ApiToken` type and `createApiToken`) +- Modify: `web/components/apikeys/CreateKeyDialog.tsx`, `web/components/apikeys/KeyLedger.tsx` + +- [ ] **Step 1: Carry the field in the API client** + +Add `tag_selector?: Record | null` to the `ApiToken` type, and `tag_selector?: Record` to `createApiToken`'s body. The server already models, accepts and enforces it — `models/api_token.go` and `api/tokens.go` — so this is the client catching up, not a new contract. + +- [ ] **Step 2: Add the field to the dialog** + +Below the scope matrix, a "Restrict to servers tagged" control offering the key/value vocabulary from `GET /api/servers/tags` (`api.listKnownTags`, already in the client). Reuse the workflow target tag rows from `EditWorkflowModal` if that component can be lifted without dragging workflow state with it; build the smallest possible thing if it cannot. + +Send `tag_selector` omitted or `{}` when unrestricted. **This field is not licence-gated** — tag scoping ships useful on its own and is shown to everyone. + +Two lines of copy earn their place here, because the asymmetry is genuinely surprising: an **empty** selector means unrestricted, and a selector matches a server only when **every** pair matches. Say both. + +- [ ] **Step 3: Show the restriction in the ledger** + +Render a token's `tag_selector` as a chip beside its scopes — `env=prod` in mono. An unrestricted token renders nothing at all, not an empty chip and not "unrestricted": most tokens are unrestricted, and a chip on every row for the common case is noise. Include the selector in the preview line's sentence. + +- [ ] **Step 4: Verify** + +Create a restricted key, confirm the chip appears, and confirm the audit detail on the server records the restriction (`api/tokens.go` already appends "restricted to …"). + +- [ ] **Step 5: Commit** + +```bash +git add web/lib/api.ts web/components/apikeys/ +git commit -m "feat: restrict an api key to tagged servers from the create dialog" +``` + +--- + +### Task 7: Agent access — absorbs MCP Task 12 steps 3 and 5 + +**Requires MCP Tasks 6–11 (the endpoint itself) and the `mcp` licence feature.** Skip on a branch without them. + +**Files:** +- Create: `web/components/apikeys/AgentAccessPanel.tsx` +- Modify: `web/components/apikeys/ApiKeysPanel.tsx`, `web/components/apikeys/ScopeMatrix.tsx` + +- [ ] **Step 1: Gate the MCP scopes in the matrix** + +`mcp:read` and `mcp:write` arrive from `GET /api/tokens/scopes` with no client change. Hide that row when `license.features.mcp` is false, following whatever the console-gated UI already does — check `web/lib/useLicense.ts` for the existing pattern rather than inventing a second one. + +- [ ] **Step 2: Build the panel** + +Below the ledger, visible only when `license.features.mcp` is true: the endpoint URL (`${window.location.origin}/api/mcp`) with a copy button, the copyable client configuration JSON from MCP Task 12 step 5, and one line saying the token needs `mcp:read`, plus `mcp:write` for tools that change anything, linking to the docs page from MCP Task 15. + +Style it as a `well` block, not a card — it is machine output being handed to the operator, the same treatment the install one-liner gets on `/servers/new`. + +- [ ] **Step 3: Verify** + +With the feature off: no panel, no MCP row in the matrix. With it on: both appear, and the copied JSON pastes into a client and connects. + +- [ ] **Step 4: Commit** + +```bash +git add web/components/apikeys/ +git commit -m "feat: surface the mcp endpoint and its scopes on the api keys page" +``` + +- [ ] **Step 5: Amend the MCP plan** + +In `docs/superpowers/plans/2026-09-08-mcp-server.md`, strike steps 2–5 of Task 12, correct its stale file list to `web/app/(app)/tokens/` plus `web/components/apikeys/`, and point the remaining step 1 at this plan for the rest. Commit as `docs:`. + +--- + +### Task 8: Documentation + +**Files:** +- Modify: `vantage-docs/docs/reference/api-tokens.md` + +- [ ] **Step 1: Update the screenshots and the walkthrough** + +The reference page describes the old form field by field. Rewrite the creation walkthrough around the matrix and the preview line, and document the lifetime bar's four states so the colours mean the same thing to a reader as to an operator. If Task 6 landed, document the tag restriction and both halves of its asymmetry. + +- [ ] **Step 2: Commit** + +```bash +cd vantage-docs +git add docs/reference/api-tokens.md +git commit -m "docs: describe the redesigned api keys page" +``` + +--- + +## Verification checklist + +Run before calling the work done: + +- [ ] `npm run lint` and `npm run build` clean from `vantage-app/web`. +- [ ] `grep -rn "#[0-9a-fA-F]\{6\}" web/components/apikeys/` returns nothing. +- [ ] `/tokens` renders correctly at 1440px, 900px and 375px, with nothing clipped and every mobile cell labelled. +- [ ] Every state has a fixture that was actually looked at: healthy, expiring, expired, never-expiring, unscoped, never-used, outside-policy. +- [ ] Keyboard: every control reachable, focus rings visible on the dark ground, the dialog still traps focus and restores it on close. +- [ ] A member (not owner or admin) sees the page, sees only their own keys, and sees no `All keys` toggle. +- [ ] Revoke still works, still names the key in its confirmation and its toast, and still shows the server's error inline on failure. +- [ ] The plaintext key is still shown exactly once, and closing the dialog after a reveal still invalidates the list. diff --git a/web/lib/keyLifetime.ts b/web/lib/keyLifetime.ts new file mode 100644 index 0000000..d55053d --- /dev/null +++ b/web/lib/keyLifetime.ts @@ -0,0 +1,72 @@ +import type { ApiToken } from "@/lib/api"; + +/** + * How much of an API key's issued life is left, as one value. + * + * The list draws expiry as a bar rather than a date, so the calculation behind + * it stopped being a formatting detail of one cell and became the only real + * logic on the page. It lives here so it can be read in one sitting, and so the + * ledger and the posture strip cannot disagree about what "expiring soon" means. + */ + +const DAY_MS = 24 * 60 * 60 * 1000; +const SEVEN_DAYS_MS = 7 * DAY_MS; + +export type LifetimeState = "healthy" | "soon" | "expired" | "eternal"; + +export type Lifetime = { + state: LifetimeState; + /** 0–100, the share of the token's issued life still to run. `eternal` is 100. */ + remainingPct: number; + /** e.g. "64 days left · 12 Nov", "Expired 2 Sep", "No expiry". */ + label: string; + /** True when the instance cap has tightened since this token was issued. */ + outsidePolicy: boolean; +}; + +function shortDate(d: Date) { + return d.toLocaleDateString(undefined, { day: "numeric", month: "short", year: d.getFullYear() === new Date().getFullYear() ? undefined : "numeric" }); +} + +/** + * `capDays` is the instance's current `api_token_max_days`, 0 when unset. It is + * never applied retroactively — a token issued before the cap tightened keeps + * working, and `outsidePolicy` is a prompt to rotate rather than a failure of + * any kind. Copy built on this flag must not imply the key has stopped working. + */ +export function keyLifetime(token: ApiToken, capDays = 0, now = Date.now()): Lifetime { + const outsidePolicy = + capDays > 0 && (!token.expires_at || new Date(token.expires_at).getTime() > now + capDays * DAY_MS); + + if (!token.expires_at) { + // Not "healthy": a key that runs forever is the state the posture strip + // counts as a risk, so it gets its own name rather than the good one. + return { state: "eternal", remainingPct: 100, label: "No expiry", outsidePolicy }; + } + + const expiresAt = new Date(token.expires_at).getTime(); + const issuedAt = new Date(token.created_at).getTime(); + const remainingMs = expiresAt - now; + + if (remainingMs <= 0) { + return { state: "expired", remainingPct: 0, label: `Expired ${shortDate(new Date(expiresAt))}`, outsidePolicy }; + } + + // Measured against the token's own issued span, not against the instance + // cap: a 30-day key at day 15 is half gone, a 365-day key at day 15 is + // barely started, and one bar has to say which. A zero-length span is not + // reachable through the UI but is cheap to survive. + const span = expiresAt - issuedAt; + const rawPct = span > 0 ? (remainingMs / span) * 100 : 100; + const remainingPct = Math.min(100, Math.max(0, rawPct)); + + const days = Math.ceil(remainingMs / DAY_MS); + const label = `${days} day${days === 1 ? "" : "s"} left · ${shortDate(new Date(expiresAt))}`; + + return { + state: remainingMs <= SEVEN_DAYS_MS ? "soon" : "healthy", + remainingPct, + label, + outsidePolicy, + }; +}