@decentrys/protect 0.1.0

package/dist/browser/decentrys-protect.mjs

@@ -0,0 +1,876 @@
+// src/model.ts
+var RISK_LEVELS = [
+  "NO_CRITICAL_RISK_DETECTED",
+  "INFORMATIONAL",
+  "CAUTION",
+  "ELEVATED_RISK",
+  "HIGH_RISK",
+  "CRITICAL_THREAT",
+  "KNOWN_MALICIOUS"
+];
+var RISK_ORDER = {
+  NO_CRITICAL_RISK_DETECTED: 0,
+  INFORMATIONAL: 1,
+  CAUTION: 2,
+  ELEVATED_RISK: 3,
+  HIGH_RISK: 4,
+  CRITICAL_THREAT: 5,
+  KNOWN_MALICIOUS: 6
+};
+function isAtLeast(level, floor) {
+  return RISK_ORDER[level] >= RISK_ORDER[floor];
+}
+var RISK_LEVEL_MEANING = {
+  NO_CRITICAL_RISK_DETECTED: "No known critical threat evidence was identified. This is not an assurance of safety.",
+  INFORMATIONAL: "Facts worth knowing before proceeding. Nothing here indicates danger.",
+  CAUTION: "A security-sensitive capability or behaviour exists that deserves attention.",
+  ELEVATED_RISK: "Several meaningful risk signals are present together.",
+  HIGH_RISK: "Strong technical or behavioural evidence of significant danger.",
+  CRITICAL_THREAT: "Severe threat supported by concrete evidence.",
+  KNOWN_MALICIOUS: "Confirmed malicious infrastructure or behaviour, verified against evidence."
+};
+var HISTORY_STATUS_MEANING = {
+  ESTABLISHED: "Substantial on-chain history is available.",
+  MODERATE: "Some history is available.",
+  LIMITED: "Little history is available yet. This is normal for anything recently deployed and is not a risk finding.",
+  NONE: "No history is available. This is not a risk finding."
+};
+var PROTECT_MODEL_VERSION = "protect-1.0.0";
+
+// src/classify.ts
+var RAISING_STATUSES = ["ACTIVE"];
+var MIN_RAISING_CONFIDENCE = 0.5;
+function classify(input) {
+  const now = input.now ?? /* @__PURE__ */ new Date();
+  const facts = input.facts ?? [];
+  const capabilities = input.capabilities ?? [];
+  const unknowns = input.unknowns ?? [];
+  const historyStatus = input.historyStatus ?? "LIMITED";
+  const threatSignals = (input.threatSignals ?? []).map((signal) => applyDecay(signal, now));
+  const raising = threatSignals.filter(
+    (s) => RAISING_STATUSES.includes(s.status) && s.confidence >= MIN_RAISING_CONFIDENCE
+  );
+  const explanation = [];
+  let level = "NO_CRITICAL_RISK_DETECTED";
+  const confirmed = raising.filter(
+    (s) => s.severity === "CRITICAL" && s.evidence.some((e) => e.analystVerified)
+  );
+  const confirmedMalicious = confirmed.length > 0;
+  if (confirmedMalicious) {
+    level = "KNOWN_MALICIOUS";
+    for (const signal of confirmed) {
+      explanation.push(`${signal.explanation} (verified by an analyst)`);
+    }
+  } else {
+    const critical = raising.filter((s) => s.severity === "CRITICAL");
+    const high = raising.filter((s) => s.severity === "HIGH");
+    const medium = raising.filter((s) => s.severity === "MEDIUM");
+    if (critical.length > 0) {
+      level = "CRITICAL_THREAT";
+      for (const s of critical) explanation.push(s.explanation);
+    } else if (high.length > 0) {
+      level = high.length > 1 ? "HIGH_RISK" : "ELEVATED_RISK";
+      for (const s of high) explanation.push(s.explanation);
+    } else if (medium.length > 1) {
+      level = "ELEVATED_RISK";
+      for (const s of medium) explanation.push(s.explanation);
+    } else if (medium.length === 1) {
+      level = "CAUTION";
+      explanation.push(medium[0].explanation);
+    }
+    const significant = capabilities.filter((c) => c.severity === "SIGNIFICANT");
+    if (significant.length > 0 && rank(level) < rank("CAUTION")) {
+      level = "CAUTION";
+      for (const c of significant) explanation.push(c.statement);
+    } else if (rank(level) < rank("INFORMATIONAL") && capabilities.length > 0) {
+      level = "INFORMATIONAL";
+      for (const c of capabilities.slice(0, 3)) explanation.push(c.statement);
+    }
+  }
+  for (const signal of threatSignals) {
+    if (raising.includes(signal)) continue;
+    if (signal.status !== "ACTIVE") {
+      explanation.push(
+        `${signal.explanation} \u2014 this signal is ${signal.status.toLowerCase()} and did not affect the assessment.`
+      );
+    } else if (signal.confidence < MIN_RAISING_CONFIDENCE) {
+      explanation.push(
+        `${signal.explanation} \u2014 reported at ${Math.round(signal.confidence * 100)}% confidence, which is too low to raise the risk level on its own.`
+      );
+    }
+  }
+  if (level === "NO_CRITICAL_RISK_DETECTED" && facts.length > 0) {
+    level = "INFORMATIONAL";
+  }
+  if (historyStatus === "LIMITED" || historyStatus === "NONE") {
+    explanation.push(HISTORY_STATUS_MEANING[historyStatus]);
+  }
+  if (unknowns.length > 0) {
+    explanation.push(
+      `${unknowns.length} ${unknowns.length === 1 ? "attribute is" : "attributes are"} unknown. Unknown is reported as unknown; it does not contribute to risk.`
+    );
+  }
+  if (explanation.length === 0) {
+    explanation.push(RISK_LEVEL_MEANING[level]);
+  }
+  return {
+    riskLevel: level,
+    confirmedMalicious,
+    confidence: confidenceFor(level, raising, historyStatus),
+    historyStatus,
+    facts,
+    capabilities,
+    threatSignals,
+    unknowns,
+    components: {
+      technicalRisk: technicalRisk(capabilities),
+      behavioralRisk: behavioralRisk(raising),
+      threatIntelligenceRisk: threatIntelligenceRisk(raising),
+      // Coverage, reported separately so it cannot be summed into a risk total.
+      historyConfidence: input.historyConfidence ?? historyConfidenceFor(historyStatus)
+    },
+    explanation,
+    modelVersion: PROTECT_MODEL_VERSION,
+    assessedAt: now.toISOString()
+  };
+}
+function rank(level) {
+  return [
+    "NO_CRITICAL_RISK_DETECTED",
+    "INFORMATIONAL",
+    "CAUTION",
+    "ELEVATED_RISK",
+    "HIGH_RISK",
+    "CRITICAL_THREAT",
+    "KNOWN_MALICIOUS"
+  ].indexOf(level);
+}
+function applyDecay(signal, now) {
+  if (signal.status !== "ACTIVE") return signal;
+  if (!signal.expiresAt) return signal;
+  return Date.parse(signal.expiresAt) <= now.getTime() ? { ...signal, status: "STALE" } : signal;
+}
+function confidenceFor(level, raising, history) {
+  if (raising.length > 0) {
+    const best = Math.max(...raising.map((s) => s.confidence));
+    return Number(best.toFixed(2));
+  }
+  switch (history) {
+    case "ESTABLISHED":
+      return 0.85;
+    case "MODERATE":
+      return 0.7;
+    case "LIMITED":
+      return 0.5;
+    default:
+      return 0.35;
+  }
+}
+function technicalRisk(capabilities) {
+  const weight = { INFO: 4, NOTABLE: 12, SIGNIFICANT: 25 };
+  return Math.min(100, capabilities.reduce((sum, c) => sum + weight[c.severity], 0));
+}
+function behavioralRisk(raising) {
+  const weight = { LOW: 5, MEDIUM: 20, HIGH: 40, CRITICAL: 70 };
+  return Math.min(100, raising.filter((s) => s.hops === 0).reduce((sum, s) => sum + weight[s.severity] * s.confidence, 0));
+}
+function threatIntelligenceRisk(raising) {
+  const weight = { LOW: 5, MEDIUM: 15, HIGH: 35, CRITICAL: 60 };
+  return Math.min(100, raising.reduce((sum, s) => {
+    const decay = Math.pow(0.6, Math.max(0, s.hops));
+    return sum + weight[s.severity] * s.confidence * decay;
+  }, 0));
+}
+function historyConfidenceFor(status) {
+  switch (status) {
+    case "ESTABLISHED":
+      return 90;
+    case "MODERATE":
+      return 60;
+    case "LIMITED":
+      return 25;
+    default:
+      return 5;
+  }
+}
+var DEFAULT_POLICY = {
+  NO_CRITICAL_RISK_DETECTED: "allow",
+  INFORMATIONAL: "inform",
+  CAUTION: "warn",
+  ELEVATED_RISK: "warn_strong",
+  HIGH_RISK: "require_confirmation",
+  CRITICAL_THREAT: "require_confirmation",
+  KNOWN_MALICIOUS: "block"
+};
+function applyPolicy(assessment, policy = {}) {
+  const action = policy[assessment.riskLevel] ?? DEFAULT_POLICY[assessment.riskLevel];
+  return {
+    action,
+    reason: assessment.explanation[0] ?? RISK_LEVEL_MEANING[assessment.riskLevel]
+  };
+}
+function unavailableAssessment(failMode, reason, now = /* @__PURE__ */ new Date()) {
+  return {
+    riskLevel: "NO_CRITICAL_RISK_DETECTED",
+    confirmedMalicious: false,
+    confidence: 0,
+    historyStatus: "NONE",
+    facts: [],
+    capabilities: [],
+    threatSignals: [],
+    unknowns: [{
+      field: "assessment",
+      reason: "PROVIDER_UNAVAILABLE",
+      statement: `Decentrys could not be reached: ${reason}. Nothing was checked.`
+    }],
+    components: { technicalRisk: 0, behavioralRisk: 0, threatIntelligenceRisk: 0, historyConfidence: 0 },
+    explanation: [
+      `Decentrys could not be reached: ${reason}.`,
+      failMode === "closed" ? "This deployment is configured to refuse unverified transactions." : failMode === "warn" ? "No security check was performed. Proceed with the care you would use without any tool." : "No security check was performed."
+    ],
+    modelVersion: PROTECT_MODEL_VERSION,
+    assessedAt: now.toISOString()
+  };
+}
+
+// src/wire.ts
+var COVERAGE_SIGNAL_TYPES = /* @__PURE__ */ new Set([
+  "NEW_ADDRESS",
+  "NEW_CONTRACT",
+  "NEW_DEPLOYMENT",
+  "LOW_ACTIVITY",
+  "LIMITED_HISTORY",
+  "NO_HISTORY",
+  "ESTABLISHED_HISTORY",
+  "UNVERIFIED_SOURCE",
+  "UNVERIFIED_CONTRACT",
+  "NO_AUDIT",
+  "UNAUDITED",
+  "ANONYMOUS_DEPLOYER",
+  "ANONYMOUS_TEAM",
+  "UNKNOWN_DEPLOYER",
+  "LOW_LIQUIDITY",
+  "THIN_LIQUIDITY",
+  "SMALL_MARKET_CAP",
+  "HOLDER_CONCENTRATION",
+  "LOW_HOLDER_COUNT",
+  "NOT_ON_TOKEN_LIST",
+  "UNKNOWN_TOKEN",
+  "NO_SOCIAL_PRESENCE"
+]);
+var NO_HISTORY_TYPES = /* @__PURE__ */ new Set(["NO_HISTORY", "UNKNOWN_TOKEN"]);
+function normalizeEvidence(raw, fallback) {
+  const body = isRecord(raw) ? raw : {};
+  const demotedSignals = [];
+  const facts = asArray(body.facts).map(toFact).filter(isPresent);
+  const capabilities = asArray(body.capabilities).map(toCapability).filter(isPresent);
+  const unknowns = asArray(body.unknowns).map(toUnknown).filter(isPresent);
+  const threatSignals = [];
+  let noHistoryObserved = false;
+  for (const item of asArray(body.threatSignals)) {
+    const signal = toSignal(item);
+    if (!signal) continue;
+    if (COVERAGE_SIGNAL_TYPES.has(signal.type)) {
+      demotedSignals.push(signal.type);
+      if (NO_HISTORY_TYPES.has(signal.type)) noHistoryObserved = true;
+      facts.push({
+        type: signal.type,
+        value: null,
+        statement: signal.explanation,
+        source: signal.evidence[0]?.source ?? "decentrys",
+        observedAt: signal.lastSeen
+      });
+      continue;
+    }
+    threatSignals.push(signal);
+  }
+  const declaredHistory = asHistoryStatus(body.historyStatus);
+  const historyStatus = declaredHistory ?? (noHistoryObserved ? "NONE" : "LIMITED");
+  return {
+    subject: toSubject(body.subject, fallback),
+    facts,
+    capabilities,
+    threatSignals,
+    unknowns,
+    historyStatus,
+    historyConfidence: asNumber(body.historyConfidence) ?? void 0,
+    producedAt: asString(body.producedAt) ?? (/* @__PURE__ */ new Date()).toISOString(),
+    demotedSignals
+  };
+}
+function toSubject(raw, fallback) {
+  if (!isRecord(raw)) return fallback;
+  const kind = asString(raw.kind);
+  return {
+    kind: isSubjectKind(kind) ? kind : fallback.kind,
+    chain: asString(raw.chain) ?? fallback.chain,
+    identifier: asString(raw.identifier) ?? fallback.identifier
+  };
+}
+function toFact(raw) {
+  if (!isRecord(raw)) return null;
+  const type = asString(raw.type);
+  const statement = asString(raw.statement);
+  if (!type || !statement) return null;
+  return {
+    type,
+    value: asFactValue(raw.value),
+    statement,
+    source: asString(raw.source) ?? "decentrys",
+    observedAt: asString(raw.observedAt) ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function toCapability(raw) {
+  if (!isRecord(raw)) return null;
+  const type = asString(raw.type);
+  const statement = asString(raw.statement);
+  if (!type || !statement) return null;
+  const severity = asString(raw.severity);
+  return {
+    type,
+    // An unrecognised severity becomes INFO, the least consequential value.
+    // Guessing upward would let a typo raise someone's risk level.
+    severity: severity === "NOTABLE" || severity === "SIGNIFICANT" ? severity : "INFO",
+    statement,
+    grantedBy: asString(raw.grantedBy) ?? void 0
+  };
+}
+function toSignal(raw) {
+  if (!isRecord(raw)) return null;
+  const type = asString(raw.type);
+  const explanation = asString(raw.explanation);
+  if (!type || !explanation) return null;
+  const evidence = asArray(raw.evidence).map(toEvidence).filter(isPresent);
+  const createdAt = asString(raw.createdAt) ?? (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    type,
+    severity: asSeverity(raw.severity),
+    confidence: clamp01(asNumber(raw.confidence) ?? 0),
+    explanation,
+    // A missing hop count means we do not know how far away this is, and an
+    // unknown distance is an inference, not a direct observation.
+    hops: Math.max(0, Math.trunc(asNumber(raw.hops) ?? 1)),
+    evidence,
+    status: asSignalStatus(raw.status),
+    createdAt,
+    lastSeen: asString(raw.lastSeen) ?? createdAt,
+    expiresAt: asString(raw.expiresAt) ?? void 0
+  };
+}
+function toEvidence(raw) {
+  if (!isRecord(raw)) return null;
+  const id = asString(raw.id);
+  const type = asString(raw.type);
+  if (!id || !type) return null;
+  return {
+    id,
+    type,
+    source: asString(raw.source) ?? "decentrys",
+    chain: asString(raw.chain) ?? void 0,
+    txHash: asString(raw.txHash) ?? void 0,
+    contract: asString(raw.contract) ?? void 0,
+    address: asString(raw.address) ?? void 0,
+    observedAt: asString(raw.observedAt) ?? (/* @__PURE__ */ new Date()).toISOString(),
+    confidence: clamp01(asNumber(raw.confidence) ?? 0),
+    // Defaults to false. `analystVerified` is what gates KNOWN_MALICIOUS, so
+    // an absent field must never be read as a human having checked.
+    analystVerified: raw.analystVerified === true,
+    metadata: isRecord(raw.metadata) ? raw.metadata : void 0
+  };
+}
+function toUnknown(raw) {
+  if (!isRecord(raw)) return null;
+  const field = asString(raw.field);
+  const statement = asString(raw.statement);
+  if (!field || !statement) return null;
+  const reason = asString(raw.reason);
+  const reasons = ["UNKNOWN", "INSUFFICIENT_DATA", "PROVIDER_UNAVAILABLE", "NOT_APPLICABLE"];
+  return {
+    field,
+    reason: reasons.includes(reason) ? reason : "UNKNOWN",
+    statement
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function asFactValue(value) {
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  return null;
+}
+function asSeverity(value) {
+  const severities = ["LOW", "MEDIUM", "HIGH", "CRITICAL"];
+  return severities.includes(value) ? value : "LOW";
+}
+function asSignalStatus(value) {
+  const statuses = ["ACTIVE", "STALE", "RESOLVED", "DISPUTED_FACT", "REMOVED"];
+  return statuses.includes(value) ? value : "ACTIVE";
+}
+function asHistoryStatus(value) {
+  const statuses = ["ESTABLISHED", "MODERATE", "LIMITED", "NONE"];
+  return statuses.includes(value) ? value : null;
+}
+function isSubjectKind(value) {
+  return value === "address" || value === "contract" || value === "token" || value === "transaction" || value === "approval" || value === "dapp";
+}
+function clamp01(value) {
+  return Math.min(1, Math.max(0, value));
+}
+function isPresent(value) {
+  return value !== null;
+}
+
+// src/simulation.ts
+function unavailableSimulation(reason, now = /* @__PURE__ */ new Date()) {
+  return {
+    outcome: "UNAVAILABLE",
+    balanceChanges: [],
+    approvalChanges: [],
+    contractsCalled: [],
+    unavailableReason: reason,
+    simulatedAt: now.toISOString()
+  };
+}
+
+// src/transport.ts
+var TransportError = class extends Error {
+  failure;
+  status;
+  constructor(failure, message, status) {
+    super(message);
+    this.name = "TransportError";
+    this.failure = failure;
+    this.status = status;
+  }
+};
+function failureForStatus(status) {
+  if (status === 401) return "unauthorized";
+  if (status === 403) return "forbidden";
+  if (status === 429) return "rate_limited";
+  if (status >= 400 && status < 500) return "invalid_request";
+  return "server_error";
+}
+var RETRYABLE = ["network", "timeout", "server_error", "rate_limited"];
+var HttpTransport = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async request(options) {
+    const attempts = options.idempotent ? this.config.retries + 1 : 1;
+    let last = new TransportError("network", "No attempt was made.");
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      try {
+        return await this.attempt(options);
+      } catch (error) {
+        last = error instanceof TransportError ? error : new TransportError("network", error instanceof Error ? error.message : "Unknown error.");
+        if (!RETRYABLE.includes(last.failure)) throw last;
+        if (attempt === attempts - 1) throw last;
+        await delay(120 * (attempt + 1));
+      }
+    }
+    throw last;
+  }
+  async attempt(options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    const onAbort = () => controller.abort();
+    options.signal?.addEventListener("abort", onAbort);
+    try {
+      const response = await this.config.fetch(joinUrl(this.config.baseUrl, options.path), {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": this.config.apiKey,
+          "user-agent": this.config.userAgent
+        },
+        body: JSON.stringify(options.body ?? {}),
+        signal: controller.signal
+      });
+      const text = await response.text();
+      if (!response.ok) {
+        throw new TransportError(
+          failureForStatus(response.status),
+          messageFrom(text) ?? `Decentrys returned HTTP ${response.status}.`,
+          response.status
+        );
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        throw new TransportError("malformed_response", "The response was not valid JSON.");
+      }
+      const envelope = parsed;
+      return envelope && typeof envelope === "object" && "data" in envelope ? envelope.data : parsed;
+    } catch (error) {
+      if (error instanceof TransportError) throw error;
+      if (isAbort(error)) {
+        throw options.signal?.aborted ? new TransportError("network", "The request was cancelled by the caller.") : new TransportError("timeout", `No response within ${this.config.timeoutMs}ms.`);
+      }
+      throw new TransportError("network", error instanceof Error ? error.message : "Network request failed.");
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+};
+function isAbort(error) {
+  return typeof error === "object" && error !== null && (error.name === "AbortError" || error.code === "ABORT_ERR");
+}
+function messageFrom(text) {
+  try {
+    const body = JSON.parse(text);
+    if (typeof body.message === "string" && body.message.trim()) return body.message;
+    if (typeof body.error === "string" && body.error.trim()) return body.error;
+  } catch {
+  }
+  return null;
+}
+function joinUrl(base, path) {
+  return `${base.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+// src/cache.ts
+var TtlCache = class {
+  constructor(options) {
+    this.options = options;
+    this.now = options.now ?? (() => Date.now());
+  }
+  options;
+  entries = /* @__PURE__ */ new Map();
+  now;
+  get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= this.now()) {
+      this.entries.delete(key);
+      return void 0;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+  set(key, value, ttlMs = this.options.ttlMs) {
+    if (ttlMs <= 0 || this.options.maxEntries <= 0) return;
+    this.entries.delete(key);
+    this.entries.set(key, { value, expiresAt: this.now() + ttlMs });
+    while (this.entries.size > this.options.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done) break;
+      this.entries.delete(oldest.value);
+    }
+  }
+  delete(key) {
+    this.entries.delete(key);
+  }
+  clear() {
+    this.entries.clear();
+  }
+  get size() {
+    return this.entries.size;
+  }
+};
+function cacheKey(kind, parts) {
+  return [kind, ...parts.map((p) => p === void 0 || p === null ? "" : String(p))].join("|");
+}
+
+// src/client.ts
+var SDK_VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://api.decentrys.com";
+var DEFAULT_TIMEOUT_MS = 4e3;
+var DEFAULT_CACHE_TTL_MS = 12e4;
+var DEFAULT_CACHE_ENTRIES = 500;
+var Decentrys = class {
+  transport;
+  failMode;
+  policy;
+  cache;
+  constructor(config) {
+    if (!config.apiKey || !config.apiKey.trim()) {
+      throw new Error("Decentrys: an apiKey is required. Create one at https://decentrys.com/developers.");
+    }
+    this.failMode = config.failMode ?? "warn";
+    this.policy = config.policy ?? {};
+    this.cache = new TtlCache({
+      ttlMs: config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS,
+      maxEntries: config.cacheMaxEntries ?? DEFAULT_CACHE_ENTRIES
+    });
+    this.transport = config.transport ?? new HttpTransport({
+      baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+      apiKey: config.apiKey,
+      timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      retries: config.retries ?? 1,
+      fetch: config.fetch ?? resolveFetch(),
+      userAgent: `decentrys-protect/${SDK_VERSION}`
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Assessments
+  // -------------------------------------------------------------------------
+  /** Pre-sign analysis of a transaction the user is about to approve. */
+  async assessTransaction(tx, options = {}) {
+    return this.assess({
+      path: "/v1/protect/transaction",
+      body: tx,
+      subject: { kind: "transaction", chain: tx.chain, identifier: tx.to ?? tx.from },
+      // A transaction's assessment depends on its calldata and its moment.
+      // Caching one would serve a stale answer for a different transaction.
+      cacheable: false,
+      idempotent: true,
+      options
+    });
+  }
+  /** What a contract *can* do — capabilities, proxy status, admin controls. */
+  async scanContract(request, options = {}) {
+    return this.assess({
+      path: "/v1/protect/contract",
+      body: request,
+      subject: { kind: "contract", chain: request.chain, identifier: request.address },
+      cacheable: true,
+      idempotent: true,
+      options
+    });
+  }
+  async screenAddress(request, options = {}) {
+    return this.assess({
+      path: "/v1/protect/address",
+      body: request,
+      subject: { kind: "address", chain: request.chain, identifier: request.address },
+      cacheable: true,
+      idempotent: true,
+      options
+    });
+  }
+  async screenToken(request, options = {}) {
+    return this.assess({
+      path: "/v1/protect/token",
+      body: request,
+      subject: { kind: "token", chain: request.chain, identifier: request.address },
+      cacheable: true,
+      idempotent: true,
+      options
+    });
+  }
+  /**
+   * An approval is assessed on the spender and the allowance together.
+   *
+   * Not cached: the same spender with an unlimited allowance and with a
+   * one-off allowance are different decisions, and the amount is the part a
+   * user most needs told.
+   */
+  async screenApproval(request, options = {}) {
+    return this.assess({
+      path: "/v1/protect/approval",
+      body: request,
+      subject: { kind: "approval", chain: request.chain, identifier: request.spender },
+      cacheable: false,
+      idempotent: true,
+      options
+    });
+  }
+  async assessDapp(request, options = {}) {
+    return this.assess({
+      path: "/v1/protect/dapp",
+      body: request,
+      subject: { kind: "dapp", chain: request.chain ?? "multi", identifier: request.origin },
+      cacheable: true,
+      idempotent: true,
+      options
+    });
+  }
+  /**
+   * The threat signals on a subject, without a classification.
+   *
+   * For integrators building their own presentation. An empty array means no
+   * signals were found — which is not the same as safe, and the SDK will not
+   * pretend otherwise on their behalf.
+   */
+  async getThreatSignals(request, options = {}) {
+    try {
+      const raw = await this.transport.request({
+        path: "/v1/protect/signals",
+        body: request,
+        idempotent: true,
+        signal: options.signal
+      });
+      return normalizeEvidence(raw, {
+        kind: "address",
+        chain: request.chain,
+        identifier: request.address
+      }).threatSignals;
+    } catch {
+      return [];
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Decoding and simulation
+  // -------------------------------------------------------------------------
+  /** What this transaction does, in the words a user would use. */
+  async explainTransaction(tx, options = {}) {
+    try {
+      const raw = await this.transport.request({
+        path: "/v1/protect/explain",
+        body: tx,
+        idempotent: true,
+        signal: options.signal
+      });
+      return {
+        summary: typeof raw?.summary === "string" && raw.summary ? raw.summary : "This transaction could not be decoded.",
+        actions: stringList(raw?.actions),
+        exposure: stringList(raw?.exposure),
+        undecoded: stringList(raw?.undecoded)
+      };
+    } catch (error) {
+      return {
+        summary: "This transaction could not be decoded.",
+        actions: [],
+        exposure: [],
+        undecoded: [`Decentrys could not be reached: ${describe(error)}.`]
+      };
+    }
+  }
+  /** Execute the transaction against a fork and report what would change. */
+  async simulateTransaction(tx, options = {}) {
+    try {
+      const raw = await this.transport.request({
+        path: "/v1/protect/simulate",
+        body: tx,
+        idempotent: true,
+        signal: options.signal
+      });
+      return normalizeSimulation(raw);
+    } catch (error) {
+      return unavailableSimulation(describe(error));
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Cache control
+  // -------------------------------------------------------------------------
+  /** Drop cached evidence. Call after a user reports a stale result. */
+  clearCache() {
+    this.cache.clear();
+  }
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  async assess(params) {
+    const key = params.cacheable ? cacheKey(params.subject.kind, [params.subject.chain, params.subject.identifier]) : null;
+    if (key && !params.options.skipCache) {
+      const hit = this.cache.get(key);
+      if (hit) return this.finish(hit, true);
+    }
+    let evidence;
+    try {
+      const raw = await this.transport.request({
+        path: params.path,
+        body: params.body,
+        idempotent: params.idempotent,
+        signal: params.options.signal
+      });
+      evidence = normalizeEvidence(raw, params.subject);
+    } catch (error) {
+      return {
+        subject: params.subject,
+        assessment: unavailableAssessment(this.failMode, describe(error)),
+        decision: {
+          // `closed` is the only mode where unavailability is itself a stop.
+          // The others must not fabricate a risk level to justify blocking.
+          action: this.failMode === "closed" ? "block" : "warn",
+          reason: `Decentrys could not be reached: ${describe(error)}.`
+        },
+        cached: false,
+        demotedSignals: []
+      };
+    }
+    if (key) this.cache.set(key, evidence);
+    return this.finish(evidence, false);
+  }
+  finish(evidence, cached) {
+    const assessment = classify({
+      facts: evidence.facts,
+      capabilities: evidence.capabilities,
+      threatSignals: evidence.threatSignals,
+      unknowns: evidence.unknowns,
+      historyStatus: evidence.historyStatus,
+      historyConfidence: evidence.historyConfidence
+    });
+    return {
+      subject: evidence.subject,
+      assessment,
+      decision: applyPolicy(assessment, this.policy),
+      cached,
+      demotedSignals: evidence.demotedSignals
+    };
+  }
+};
+function resolveFetch() {
+  const candidate = globalThis.fetch;
+  if (typeof candidate !== "function") {
+    throw new Error(
+      "Decentrys: no global fetch was found. Pass one via `new Decentrys({ fetch })` (Node 18+, modern browsers and React Native provide one)."
+    );
+  }
+  return candidate.bind(globalThis);
+}
+function describe(error) {
+  if (error instanceof TransportError) return error.message;
+  if (error instanceof Error) return error.message;
+  return "unknown error";
+}
+function stringList(value) {
+  return Array.isArray(value) ? value.filter((v) => typeof v === "string" && v.length > 0) : [];
+}
+function normalizeSimulation(raw) {
+  const body = typeof raw === "object" && raw !== null ? raw : {};
+  const outcomes = ["SUCCESS", "REVERT", "NOT_SUPPORTED", "UNAVAILABLE"];
+  return {
+    // An unrecognised outcome is not a success. Defaulting the other way would
+    // let a malformed response read as "this transaction is fine".
+    outcome: outcomes.includes(body.outcome) ? body.outcome : "UNAVAILABLE",
+    revertReason: typeof body.revertReason === "string" ? body.revertReason : void 0,
+    balanceChanges: Array.isArray(body.balanceChanges) ? body.balanceChanges : [],
+    approvalChanges: Array.isArray(body.approvalChanges) ? body.approvalChanges : [],
+    contractsCalled: stringList(body.contractsCalled),
+    gasUsed: typeof body.gasUsed === "string" ? body.gasUsed : void 0,
+    unavailableReason: typeof body.unavailableReason === "string" ? body.unavailableReason : void 0,
+    simulatedAt: typeof body.simulatedAt === "string" ? body.simulatedAt : (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+export {
+  COVERAGE_SIGNAL_TYPES,
+  DEFAULT_POLICY,
+  Decentrys,
+  HISTORY_STATUS_MEANING,
+  HttpTransport,
+  MIN_RAISING_CONFIDENCE,
+  PROTECT_MODEL_VERSION,
+  RISK_LEVELS,
+  RISK_LEVEL_MEANING,
+  SDK_VERSION,
+  TransportError,
+  TtlCache,
+  applyPolicy,
+  cacheKey,
+  classify,
+  isAtLeast,
+  joinUrl,
+  normalizeEvidence,
+  unavailableAssessment,
+  unavailableSimulation
+};