@decentrys/protect 0.1.0

package/src/classify.ts

@@ -0,0 +1,323 @@
+import {
+  HISTORY_STATUS_MEANING, PROTECT_MODEL_VERSION, RISK_LEVEL_MEANING,
+  type Assessment, type HistoryStatus, type ObservedFact, type RiskLevel,
+  type SignalStatus, type TechnicalCapability, type ThreatSignal,
+  type UnknownField,
+} from './model';
+
+/**
+ * Classification.
+ *
+ * The whole point of this function is what it *refuses* to do. Age, audit
+ * status, liquidity, holder concentration, deployer history and anonymity are
+ * inputs to `facts` and to `historyConfidence` — and to nothing else. There is
+ * no path in this file by which any of them raises a risk level.
+ *
+ * Risk comes from two places only:
+ *
+ *  - **Capabilities**, which can reach CAUTION. A contract that can mint
+ *    unlimited supply deserves attention; it does not deserve an accusation.
+ *  - **Threat signals**, which are the only way past CAUTION, and which
+ *    require evidence.
+ *
+ * `KNOWN_MALICIOUS` additionally requires analyst-verified evidence, because
+ * it is the one output that is a public accusation about a third party.
+ */
+
+/** Signals that are no longer live cannot raise a level. */
+const RAISING_STATUSES: SignalStatus[] = ['ACTIVE'];
+
+/**
+ * Below this, a signal is reported but cannot raise the level on its own.
+ *
+ * A 30%-confidence four-hop association is a real observation and belongs in
+ * the response. It is not grounds for telling a user their transaction is
+ * dangerous.
+ */
+/**
+ * Exported so a renderer cannot drift from the classifier.
+ *
+ * `@decentrys/ui` decides whether to show a signal as one that counted, and
+ * it has to use the same floor the classifier used to decide whether it did.
+ * Two copies of this number that disagree would put a signal in the "did not
+ * raise the level" list while it was in fact raising it.
+ */
+export const MIN_RAISING_CONFIDENCE = 0.5;
+
+export interface ClassifyInput {
+  facts?: ObservedFact[];
+  capabilities?: TechnicalCapability[];
+  threatSignals?: ThreatSignal[];
+  unknowns?: UnknownField[];
+  historyStatus?: HistoryStatus;
+  /** 0–100. Coverage, not danger. */
+  historyConfidence?: number;
+  now?: Date;
+}
+
+export function classify(input: ClassifyInput): Assessment {
+  const now = input.now ?? new Date();
+  const facts = input.facts ?? [];
+  const capabilities = input.capabilities ?? [];
+  const unknowns = input.unknowns ?? [];
+  const historyStatus = input.historyStatus ?? 'LIMITED';
+
+  // Expiry is applied here rather than trusted from the caller, so a stale
+  // signal cannot keep raising a level because nobody re-ran a job.
+  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: string[] = [];
+  let level: RiskLevel = 'NO_CRITICAL_RISK_DETECTED';
+
+  // --- 1. Confirmed malicious -----------------------------------------------
+  // The only claim that accuses. It needs a human behind it.
+  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 {
+    // --- 2. Threat signals --------------------------------------------------
+    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);
+    }
+
+    // --- 3. Capabilities ----------------------------------------------------
+    // Can reach CAUTION and no further. A capability is what the code can do,
+    // not proof that it will.
+    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);
+    }
+  }
+
+  // Signals that exist but did not raise the level are still reported, and the
+  // explanation says why they did not — silence would look like we missed them.
+  for (const signal of threatSignals) {
+    if (raising.includes(signal)) continue;
+    if (signal.status !== 'ACTIVE') {
+      explanation.push(
+        `${signal.explanation} — this signal is ${signal.status.toLowerCase()} and did not affect the assessment.`,
+      );
+    } else if (signal.confidence < MIN_RAISING_CONFIDENCE) {
+      explanation.push(
+        `${signal.explanation} — reported at ${Math.round(signal.confidence * 100)}% confidence, which is too low `
+        + 'to raise the risk level on its own.',
+      );
+    }
+  }
+
+  // --- 4. Facts worth showing make it informational -----------------------
+  // Independent of history. Promoting only for LIMITED history would have made
+  // the level depend on how new the subject is, which is precisely the
+  // behaviour this model exists to refuse — and a test caught it.
+  if (level === 'NO_CRITICAL_RISK_DETECTED' && facts.length > 0) {
+    level = 'INFORMATIONAL';
+  }
+
+  // Limited history is stated, never scored.
+  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: RiskLevel): number {
+  return [
+    'NO_CRITICAL_RISK_DETECTED', 'INFORMATIONAL', 'CAUTION',
+    'ELEVATED_RISK', 'HIGH_RISK', 'CRITICAL_THREAT', 'KNOWN_MALICIOUS',
+  ].indexOf(level);
+}
+
+/** Expire a signal whose window has passed, rather than trusting its status. */
+function applyDecay(signal: ThreatSignal, now: Date): ThreatSignal {
+  if (signal.status !== 'ACTIVE') return signal;
+  if (!signal.expiresAt) return signal;
+  return Date.parse(signal.expiresAt) <= now.getTime()
+    ? { ...signal, status: 'STALE' }
+    : signal;
+}
+
+/**
+ * How sure we are of the *classification*.
+ *
+ * Bounded by the evidence behind it. A clean result on thin history is a
+ * low-confidence clean result, and saying so is the honest thing — but note it
+ * lowers confidence, not raises risk.
+ */
+function confidenceFor(level: RiskLevel, raising: ThreatSignal[], history: HistoryStatus): number {
+  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;
+  }
+}
+
+/** Capabilities only. Contract age contributes nothing, by construction. */
+function technicalRisk(capabilities: TechnicalCapability[]): number {
+  const weight = { INFO: 4, NOTABLE: 12, SIGNIFICANT: 25 } as const;
+  return Math.min(100, capabilities.reduce((sum, c) => sum + weight[c.severity], 0));
+}
+
+function behavioralRisk(raising: ThreatSignal[]): number {
+  const weight = { LOW: 5, MEDIUM: 20, HIGH: 40, CRITICAL: 70 } as const;
+  return Math.min(100, raising
+    .filter((s) => s.hops === 0)
+    .reduce((sum, s) => sum + weight[s.severity] * s.confidence, 0));
+}
+
+function threatIntelligenceRisk(raising: ThreatSignal[]): number {
+  const weight = { LOW: 5, MEDIUM: 15, HIGH: 35, CRITICAL: 60 } as const;
+  return Math.min(100, raising.reduce((sum, s) => {
+    // Each hop is another inference; weight decays accordingly.
+    const decay = Math.pow(0.6, Math.max(0, s.hops));
+    return sum + weight[s.severity] * s.confidence * decay;
+  }, 0));
+}
+
+function historyConfidenceFor(status: HistoryStatus): number {
+  switch (status) {
+    case 'ESTABLISHED': return 90;
+    case 'MODERATE': return 60;
+    case 'LIMITED': return 25;
+    default: return 5;
+  }
+}
+
+/**
+ * How an integrator turns an assessment into behaviour.
+ *
+ * The SDK never blocks on its own. Decentrys returns intelligence; the wallet
+ * or exchange decides policy, and a consumer wallet and an institutional
+ * custodian will reasonably decide differently.
+ */
+export type PolicyAction = 'allow' | 'inform' | 'warn' | 'warn_strong' | 'require_confirmation' | 'block';
+
+export type Policy = Partial<Record<RiskLevel, PolicyAction>>;
+
+/**
+ * Transparency over blocking.
+ *
+ * The default blocks only what is confirmed malicious with analyst-verified
+ * evidence. Everything else informs or warns, leaving the decision with the
+ * person whose funds are at stake.
+ */
+export const DEFAULT_POLICY: Required<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',
+};
+
+export function applyPolicy(assessment: Assessment, policy: Policy = {}): {
+  action: PolicyAction;
+  reason: string;
+} {
+  const action = policy[assessment.riskLevel] ?? DEFAULT_POLICY[assessment.riskLevel];
+  return {
+    action,
+    reason: assessment.explanation[0] ?? RISK_LEVEL_MEANING[assessment.riskLevel],
+  };
+}
+
+/**
+ * What the SDK does when Decentrys is unreachable.
+ *
+ * A wallet must not become unusable because a security service is down.
+ * `warn` is the consumer default; an institution may choose `closed`.
+ */
+export type FailMode = 'open' | 'warn' | 'closed';
+
+export function unavailableAssessment(failMode: FailMode, reason: string, now = new Date()): Assessment {
+  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(),
+  };
+}

package/src/client.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Decentrys } from './client';
+import { TransportError, type RequestOptions, type Transport } from './transport';
+
+/** A transport whose every response the test controls. */
+function stub(handler: (options: RequestOptions) => Promise<unknown>): Transport & { calls: RequestOptions[] } {
+  const calls: RequestOptions[] = [];
+  return {
+    calls,
+    request: <T>(options: RequestOptions): Promise<T> => {
+      calls.push(options);
+      return handler(options) as Promise<T>;
+    },
+  };
+}
+
+const CLEAN = { facts: [], capabilities: [], threatSignals: [], unknowns: [], historyStatus: 'LIMITED' };
+
+function client(transport: Transport, config: Partial<ConstructorParameters<typeof Decentrys>[0]> = {}) {
+  return new Decentrys({ apiKey: 'test-key', transport, ...config });
+}
+
+describe('Decentrys — construction', () => {
+  it('refuses to construct without an API key, at wiring time', () => {
+    expect(() => new Decentrys({ apiKey: '' })).toThrow(/apiKey is required/);
+  });
+});
+
+describe('Decentrys — availability', () => {
+  /**
+   * The contract this whole class exists to keep. A wallet that throws an
+   * error dialog because a security service had a bad minute has made the
+   * user's day worse for no security benefit — and taught them to dismiss the
+   * dialog, which is the outcome the product exists to prevent.
+   */
+  it('never throws when Decentrys is unreachable', async () => {
+    const d = client(stub(() => Promise.reject(new TransportError('network', 'connection refused'))));
+
+    const result = await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+
+    expect(result.assessment.riskLevel).toBe('NO_CRITICAL_RISK_DETECTED');
+    expect(result.assessment.confidence).toBe(0);
+    expect(result.assessment.unknowns[0]?.reason).toBe('PROVIDER_UNAVAILABLE');
+    expect(result.assessment.explanation[0]).toContain('connection refused');
+  });
+
+  it('says nothing was checked rather than reporting a clean result', async () => {
+    const d = client(stub(() => Promise.reject(new TransportError('timeout', 'no response'))));
+
+    const result = await d.assessTransaction({ chain: 'ethereum', from: '0x1', to: '0x2' });
+    expect(result.assessment.unknowns[0]?.statement).toContain('Nothing was checked');
+  });
+
+  it('warns by default when unavailable, and blocks only in closed mode', async () => {
+    const down = stub(() => Promise.reject(new TransportError('network', 'down')));
+
+    await expect(client(down).screenAddress({ chain: 'ethereum', address: '0xa' }))
+      .resolves.toMatchObject({ decision: { action: 'warn' } });
+
+    await expect(client(down, { failMode: 'open' }).screenAddress({ chain: 'ethereum', address: '0xa' }))
+      .resolves.toMatchObject({ decision: { action: 'warn' } });
+
+    await expect(client(down, { failMode: 'closed' }).screenAddress({ chain: 'ethereum', address: '0xa' }))
+      .resolves.toMatchObject({ decision: { action: 'block' } });
+  });
+
+  /**
+   * Unavailability must not be dressed up as a finding. `closed` stops the
+   * transaction on policy grounds; it does not invent a risk level to justify
+   * itself, and the assessment still says plainly that nothing was checked.
+   */
+  it('does not fabricate a risk level to justify blocking', async () => {
+    const d = client(stub(() => Promise.reject(new TransportError('network', 'down'))), { failMode: 'closed' });
+
+    const result = await d.screenAddress({ chain: 'ethereum', address: '0xa' });
+    expect(result.assessment.riskLevel).toBe('NO_CRITICAL_RISK_DETECTED');
+    expect(result.assessment.confirmedMalicious).toBe(false);
+  });
+
+  it('returns an unavailable simulation rather than an empty one', async () => {
+    const d = client(stub(() => Promise.reject(new TransportError('timeout', 'no response'))));
+
+    const sim = await d.simulateTransaction({ chain: 'ethereum', from: '0x1' });
+    expect(sim.outcome).toBe('UNAVAILABLE');
+    expect(sim.unavailableReason).toBe('no response');
+  });
+
+  it('says a transaction could not be decoded rather than inventing a summary', async () => {
+    const d = client(stub(() => Promise.reject(new TransportError('network', 'down'))));
+
+    const explained = await d.explainTransaction({ chain: 'ethereum', from: '0x1' });
+    expect(explained.summary).toContain('could not be decoded');
+    expect(explained.undecoded[0]).toContain('down');
+  });
+});
+
+describe('Decentrys — classification is local', () => {
+  it('classifies from evidence and ignores any level the server asserts', async () => {
+    const d = client(stub(() => Promise.resolve({
+      ...CLEAN,
+      // A server insisting on a verdict. The SDK does not read it.
+      riskLevel: 'KNOWN_MALICIOUS',
+      confirmedMalicious: true,
+    })));
+
+    const result = await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+    expect(result.assessment.riskLevel).toBe('NO_CRITICAL_RISK_DETECTED');
+    expect(result.assessment.confirmedMalicious).toBe(false);
+  });
+
+  it('reports which coverage signals it refused', async () => {
+    const d = client(stub(() => Promise.resolve({
+      ...CLEAN,
+      threatSignals: [{
+        type: 'NEW_ADDRESS', severity: 'HIGH', confidence: 0.9,
+        explanation: 'Deployed today.', hops: 0, evidence: [],
+        status: 'ACTIVE', createdAt: '2026-09-01T00:00:00.000Z',
+      }],
+    })));
+
+    const result = await d.screenToken({ chain: 'ethereum', address: '0xtoken' });
+    expect(result.demotedSignals).toEqual(['NEW_ADDRESS']);
+    expect(result.assessment.riskLevel).toBe('INFORMATIONAL');
+  });
+
+  it('applies the integrator policy, not its own', async () => {
+    const evidence = {
+      ...CLEAN,
+      capabilities: [{ type: 'MINT_AUTHORITY', severity: 'SIGNIFICANT', statement: 'Supply can be increased.' }],
+    };
+
+    const permissive = await client(stub(() => Promise.resolve(evidence)))
+      .scanContract({ chain: 'ethereum', address: '0xc' });
+    expect(permissive.decision.action).toBe('warn');
+
+    const strict = await client(stub(() => Promise.resolve(evidence)), { policy: { CAUTION: 'block' } })
+      .scanContract({ chain: 'ethereum', address: '0xc' });
+    expect(strict.decision.action).toBe('block');
+  });
+});
+
+describe('Decentrys — caching', () => {
+  it('serves a repeated address lookup from memory', async () => {
+    const transport = stub(() => Promise.resolve(CLEAN));
+    const d = client(transport);
+
+    const first = await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+    const second = await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+
+    expect(first.cached).toBe(false);
+    expect(second.cached).toBe(true);
+    expect(transport.calls).toHaveLength(1);
+  });
+
+  it('does not share a cache entry across chains', async () => {
+    const transport = stub(() => Promise.resolve(CLEAN));
+    const d = client(transport);
+
+    await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+    await d.screenAddress({ chain: 'polygon', address: '0xabc' });
+
+    expect(transport.calls).toHaveLength(2);
+  });
+
+  /**
+   * A transaction's assessment depends on its calldata and its moment, and an
+   * approval's on the allowance being granted. Caching either would answer a
+   * different question than the one asked.
+   */
+  it('never caches a transaction or an approval', async () => {
+    const transport = stub(() => Promise.resolve(CLEAN));
+    const d = client(transport);
+
+    await d.assessTransaction({ chain: 'ethereum', from: '0x1', to: '0x2', data: '0xa' });
+    await d.assessTransaction({ chain: 'ethereum', from: '0x1', to: '0x2', data: '0xa' });
+    await d.screenApproval({ chain: 'ethereum', owner: '0x1', spender: '0x2', token: '0x3' });
+    await d.screenApproval({ chain: 'ethereum', owner: '0x1', spender: '0x2', token: '0x3' });
+
+    expect(transport.calls).toHaveLength(4);
+  });
+
+  it('honours skipCache and clearCache', async () => {
+    const transport = stub(() => Promise.resolve(CLEAN));
+    const d = client(transport);
+
+    await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+    await d.screenAddress({ chain: 'ethereum', address: '0xabc' }, { skipCache: true });
+    expect(transport.calls).toHaveLength(2);
+
+    d.clearCache();
+    await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+    expect(transport.calls).toHaveLength(3);
+  });
+
+  it('does not cache an unavailable result', async () => {
+    const transport = stub(vi.fn()
+      .mockRejectedValueOnce(new TransportError('network', 'down'))
+      .mockResolvedValue(CLEAN));
+    const d = client(transport);
+
+    const down = await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+    expect(down.assessment.confidence).toBe(0);
+
+    const recovered = await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+    expect(recovered.cached).toBe(false);
+    expect(transport.calls).toHaveLength(2);
+  });
+});
+
+describe('Decentrys — request shape', () => {
+  it('marks lookups idempotent so the transport may retry them', async () => {
+    const transport = stub(() => Promise.resolve(CLEAN));
+    const d = client(transport);
+
+    await d.screenAddress({ chain: 'ethereum', address: '0xabc' });
+    expect(transport.calls[0]!.idempotent).toBe(true);
+    expect(transport.calls[0]!.path).toBe('/v1/protect/address');
+  });
+
+  it('returns no signals rather than throwing when signals cannot be fetched', async () => {
+    const d = client(stub(() => Promise.reject(new TransportError('network', 'down'))));
+    await expect(d.getThreatSignals({ chain: 'ethereum', address: '0xabc' })).resolves.toEqual([]);
+  });
+});