@decentrys/protect 0.1.0

package/src/client.ts

@@ -0,0 +1,420 @@
+/**
+ * The client an integrator installs.
+ *
+ * Its contract is narrow and absolute: **every method returns, and none of
+ * them throws.** This code sits between a user and a signing screen. A wallet
+ * that shows an error dialog because a security service had a bad minute has
+ * made the user's day worse for no security benefit, and the user learns to
+ * dismiss the dialog — which is the outcome the whole product exists to avoid.
+ *
+ * So an unreachable Decentrys produces an assessment that says exactly that,
+ * in `unknowns` and in `explanation`, and the configured `failMode` decides
+ * what the integrator does about it. Nothing is invented, and nothing is
+ * silently reported as clean.
+ */
+
+import { type Assessment, type ThreatSignal } from './model';
+import { type FailMode, type Policy, type PolicyAction, applyPolicy, classify, unavailableAssessment } from './classify';
+import { HttpTransport, type FetchLike, type Transport, TransportError } from './transport';
+import { TtlCache, cacheKey } from './cache';
+import { type NormalizedEvidence, type SubjectRef, normalizeEvidence } from './wire';
+import {
+  type SimulationResult, type TransactionExplanation, unavailableSimulation,
+} from './simulation';
+
+export const SDK_VERSION = '0.1.0';
+
+const DEFAULT_BASE_URL = 'https://api.decentrys.com';
+const DEFAULT_TIMEOUT_MS = 4_000;
+const DEFAULT_CACHE_TTL_MS = 120_000;
+const DEFAULT_CACHE_ENTRIES = 500;
+
+export interface DecentrysConfig {
+  apiKey: string;
+  baseUrl?: string;
+  /**
+   * What the integrator does when Decentrys is unreachable. `warn` is the
+   * consumer default; `closed` is for deployments that would rather stop.
+   */
+  failMode?: FailMode;
+  /**
+   * A deadline, not a target. Exceeding it returns an unavailable assessment
+   * rather than leaving the user on a spinner holding a signature.
+   */
+  timeoutMs?: number;
+  /** Retries apply to idempotent lookups only. */
+  retries?: number;
+  policy?: Policy;
+  cacheTtlMs?: number;
+  cacheMaxEntries?: number;
+  /** Injected so the SDK works in a browser, an extension, RN and Node alike. */
+  fetch?: FetchLike;
+  /** For tests and for integrators who route through their own gateway. */
+  transport?: Transport;
+}
+
+export interface TransactionRequest {
+  chain: string;
+  from: string;
+  to?: string;
+  /** Base units, as a string. Numbers lose precision at these magnitudes. */
+  value?: string;
+  /** EVM calldata. */
+  data?: string;
+  /** Non-EVM families carry their serialized payload here instead. */
+  raw?: string;
+  /** The site requesting the signature, when there is one. */
+  origin?: string;
+}
+
+export interface AddressRequest {
+  chain: string;
+  address: string;
+}
+
+export interface ApprovalRequest {
+  chain: string;
+  owner: string;
+  spender: string;
+  token: string;
+  /** Base units, or `unlimited`. */
+  amount?: string;
+}
+
+export interface DappRequest {
+  origin: string;
+  chain?: string;
+}
+
+export interface ProtectResult {
+  subject: SubjectRef;
+  assessment: Assessment;
+  /** What the integrator's policy says to do. Advice — never enforced here. */
+  decision: { action: PolicyAction; reason: string };
+  /** True when served from the local cache rather than the network. */
+  cached: boolean;
+  /**
+   * Coverage signals the SDK refused to treat as risk. Surfaced rather than
+   * hidden: an integrator should be able to see the rule being applied.
+   */
+  demotedSignals: string[];
+}
+
+export class Decentrys {
+  private readonly transport: Transport;
+  private readonly failMode: FailMode;
+  private readonly policy: Policy;
+  private readonly cache: TtlCache<NormalizedEvidence>;
+
+  constructor(config: DecentrysConfig) {
+    if (!config.apiKey || !config.apiKey.trim()) {
+      // Thrown at construction, which is a developer error at wiring time —
+      // as opposed to anything at call time, which is a user's transaction.
+      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<NormalizedEvidence>({
+      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: TransactionRequest, options: CallOptions = {}): Promise<ProtectResult> {
+    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: AddressRequest, options: CallOptions = {}): Promise<ProtectResult> {
+    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: AddressRequest, options: CallOptions = {}): Promise<ProtectResult> {
+    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: AddressRequest, options: CallOptions = {}): Promise<ProtectResult> {
+    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: ApprovalRequest, options: CallOptions = {}): Promise<ProtectResult> {
+    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: DappRequest, options: CallOptions = {}): Promise<ProtectResult> {
+    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: AddressRequest, options: CallOptions = {}): Promise<ThreatSignal[]> {
+    try {
+      const raw = await this.transport.request<unknown>({
+        path: '/v1/protect/signals',
+        body: request,
+        idempotent: true,
+        signal: options.signal,
+      });
+      return normalizeEvidence(raw, {
+        kind: 'address', chain: request.chain, identifier: request.address,
+      }).threatSignals;
+    } catch {
+      // No signals is the only honest answer when we could not look. The
+      // caller distinguishes it from a real empty result by asking for a full
+      // assessment, whose `unknowns` say so explicitly.
+      return [];
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Decoding and simulation
+  // -------------------------------------------------------------------------
+
+  /** What this transaction does, in the words a user would use. */
+  async explainTransaction(
+    tx: TransactionRequest, options: CallOptions = {},
+  ): Promise<TransactionExplanation> {
+    try {
+      const raw = await this.transport.request<Partial<TransactionExplanation>>({
+        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: TransactionRequest, options: CallOptions = {},
+  ): Promise<SimulationResult> {
+    try {
+      const raw = await this.transport.request<SimulationResult>({
+        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(): void {
+    this.cache.clear();
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  private async assess(params: {
+    path: string;
+    body: unknown;
+    subject: SubjectRef;
+    cacheable: boolean;
+    idempotent: boolean;
+    options: CallOptions;
+  }): Promise<ProtectResult> {
+    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: NormalizedEvidence;
+    try {
+      const raw = await this.transport.request<unknown>({
+        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);
+  }
+
+  private finish(evidence: NormalizedEvidence, cached: boolean): ProtectResult {
+    // Classification happens here, on the client, from evidence — not read
+    // off a server response. That is what makes the rule auditable by the
+    // integrator rather than a promise made in a marketing page.
+    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,
+    };
+  }
+}
+
+export interface CallOptions {
+  signal?: AbortSignal;
+  /** Bypass the cache for this call. The result still populates it. */
+  skipCache?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function resolveFetch(): FetchLike {
+  const candidate = (globalThis as { fetch?: unknown }).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) as FetchLike;
+}
+
+function describe(error: unknown): string {
+  if (error instanceof TransportError) return error.message;
+  if (error instanceof Error) return error.message;
+  return 'unknown error';
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string' && v.length > 0) : [];
+}
+
+function normalizeSimulation(raw: unknown): SimulationResult {
+  const body = (typeof raw === 'object' && raw !== null ? raw : {}) as Partial<SimulationResult>;
+  const outcomes: SimulationResult['outcome'][] = ['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 as SimulationResult['outcome'])
+      ? (body.outcome as SimulationResult['outcome'])
+      : 'UNAVAILABLE',
+    revertReason: typeof body.revertReason === 'string' ? body.revertReason : undefined,
+    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 : undefined,
+    unavailableReason: typeof body.unavailableReason === 'string' ? body.unavailableReason : undefined,
+    simulatedAt: typeof body.simulatedAt === 'string' ? body.simulatedAt : new Date().toISOString(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './model';
+export * from './classify';
+export * from './wire';
+export * from './simulation';
+export * from './transport';
+export * from './cache';
+export * from './client';

package/src/model.ts

@@ -0,0 +1,237 @@
+/**
+ * The Decentrys risk model.
+ *
+ * One rule governs this file, and every other decision follows from it:
+ *
+ *   **LACK OF EVIDENCE IS NOT EVIDENCE OF MALICE.**
+ *
+ * A contract deployed two hours ago by an anonymous wallet with no audit and
+ * thin liquidity is *unknown*, not dangerous. The industry habit of scoring
+ * those facts as risk produces a system that protects incumbents and taxes
+ * every new project — which is a gatekeeping product, not a security one.
+ *
+ * The model therefore separates four things that are usually collapsed:
+ *
+ *  - **Facts** — directly verifiable, carrying no accusation.
+ *  - **Capabilities** — what the code *can* do. A mint authority is a
+ *    capability, not a vulnerability; it becomes one when behaviour or context
+ *    shows it being abused.
+ *  - **Threat signals** — require actual technical or behavioural evidence.
+ *    These, and only these, can raise a risk level.
+ *  - **Unknowns** — stated as unknown. Never silently converted to risk.
+ *
+ * `historyConfidence` exists to express how much Decentrys knows. It is
+ * deliberately not part of the risk computation: it is a measure of our
+ * coverage, not of the subject's danger.
+ */
+
+// ---------------------------------------------------------------------------
+// Risk levels
+// ---------------------------------------------------------------------------
+
+/**
+ * Deliberately not SAFE/SCAM.
+ *
+ * "Safe" is a claim no analysis can support, and "scam" is an accusation that
+ * needs evidence. The scale runs from "we found no critical threat evidence"
+ * to "confirmed malicious infrastructure", and every step above CAUTION
+ * requires a threat signal to reach it.
+ */
+export const RISK_LEVELS = [
+  'NO_CRITICAL_RISK_DETECTED',
+  'INFORMATIONAL',
+  'CAUTION',
+  'ELEVATED_RISK',
+  'HIGH_RISK',
+  'CRITICAL_THREAT',
+  'KNOWN_MALICIOUS',
+] as const;
+export type RiskLevel = (typeof RISK_LEVELS)[number];
+
+const RISK_ORDER: Record<RiskLevel, number> = {
+  NO_CRITICAL_RISK_DETECTED: 0,
+  INFORMATIONAL: 1,
+  CAUTION: 2,
+  ELEVATED_RISK: 3,
+  HIGH_RISK: 4,
+  CRITICAL_THREAT: 5,
+  KNOWN_MALICIOUS: 6,
+};
+
+export function isAtLeast(level: RiskLevel, floor: RiskLevel): boolean {
+  return RISK_ORDER[level] >= RISK_ORDER[floor];
+}
+
+/** What each level is allowed to mean, in the words an integrator may show. */
+export const RISK_LEVEL_MEANING: Record<RiskLevel, string> = {
+  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.',
+};
+
+// ---------------------------------------------------------------------------
+// Observed facts
+// ---------------------------------------------------------------------------
+
+export type FactValue = string | number | boolean | null;
+
+/**
+ * Something directly verifiable.
+ *
+ * Facts carry no severity. "Deployed two hours ago" and "mint authority
+ * present" are both simply true; what they mean is the integrator's call and,
+ * where it matters, the threat signals' job to establish.
+ */
+export interface ObservedFact {
+  type: string;
+  value: FactValue;
+  /** Plain language, shown to a user as-is. Never accusatory. */
+  statement: string;
+  /** Where the fact came from, so it can be checked. */
+  source: string;
+  observedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Capabilities
+// ---------------------------------------------------------------------------
+
+/**
+ * `INFO` is the default and the common case.
+ *
+ * A capability's severity describes how much power it confers, not how likely
+ * it is to be abused. Nothing here alone can push a subject past CAUTION.
+ */
+export type CapabilitySeverity = 'INFO' | 'NOTABLE' | 'SIGNIFICANT';
+
+export interface TechnicalCapability {
+  type: string;
+  severity: CapabilitySeverity;
+  /** What the contract *can* do, phrased as capability, never as accusation. */
+  statement: string;
+  /** The function, role or storage slot that grants it. */
+  grantedBy?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Evidence
+// ---------------------------------------------------------------------------
+
+export interface Evidence {
+  id: string;
+  type: string;
+  source: string;
+  chain?: string;
+  txHash?: string;
+  contract?: string;
+  address?: string;
+  observedAt: string;
+  confidence: number;
+  /** True when a human analyst confirmed it. Required for KNOWN_MALICIOUS. */
+  analystVerified: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Signals decay.
+ *
+ * A low-confidence association from three years ago must not poison an address
+ * permanently. A signal that is STALE still appears — suppressing it would
+ * hide a real observation — but it cannot raise the risk level.
+ */
+export type SignalStatus = 'ACTIVE' | 'STALE' | 'RESOLVED' | 'DISPUTED_FACT' | 'REMOVED';
+
+export type ThreatSeverity = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+
+export interface ThreatSignal {
+  type: string;
+  severity: ThreatSeverity;
+  /** 0–1. Presented alongside the signal, never rounded away. */
+  confidence: number;
+  /** Why this signal exists, in language a user can act on. */
+  explanation: string;
+  /** Hops from the subject. 0 is direct; anything above is inference. */
+  hops: number;
+  evidence: Evidence[];
+  status: SignalStatus;
+  createdAt: string;
+  lastSeen: string;
+  expiresAt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Unknowns
+// ---------------------------------------------------------------------------
+
+export type UnknownReason = 'UNKNOWN' | 'INSUFFICIENT_DATA' | 'PROVIDER_UNAVAILABLE' | 'NOT_APPLICABLE';
+
+export interface UnknownField {
+  field: string;
+  reason: UnknownReason;
+  /** Says plainly that we do not know, rather than implying anything. */
+  statement: string;
+}
+
+/**
+ * How much Decentrys knows about a subject — never how dangerous it is.
+ *
+ * `LIMITED` is the correct and expected state for anything new, and it must
+ * never be rendered as a warning.
+ */
+export type HistoryStatus = 'ESTABLISHED' | 'MODERATE' | 'LIMITED' | 'NONE';
+
+export const HISTORY_STATUS_MEANING: Record<HistoryStatus, string> = {
+  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.',
+};
+
+// ---------------------------------------------------------------------------
+// Assessment
+// ---------------------------------------------------------------------------
+
+export interface RiskComponents {
+  /** From capabilities the code genuinely holds. Never inflated by age. */
+  technicalRisk: number;
+  /** From observed behaviour. */
+  behavioralRisk: number;
+  /** From confirmed threat intelligence. */
+  threatIntelligenceRisk: number;
+  /**
+   * How much we know, 0–100. **Not a danger score.** A low value means thin
+   * coverage on our side, and it is reported separately so no integrator can
+   * accidentally add it to a risk total.
+   */
+  historyConfidence: number;
+}
+
+export interface Assessment {
+  riskLevel: RiskLevel;
+  /** True only with analyst-verified evidence. Never inferred. */
+  confirmedMalicious: boolean;
+  confidence: number;
+  historyStatus: HistoryStatus;
+  facts: ObservedFact[];
+  capabilities: TechnicalCapability[];
+  threatSignals: ThreatSignal[];
+  unknowns: UnknownField[];
+  components: RiskComponents;
+  /** Why this level was reached. Never empty — no black-box classifications. */
+  explanation: string[];
+  modelVersion: string;
+  assessedAt: string;
+}
+
+export const PROTECT_MODEL_VERSION = 'protect-1.0.0';