@decentrys/ui-sdk 0.1.0

package/src/presentation.ts

@@ -0,0 +1,846 @@
+/**
+ * Where the risk model becomes words a person reads.
+ *
+ * This file is pure. It takes an `Assessment` and returns descriptions —
+ * labels, tones, statements, aria strings — and renders nothing. That split is
+ * deliberate: the rule
+ *
+ *   Unknown is neutral. Risk requires evidence. Malicious requires stronger
+ *   evidence. Users should be shown why.
+ *
+ * is broken in *presentation*, not in markup. A component that paints
+ * "deployed 3 days ago" the same amber as "attributed to a drainer family" has
+ * defeated the entire model while passing every classifier test. So the
+ * decisions that could do that live here, in functions a test can call
+ * directly, rather than being spread across seven components where they can
+ * only be checked by eye.
+ *
+ * Four load-bearing choices:
+ *
+ *  - **Kinds have their own tone families.** `fact`, `capability` and
+ *    `unknown` are not points on the risk scale. They cannot be rendered in a
+ *    severity colour because they are never handed one.
+ *  - **`HistoryPresentation.tone` is the literal type `'neutral'` and
+ *    `isWarning` is the literal type `false`.** Limited history being drawn as
+ *    a warning is not a bug this codebase can have; it does not compile.
+ *  - **A signal that did not raise the level is toned `inactive`.** A stale or
+ *    low-confidence signal is still shown — hiding an observation is its own
+ *    failure — but it is not shown in the colour of one that counted.
+ *  - **Anything above zero hops says so in a sentence**, not just a badge,
+ *    because a hop is an inference about a counterparty and a badge reading
+ *    "2" does not tell anyone that.
+ */
+
+import {
+  HISTORY_STATUS_MEANING,
+  MIN_RAISING_CONFIDENCE,
+  RISK_LEVEL_MEANING,
+  type Assessment,
+  type CapabilitySeverity,
+  type Evidence,
+  type HistoryStatus,
+  type ObservedFact,
+  type PolicyAction,
+  type RiskComponents,
+  type RiskLevel,
+  type SignalStatus,
+  type TechnicalCapability,
+  type ThreatSeverity,
+  type ThreatSignal,
+  type UnknownField,
+  type UnknownReason,
+} from '@decentrys/protect';
+import type { Tone } from './theme';
+import type { UiCopy } from './copy';
+
+// ---------------------------------------------------------------------------
+// Risk levels
+// ---------------------------------------------------------------------------
+
+/**
+ * The labels already published to customers on the marketing site.
+ *
+ * They are copied rather than invented so that a user who read the pricing
+ * page and a user looking at a wallet see the same seven words. Overridable
+ * per component for translation; the meanings come from the model itself.
+ */
+export const RISK_LEVEL_LABEL: Record<RiskLevel, string> = {
+  NO_CRITICAL_RISK_DETECTED: 'No critical risk detected',
+  INFORMATIONAL: 'Informational',
+  CAUTION: 'Caution',
+  ELEVATED_RISK: 'Elevated risk',
+  HIGH_RISK: 'High risk',
+  CRITICAL_THREAT: 'Critical threat',
+  KNOWN_MALICIOUS: 'Known malicious',
+};
+
+/**
+ * A colour-independent ordinal marker.
+ *
+ * Colour must never be the only thing separating these levels — for a
+ * colour-blind user it would be the only thing, and then "informational" and
+ * "critical threat" are the same badge. The glyph escalates monotonically and
+ * `KNOWN_MALICIOUS`, the one level that accuses, gets a different mark
+ * entirely rather than one more exclamation point.
+ */
+const LEVEL_GLYPH: Record<RiskLevel, string> = {
+  NO_CRITICAL_RISK_DETECTED: '·',
+  INFORMATIONAL: 'i',
+  CAUTION: '!',
+  ELEVATED_RISK: '!!',
+  HIGH_RISK: '!!!',
+  CRITICAL_THREAT: '!!!!',
+  KNOWN_MALICIOUS: '✕',
+};
+
+const LEVEL_TONE: Record<RiskLevel, Tone> = {
+  // Neither of these two may look like a warning. Nothing in them indicates
+  // danger, and a new project landing on INFORMATIONAL is the common case.
+  NO_CRITICAL_RISK_DETECTED: 'neutral',
+  INFORMATIONAL: 'info',
+  CAUTION: 'caution',
+  ELEVATED_RISK: 'elevated',
+  HIGH_RISK: 'high',
+  CRITICAL_THREAT: 'critical',
+  KNOWN_MALICIOUS: 'critical',
+};
+
+const LEVEL_ORDER: RiskLevel[] = [
+  'NO_CRITICAL_RISK_DETECTED',
+  'INFORMATIONAL',
+  'CAUTION',
+  'ELEVATED_RISK',
+  'HIGH_RISK',
+  'CRITICAL_THREAT',
+  'KNOWN_MALICIOUS',
+];
+
+export function levelRank(level: RiskLevel): number {
+  return LEVEL_ORDER.indexOf(level);
+}
+
+export interface LevelPresentation {
+  level: RiskLevel;
+  label: string;
+  /** The model's own words for what this level is allowed to mean. */
+  meaning: string;
+  tone: Tone;
+  glyph: string;
+  /**
+   * True from ELEVATED_RISK upward — the levels the classifier can only reach
+   * with threat-signal evidence. Drives whether a banner interrupts a screen
+   * reader, which nothing below that threshold has earned.
+   */
+  evidenceBacked: boolean;
+  /** Only KNOWN_MALICIOUS. The one output that accuses a third party. */
+  accusatory: boolean;
+  liveRegionRole: 'status' | 'alert';
+  ariaLabel: string;
+}
+
+export function levelPresentation(
+  level: RiskLevel,
+  options: { labels?: Partial<Record<RiskLevel, string>> } = {},
+): LevelPresentation {
+  const label = options.labels?.[level] ?? RISK_LEVEL_LABEL[level];
+  const meaning = RISK_LEVEL_MEANING[level];
+  const evidenceBacked = levelRank(level) >= levelRank('ELEVATED_RISK');
+  return {
+    level,
+    label,
+    meaning,
+    tone: LEVEL_TONE[level],
+    glyph: LEVEL_GLYPH[level],
+    evidenceBacked,
+    accusatory: level === 'KNOWN_MALICIOUS',
+    liveRegionRole: evidenceBacked ? 'alert' : 'status',
+    ariaLabel: `Decentrys assessment: ${label}. ${meaning}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Kinds — the separation that keeps a fact from reading as a threat
+// ---------------------------------------------------------------------------
+
+export type EvidenceKind = 'fact' | 'capability' | 'signal' | 'unknown';
+
+export interface KindPresentation {
+  kind: EvidenceKind;
+  /** Rendered as text on every row. Meaning never rests on colour alone. */
+  label: string;
+  /** A distinct *shape* per kind, legible without colour vision. */
+  glyph: string;
+  tone: Tone;
+  /** A second non-colour carrier: each kind has its own left-rule style. */
+  rule: 'solid' | 'dashed' | 'dotted';
+  ruleWidth: string;
+}
+
+export function kindPresentation(kind: EvidenceKind, copy: UiCopy): KindPresentation {
+  switch (kind) {
+    case 'fact':
+      return { kind, label: copy.factLabel, glyph: '·', tone: 'fact', rule: 'solid', ruleWidth: '2px' };
+    case 'capability':
+      return { kind, label: copy.capabilityLabel, glyph: '◇', tone: 'capability', rule: 'dashed', ruleWidth: '2px' };
+    case 'signal':
+      return { kind, label: copy.signalLabel, glyph: '▲', tone: 'critical', rule: 'solid', ruleWidth: '4px' };
+    case 'unknown':
+      return { kind, label: copy.unknownLabel, glyph: '?', tone: 'unknown', rule: 'dotted', ruleWidth: '2px' };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Facts
+// ---------------------------------------------------------------------------
+
+export interface FactPresentation {
+  kind: 'fact';
+  statement: string;
+  source: string;
+  observedAt: string;
+  /** Always the fact tone. A fact has no severity to render. */
+  tone: 'fact';
+}
+
+export function factPresentation(fact: ObservedFact): FactPresentation {
+  return {
+    kind: 'fact',
+    statement: fact.statement,
+    source: fact.source,
+    observedAt: formatTimestamp(fact.observedAt),
+    tone: 'fact',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Capabilities
+// ---------------------------------------------------------------------------
+
+const CAPABILITY_SEVERITY_LABEL: Record<CapabilitySeverity, string> = {
+  INFO: 'Standard',
+  NOTABLE: 'Notable',
+  SIGNIFICANT: 'Significant',
+};
+
+export interface CapabilityPresentation {
+  kind: 'capability';
+  statement: string;
+  severity: CapabilitySeverity;
+  severityLabel: string;
+  grantedBy?: string;
+  /**
+   * Always the capability tone, at every severity.
+   *
+   * A significant capability is emphasised with weight, not recoloured into
+   * the threat palette. "The owner can mint additional supply" is a true
+   * statement about code; painting it the same red as an analyst-verified
+   * drainer match tells a user the two are the same kind of thing.
+   */
+  tone: 'capability';
+  emphasis: 'normal' | 'strong';
+}
+
+export function capabilityPresentation(capability: TechnicalCapability): CapabilityPresentation {
+  return {
+    kind: 'capability',
+    statement: capability.statement,
+    severity: capability.severity,
+    severityLabel: CAPABILITY_SEVERITY_LABEL[capability.severity],
+    grantedBy: capability.grantedBy,
+    tone: 'capability',
+    emphasis: capability.severity === 'SIGNIFICANT' ? 'strong' : 'normal',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Threat signals
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-exported from the classifier rather than redeclared.
+ *
+ * This is the floor the model itself uses to decide whether a signal raised
+ * the level. A second copy here that drifted would show a signal as "did not
+ * count" while it was in fact counting.
+ */
+export { MIN_RAISING_CONFIDENCE };
+
+
+const SEVERITY_LABEL: Record<ThreatSeverity, string> = {
+  LOW: 'Low',
+  MEDIUM: 'Medium',
+  HIGH: 'High',
+  CRITICAL: 'Critical',
+};
+
+const SEVERITY_TONE: Record<ThreatSeverity, Tone> = {
+  LOW: 'caution',
+  MEDIUM: 'elevated',
+  HIGH: 'high',
+  CRITICAL: 'critical',
+};
+
+const SIGNAL_STATUS_LABEL: Record<SignalStatus, string> = {
+  ACTIVE: 'Active',
+  STALE: 'Stale',
+  RESOLVED: 'Resolved',
+  DISPUTED_FACT: 'Disputed',
+  REMOVED: 'Withdrawn',
+};
+
+export interface SignalPresentation {
+  kind: 'signal';
+  explanation: string;
+  severity: ThreatSeverity;
+  severityLabel: string;
+  /**
+   * The severity tone only while the signal is actually counting. A stale or
+   * low-confidence signal is toned `inactive`, because showing it in critical
+   * red would tell a user something contributed to the assessment when the
+   * classifier explicitly excluded it.
+   */
+  tone: Tone;
+  status: SignalStatus;
+  statusLabel: string;
+  active: boolean;
+  raising: boolean;
+  /** Present whenever `raising` is false. Never left to inference. */
+  inertStatement?: string;
+  hops: number;
+  hopLabel: string;
+  hopStatement: string;
+  /** Any hop above zero is an inference about a counterparty. */
+  indirect: boolean;
+  confidence: number;
+  confidenceLabel: string;
+  analystConfirmed: boolean;
+  attribution: string;
+  evidenceCount: number;
+  ariaLabel: string;
+}
+
+export function signalPresentation(
+  signal: ThreatSignal,
+  copy: UiCopy,
+  options: { subjectNoun?: string } = {},
+): SignalPresentation {
+  const subject = options.subjectNoun ?? 'address';
+  const active = signal.status === 'ACTIVE';
+  const raising = active && signal.confidence >= MIN_RAISING_CONFIDENCE;
+  const statusLabel = SIGNAL_STATUS_LABEL[signal.status];
+  const analystConfirmed = signal.evidence.some((e) => e.analystVerified);
+
+  let inertStatement: string | undefined;
+  if (!active) {
+    inertStatement = `This signal is ${statusLabel.toLowerCase()} and did not affect this assessment.`;
+  } else if (!raising) {
+    inertStatement =
+      `Reported at ${formatConfidence(signal.confidence)} confidence, which is too low to raise the risk `
+      + 'level on its own. It is shown because it was observed, not because it counted.';
+  }
+
+  const hop = hopPresentation(signal.hops, subject);
+
+  return {
+    kind: 'signal',
+    explanation: signal.explanation,
+    severity: signal.severity,
+    severityLabel: SEVERITY_LABEL[signal.severity],
+    tone: raising ? SEVERITY_TONE[signal.severity] : 'inactive',
+    status: signal.status,
+    statusLabel,
+    active,
+    raising,
+    inertStatement,
+    hops: signal.hops,
+    hopLabel: hop.label,
+    hopStatement: hop.statement,
+    indirect: hop.indirect,
+    confidence: signal.confidence,
+    confidenceLabel: formatConfidence(signal.confidence),
+    analystConfirmed,
+    attribution: analystConfirmed ? copy.analystConfirmed : copy.notAnalystConfirmed,
+    evidenceCount: signal.evidence.length,
+    ariaLabel:
+      `${copy.signalLabel}, ${SEVERITY_LABEL[signal.severity].toLowerCase()} severity, `
+      + `${formatConfidence(signal.confidence)} confidence, ${hop.label.toLowerCase()}. ${signal.explanation}`,
+  };
+}
+
+export interface HopPresentation {
+  hops: number;
+  label: string;
+  statement: string;
+  indirect: boolean;
+}
+
+/**
+ * Hop distance, in a sentence.
+ *
+ * Zero hops is an observation about the subject. Everything else is an
+ * observation about somebody the subject transacted with, and the further out
+ * it goes the weaker the inference — a badge reading "3" communicates none of
+ * that, so the wording carries it instead.
+ */
+export function hopPresentation(hops: number, subjectNoun = 'address'): HopPresentation {
+  const n = Math.max(0, Math.trunc(hops));
+  if (n === 0) {
+    return {
+      hops: 0,
+      label: 'Direct',
+      statement: `Observed directly on this ${subjectNoun}.`,
+      indirect: false,
+    };
+  }
+  if (n === 1) {
+    return {
+      hops: 1,
+      label: '1 hop',
+      statement:
+        `Observed one hop away. This is an inference about a counterparty of this ${subjectNoun}, `
+        + `not an observation about the ${subjectNoun} itself.`,
+      indirect: true,
+    };
+  }
+  return {
+    hops: n,
+    label: `${n} hops`,
+    statement:
+      `Observed ${n} hops away. This is an inference about a counterparty ${n} steps removed from this `
+      + `${subjectNoun}, not an observation about the ${subjectNoun} itself.`,
+    indirect: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Evidence
+// ---------------------------------------------------------------------------
+
+export interface EvidencePresentation {
+  id: string;
+  type: string;
+  source: string;
+  observedAt: string;
+  confidenceLabel: string;
+  analystConfirmed: boolean;
+  attribution: string;
+  reference?: string;
+}
+
+export function evidencePresentation(evidence: Evidence, copy: UiCopy): EvidencePresentation {
+  return {
+    id: evidence.id,
+    type: evidence.type,
+    source: evidence.source,
+    observedAt: formatTimestamp(evidence.observedAt),
+    confidenceLabel: formatConfidence(evidence.confidence),
+    analystConfirmed: evidence.analystVerified,
+    attribution: evidence.analystVerified ? copy.analystConfirmed : copy.notAnalystConfirmed,
+    reference: evidence.txHash ?? evidence.contract ?? evidence.address,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Unknowns
+// ---------------------------------------------------------------------------
+
+const UNKNOWN_REASON_LABEL: Record<UnknownReason, string> = {
+  UNKNOWN: 'Not known',
+  INSUFFICIENT_DATA: 'Not enough data',
+  PROVIDER_UNAVAILABLE: 'Could not be checked',
+  NOT_APPLICABLE: 'Not applicable',
+};
+
+export interface UnknownPresentation {
+  kind: 'unknown';
+  field: string;
+  statement: string;
+  reasonLabel: string;
+  /** Always the unknown tone. Unknown is neutral; it is not a finding. */
+  tone: 'unknown';
+}
+
+export function unknownPresentation(unknown: UnknownField): UnknownPresentation {
+  return {
+    kind: 'unknown',
+    field: unknown.field,
+    statement: unknown.statement,
+    reasonLabel: UNKNOWN_REASON_LABEL[unknown.reason],
+    tone: 'unknown',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// History
+// ---------------------------------------------------------------------------
+
+const HISTORY_LABEL: Record<HistoryStatus, string> = {
+  ESTABLISHED: 'Established history',
+  MODERATE: 'Some history',
+  LIMITED: 'Limited history',
+  NONE: 'No history',
+};
+
+/**
+ * Note the literal types on `tone` and `isWarning`.
+ *
+ * `historyStatus: 'LIMITED'` is the correct, expected state for anything
+ * recently deployed, and the single most likely place for this product to
+ * betray its own rule. Typing the fields as literals means a future component
+ * cannot render history as a warning by mistake — the attempt does not
+ * typecheck, which is a stronger guarantee than a comment asking nicely.
+ */
+export interface HistoryPresentation {
+  status: HistoryStatus;
+  label: string;
+  statement: string;
+  tone: 'neutral';
+  isWarning: false;
+}
+
+export function historyPresentation(status: HistoryStatus): HistoryPresentation {
+  return {
+    status,
+    label: HISTORY_LABEL[status],
+    statement: HISTORY_STATUS_MEANING[status],
+    tone: 'neutral',
+    isWarning: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Score components
+// ---------------------------------------------------------------------------
+
+export interface ComponentRow {
+  key: keyof RiskComponents;
+  label: string;
+  value: number;
+  /** True for `historyConfidence`, which is coverage rather than danger. */
+  isCoverage: boolean;
+  caveat?: string;
+}
+
+export function componentRows(components: RiskComponents, copy: UiCopy): ComponentRow[] {
+  return [
+    { key: 'technicalRisk', label: 'Technical', value: components.technicalRisk, isCoverage: false },
+    { key: 'behavioralRisk', label: 'Behavioural', value: components.behavioralRisk, isCoverage: false },
+    {
+      key: 'threatIntelligenceRisk',
+      label: 'Threat intelligence',
+      value: components.threatIntelligenceRisk,
+      isCoverage: false,
+    },
+    {
+      key: 'historyConfidence',
+      label: 'Coverage',
+      value: components.historyConfidence,
+      isCoverage: true,
+      caveat: copy.coverageIsNotRisk,
+    },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Sections
+// ---------------------------------------------------------------------------
+
+export interface AssessmentSections {
+  facts: ObservedFact[];
+  capabilities: TechnicalCapability[];
+  /** Signals the classifier counted. */
+  activeSignals: ThreatSignal[];
+  /** Stale, resolved, withdrawn or below the confidence floor. Still shown. */
+  inertSignals: ThreatSignal[];
+  unknowns: UnknownField[];
+  /** True when nothing at all came back — never rendered as a blank panel. */
+  isEmpty: boolean;
+  /** Present exactly when `isEmpty`. Says what the emptiness means. */
+  emptyStatement?: string;
+  summary: string;
+}
+
+/**
+ * Split an assessment into what gets rendered where.
+ *
+ * Facts and capabilities never enter the signal list and signals never enter
+ * the fact list; the separation is structural rather than a convention each
+ * component is trusted to follow. Coverage signals have already been demoted
+ * to facts by `normalizeEvidence` on the wire boundary, so anything arriving
+ * in `threatSignals` here genuinely claims to be one.
+ */
+export function assessmentSections(assessment: Assessment, copy: UiCopy): AssessmentSections {
+  const facts = assessment.facts ?? [];
+  const capabilities = assessment.capabilities ?? [];
+  const signals = assessment.threatSignals ?? [];
+  const unknowns = assessment.unknowns ?? [];
+
+  const activeSignals = signals.filter(
+    (s) => s.status === 'ACTIVE' && s.confidence >= MIN_RAISING_CONFIDENCE,
+  );
+  const inertSignals = signals.filter((s) => !activeSignals.includes(s));
+
+  const isEmpty =
+    facts.length === 0 && capabilities.length === 0 && signals.length === 0 && unknowns.length === 0;
+
+  const parts: string[] = [];
+  if (facts.length) parts.push(`${facts.length} ${plural(facts.length, 'fact')}`);
+  if (capabilities.length) {
+    parts.push(`${capabilities.length} ${plural(capabilities.length, 'capability', 'capabilities')}`);
+  }
+  if (signals.length) parts.push(`${signals.length} ${plural(signals.length, 'threat signal')}`);
+  if (unknowns.length) parts.push(`${unknowns.length} ${plural(unknowns.length, 'unknown')}`);
+
+  return {
+    facts,
+    capabilities,
+    activeSignals,
+    inertSignals,
+    unknowns,
+    isEmpty,
+    emptyStatement: isEmpty ? `${copy.nothingReturned} ${copy.notAnAssurance}` : undefined,
+    summary: parts.length ? parts.join(' · ') : copy.nothingReturned,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Availability
+// ---------------------------------------------------------------------------
+
+export interface AvailabilityPresentation {
+  unavailable: boolean;
+  /** Present when unavailable. Says nothing was checked, and implies nothing. */
+  statement?: string;
+  /**
+   * Never a severity tone.
+   *
+   * Decentrys being unreachable is a fact about Decentrys, not a finding about
+   * the user's transaction. Rendering our own outage in red teaches people
+   * that red means nothing.
+   */
+  tone: 'neutral';
+}
+
+export function availabilityPresentation(assessment: Assessment): AvailabilityPresentation {
+  const outage = (assessment.unknowns ?? []).filter((u) => u.reason === 'PROVIDER_UNAVAILABLE');
+  if (outage.length === 0) return { unavailable: false, tone: 'neutral' };
+  return {
+    unavailable: true,
+    statement: outage.map((u) => u.statement).join(' '),
+    tone: 'neutral',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Policy decision
+// ---------------------------------------------------------------------------
+
+const DECISION_LABEL: Record<PolicyAction, string> = {
+  allow: 'No action requested',
+  inform: 'For your information',
+  warn: 'Review before continuing',
+  warn_strong: 'Review carefully before continuing',
+  require_confirmation: 'Explicit confirmation requested',
+  block: 'This application will not continue',
+};
+
+const DECISION_STATEMENT: Record<PolicyAction, string> = {
+  allow: 'This application’s policy asks for nothing further.',
+  inform: 'Shown because this application’s policy asks that you see it.',
+  warn: 'This application’s policy asks you to read the detail before continuing.',
+  warn_strong: 'This application’s policy asks you to read the detail carefully before continuing.',
+  require_confirmation:
+    'This application’s policy asks you to confirm explicitly before continuing.',
+  block:
+    'This application’s policy stops here. That decision belongs to this application; Decentrys reports evidence and does not stop anything.',
+};
+
+export interface DecisionPresentation {
+  action: PolicyAction;
+  label: string;
+  statement: string;
+  reason: string;
+  /**
+   * These components never disable a host application's controls.
+   *
+   * Typed as the literal `false` so no component can be written that reads
+   * this field and switches a button off. Policy is the integrator's, and it
+   * is theirs to enforce in their own UI.
+   */
+  blocksUi: false;
+}
+
+export function decisionPresentation(
+  decision: { action: PolicyAction; reason: string },
+): DecisionPresentation {
+  return {
+    action: decision.action,
+    label: DECISION_LABEL[decision.action],
+    statement: DECISION_STATEMENT[decision.action],
+    reason: decision.reason,
+    blocksUi: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Approvals
+// ---------------------------------------------------------------------------
+
+export interface ApprovalDetails {
+  token: string;
+  symbol?: string;
+  decimals?: number;
+  spender: string;
+  /** A name the integrator already has for the spender, if any. */
+  spenderLabel?: string;
+  /** Base units, or the literal string `unlimited`. */
+  amount?: string;
+}
+
+export interface ApprovalPresentation {
+  unlimited: boolean;
+  amountKnown: boolean;
+  amountLabel: string;
+  scopeLabel: string;
+  statement: string;
+  spenderName: string;
+  assetName: string;
+  /**
+   * The capability tone, never a threat tone.
+   *
+   * An unlimited allowance is a *scope*, and describing it accurately is the
+   * whole job: "unlimited approval requested" is useful, "scam detected" is
+   * both unsupported and the thing that trains people to click through.
+   */
+  tone: 'capability';
+  emphasis: 'normal' | 'strong';
+}
+
+export function approvalPresentation(details: ApprovalDetails): ApprovalPresentation {
+  const spenderName = details.spenderLabel?.trim() || shortenAddress(details.spender);
+  const assetName = details.symbol?.trim() || `tokens at ${shortenAddress(details.token)}`;
+
+  if (details.amount === undefined || details.amount === null || details.amount === '') {
+    return {
+      unlimited: false,
+      amountKnown: false,
+      amountLabel: 'Not decoded',
+      scopeLabel: 'Allowance amount not decoded',
+      statement:
+        `The allowance amount could not be decoded, so how much this grants ${spenderName} over your `
+        + `${assetName} is not known.`,
+      spenderName,
+      assetName,
+      tone: 'capability',
+      emphasis: 'strong',
+    };
+  }
+
+  if (isUnlimitedAllowance(details.amount)) {
+    return {
+      unlimited: true,
+      amountKnown: true,
+      amountLabel: 'Unlimited',
+      scopeLabel: 'Unlimited allowance',
+      statement:
+        `This grants ${spenderName} permission to spend an unlimited amount of your ${assetName}, `
+        + 'now and at any time in the future, until it is revoked.',
+      spenderName,
+      assetName,
+      tone: 'capability',
+      emphasis: 'strong',
+    };
+  }
+
+  // With no decimals supplied the figure is base units, and it is *labelled*
+  // as base units rather than silently presented as whole tokens — an
+  // allowance shown 10^18 times too small is worse than one not shown at all.
+  const baseUnits = details.decimals === undefined;
+  const figure = formatTokenAmount(details.amount, details.decimals);
+  const amountLabel = baseUnits ? `${figure} base units` : `${figure} ${assetName}`;
+  return {
+    unlimited: false,
+    amountKnown: true,
+    amountLabel,
+    scopeLabel: 'Limited allowance',
+    statement:
+      `This grants ${spenderName} permission to spend up to ${figure} `
+      + `${baseUnits ? `base units of ${assetName}` : assetName}, until it is revoked.`,
+    spenderName,
+    assetName,
+    tone: 'capability',
+    emphasis: 'normal',
+  };
+}
+
+/** ERC-20 approvals commonly use a sentinel near uint256 max to mean "no cap". */
+export function isUnlimitedAllowance(amount: string): boolean {
+  if (amount.trim().toLowerCase() === 'unlimited') return true;
+  try {
+    return BigInt(amount) >= 1n << 255n;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+/** `0.5` becomes `50%`. Never rounded away to "high" or "low". */
+export function formatConfidence(confidence: number): string {
+  const clamped = Math.min(1, Math.max(0, confidence));
+  return `${Math.round(clamped * 100)}%`;
+}
+
+/**
+ * A fixed UTC rendering rather than a locale one.
+ *
+ * Locale formatting differs between a browser, an extension service worker and
+ * a React Native runtime, and an integrator wanting their own format has the
+ * raw ISO string on the model. Predictable beats pretty here.
+ */
+export function formatTimestamp(iso: string): string {
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) return iso;
+  return `${new Date(ms).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+
+export function shortenAddress(address: string, lead = 6, tail = 4): string {
+  if (address.length <= lead + tail + 1) return address;
+  return `${address.slice(0, lead)}…${address.slice(-tail)}`;
+}
+
+/**
+ * Base units to a human amount, in integer arithmetic.
+ *
+ * Token balances routinely exceed what a double can hold exactly, and a
+ * rounding artefact in an allowance figure is a number a user would act on.
+ * With no decimals supplied the raw base units are returned unscaled; the
+ * caller is responsible for saying so, and `approvalPresentation` does.
+ */
+export function formatTokenAmount(amount: string, decimals?: number): string {
+  let value: bigint;
+  try {
+    value = BigInt(amount);
+  } catch {
+    return amount;
+  }
+  if (decimals === undefined || decimals < 0) return group(value.toString());
+  const negative = value < 0n;
+  const abs = negative ? -value : value;
+  const scale = 10n ** BigInt(decimals);
+  const whole = abs / scale;
+  const fraction = (abs % scale).toString().padStart(decimals, '0').replace(/0+$/, '');
+  const text = fraction ? `${group(whole.toString())}.${fraction}` : group(whole.toString());
+  return negative ? `-${text}` : text;
+}
+
+function group(digits: string): string {
+  return digits.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+export function plural(count: number, singular: string, pluralForm?: string): string {
+  if (count === 1) return singular;
+  return pluralForm ?? `${singular}s`;
+}