src/audit-detail.ts

Functions

Imports

It imports src/ops-types/portal.ts. Imported by src/portal-activity.ts.

Source

1import type { AuditChange, AuditDetail, AuditField } from "./ops-types/portal";
2
3// What an audit row recorded, in plain English, for the Portal's Activity drawer
4// (job_fe0da37c07e0 PR 2). The reason typed with a change, a field-by-field before and after
5// where the row carries both, and the row's other fields by name.
6//
7// NAMED FIELDS, NEVER RAW PARAMS. The same rule capsid_admin_read_ops follows ("copies
8// named fields only"): a document write's params carry a content hash, and a signed
9// row a signature, neither of which belongs on a page. Those, and any nested value,
10// are counted in `withheld` and not shown.
11
12// A key naming a hash, a signature, a credential or a body. Matched per underscore-
13// separated word, so `sha256` and `body_sha256` are withheld and `merge_sha` is shown.
14const WITHHELD_WORD = /^(sha256|hash|sig|signature|token|secret|key|jti|nonce|body|content|text)$/i;
15const VALUE_MAX = 300;
16
17// How a key reads in the drawer, where the plain form ("job_id" as "Job id") is not
18// enough. Anything else is shown with its underscores as spaces.
19const LABELS: Record<string, string> = {
20  id: "Id",
21  job_id: "Job",
22  run_url: "GitHub run",
23  pr_url: "Pull request",
24  undo: "Undo of a change just made",
25  ran: "Ran",
26  posted: "Findings posted",
27  cleared: "Findings cleared",
28  note: "Note",
29  error: "Error",
30  value: "Set to",
31  enabled: "On",
32  old: "From",
33  new: "To",
34  new_path: "New path",
35  max_sessions: "Most sessions at once",
36};
37
38function withheld(key: string): boolean {
39  return key.split("_").some((word) => WITHHELD_WORD.test(word));
40}
41
42function label(key: string): string {
43  const known = LABELS[key];
44  if (known) return known;
45  const plain = key.replace(/_/g, " ").trim();
46  return plain.charAt(0).toUpperCase() + plain.slice(1);
47}
48
49function isObject(v: unknown): v is Record<string, unknown> {
50  return typeof v === "object" && v !== null && !Array.isArray(v);
51}
52
53/** A scalar, or a list of scalars, as one line; null for anything nested. */
54function text(v: unknown): string | null {
55  if (v === null || v === undefined) return "none";
56  if (typeof v === "boolean") return v ? "yes" : "no";
57  if (typeof v === "number") return String(v);
58  if (typeof v === "string") return v.length > VALUE_MAX ? `${v.slice(0, VALUE_MAX - 1)}…` : v;
59  if (Array.isArray(v)) {
60    if (v.length === 0) return "none";
61    const parts = v.map(text);
62    return parts.every((p): p is string => p !== null) ? text(parts.join(", ")) : null;
63  }
64  return null;
65}
66
67/** Each field that differs between `before` and `after`, in the order the row has
68 *  them. A row with only `after` (an add) lists every field as new; only `before` (a
69 *  remove) lists every field as gone. */
70function changesOf(before: Record<string, unknown> | null, after: Record<string, unknown> | null): { changes: AuditChange[]; withheld: number } {
71  const keys = [...new Set([...Object.keys(after ?? {}), ...Object.keys(before ?? {})])];
72  const changes: AuditChange[] = [];
73  let hidden = 0;
74  for (const key of keys) {
75    if (withheld(key)) {
76      hidden++;
77      continue;
78    }
79    const was = before && key in before ? text(before[key]) : null;
80    const is = after && key in after ? text(after[key]) : null;
81    if ((before && key in before && was === null) || (after && key in after && is === null)) {
82      hidden++;
83      continue;
84    }
85    if (before && after && was === is) continue;
86    changes.push({ field: label(key), before: before ? was : null, after: after ? is : null });
87  }
88  return { changes, withheld: hidden };
89}
90
91export function auditDetail(params: string | null): AuditDetail {
92  const empty: AuditDetail = { reason: null, changes: null, fields: [], withheld: 0, unreadable: false };
93  if (params === null || params.trim() === "") return empty;
94  let parsed: unknown;
95  try {
96    parsed = JSON.parse(params);
97  } catch {
98    // Rows written before params were always JSON exist. Said, not hidden.
99    return { ...empty, unreadable: true };
100  }
101  if (!isObject(parsed)) {
102    const value = text(parsed);
103    return value === null || value === "none" ? { ...empty, withheld: value === null ? 1 : 0 } : { ...empty, fields: [{ name: "Recorded", value }] };
104  }
105
106  const reason = typeof parsed.reason === "string" && parsed.reason.trim() ? parsed.reason.trim() : null;
107  const before = isObject(parsed.before) ? parsed.before : null;
108  const after = isObject(parsed.after) ? parsed.after : null;
109  let hidden = 0;
110  let changes: AuditChange[] | null = null;
111  if (before || after) {
112    const diff = changesOf(before, after);
113    changes = diff.changes;
114    hidden += diff.withheld;
115  }
116
117  const fields: AuditField[] = [];
118  for (const [key, v] of Object.entries(parsed)) {
119    // The reason is shown above the fields, and a blank one is no reason at all.
120    if (key === "reason" && typeof v === "string") continue;
121    if ((key === "before" && before) || (key === "after" && after)) continue;
122    const value = withheld(key) ? null : text(v);
123    if (value === null) {
124      hidden++;
125      continue;
126    }
127    fields.push({ name: label(key), value });
128  }
129  return { reason, changes, fields, withheld: hidden, unreadable: false };
130}