api-keys.ts · Source

api-keys.tsapps/web/src/lib/api-keys.tsraw ← lib5,445 B← Back to the app
1/**
2 * API-key UI logic (TASK-0128) — pure functions so the scope-implication
3 * rules, the curl example, and the date formatting are unit-testable
4 * without the DOM.
5 *
6 * Scope semantics (docs/api/authentication.md §7): the scopes are an
7 * implication hierarchy — ADMIN implies WRITE implies READ. The UI shows
8 * the implication (a checkbox row states what it grants) and the CREATION
9 * request stores the MINIMAL selected set (selecting ADMIN alone is sent
10 * as `["ADMIN"]`; the server expands the hierarchy, and the stored row
11 * keeps the minimal set — `api-keys.service.ts` already dedupes, and
12 * `auth.guard.ts` expands ADMIN→WRITE→READ on lookup).
13 */
14 
15export const API_KEY_SCOPES = ["READ", "WRITE", "ADMIN"] as const;
16export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
17 
18/** What each scope grants (shown in the create dialog + badges).
19 *  Kept free of the other scope names so the E2E can address each
20 *  checkbox by role + name unambiguously. The implication is stated once,
21 *  as the dialog footer line ("Implication: ADMIN → WRITE → READ"). */
22export const SCOPE_GRANTS: Record<ApiKeyScope, string> = {
23  READ: "Read workspace content.",
24  WRITE: "Read and create/update content.",
25  ADMIN: "Full access, including admin operations.",
26};
27 
28/** The implied hierarchy: scope → every scope it implies (itself included). */
29export const SCOPE_IMPLIES: Record<ApiKeyScope, ApiKeyScope[]> = {
30  READ: ["READ"],
31  WRITE: ["WRITE", "READ"],
32  ADMIN: ["ADMIN", "WRITE", "READ"],
33};
34 
35/**
36 * The minimal set to STORE for a checked set: drop any scope that is
37 * implied by another selected scope. `["ADMIN","WRITE","READ"]` →
38 * `["ADMIN"]`; `["WRITE","READ"]` → `["WRITE"]`; `["READ"]` → `["READ"]`.
39 */
40export function minimalScopes(selected: readonly ApiKeyScope[]): ApiKeyScope[] {
41  const set = new Set(selected);
42  return API_KEY_SCOPES.filter((s) => {
43    if (!set.has(s)) return false;
44    // Keep `s` only if no OTHER selected scope implies it.
45    const impliedByOther = selected.some((o) => o !== s && SCOPE_IMPLIES[o].includes(s));
46    return !impliedByOther;
47  });
48}
49 
50/** True when `selected` grants `need` (through the implication chain). */
51export function grants(selected: readonly ApiKeyScope[], need: ApiKeyScope): boolean {
52  return selected.some((s) => SCOPE_IMPLIES[s].includes(need));
53}
54 
55/**
56 * A curl example for a key row (the expandable per-key helper). The prefix
57 * is shown masked, the secret is a placeholder — the raw key is never in
58 * this string (it only ever exists in the create response + the reveal
59 * dialog state).
60 */
61export function curlExample(
62  prefix: string,
63  method: "GET" | "POST" | "PATCH" | "DELETE",
64  url: string,
65  body?: string,
66): string {
67  const lines = [`curl -X ${method} \\`];
68  lines.push(`  -H "Authorization: Bearer ${prefix}…(your key)" \\`);
69  if (body) {
70    lines.push(`  -H "Content-Type: application/json" \\`);
71    lines.push(`  -d '${body}' \\`);
72  }
73  lines.push(`  ${url}`);
74  return lines.join("\n");
75}
76 
77export type KeyExpiryState = "never" | "active" | "soon" | "expired";
78 
79const DAY_MS = 24 * 60 * 60 * 1000;
80 
81/**
82 * Expiry state for the list: `never` (no expiry), `soon` (≤ 7 d — red),
83 * `expired` (passed — grey), `active`. Pure (takes `now`) so the red-window
84 * test is deterministic.
85 */
86export function expiryState(expiresAt: string | null | undefined, now: number): KeyExpiryState {
87  if (!expiresAt) return "never";
88  const t = new Date(expiresAt).getTime();
89  if (Number.isNaN(t)) return "expired";
90  if (t <= now) return "expired";
91  if (t - now <= 7 * DAY_MS) return "soon";
92  return "active";
93}
94 
95/** Status badge: Revoked wins, then Expired, then Active. */
96export function keyStatus(
97  row: { revokedAt: string | null; expiresAt: string | null },
98  now: number,
99): "Active" | "Revoked" | "Expired" {
100  if (row.revokedAt) return "Revoked";
101  if (expiryState(row.expiresAt, now) === "expired") return "Expired";
102  return "Active";
103}
104 
105/** Relative time for `lastUsedAt` ("never", "just now", "3 m ago", …). */
106export function relativeTime(iso: string | null | undefined, now: number): string {
107  if (!iso) return "never";
108  const t = new Date(iso).getTime();
109  if (Number.isNaN(t)) return "never";
110  const diff = now - t;
111  if (diff < 0) return "just now";
112  if (diff < 45_000) return "just now";
113  const min = Math.floor(diff / 60_000);
114  if (min < 60) return `${min} m ago`;
115  const h = Math.floor(min / 60);
116  if (h < 24) return `${h} h ago`;
117  const d = Math.floor(h / 24);
118  if (d < 30) return `${d} d ago`;
119  const mo = Math.floor(d / 30);
120  if (mo < 12) return `${mo} mo ago`;
121  return `${Math.floor(mo / 12)} y ago`;
122}
123 
124/** A short date label for expiry ("Jan 5, 2027"). */
125export function shortDate(iso: string): string {
126  const d = new Date(iso);
127  if (Number.isNaN(d.getTime())) return "—";
128  return d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
129}
130 
131/** Validation bounds (mirror the server DTO — the server is authoritative). */
132export const KEY_NAME_MAX = 100;
133export const RATE_LIMIT_MIN = 1;
134export const RATE_LIMIT_MAX = 10_000;
135/** Expiry window: now + 1 h … now + 1 y (docs §7 / the create dialog). */
136export function expiryBounds(now: number): { min: string; max: string } {
137  const toInput = (ms: number) => new Date(ms).toISOString().slice(0, 16);
138  return { min: toInput(now + 3_600_000), max: toInput(now + 365 * 24 * 3_600_000) };
139}
140