@decentrys/sentinel-sdk 0.1.0

package/src/from-audit.ts

@@ -0,0 +1,253 @@
+/**
+ * Audit findings → monitoring rules.
+ *
+ * The single most valuable thing the platform does, and the reason Audit and
+ * Sentinel belong in one product.
+ *
+ * An audit ends with a report, and a report is a document. Two months later
+ * the upgrade path a reviewer spent a day understanding is a paragraph nobody
+ * has reopened, and the person who reads it next is reading it during an
+ * incident. This turns what the audit *learned* into what the system
+ * *watches*: the privileged functions a reviewer identified become the
+ * functions that page someone when they are called.
+ *
+ * Two constraints shape the output:
+ *
+ *  - **A capability is not a finding.** A contract being upgradeable is not a
+ *    vulnerability, and the generated rule does not say it is. It watches for
+ *    the upgrade *happening*, which is an event worth knowing about however
+ *    legitimate the protocol.
+ *  - **Every rule must be actionable.** A rule that fires on something nobody
+ *    can respond to trains a team to close alerts unread, and then the real
+ *    one is closed unread too. Nothing here generates a rule for an event
+ *    with no plausible response.
+ */
+
+import type { AlertSeverity, RuleAction } from './model';
+import type { CreateRuleInput } from './client';
+
+/** What an audit observed about a contract, in the shape Protect reports it. */
+export interface AuditCapability {
+  /** e.g. UPGRADEABLE, MINT_AUTHORITY, PAUSABLE, BLACKLIST, FEE_CONTROL. */
+  type: string;
+  statement?: string;
+  /** The function, role or slot that grants it, when known. */
+  grantedBy?: string;
+}
+
+export interface AuditHandoverInput {
+  projectId: string;
+  /** Capabilities the audit confirmed the deployed code holds. */
+  capabilities: AuditCapability[];
+  /** Where alerts go. At minimum an in-platform alert. */
+  actions?: RuleAction[];
+  /**
+   * Treasury alert threshold in USD. Omitted means no treasury rule is
+   * generated: a threshold guessed on a customer's behalf is either so low it
+   * pages constantly or so high it never fires, and both teach people to
+   * ignore it.
+   */
+  treasuryThresholdUsd?: number;
+}
+
+interface Generated {
+  capability: string;
+  rule: CreateRuleInput;
+}
+
+const DEFAULT_ACTIONS: RuleAction[] = [{ type: 'ALERT', config: {} }];
+
+/**
+ * Capability → the event worth watching, and why.
+ *
+ * Severity reflects how hard the change is to reverse, not how suspicious it
+ * is. A logic replacement is CRITICAL because every assumption in the audit
+ * stops holding the moment it lands — not because upgrading is wrong.
+ */
+const RULES: Record<string, {
+  name: string;
+  description: string;
+  severity: AlertSeverity;
+  triggerType: string;
+  conditions: Record<string, unknown>;
+}> = {
+  UPGRADEABLE: {
+    name: 'Contract logic replaced',
+    description:
+      'The proxy now points at different code. Every finding in the audit describes the previous '
+      + 'implementation and stops applying the moment this fires.',
+    severity: 'CRITICAL',
+    triggerType: 'contract.upgraded',
+    conditions: { op: 'eq', field: 'upgrade.changed', value: true },
+  },
+  ADMIN_CONTROL: {
+    name: 'Admin address changed',
+    description: 'Whoever can upgrade or configure this contract is now a different account.',
+    severity: 'CRITICAL',
+    triggerType: 'contract.admin_changed',
+    conditions: { op: 'eq', field: 'admin.changed', value: true },
+  },
+  OWNERSHIP: {
+    name: 'Ownership transferred',
+    description: 'Owner-only functions identified during the audit are now controlled by someone else.',
+    severity: 'HIGH',
+    triggerType: 'contract.ownership_transferred',
+    conditions: { op: 'eq', field: 'ownership.changed', value: true },
+  },
+  MINT_AUTHORITY: {
+    name: 'Supply increased',
+    description:
+      'The mint authority the audit identified was used. Legitimate for many designs — this reports it '
+      + 'so holders are not the last to know.',
+    severity: 'HIGH',
+    triggerType: 'token.supply_changed',
+    conditions: {
+      op: 'AND',
+      conditions: [
+        { op: 'eq', field: 'token.supplyIncreased', value: true },
+        // A percentage rather than an absolute: a fixed figure is meaningless
+        // across tokens with different supplies and decimals.
+        { op: 'gt', field: 'token.supplyChangePercent', value: 1 },
+      ],
+    },
+  },
+  PAUSABLE: {
+    name: 'Pause state changed',
+    description:
+      'The contract was paused or unpaused. Pausing is usually a defence, and knowing it happened is '
+      + 'how you find out an incident started without you.',
+    severity: 'HIGH',
+    triggerType: 'contract.paused',
+    conditions: { op: 'eq', field: 'contract.pauseChanged', value: true },
+  },
+  BLACKLIST: {
+    name: 'Transfer restriction applied',
+    description: 'An address was restricted from transferring. Reported because it is invisible on-chain otherwise.',
+    severity: 'MEDIUM',
+    triggerType: 'contract.function_called',
+    conditions: { op: 'contains', field: 'event.types', value: 'BLACKLIST' },
+  },
+  FORCED_BALANCE_CHANGE: {
+    name: 'Balance moved without the holder acting',
+    description:
+      'A permanent delegate or equivalent authority moved tokens from an account that did not sign for it. '
+      + 'Legitimate for some regulated designs, and always worth knowing about.',
+    severity: 'CRITICAL',
+    triggerType: 'contract.function_called',
+    conditions: { op: 'contains', field: 'event.types', value: 'FORCED_TRANSFER' },
+  },
+  GOVERNANCE: {
+    name: 'Governance proposal executed',
+    description: 'An executed proposal can change anything the audit assumed was fixed.',
+    severity: 'HIGH',
+    triggerType: 'governance.executed',
+    conditions: { op: 'eq', field: 'governance.executed', value: true },
+  },
+};
+
+/** Capability names normalised, so an audit may say MINT or MINT_AUTHORITY. */
+const ALIASES: Record<string, string> = {
+  // The canonical names the Protect layer emits. Chain-specific spellings —
+  // Sui's TreasuryCap, Solana's mintAuthority, an EIP-1967 slot — are already
+  // normalised to these before an audit hands anything over, so mapping raw
+  // chain vocabulary here would be mapping names that never arrive.
+  UPGRADEABLE: 'UPGRADEABLE',
+  DELEGATED_EXECUTION: 'UPGRADEABLE',
+  MINT_AUTHORITY: 'MINT_AUTHORITY',
+  PAUSABLE: 'PAUSABLE',
+  ACCOUNT_FREEZE: 'BLACKLIST',
+  FORCED_BALANCE_CHANGE: 'FORCED_BALANCE_CHANGE',
+  GOVERNANCE: 'GOVERNANCE',
+  // Accepted because an audit report may use them in prose, and rejecting a
+  // reviewer's own wording would silently drop a rule they expected.
+  PROXY: 'UPGRADEABLE',
+  UPGRADE_AUTHORITY: 'UPGRADEABLE',
+  ADMIN: 'ADMIN_CONTROL',
+  ADMIN_CONTROL: 'ADMIN_CONTROL',
+  OWNER: 'OWNERSHIP',
+  OWNERSHIP: 'OWNERSHIP',
+  MINT: 'MINT_AUTHORITY',
+  PAUSE: 'PAUSABLE',
+  FREEZE_AUTHORITY: 'BLACKLIST',
+  BLACKLIST: 'BLACKLIST',
+};
+
+/**
+ * Turn confirmed capabilities into rules.
+ *
+ * Deduplicated: a contract with both a proxy and an upgrade authority holds
+ * one capability described twice, and generating two identical rules would
+ * page someone twice for one event.
+ */
+export function rulesFromAudit(input: AuditHandoverInput): Generated[] {
+  const actions = input.actions?.length ? input.actions : DEFAULT_ACTIONS;
+  const seen = new Set<string>();
+  const generated: Generated[] = [];
+
+  for (const capability of input.capabilities) {
+    const key = ALIASES[capability.type.toUpperCase()];
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+
+    const template = RULES[key];
+    if (!template) continue;
+
+    generated.push({
+      capability: capability.type,
+      rule: {
+        projectId: input.projectId,
+        name: template.name,
+        description: capability.grantedBy
+          ? `${template.description} Granted by ${capability.grantedBy}, identified during the audit.`
+          : `${template.description} Identified during the audit.`,
+        severity: template.severity,
+        triggerType: template.triggerType,
+        conditions: template.conditions,
+        actions,
+        // Five minutes. Long enough that one event in a loop does not page a
+        // team repeatedly, short enough that a second, genuinely separate
+        // occurrence still gets through.
+        cooldownSeconds: 300,
+      },
+    });
+  }
+
+  if (typeof input.treasuryThresholdUsd === 'number' && input.treasuryThresholdUsd > 0) {
+    generated.push({
+      capability: 'TREASURY',
+      rule: {
+        projectId: input.projectId,
+        name: 'Large treasury outflow',
+        description:
+          `An outbound movement above $${input.treasuryThresholdUsd.toLocaleString()}, the threshold agreed `
+          + 'during the audit.',
+        severity: 'HIGH',
+        triggerType: 'treasury.transfer',
+        conditions: {
+          op: 'AND',
+          conditions: [
+            { op: 'eq', field: 'transfer.direction', value: 'OUT' },
+            { op: 'gt', field: 'transfer.valueUsd', value: input.treasuryThresholdUsd },
+          ],
+        },
+        actions,
+        cooldownSeconds: 300,
+      },
+    });
+  }
+
+  return generated;
+}
+
+/**
+ * Which capabilities produced no rule.
+ *
+ * Returned rather than silently dropped: a customer handed six rules for nine
+ * capabilities should be told which three are unwatched, so the gap is a
+ * decision rather than an assumption.
+ */
+export function unmappedCapabilities(capabilities: AuditCapability[]): string[] {
+  return capabilities
+    .filter((capability) => !ALIASES[capability.type.toUpperCase()])
+    .map((capability) => capability.type);
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './model';
+export * from './client';
+export * from './from-audit';

package/src/model.ts

@@ -0,0 +1,85 @@
+/**
+ * The Sentinel model.
+ *
+ * Sentinel answers a different question from Protect. Protect asks "should I
+ * sign this?" about something a user is about to do; Sentinel asks "did
+ * something happen to what I own?" about systems already deployed. That
+ * changes what matters:
+ *
+ *  - **The subject is yours.** You register your own contracts, wallets and
+ *    treasuries. Nothing here classifies a third party, so none of Protect's
+ *    machinery for avoiding accusations applies — and neither does its
+ *    restraint about severity.
+ *  - **A rule is a statement about facts, not a score.** A rule fires or it
+ *    does not, and the alert says which fact made it fire. There is no
+ *    threshold model to argue with.
+ *  - **An alert must be actionable.** An alert nobody can act on trains
+ *    people to close alerts, which is worse than having none.
+ */
+
+export const ALERT_SEVERITIES = ['INFO', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] as const;
+export type AlertSeverity = (typeof ALERT_SEVERITIES)[number];
+
+/** What a monitored thing is. Determines which rules can apply to it. */
+export const TARGET_TYPES = [
+  'CONTRACT', 'WALLET', 'TREASURY', 'MULTISIG', 'LP_POOL', 'ORACLE', 'BRIDGE', 'GOVERNANCE',
+] as const;
+export type TargetType = (typeof TARGET_TYPES)[number];
+
+export interface MonitoringTarget {
+  id: string;
+  projectId: string;
+  chainKey: string;
+  address: string;
+  targetType: TargetType;
+  label: string | null;
+  enabled: boolean;
+  createdAt: string;
+}
+
+export interface RuleAction {
+  type: string;
+  config: Record<string, unknown>;
+}
+
+export interface MonitoringRule {
+  id: string;
+  projectId: string;
+  name: string;
+  description: string | null;
+  severity: AlertSeverity;
+  triggerType: string;
+  conditions: Record<string, unknown>;
+  actions: RuleAction[];
+  /**
+   * Suppression window. Without one, a contract emitting the same event in a
+   * loop pages someone a thousand times for one incident, and the thousandth
+   * page is less useful than the first.
+   */
+  cooldownSeconds: number;
+  enabled: boolean;
+  createdAt: string;
+}
+
+export interface Alert {
+  id: string;
+  ruleId: string | null;
+  ruleName: string | null;
+  severity: AlertSeverity;
+  title: string;
+  description: string | null;
+  chainKey: string | null;
+  address: string | null;
+  txHash: string | null;
+  /** The facts that made the rule fire. An alert without these is unactionable. */
+  facts: Record<string, unknown> | null;
+  status: string;
+  acknowledgedAt: string | null;
+  createdAt: string;
+}
+
+export interface RuleTestResult {
+  matched: boolean;
+  /** Which conditions passed and which did not, so a rule can be debugged. */
+  explanation: string[];
+}