@decentrys/sentinel-sdk 0.1.0

package/dist/model.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TARGET_TYPES = exports.ALERT_SEVERITIES = void 0;
+exports.ALERT_SEVERITIES = ['INFO', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+/** What a monitored thing is. Determines which rules can apply to it. */
+exports.TARGET_TYPES = [
+    'CONTRACT', 'WALLET', 'TREASURY', 'MULTISIG', 'LP_POOL', 'ORACLE', 'BRIDGE', 'GOVERNANCE',
+];
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEU,QAAA,gBAAgB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAGvF,yEAAyE;AAC5D,QAAA,YAAY,GAAG;IAC1B,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY;CACjF,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@decentrys/sentinel-sdk",
+  "version": "0.1.0",
+  "description": "Monitoring for deployed contracts, wallets and treasuries: targets, detection rules, alerts, and audit-to-monitoring handover.",
+  "license": "MIT",
+  "author": "Decentrys Labs",
+  "homepage": "https://decentrys.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teamdecentrys-byte/Decentrys.git",
+    "directory": "sdk/sentinel"
+  },
+  "bugs": {
+    "url": "https://github.com/teamdecentrys-byte/Decentrys/issues"
+  },
+  "keywords": [
+    "decentrys",
+    "blockchain",
+    "web3",
+    "security",
+    "crypto",
+    "monitoring",
+    "smart-contract",
+    "alerting",
+    "detection",
+    "defi"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/browser/decentrys-sentinel.mjs",
+      "default": "./dist/index.js"
+    },
+    "./browser": "./dist/browser/decentrys-sentinel.mjs"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo*",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && npm run build:browser",
+    "build:browser": "../../node_modules/.bin/esbuild src/index.ts --bundle --format=esm --target=es2022 --outfile=dist/browser/decentrys-sentinel.mjs && ../../node_modules/.bin/esbuild src/index.ts --bundle --format=iife --global-name=DecentrysSentinel --target=es2022 --outfile=dist/browser/decentrys-sentinel.js",
+    "typecheck": "tsc -p tsconfig.spec.json",
+    "test": "vitest run"
+  }
+}

package/src/client.ts

@@ -0,0 +1,289 @@
+/**
+ * The Sentinel client.
+ *
+ * The contract is the opposite of Protect's, and deliberately.
+ *
+ * Protect sits between a user and a signing screen, so it never throws: a
+ * security service having a bad minute must not cost someone their
+ * transaction. Sentinel is management and reporting — you are registering a
+ * contract, writing a rule, acknowledging an alert. Swallowing a failure
+ * there would leave an operator believing they are monitored when they are
+ * not, which is the more dangerous silence of the two.
+ *
+ * So Sentinel throws. Loudly, with the API's own message.
+ *
+ * The one exception is `reportEvent`, which runs on a hot path in a
+ * customer's own system and must never be able to break it.
+ */
+
+import type {
+  Alert, AlertSeverity, MonitoringRule, MonitoringTarget, RuleAction, RuleTestResult, TargetType,
+} from './model';
+
+export const SDK_VERSION = '0.1.0';
+
+const DEFAULT_BASE_URL = 'https://api.decentrys.com';
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export type FetchLike = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body?: string; signal?: AbortSignal },
+) => Promise<{ ok: boolean; status: number; text: () => Promise<string> }>;
+
+export class SentinelError extends Error {
+  constructor(readonly status: number, message: string, readonly code?: string) {
+    super(message);
+    this.name = 'SentinelError';
+  }
+}
+
+export interface SentinelConfig {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: FetchLike;
+}
+
+export interface RegisterTargetInput {
+  projectId: string;
+  chain: string;
+  address: string;
+  label?: string;
+}
+
+export interface CreateRuleInput {
+  projectId: string;
+  name: string;
+  description?: string;
+  severity: AlertSeverity;
+  triggerType: string;
+  conditions: Record<string, unknown>;
+  actions: RuleAction[];
+  cooldownSeconds?: number;
+}
+
+export interface ListAlertsInput {
+  status?: string;
+  severity?: AlertSeverity;
+  limit?: number;
+}
+
+export class Sentinel {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(config: SentinelConfig) {
+    if (!config.apiKey?.trim()) {
+      throw new Error('Sentinel: an apiKey is required. Create one at https://decentrys.com/developers.');
+    }
+    // A publishable key is readable by anyone who downloads the app carrying
+    // it. Registering monitoring targets and writing detection rules is not
+    // something that credential may do, and saying so here is clearer than a
+    // 403 from the server later.
+    if (config.apiKey.startsWith('dk_pub_')) {
+      throw new Error(
+        'Sentinel: that is a publishable key. Monitoring is managed server-side with a secret key — a '
+        + 'publishable key ships inside clients and cannot be trusted to configure detection.',
+      );
+    }
+
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = config.fetch ?? resolveFetch();
+  }
+
+  // --- Targets ------------------------------------------------------------
+
+  /** Watch a deployed contract. */
+  registerContract(input: RegisterTargetInput): Promise<MonitoringTarget> {
+    return this.addTarget(input, 'CONTRACT');
+  }
+
+  registerWallet(input: RegisterTargetInput): Promise<MonitoringTarget> {
+    return this.addTarget(input, 'WALLET');
+  }
+
+  registerTreasury(input: RegisterTargetInput): Promise<MonitoringTarget> {
+    return this.addTarget(input, 'TREASURY');
+  }
+
+  registerTarget(input: RegisterTargetInput, targetType: TargetType): Promise<MonitoringTarget> {
+    return this.addTarget(input, targetType);
+  }
+
+  listTargets(projectId?: string): Promise<MonitoringTarget[]> {
+    const query = projectId ? `?projectId=${encodeURIComponent(projectId)}` : '';
+    return this.request<MonitoringTarget[]>('GET', `/v1/monitoring/targets${query}`);
+  }
+
+  async setTargetEnabled(targetId: string, enabled: boolean): Promise<MonitoringTarget> {
+    return this.request<MonitoringTarget>('PATCH', `/v1/monitoring/targets/${targetId}`, { enabled });
+  }
+
+  async removeTarget(targetId: string): Promise<void> {
+    await this.request<unknown>('DELETE', `/v1/monitoring/targets/${targetId}`);
+  }
+
+  // --- Rules --------------------------------------------------------------
+
+  createRule(input: CreateRuleInput): Promise<MonitoringRule> {
+    return this.request<MonitoringRule>('POST', '/v1/monitoring/rules', input);
+  }
+
+  updateRule(ruleId: string, changes: Partial<CreateRuleInput> & { enabled?: boolean }): Promise<MonitoringRule> {
+    return this.request<MonitoringRule>('PATCH', `/v1/monitoring/rules/${ruleId}`, changes);
+  }
+
+  async deleteRule(ruleId: string): Promise<void> {
+    await this.request<unknown>('DELETE', `/v1/monitoring/rules/${ruleId}`);
+  }
+
+  listRules(projectId?: string): Promise<{ data: MonitoringRule[] }> {
+    const query = projectId ? `?projectId=${encodeURIComponent(projectId)}` : '';
+    return this.request<{ data: MonitoringRule[] }>('GET', `/v1/monitoring/rules${query}`);
+  }
+
+  /**
+   * Evaluate a rule against facts without arming it.
+   *
+   * A rule that has never been tested against a fact set is a rule nobody
+   * knows the behaviour of, and finding out during an incident is the worst
+   * possible time.
+   */
+  testRule(ruleId: string, facts: Record<string, unknown>): Promise<RuleTestResult> {
+    return this.request<RuleTestResult>('POST', `/v1/monitoring/rules/${ruleId}/test`, { facts });
+  }
+
+  /** The vocabulary rules are built from: fields, operators, actions, templates. */
+  catalog(): Promise<Record<string, unknown>> {
+    return this.request<Record<string, unknown>>('GET', '/v1/monitoring/catalog');
+  }
+
+  // --- Alerts -------------------------------------------------------------
+
+  listAlerts(input: ListAlertsInput = {}): Promise<{ data: Alert[] }> {
+    const params = new URLSearchParams();
+    if (input.status) params.set('status', input.status);
+    if (input.severity) params.set('severity', input.severity);
+    if (input.limit) params.set('limit', String(input.limit));
+    const query = params.toString();
+    return this.request<{ data: Alert[] }>('GET', `/v1/alerts${query ? `?${query}` : ''}`);
+  }
+
+  getAlert(alertId: string): Promise<Alert> {
+    return this.request<Alert>('GET', `/v1/alerts/${alertId}`);
+  }
+
+  acknowledgeAlert(alertId: string, note?: string): Promise<Alert> {
+    return this.request<Alert>('PATCH', `/v1/alerts/${alertId}`, {
+      status: 'ACKNOWLEDGED',
+      ...(note ? { note } : {}),
+    });
+  }
+
+  // --- Reporting ----------------------------------------------------------
+
+  /**
+   * Report an event from your own system.
+   *
+   * The one method here that never throws. It is called from a customer's hot
+   * path — a deploy script, a treasury movement, a governance execution — and
+   * a monitoring call must not be able to fail the thing it is monitoring.
+   * The boolean says whether it was recorded, so a caller who cares can check.
+   */
+  async reportEvent(event: {
+    projectId: string;
+    eventName: string;
+    chain?: string;
+    address?: string;
+    txHash?: string;
+    facts?: Record<string, unknown>;
+  }): Promise<boolean> {
+    try {
+      await this.request<unknown>('POST', '/v1/monitoring/events', event);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // --- Internals ----------------------------------------------------------
+
+  private addTarget(input: RegisterTargetInput, targetType: TargetType): Promise<MonitoringTarget> {
+    return this.request<MonitoringTarget>('POST', '/v1/monitoring/targets', {
+      projectId: input.projectId,
+      chainKey: input.chain,
+      address: input.address,
+      targetType,
+      ...(input.label ? { label: input.label } : {}),
+    });
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          'content-type': 'application/json',
+          'x-api-key': this.apiKey,
+          'user-agent': `decentrys-sentinel/${SDK_VERSION}`,
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: controller.signal,
+      });
+
+      const text = await response.text();
+
+      if (!response.ok) {
+        const parsed = safeParse(text);
+        throw new SentinelError(
+          response.status,
+          typeof parsed?.message === 'string' ? parsed.message : `Decentrys returned HTTP ${response.status}.`,
+          typeof parsed?.code === 'string' ? parsed.code : undefined,
+        );
+      }
+
+      if (!text) return undefined as T;
+
+      const parsed = safeParse(text);
+      if (parsed === null) throw new SentinelError(response.status, 'The response was not valid JSON.');
+
+      // The platform wraps successful bodies as `{ data: ... }`, except for
+      // paginated responses which carry `data` alongside pagination fields.
+      return (('data' in parsed && !('total' in parsed) && !('page' in parsed))
+        ? parsed.data
+        : parsed) as T;
+    } catch (error) {
+      if (error instanceof SentinelError) throw error;
+      if (controller.signal.aborted) {
+        throw new SentinelError(0, `No response within ${this.timeoutMs}ms.`);
+      }
+      throw new SentinelError(0, error instanceof Error ? error.message : 'Request failed.');
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function safeParse(text: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveFetch(): FetchLike {
+  const candidate = (globalThis as { fetch?: unknown }).fetch;
+  if (typeof candidate !== 'function') {
+    throw new Error('Sentinel: no global fetch was found. Pass one via `new Sentinel({ fetch })`.');
+  }
+  return candidate.bind(globalThis) as FetchLike;
+}

package/src/from-audit.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+import { rulesFromAudit, unmappedCapabilities } from './from-audit';
+
+const PROJECT = 'proj-1';
+
+describe('audit handover', () => {
+  it('turns an upgrade capability into a rule that watches the upgrade, not the capability', () => {
+    const [generated] = rulesFromAudit({
+      projectId: PROJECT,
+      capabilities: [{ type: 'UPGRADEABLE', grantedBy: 'EIP1967' }],
+    });
+
+    expect(generated!.rule.triggerType).toBe('contract.upgraded');
+    expect(generated!.rule.severity).toBe('CRITICAL');
+    expect(generated!.rule.description).toContain('EIP1967');
+  });
+
+  /**
+   * The distinction the whole product rests on. Being upgradeable is a design
+   * choice most serious protocols make; the rule must describe the event, not
+   * accuse the contract of having the capability.
+   */
+  it('never describes a capability as a fault', () => {
+    const generated = rulesFromAudit({
+      projectId: PROJECT,
+      capabilities: [
+        { type: 'UPGRADEABLE' }, { type: 'MINT_AUTHORITY' }, { type: 'PAUSABLE' },
+        { type: 'BLACKLIST' }, { type: 'GOVERNANCE' },
+      ],
+    });
+
+    for (const { rule } of generated) {
+      const text = `${rule.name} ${rule.description}`;
+      expect(text, rule.name).not.toMatch(/scam|malicious|fraud|dangerous|vulnerab/i);
+    }
+  });
+
+  /**
+   * A proxy and an upgrade authority are one capability described two ways.
+   * Two identical rules means two pages for one event, which is how a team
+   * learns to mute the channel.
+   */
+  it('deduplicates capabilities that mean the same thing', () => {
+    const generated = rulesFromAudit({
+      projectId: PROJECT,
+      capabilities: [{ type: 'PROXY' }, { type: 'UPGRADEABLE' }, { type: 'UPGRADE_AUTHORITY' }],
+    });
+
+    expect(generated).toHaveLength(1);
+  });
+
+  /**
+   * The alias table must be written against the canonical names the Protect
+   * layer actually emits, not against chain vocabulary. It was not, and this
+   * test is why: `TreasuryCap` never reaches here — Sui's capability is
+   * already normalised to MINT_AUTHORITY upstream.
+   */
+  it.each([
+    'UPGRADEABLE', 'DELEGATED_EXECUTION', 'MINT_AUTHORITY', 'PAUSABLE',
+    'ACCOUNT_FREEZE', 'FORCED_BALANCE_CHANGE',
+  ])('produces a rule for the canonical capability %s', (type) => {
+    expect(rulesFromAudit({ projectId: PROJECT, capabilities: [{ type }] })).toHaveLength(1);
+  });
+
+  it('accepts a reviewer\'s prose wording as well as the canonical name', () => {
+    const prose = rulesFromAudit({ projectId: PROJECT, capabilities: [{ type: 'mint' }] });
+    const canonical = rulesFromAudit({ projectId: PROJECT, capabilities: [{ type: 'MINT_AUTHORITY' }] });
+
+    expect(prose[0]!.rule.triggerType).toBe(canonical[0]!.rule.triggerType);
+  });
+
+  /**
+   * A threshold guessed on a customer's behalf is either so low it pages
+   * constantly or so high it never fires. Both end with the alert ignored.
+   */
+  it('generates no treasury rule without an agreed threshold', () => {
+    const without = rulesFromAudit({ projectId: PROJECT, capabilities: [] });
+    expect(without).toHaveLength(0);
+
+    const withThreshold = rulesFromAudit({
+      projectId: PROJECT, capabilities: [], treasuryThresholdUsd: 50_000,
+    });
+    expect(withThreshold).toHaveLength(1);
+    expect(JSON.stringify(withThreshold[0]!.rule.conditions)).toContain('50000');
+  });
+
+  it('gives every rule a cooldown, so one looping event cannot page repeatedly', () => {
+    const generated = rulesFromAudit({
+      projectId: PROJECT,
+      capabilities: [{ type: 'UPGRADEABLE' }, { type: 'MINT_AUTHORITY' }],
+      treasuryThresholdUsd: 10_000,
+    });
+
+    for (const { rule } of generated) {
+      expect(rule.cooldownSeconds, rule.name).toBeGreaterThan(0);
+    }
+  });
+
+  it('defaults to raising an in-platform alert rather than nothing', () => {
+    const [generated] = rulesFromAudit({ projectId: PROJECT, capabilities: [{ type: 'OWNERSHIP' }] });
+    expect(generated!.rule.actions).toEqual([{ type: 'ALERT', config: {} }]);
+  });
+
+  it('honours the caller\'s own routing', () => {
+    const actions = [{ type: 'PAGERDUTY', config: { routingKey: 'k' } }];
+    const [generated] = rulesFromAudit({
+      projectId: PROJECT, capabilities: [{ type: 'UPGRADEABLE' }], actions,
+    });
+    expect(generated!.rule.actions).toEqual(actions);
+  });
+});
+
+describe('unmappedCapabilities', () => {
+  /**
+   * A customer handed six rules for nine capabilities must be told which
+   * three are unwatched. Silence there becomes an assumption of coverage.
+   */
+  it('reports what produced no rule instead of dropping it', () => {
+    const capabilities = [{ type: 'UPGRADEABLE' }, { type: 'ORACLE_SETTER' }, { type: 'FEE_CONTROL' }];
+    // FEE_CONTROL is real and deliberately unmapped: a fee change has no
+    // single response, and a rule nobody can act on trains people to ignore
+    // the channel that matters.
+
+    expect(rulesFromAudit({ projectId: PROJECT, capabilities })).toHaveLength(1);
+    expect(unmappedCapabilities(capabilities)).toEqual(['ORACLE_SETTER', 'FEE_CONTROL']);
+  });
+
+  it('is empty when everything mapped', () => {
+    expect(unmappedCapabilities([{ type: 'UPGRADEABLE' }, { type: 'PAUSABLE' }])).toEqual([]);
+  });
+});