@decentrys/sentinel-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decentrys Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @decentrys/sentinel-sdk
+
+Monitoring for deployed contracts, wallets and treasuries.
+
+## Install
+
+```bash
+npm install @decentrys/sentinel-sdk
+```
+
+## Use
+
+```ts
+import { Sentinel, rulesFromAudit } from '@decentrys/sentinel-sdk';
+
+const sentinel = new Sentinel({ apiKey: 'dk_live_...' });
+
+await sentinel.registerContract({ projectId, chain: 'ethereum', address });
+
+// Turn what an audit learned into what the system watches.
+for (const { rule } of rulesFromAudit({ projectId, capabilities })) {
+  await sentinel.createRule(rule);
+}
+```
+
+## It throws, deliberately
+
+Unlike `@decentrys/protect`, this client raises errors. It is management —
+registering a contract, writing a rule. Swallowing a failure would leave an
+operator believing they are monitored when they are not, which is the more
+dangerous silence.
+
+`reportEvent()` is the exception: it runs on your hot path and returns a
+boolean, because a monitoring call must not be able to fail the thing it is
+monitoring.
+
+## Audit handover
+
+`rulesFromAudit()` watches the upgrade *happening*, never the contract *being*
+upgradeable. A capability is not a fault. Capabilities with no plausible
+response generate no rule, and `unmappedCapabilities()` tells you which — a
+rule nobody can act on trains a team to close alerts unread.
+
+**Secret keys only.** A publishable key is refused at construction.
+
+## Licence
+
+MIT © Decentrys Labs
+
+## Links
+
+- [decentrys.com](https://decentrys.com) · [SDK overview](https://decentrys.com/sdk) · [Developer API](https://decentrys.com/developers)
+- Source: [github.com/teamdecentrys-byte/Decentrys](https://github.com/teamdecentrys-byte/Decentrys)

package/dist/browser/decentrys-sentinel.js

@@ -0,0 +1,377 @@
+"use strict";
+var DecentrysSentinel = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/index.ts
+  var index_exports = {};
+  __export(index_exports, {
+    ALERT_SEVERITIES: () => ALERT_SEVERITIES,
+    SDK_VERSION: () => SDK_VERSION,
+    Sentinel: () => Sentinel,
+    SentinelError: () => SentinelError,
+    TARGET_TYPES: () => TARGET_TYPES,
+    rulesFromAudit: () => rulesFromAudit,
+    unmappedCapabilities: () => unmappedCapabilities
+  });
+
+  // src/model.ts
+  var ALERT_SEVERITIES = ["INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL"];
+  var TARGET_TYPES = [
+    "CONTRACT",
+    "WALLET",
+    "TREASURY",
+    "MULTISIG",
+    "LP_POOL",
+    "ORACLE",
+    "BRIDGE",
+    "GOVERNANCE"
+  ];
+
+  // src/client.ts
+  var SDK_VERSION = "0.1.0";
+  var DEFAULT_BASE_URL = "https://api.decentrys.com";
+  var DEFAULT_TIMEOUT_MS = 1e4;
+  var SentinelError = class extends Error {
+    constructor(status, message, code) {
+      super(message);
+      this.status = status;
+      this.code = code;
+      this.name = "SentinelError";
+    }
+    status;
+    code;
+  };
+  var Sentinel = class {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    fetchImpl;
+    constructor(config) {
+      if (!config.apiKey?.trim()) {
+        throw new Error("Sentinel: an apiKey is required. Create one at https://decentrys.com/developers.");
+      }
+      if (config.apiKey.startsWith("dk_pub_")) {
+        throw new Error(
+          "Sentinel: that is a publishable key. Monitoring is managed server-side with a secret key \u2014 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) {
+      return this.addTarget(input, "CONTRACT");
+    }
+    registerWallet(input) {
+      return this.addTarget(input, "WALLET");
+    }
+    registerTreasury(input) {
+      return this.addTarget(input, "TREASURY");
+    }
+    registerTarget(input, targetType) {
+      return this.addTarget(input, targetType);
+    }
+    listTargets(projectId) {
+      const query = projectId ? `?projectId=${encodeURIComponent(projectId)}` : "";
+      return this.request("GET", `/v1/monitoring/targets${query}`);
+    }
+    async setTargetEnabled(targetId, enabled) {
+      return this.request("PATCH", `/v1/monitoring/targets/${targetId}`, { enabled });
+    }
+    async removeTarget(targetId) {
+      await this.request("DELETE", `/v1/monitoring/targets/${targetId}`);
+    }
+    // --- Rules --------------------------------------------------------------
+    createRule(input) {
+      return this.request("POST", "/v1/monitoring/rules", input);
+    }
+    updateRule(ruleId, changes) {
+      return this.request("PATCH", `/v1/monitoring/rules/${ruleId}`, changes);
+    }
+    async deleteRule(ruleId) {
+      await this.request("DELETE", `/v1/monitoring/rules/${ruleId}`);
+    }
+    listRules(projectId) {
+      const query = projectId ? `?projectId=${encodeURIComponent(projectId)}` : "";
+      return this.request("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, facts) {
+      return this.request("POST", `/v1/monitoring/rules/${ruleId}/test`, { facts });
+    }
+    /** The vocabulary rules are built from: fields, operators, actions, templates. */
+    catalog() {
+      return this.request("GET", "/v1/monitoring/catalog");
+    }
+    // --- Alerts -------------------------------------------------------------
+    listAlerts(input = {}) {
+      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("GET", `/v1/alerts${query ? `?${query}` : ""}`);
+    }
+    getAlert(alertId) {
+      return this.request("GET", `/v1/alerts/${alertId}`);
+    }
+    acknowledgeAlert(alertId, note) {
+      return this.request("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) {
+      try {
+        await this.request("POST", "/v1/monitoring/events", event);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    // --- Internals ----------------------------------------------------------
+    addTarget(input, targetType) {
+      return this.request("POST", "/v1/monitoring/targets", {
+        projectId: input.projectId,
+        chainKey: input.chain,
+        address: input.address,
+        targetType,
+        ...input.label ? { label: input.label } : {}
+      });
+    }
+    async request(method, path, body) {
+      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 === void 0 ? {} : { body: JSON.stringify(body) },
+          signal: controller.signal
+        });
+        const text = await response.text();
+        if (!response.ok) {
+          const parsed2 = safeParse(text);
+          throw new SentinelError(
+            response.status,
+            typeof parsed2?.message === "string" ? parsed2.message : `Decentrys returned HTTP ${response.status}.`,
+            typeof parsed2?.code === "string" ? parsed2.code : void 0
+          );
+        }
+        if (!text) return void 0;
+        const parsed = safeParse(text);
+        if (parsed === null) throw new SentinelError(response.status, "The response was not valid JSON.");
+        return "data" in parsed && !("total" in parsed) && !("page" in parsed) ? parsed.data : parsed;
+      } 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) {
+    try {
+      const parsed = JSON.parse(text);
+      return typeof parsed === "object" && parsed !== null ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  function resolveFetch() {
+    const candidate = globalThis.fetch;
+    if (typeof candidate !== "function") {
+      throw new Error("Sentinel: no global fetch was found. Pass one via `new Sentinel({ fetch })`.");
+    }
+    return candidate.bind(globalThis);
+  }
+
+  // src/from-audit.ts
+  var DEFAULT_ACTIONS = [{ type: "ALERT", config: {} }];
+  var RULES = {
+    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 \u2014 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 }
+    }
+  };
+  var ALIASES = {
+    // 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"
+  };
+  function rulesFromAudit(input) {
+    const actions = input.actions?.length ? input.actions : DEFAULT_ACTIONS;
+    const seen = /* @__PURE__ */ new Set();
+    const 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;
+  }
+  function unmappedCapabilities(capabilities) {
+    return capabilities.filter((capability) => !ALIASES[capability.type.toUpperCase()]).map((capability) => capability.type);
+  }
+  return __toCommonJS(index_exports);
+})();