@decentrys/protect 0.1.0

package/dist/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@decentrys/protect",
+  "version": "0.1.0",
+  "description": "Evidence-based on-chain risk assessment for wallets and dapps. Unknown is neutral, risk requires evidence, and nothing is ever called a scam without one.",
+  "license": "MIT",
+  "author": "Decentrys Labs",
+  "homepage": "https://decentrys.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teamdecentrys-byte/Decentrys.git",
+    "directory": "sdk/protect"
+  },
+  "bugs": {
+    "url": "https://github.com/teamdecentrys-byte/Decentrys/issues"
+  },
+  "keywords": [
+    "decentrys",
+    "blockchain",
+    "web3",
+    "security",
+    "crypto",
+    "wallet",
+    "transaction-security",
+    "risk-assessment",
+    "threat-intelligence",
+    "ethereum",
+    "solana",
+    "sui"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/browser/decentrys-protect.mjs",
+      "default": "./dist/index.js"
+    },
+    "./browser": "./dist/browser/decentrys-protect.mjs"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo*",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && npm run build:browser",
+    "typecheck": "tsc -p tsconfig.spec.json",
+    "test": "vitest run",
+    "build:browser": "../../node_modules/.bin/esbuild src/index.ts --bundle --format=esm --target=es2022 --outfile=dist/browser/decentrys-protect.mjs && ../../node_modules/.bin/esbuild src/index.ts --bundle --format=iife --global-name=DecentrysProtect --target=es2022 --outfile=dist/browser/decentrys-protect.js"
+  }
+}

package/src/cache.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { TtlCache, cacheKey } from './cache';
+
+function clock(start = 0) {
+  let t = start;
+  return { now: () => t, advance: (ms: number) => { t += ms; } };
+}
+
+describe('TtlCache', () => {
+  it('serves a value inside its TTL', () => {
+    const c = clock();
+    const cache = new TtlCache<string>({ ttlMs: 100, maxEntries: 10, now: c.now });
+
+    cache.set('a', 'value');
+    c.advance(99);
+    expect(cache.get('a')).toBe('value');
+  });
+
+  /**
+   * Threat intelligence changes. An entry that outlives the discovery of a
+   * drainer is worse than no cache at all.
+   */
+  it('drops a value once its TTL passes', () => {
+    const c = clock();
+    const cache = new TtlCache<string>({ ttlMs: 100, maxEntries: 10, now: c.now });
+
+    cache.set('a', 'value');
+    c.advance(100);
+    expect(cache.get('a')).toBeUndefined();
+    expect(cache.size).toBe(0);
+  });
+
+  it('evicts the least recently used entry when full', () => {
+    const cache = new TtlCache<string>({ ttlMs: 1_000, maxEntries: 2, now: () => 0 });
+
+    cache.set('a', '1');
+    cache.set('b', '2');
+    cache.get('a');           // 'a' becomes the most recent
+    cache.set('c', '3');      // evicts 'b'
+
+    expect(cache.get('a')).toBe('1');
+    expect(cache.get('b')).toBeUndefined();
+    expect(cache.get('c')).toBe('3');
+  });
+
+  it('stores nothing when caching is disabled', () => {
+    const cache = new TtlCache<string>({ ttlMs: 0, maxEntries: 10, now: () => 0 });
+    cache.set('a', '1');
+    expect(cache.get('a')).toBeUndefined();
+  });
+});
+
+describe('cacheKey', () => {
+  /**
+   * Two subjects that differ only in a field the key forgot would share an
+   * assessment, and one of them would be wrong.
+   */
+  it('separates the same address on different chains', () => {
+    const evm = cacheKey('address', ['ethereum', '0xabc']);
+    const other = cacheKey('address', ['polygon', '0xabc']);
+    expect(evm).not.toBe(other);
+  });
+
+  it('is stable for the same inputs', () => {
+    expect(cacheKey('token', ['sui', '0x2::sui::SUI'])).toBe(cacheKey('token', ['sui', '0x2::sui::SUI']));
+  });
+});

package/src/cache.ts

@@ -0,0 +1,87 @@
+/**
+ * A small TTL cache with a bounded size.
+ *
+ * Wallets call `screenAddress` on the same handful of addresses constantly —
+ * the token they always trade, the exchange they always withdraw to, the
+ * router every swap goes through. Serving those from memory is the difference
+ * between a signing screen that appears instantly and one that flashes a
+ * spinner every time.
+ *
+ * Two deliberate limits:
+ *
+ *  - **Bounded.** A long-lived extension background page would otherwise grow
+ *    without end. Eviction is oldest-first, which is right for this shape of
+ *    traffic and costs nothing to maintain.
+ *  - **Short.** Threat intelligence changes. A cached "no critical risk"
+ *    entry that outlives the discovery of a drainer is worse than no cache,
+ *    so the default TTL is measured in minutes, not hours.
+ */
+
+interface Entry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+export interface CacheOptions {
+  ttlMs: number;
+  maxEntries: number;
+  now?: () => number;
+}
+
+export class TtlCache<T> {
+  private readonly entries = new Map<string, Entry<T>>();
+  private readonly now: () => number;
+
+  constructor(private readonly options: CacheOptions) {
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.entries.get(key);
+    if (!entry) return undefined;
+
+    if (entry.expiresAt <= this.now()) {
+      this.entries.delete(key);
+      return undefined;
+    }
+
+    // Re-insert so recency ordering reflects use, not just insertion.
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: T, ttlMs = this.options.ttlMs): void {
+    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: string): void {
+    this.entries.delete(key);
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+}
+
+/**
+ * Cache keys are built from the request, never from a hash of a stringified
+ * object: two subjects that differ only in a field the key forgot would
+ * otherwise share an assessment, and one of them would be wrong.
+ */
+export function cacheKey(kind: string, parts: Array<string | number | undefined | null>): string {
+  return [kind, ...parts.map((p) => (p === undefined || p === null ? '' : String(p)))].join('|');
+}

package/src/classify.test.ts

@@ -0,0 +1,294 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_POLICY, applyPolicy, classify, unavailableAssessment } from './classify';
+import { isAtLeast, type Evidence, type ThreatSignal } from './model';
+
+/**
+ * The non-negotiable cases.
+ *
+ * These encode the product's central claim — **unknown is neutral, risk
+ * requires evidence** — and they are written to fail loudly if anyone ever
+ * "improves" the model by scoring newness, thin liquidity or a missing audit.
+ * That change would be easy to make, would look like a security improvement,
+ * and would quietly turn Decentrys into a gatekeeper that taxes every new
+ * project while protecting incumbents.
+ */
+
+const NOW = new Date('2026-09-06T00:00:00Z');
+
+function evidence(overrides: Partial<Evidence> = {}): Evidence {
+  return {
+    id: 'ev_1', type: 'BYTECODE_MATCH', source: 'Decentrys',
+    observedAt: NOW.toISOString(), confidence: 0.99, analystVerified: false,
+    ...overrides,
+  };
+}
+
+function signal(overrides: Partial<ThreatSignal> = {}): ThreatSignal {
+  return {
+    type: 'KNOWN_DRAINER_BYTECODE', severity: 'CRITICAL', confidence: 0.99,
+    explanation: 'Bytecode matches a confirmed drainer family.', hops: 0,
+    evidence: [evidence()], status: 'ACTIVE',
+    createdAt: NOW.toISOString(), lastSeen: NOW.toISOString(),
+    ...overrides,
+  };
+}
+
+// --- 1 ----------------------------------------------------------------------
+
+describe('TEST 1 — a new token with no malicious indicators', () => {
+  it('is not high risk', () => {
+    const result = classify({
+      now: NOW,
+      historyStatus: 'LIMITED',
+      facts: [
+        { type: 'CONTRACT_AGE_HOURS', value: 2, statement: 'Deployed 2 hours ago.', source: 'chain', observedAt: NOW.toISOString() },
+        { type: 'SOURCE_VERIFIED', value: true, statement: 'Source code is verified.', source: 'explorer', observedAt: NOW.toISOString() },
+      ],
+      capabilities: [
+        { type: 'MINT_AUTHORITY_ACTIVE', severity: 'INFO', statement: 'The owner can mint additional supply.' },
+      ],
+      threatSignals: [],
+    });
+
+    expect(isAtLeast(result.riskLevel, 'ELEVATED_RISK')).toBe(false);
+    expect(result.confirmedMalicious).toBe(false);
+    expect(result.riskLevel).toBe('INFORMATIONAL');
+  });
+
+  it('does not let two hours of age contribute to technical risk', () => {
+    const young = classify({ now: NOW, historyStatus: 'NONE', facts: [
+      { type: 'CONTRACT_AGE_HOURS', value: 2, statement: 'Deployed 2 hours ago.', source: 'chain', observedAt: NOW.toISOString() },
+    ] });
+    const old = classify({ now: NOW, historyStatus: 'ESTABLISHED', facts: [
+      { type: 'CONTRACT_AGE_HOURS', value: 40_000, statement: 'Deployed 4 years ago.', source: 'chain', observedAt: NOW.toISOString() },
+    ] });
+
+    // Age changes what we KNOW, never what we ACCUSE.
+    expect(young.components.technicalRisk).toBe(old.components.technicalRisk);
+    expect(young.riskLevel).toBe(old.riskLevel);
+    expect(young.components.historyConfidence).toBeLessThan(old.components.historyConfidence);
+  });
+
+  it('states limited history as a fact about our coverage, not a warning', () => {
+    const result = classify({ now: NOW, historyStatus: 'LIMITED' });
+    expect(result.explanation.join(' ')).toMatch(/not a risk finding/i);
+  });
+});
+
+// --- 2 ----------------------------------------------------------------------
+
+describe('TEST 2 — a new anonymous project with a valid contract', () => {
+  it('is not malicious', () => {
+    const result = classify({
+      now: NOW,
+      historyStatus: 'LIMITED',
+      facts: [
+        { type: 'DEPLOYER_HISTORY', value: 'LIMITED', statement: 'The deployer has little prior activity.', source: 'chain', observedAt: NOW.toISOString() },
+        { type: 'TEAM_IDENTIFIED', value: false, statement: 'No public team identity was located.', source: 'osint', observedAt: NOW.toISOString() },
+      ],
+      unknowns: [
+        { field: 'ownership', reason: 'UNKNOWN', statement: 'Project ownership could not be determined.' },
+      ],
+    });
+
+    expect(result.confirmedMalicious).toBe(false);
+    expect(isAtLeast(result.riskLevel, 'CAUTION')).toBe(false);
+    expect(result.components.threatIntelligenceRisk).toBe(0);
+  });
+
+  it('says the unknown is unknown rather than converting it to risk', () => {
+    const result = classify({
+      now: NOW,
+      unknowns: [{ field: 'ownership', reason: 'UNKNOWN', statement: 'Ownership unknown.' }],
+    });
+    expect(result.explanation.join(' ')).toMatch(/does not contribute to risk/i);
+  });
+});
+
+// --- 3 ----------------------------------------------------------------------
+
+describe('TEST 3 — a low-liquidity token', () => {
+  it('reports liquidity as a fact and nothing more', () => {
+    const result = classify({
+      now: NOW,
+      historyStatus: 'LIMITED',
+      facts: [
+        { type: 'LIQUIDITY_USD', value: 1200, statement: 'Pool liquidity is $1,200.', source: 'dex', observedAt: NOW.toISOString() },
+        { type: 'HOLDER_CONCENTRATION', value: 0.92, statement: 'The top holder holds 92% of supply.', source: 'chain', observedAt: NOW.toISOString() },
+      ],
+    });
+
+    expect(isAtLeast(result.riskLevel, 'CAUTION')).toBe(false);
+    expect(result.confirmedMalicious).toBe(false);
+    // The facts are still surfaced — objectivity is not silence.
+    expect(result.facts).toHaveLength(2);
+  });
+});
+
+// --- 4 ----------------------------------------------------------------------
+
+describe('TEST 4 — no audit found', () => {
+  it('records the audit status without raising risk', () => {
+    const withAudit = classify({
+      now: NOW, historyStatus: 'MODERATE',
+      facts: [{ type: 'AUDIT_STATUS', value: 'FOUND', statement: 'An audit was located.', source: 'registry', observedAt: NOW.toISOString() }],
+    });
+    const without = classify({
+      now: NOW, historyStatus: 'MODERATE',
+      facts: [{ type: 'AUDIT_STATUS', value: 'NONE_FOUND', statement: 'No audit was located.', source: 'registry', observedAt: NOW.toISOString() }],
+    });
+
+    expect(without.riskLevel).toBe(withAudit.riskLevel);
+    expect(without.components.technicalRisk).toBe(withAudit.components.technicalRisk);
+  });
+});
+
+// --- 5 ----------------------------------------------------------------------
+
+describe('TEST 5 — a known drainer contract', () => {
+  it('reaches KNOWN_MALICIOUS when an analyst has verified the evidence', () => {
+    const result = classify({
+      now: NOW,
+      threatSignals: [signal({ evidence: [evidence({ analystVerified: true })] })],
+    });
+
+    expect(result.riskLevel).toBe('KNOWN_MALICIOUS');
+    expect(result.confirmedMalicious).toBe(true);
+    expect(result.threatSignals[0].evidence[0].id).toBe('ev_1');
+    expect(result.explanation.join(' ')).toMatch(/verified by an analyst/i);
+  });
+
+  it('stops at CRITICAL_THREAT without analyst verification', () => {
+    // The accusation is the one output that needs a human behind it.
+    const result = classify({ now: NOW, threatSignals: [signal({ evidence: [evidence({ analystVerified: false })] })] });
+
+    expect(result.riskLevel).toBe('CRITICAL_THREAT');
+    expect(result.confirmedMalicious).toBe(false);
+  });
+
+  it('never reaches KNOWN_MALICIOUS from an absence of reputation', () => {
+    const result = classify({
+      now: NOW, historyStatus: 'NONE',
+      facts: [{ type: 'LISTED_ON_EXCHANGES', value: false, statement: 'Not listed on any major exchange.', source: 'registry', observedAt: NOW.toISOString() }],
+    });
+    expect(result.riskLevel).not.toBe('KNOWN_MALICIOUS');
+    expect(result.confirmedMalicious).toBe(false);
+  });
+});
+
+// --- 6 ----------------------------------------------------------------------
+
+describe('TEST 6 — direct stolen-fund exposure', () => {
+  it('raises risk and carries the transaction provenance', () => {
+    const result = classify({
+      now: NOW,
+      threatSignals: [signal({
+        type: 'STOLEN_FUNDS_DIRECT', severity: 'HIGH', hops: 0, confidence: 0.94,
+        explanation: 'Received assets directly from a wallet attributed to incident INC-2026-0012.',
+        evidence: [evidence({ type: 'INCIDENT_ATTRIBUTION', txHash: '0xabc', analystVerified: true })],
+      })],
+    });
+
+    expect(isAtLeast(result.riskLevel, 'ELEVATED_RISK')).toBe(true);
+    expect(result.threatSignals[0].evidence[0].txHash).toBe('0xabc');
+    expect(result.components.behavioralRisk).toBeGreaterThan(0);
+  });
+});
+
+// --- 7 ----------------------------------------------------------------------
+
+describe('TEST 7 — an indirect, low-confidence association', () => {
+  it('reports it with its confidence and does not treat it as proven', () => {
+    const result = classify({
+      now: NOW,
+      threatSignals: [signal({
+        type: 'MIXER_INDIRECT', severity: 'MEDIUM', hops: 4, confidence: 0.31,
+        explanation: 'Four hops from an address labelled as a mixing service.',
+      })],
+    });
+
+    // Present, visible, and explicitly not sufficient on its own.
+    expect(result.threatSignals).toHaveLength(1);
+    expect(result.confirmedMalicious).toBe(false);
+    expect(isAtLeast(result.riskLevel, 'ELEVATED_RISK')).toBe(false);
+    expect(result.explanation.join(' ')).toMatch(/too low\s+to raise the risk level/i);
+  });
+
+  it('decays a distant signal in the intelligence component', () => {
+    const direct = classify({ now: NOW, threatSignals: [signal({ severity: 'HIGH', hops: 0, confidence: 0.8 })] });
+    const distant = classify({ now: NOW, threatSignals: [signal({ severity: 'HIGH', hops: 4, confidence: 0.8 })] });
+
+    expect(distant.components.threatIntelligenceRisk)
+      .toBeLessThan(direct.components.threatIntelligenceRisk);
+  });
+});
+
+// --- decay, policy, availability -------------------------------------------
+
+describe('temporal decay', () => {
+  it('will not let an expired signal raise the level', () => {
+    const result = classify({
+      now: NOW,
+      threatSignals: [signal({ expiresAt: '2024-01-01T00:00:00Z' })],
+    });
+
+    expect(result.threatSignals[0].status).toBe('STALE');
+    expect(result.riskLevel).not.toBe('CRITICAL_THREAT');
+    // Still reported. Suppressing it would hide a real past observation.
+    expect(result.explanation.join(' ')).toMatch(/stale/i);
+  });
+
+  it('keeps a disputed signal visible but inert', () => {
+    const result = classify({ now: NOW, threatSignals: [signal({ status: 'DISPUTED_FACT' })] });
+    expect(result.riskLevel).not.toBe('CRITICAL_THREAT');
+    expect(result.threatSignals).toHaveLength(1);
+  });
+});
+
+describe('policy', () => {
+  it('blocks only what is confirmed malicious by default', () => {
+    // Transparency over blocking: the decision belongs to whoever holds the keys.
+    expect(DEFAULT_POLICY.KNOWN_MALICIOUS).toBe('block');
+    expect(DEFAULT_POLICY.CRITICAL_THREAT).toBe('require_confirmation');
+    expect(DEFAULT_POLICY.CAUTION).toBe('warn');
+    expect(DEFAULT_POLICY.INFORMATIONAL).toBe('inform');
+  });
+
+  it('lets an integrator be stricter without changing the assessment', () => {
+    const assessment = classify({ now: NOW, threatSignals: [signal({ severity: 'HIGH', confidence: 0.8 })] });
+    const institutional = applyPolicy(assessment, { ELEVATED_RISK: 'block' });
+
+    expect(institutional.action).toBe('block');
+    expect(assessment.riskLevel).toBe('ELEVATED_RISK');
+  });
+
+  it('always gives a reason with the action', () => {
+    const assessment = classify({ now: NOW, historyStatus: 'LIMITED' });
+    expect(applyPolicy(assessment).reason.length).toBeGreaterThan(0);
+  });
+});
+
+describe('when Decentrys is unreachable', () => {
+  it('says nothing was checked rather than implying safety', () => {
+    const result = unavailableAssessment('warn', 'timeout', NOW);
+
+    expect(result.confidence).toBe(0);
+    expect(result.unknowns[0].reason).toBe('PROVIDER_UNAVAILABLE');
+    expect(result.explanation.join(' ')).toMatch(/no security check was performed/i);
+    // Critically, it does not claim the subject is fine.
+    expect(result.confirmedMalicious).toBe(false);
+  });
+});
+
+describe('explainability', () => {
+  it('never returns a classification with no explanation', () => {
+    for (const input of [
+      {},
+      { historyStatus: 'ESTABLISHED' as const },
+      { threatSignals: [signal()] },
+      { capabilities: [{ type: 'PAUSE', severity: 'SIGNIFICANT' as const, statement: 'Transfers can be paused.' }] },
+    ]) {
+      expect(classify({ ...input, now: NOW }).explanation.length).toBeGreaterThan(0);
+    }
+  });
+});