@decentrys/protect 0.1.0

package/src/simulation.ts

@@ -0,0 +1,71 @@
+/**
+ * Simulation and plain-language decoding.
+ *
+ * These answer a different question from risk. "Is this dangerous?" is the
+ * classifier's job; "what does this transaction actually do?" is this one's,
+ * and for most users it is the more useful of the two. A person who can read
+ * "this grants unlimited spending of your USDC to an address you have never
+ * interacted with" does not need to be told a score.
+ */
+
+export interface BalanceChange {
+  /** Whose balance moves. Usually the signer, sometimes a contract. */
+  address: string;
+  asset: string;
+  symbol?: string;
+  decimals?: number;
+  /** Signed, base units. Negative leaves the address. */
+  delta: string;
+  usdValue?: number;
+}
+
+export interface ApprovalChange {
+  owner: string;
+  spender: string;
+  token: string;
+  symbol?: string;
+  /** Base units, or `unlimited`. */
+  amount: string;
+  unlimited: boolean;
+}
+
+export type SimulationOutcome = 'SUCCESS' | 'REVERT' | 'NOT_SUPPORTED' | 'UNAVAILABLE';
+
+export interface SimulationResult {
+  outcome: SimulationOutcome;
+  /** Present when the outcome is REVERT and the chain reported a reason. */
+  revertReason?: string;
+  balanceChanges: BalanceChange[];
+  approvalChanges: ApprovalChange[];
+  /** Contracts the transaction touches, in call order. */
+  contractsCalled: string[];
+  gasUsed?: string;
+  /**
+   * Why simulation could not run, when it could not. Stated rather than
+   * silently returning an empty result that reads like "nothing happens".
+   */
+  unavailableReason?: string;
+  simulatedAt: string;
+}
+
+export interface TransactionExplanation {
+  /** One sentence, in the words a user would use. */
+  summary: string;
+  /** Each distinct thing the transaction does, in order. */
+  actions: string[];
+  /** What the signer gives up if this is not what they intended. */
+  exposure: string[];
+  /** Anything the decoder could not resolve, stated as unresolved. */
+  undecoded: string[];
+}
+
+export function unavailableSimulation(reason: string, now = new Date()): SimulationResult {
+  return {
+    outcome: 'UNAVAILABLE',
+    balanceChanges: [],
+    approvalChanges: [],
+    contractsCalled: [],
+    unavailableReason: reason,
+    simulatedAt: now.toISOString(),
+  };
+}

package/src/transport.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it, vi } from 'vitest';
+import { HttpTransport, TransportError, joinUrl, type FetchLike } from './transport';
+
+function transport(fetchImpl: FetchLike, overrides: Partial<{ timeoutMs: number; retries: number }> = {}) {
+  return new HttpTransport({
+    baseUrl: 'https://api.test/',
+    apiKey: 'key',
+    timeoutMs: overrides.timeoutMs ?? 1_000,
+    retries: overrides.retries ?? 1,
+    fetch: fetchImpl,
+    userAgent: 'test',
+  });
+}
+
+function ok(body: unknown): ReturnType<FetchLike> {
+  return Promise.resolve({ ok: true, status: 200, text: () => Promise.resolve(JSON.stringify(body)) });
+}
+
+function fail(status: number, body: unknown = {}): ReturnType<FetchLike> {
+  return Promise.resolve({ ok: false, status, text: () => Promise.resolve(JSON.stringify(body)) });
+}
+
+describe('HttpTransport', () => {
+  it('unwraps the platform envelope', async () => {
+    const t = transport(() => ok({ data: { subject: 'x' } }));
+    await expect(t.request({ path: '/p' })).resolves.toEqual({ subject: 'x' });
+  });
+
+  it('accepts a bare body, for integrators behind a proxy that unwraps', async () => {
+    const t = transport(() => ok({ subject: 'x' }));
+    await expect(t.request({ path: '/p' })).resolves.toEqual({ subject: 'x' });
+  });
+
+  it('retries an idempotent request once on a server error', async () => {
+    const fetchImpl = vi.fn<FetchLike>()
+      .mockImplementationOnce(() => fail(503))
+      .mockImplementationOnce(() => ok({ data: 'recovered' }));
+
+    await expect(transport(fetchImpl).request({ path: '/p', idempotent: true })).resolves.toBe('recovered');
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not retry a non-idempotent request', async () => {
+    const fetchImpl = vi.fn<FetchLike>().mockImplementation(() => fail(503));
+
+    await expect(transport(fetchImpl).request({ path: '/p' })).rejects.toBeInstanceOf(TransportError);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  /**
+   * A 4xx will say the same thing the second time. Retrying it only makes the
+   * user wait longer for the same failure.
+   */
+  it('never retries a 4xx, even when idempotent', async () => {
+    const fetchImpl = vi.fn<FetchLike>().mockImplementation(() => fail(401, { message: 'Invalid API key.' }));
+
+    const error = await transport(fetchImpl)
+      .request({ path: '/p', idempotent: true })
+      .catch((e: unknown) => e);
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(error).toBeInstanceOf(TransportError);
+    expect((error as TransportError).failure).toBe('unauthorized');
+    expect((error as TransportError).message).toBe('Invalid API key.');
+  });
+
+  it('reports a rate limit as retryable', async () => {
+    const fetchImpl = vi.fn<FetchLike>()
+      .mockImplementationOnce(() => fail(429))
+      .mockImplementationOnce(() => ok({ data: 'ok' }));
+
+    await expect(transport(fetchImpl).request({ path: '/p', idempotent: true })).resolves.toBe('ok');
+  });
+
+  it('gives up at the deadline rather than hanging a signing screen', async () => {
+    const fetchImpl: FetchLike = (_url, init) => new Promise((_resolve, reject) => {
+      init.signal?.addEventListener('abort', () => {
+        reject(Object.assign(new Error('aborted'), { name: 'AbortError' }));
+      });
+    });
+
+    const error = await transport(fetchImpl, { timeoutMs: 20, retries: 0 })
+      .request({ path: '/p' })
+      .catch((e: unknown) => e);
+
+    expect((error as TransportError).failure).toBe('timeout');
+  });
+
+  it('distinguishes a caller cancellation from a timeout', async () => {
+    const controller = new AbortController();
+    const fetchImpl: FetchLike = (_url, init) => new Promise((_resolve, reject) => {
+      init.signal?.addEventListener('abort', () => {
+        reject(Object.assign(new Error('aborted'), { name: 'AbortError' }));
+      });
+      controller.abort();
+    });
+
+    const error = await transport(fetchImpl, { retries: 0 })
+      .request({ path: '/p', signal: controller.signal })
+      .catch((e: unknown) => e);
+
+    expect((error as TransportError).failure).toBe('network');
+    expect((error as TransportError).message).toContain('cancelled');
+  });
+
+  it('treats an unparseable body as malformed, not as an empty result', async () => {
+    const t = transport(() => Promise.resolve({ ok: true, status: 200, text: () => Promise.resolve('<html>502</html>') }));
+
+    const error = await t.request({ path: '/p' }).catch((e: unknown) => e);
+    expect((error as TransportError).failure).toBe('malformed_response');
+  });
+
+  it('sends the API key as a header and never in the URL', async () => {
+    const fetchImpl = vi.fn<FetchLike>().mockImplementation(() => ok({ data: null }));
+    await transport(fetchImpl).request({ path: 'p' });
+
+    const [url, init] = fetchImpl.mock.calls[0]!;
+    expect(url).toBe('https://api.test/p');
+    expect(url).not.toContain('key');
+    expect(init.headers['x-api-key']).toBe('key');
+  });
+});
+
+describe('joinUrl', () => {
+  it('collapses slashes from either side', () => {
+    expect(joinUrl('https://a.test/', '/b')).toBe('https://a.test/b');
+    expect(joinUrl('https://a.test', 'b')).toBe('https://a.test/b');
+  });
+});

package/src/transport.ts

@@ -0,0 +1,203 @@
+/**
+ * HTTP transport for the Protect SDK.
+ *
+ * Three properties matter more than anything else here, because this code runs
+ * inside a wallet on the path to signing a transaction:
+ *
+ *  1. **It always returns.** A hung request is worse than a failed one — the
+ *     user is staring at a spinner holding a signature. Every request carries
+ *     a deadline it cannot exceed.
+ *  2. **It never retries a write.** Retrying an idempotent lookup is free;
+ *     retrying anything else risks doing the thing twice.
+ *  3. **It has no ambient dependencies.** `fetch` is injected rather than
+ *     reached for, so the same code runs in a browser extension, React Native,
+ *     a Node service and a test without a global to patch.
+ */
+
+export type FetchLike = (
+  url: string,
+  init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+  },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  text: () => Promise<string>;
+}>;
+
+export type TransportFailure =
+  | 'timeout'
+  | 'network'
+  | 'unauthorized'
+  | 'forbidden'
+  | 'rate_limited'
+  | 'invalid_request'
+  | 'server_error'
+  | 'malformed_response';
+
+export class TransportError extends Error {
+  readonly failure: TransportFailure;
+  readonly status?: number;
+
+  constructor(failure: TransportFailure, message: string, status?: number) {
+    super(message);
+    this.name = 'TransportError';
+    this.failure = failure;
+    this.status = status;
+  }
+}
+
+export interface RequestOptions {
+  path: string;
+  body?: unknown;
+  /**
+   * Safe to repeat. Only idempotent requests are retried; everything else
+   * fails on the first attempt rather than risking a duplicate.
+   */
+  idempotent?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface TransportConfig {
+  baseUrl: string;
+  apiKey: string;
+  timeoutMs: number;
+  /** Retries for idempotent requests only. 0 disables retrying entirely. */
+  retries: number;
+  fetch: FetchLike;
+  userAgent: string;
+}
+
+export interface Transport {
+  request<T>(options: RequestOptions): Promise<T>;
+}
+
+/** 4xx that will never succeed on a repeat. Retrying these only adds latency. */
+function failureForStatus(status: number): TransportFailure {
+  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';
+}
+
+const RETRYABLE: TransportFailure[] = ['network', 'timeout', 'server_error', 'rate_limited'];
+
+export class HttpTransport implements Transport {
+  constructor(private readonly config: TransportConfig) {}
+
+  async request<T>(options: RequestOptions): Promise<T> {
+    const attempts = options.idempotent ? this.config.retries + 1 : 1;
+    let last: TransportError = new TransportError('network', 'No attempt was made.');
+
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      try {
+        return await this.attempt<T>(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;
+
+        // A short, bounded backoff. Anything longer defeats the point: the
+        // user is waiting on a signing screen, not a batch job.
+        await delay(120 * (attempt + 1));
+      }
+    }
+
+    throw last;
+  }
+
+  private async attempt<T>(options: RequestOptions): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+    // The caller's own cancellation (the user navigated away, the popup
+    // closed) has to reach the request too, or it keeps running after the
+    // screen that wanted it is gone.
+    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: unknown;
+      try {
+        parsed = JSON.parse(text) as unknown;
+      } catch {
+        throw new TransportError('malformed_response', 'The response was not valid JSON.');
+      }
+
+      // The platform wraps every successful body as `{ data: ... }`. Accepting
+      // a bare body too keeps the SDK usable against a proxy that unwraps it.
+      const envelope = parsed as { data?: unknown };
+      return (envelope && typeof envelope === 'object' && 'data' in envelope
+        ? envelope.data
+        : parsed) as T;
+    } 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: unknown): boolean {
+  return (
+    typeof error === 'object'
+    && error !== null
+    && ((error as { name?: string }).name === 'AbortError'
+      || (error as { code?: string }).code === 'ABORT_ERR')
+  );
+}
+
+/** Surface the API's own message when it sent one; it is better than ours. */
+function messageFrom(text: string): string | null {
+  try {
+    const body = JSON.parse(text) as { message?: unknown; error?: unknown };
+    if (typeof body.message === 'string' && body.message.trim()) return body.message;
+    if (typeof body.error === 'string' && body.error.trim()) return body.error;
+  } catch {
+    // Not JSON. Nothing to surface.
+  }
+  return null;
+}
+
+export function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}

package/src/wire.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeEvidence } from './wire';
+import { classify } from './classify';
+import type { SubjectRef } from './wire';
+
+const SUBJECT: SubjectRef = { kind: 'address', chain: 'ethereum', identifier: '0xabc' };
+
+describe('normalizeEvidence — the coverage boundary', () => {
+  /**
+   * The case this boundary exists for.
+   *
+   * Decentrys' own AML engine emits NEW_ADDRESS with a positive weight, which
+   * is correct for a custodian screening for laundering typologies and wrong
+   * for a consumer wallet. If that signal reached the classifier unchanged,
+   * every newly deployed project on earth would be taxed for being new.
+   */
+  it('demotes NEW_ADDRESS to a fact and refuses to let it raise a level', () => {
+    const evidence = normalizeEvidence({
+      threatSignals: [{
+        type: 'NEW_ADDRESS',
+        severity: 'MEDIUM',
+        confidence: 0.9,
+        explanation: 'Address first seen 2 day(s) ago with 3 transactions.',
+        hops: 0,
+        evidence: [],
+        status: 'ACTIVE',
+        createdAt: '2026-09-01T00:00:00.000Z',
+      }],
+    }, SUBJECT);
+
+    expect(evidence.threatSignals).toHaveLength(0);
+    expect(evidence.demotedSignals).toEqual(['NEW_ADDRESS']);
+
+    // Nothing is hidden — the explanation survives as a fact.
+    expect(evidence.facts[0]?.statement).toContain('first seen 2 day(s) ago');
+
+    const assessment = classify(evidence);
+    expect(assessment.riskLevel).toBe('INFORMATIONAL');
+    expect(assessment.components.behavioralRisk).toBe(0);
+  });
+
+  it.each([
+    'NO_AUDIT', 'ANONYMOUS_DEPLOYER', 'LOW_LIQUIDITY',
+    'HOLDER_CONCENTRATION', 'UNVERIFIED_SOURCE', 'NOT_ON_TOKEN_LIST',
+  ])('demotes %s however severe the sender claimed it was', (type) => {
+    const evidence = normalizeEvidence({
+      threatSignals: [{
+        type,
+        severity: 'CRITICAL',
+        confidence: 1,
+        explanation: `${type} observed.`,
+        hops: 0,
+        evidence: [],
+        status: 'ACTIVE',
+        createdAt: '2026-09-01T00:00:00.000Z',
+      }],
+    }, SUBJECT);
+
+    expect(evidence.threatSignals).toHaveLength(0);
+    expect(classify(evidence).riskLevel).toBe('INFORMATIONAL');
+  });
+
+  it('lets a genuine threat signal through untouched', () => {
+    const evidence = normalizeEvidence({
+      threatSignals: [{
+        type: 'DRAINER_INFRASTRUCTURE',
+        severity: 'CRITICAL',
+        confidence: 0.9,
+        explanation: 'This contract matches deployed wallet-drainer bytecode.',
+        hops: 0,
+        evidence: [{
+          id: 'ev-1', type: 'BYTECODE_MATCH', source: 'decentrys',
+          observedAt: '2026-09-01T00:00:00.000Z', confidence: 0.9, analystVerified: true,
+        }],
+        status: 'ACTIVE',
+        createdAt: '2026-09-01T00:00:00.000Z',
+      }],
+    }, SUBJECT);
+
+    expect(evidence.threatSignals).toHaveLength(1);
+    expect(evidence.demotedSignals).toHaveLength(0);
+  });
+});
+
+describe('normalizeEvidence — defensive coercion', () => {
+  it('survives a payload that is not an object at all', () => {
+    const evidence = normalizeEvidence('nonsense', SUBJECT);
+    expect(evidence.subject).toEqual(SUBJECT);
+    expect(evidence.threatSignals).toHaveLength(0);
+    expect(classify(evidence).riskLevel).toBe('NO_CRITICAL_RISK_DETECTED');
+  });
+
+  it('drops entries missing the fields that give them meaning', () => {
+    const evidence = normalizeEvidence({
+      facts: [{ type: 'deployed' }, null, 42, { type: 'age', statement: 'Deployed 3 days ago.' }],
+      threatSignals: [{ severity: 'CRITICAL' }],
+      capabilities: [{ type: 'mint' }],
+    }, SUBJECT);
+
+    expect(evidence.facts).toHaveLength(1);
+    expect(evidence.threatSignals).toHaveLength(0);
+    expect(evidence.capabilities).toHaveLength(0);
+  });
+
+  /**
+   * `analystVerified` is the single gate on KNOWN_MALICIOUS — the one output
+   * that is a public accusation. An absent field must never read as a human
+   * having checked.
+   */
+  it('treats absent analystVerified as false', () => {
+    const evidence = normalizeEvidence({
+      threatSignals: [{
+        type: 'CONFIRMED_DRAINER', severity: 'CRITICAL', confidence: 1,
+        explanation: 'Drainer.', hops: 0, status: 'ACTIVE',
+        createdAt: '2026-09-01T00:00:00.000Z',
+        evidence: [{ id: 'e', type: 'REPORT', confidence: 1 }],
+      }],
+    }, SUBJECT);
+
+    expect(evidence.threatSignals[0]!.evidence[0]!.analystVerified).toBe(false);
+    expect(classify(evidence).confirmedMalicious).toBe(false);
+  });
+
+  it('clamps a confidence sent outside 0–1', () => {
+    const evidence = normalizeEvidence({
+      threatSignals: [{
+        type: 'X', severity: 'HIGH', confidence: 7, explanation: 'x', hops: 0,
+        evidence: [], status: 'ACTIVE', createdAt: '2026-09-01T00:00:00.000Z',
+      }],
+    }, SUBJECT);
+
+    expect(evidence.threatSignals[0]!.confidence).toBe(1);
+  });
+
+  /**
+   * An unknown distance is an inference, not a direct observation, so a
+   * missing hop count must not default to 0 — that would present a remote
+   * association as something seen on the subject itself.
+   */
+  it('defaults a missing hop count to an inference, not a direct observation', () => {
+    const evidence = normalizeEvidence({
+      threatSignals: [{
+        type: 'X', severity: 'HIGH', confidence: 0.8, explanation: 'x',
+        evidence: [], status: 'ACTIVE', createdAt: '2026-09-01T00:00:00.000Z',
+      }],
+    }, SUBJECT);
+
+    expect(evidence.threatSignals[0]!.hops).toBe(1);
+  });
+
+  it('defaults an unrecognised capability severity down, never up', () => {
+    const evidence = normalizeEvidence({
+      capabilities: [{ type: 'mint', severity: 'APOCALYPTIC', statement: 'Can mint.' }],
+    }, SUBJECT);
+
+    expect(evidence.capabilities[0]!.severity).toBe('INFO');
+  });
+
+  it('reports NO_HISTORY as none and everything else as limited', () => {
+    const none = normalizeEvidence({
+      threatSignals: [{
+        type: 'NO_HISTORY', severity: 'LOW', confidence: 0.5,
+        explanation: 'Nothing on chain.', hops: 0, evidence: [],
+        status: 'ACTIVE', createdAt: '2026-09-01T00:00:00.000Z',
+      }],
+    }, SUBJECT);
+    expect(none.historyStatus).toBe('NONE');
+
+    expect(normalizeEvidence({}, SUBJECT).historyStatus).toBe('LIMITED');
+    expect(normalizeEvidence({ historyStatus: 'ESTABLISHED' }, SUBJECT).historyStatus).toBe('ESTABLISHED');
+  });
+});