@decentrys/protect 0.1.0

package/src/wire.ts

@@ -0,0 +1,321 @@
+/**
+ * The wire contract, and the boundary that defends the rule.
+ *
+ * Decentrys sends **evidence**, not a verdict. The SDK classifies locally with
+ * `classify()`. That is not a stylistic choice — it has two consequences that
+ * matter:
+ *
+ *  - An integrator can audit exactly why a level was reached, in code they can
+ *    read, without trusting a remote score.
+ *  - The rule is enforced on the client, where it cannot be undone by a server
+ *    change, a proxy, or a future endpoint written by someone who has not read
+ *    the model.
+ *
+ * That last point is concrete rather than theoretical. Decentrys also operates
+ * an AML engine for exchanges and custodians, and in *that* product a new
+ * address legitimately raises a score — money-laundering typologies genuinely
+ * care about freshly created accounts, and regulators expect it to be flagged.
+ * The same signal reaching a consumer wallet unchanged would tax every new
+ * project on earth. So the boundary below refuses coverage signals no matter
+ * who sends them, and turns them into what they actually are: history.
+ */
+
+import type {
+  Evidence, FactValue, HistoryStatus, ObservedFact, SignalStatus, TechnicalCapability,
+  ThreatSeverity, ThreatSignal, UnknownField, UnknownReason,
+} from './model';
+
+export type SubjectKind = 'address' | 'contract' | 'token' | 'transaction' | 'approval' | 'dapp';
+
+export interface SubjectRef {
+  kind: SubjectKind;
+  chain: string;
+  identifier: string;
+}
+
+/** What every Protect endpoint returns. Evidence in, classification local. */
+export interface EvidencePayload {
+  subject: SubjectRef;
+  facts: ObservedFact[];
+  capabilities: TechnicalCapability[];
+  threatSignals: ThreatSignal[];
+  unknowns: UnknownField[];
+  historyStatus: HistoryStatus;
+  historyConfidence?: number;
+  producedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Coverage signals — never threat signals
+// ---------------------------------------------------------------------------
+
+/**
+ * Signal types that describe how much *we* know, not how dangerous a subject
+ * is. If one arrives as a threat signal it is demoted to a fact and its
+ * explanation is preserved, so nothing is hidden — it simply stops being able
+ * to raise a risk level.
+ *
+ * Every entry here is a real signal name used somewhere in the industry, and
+ * several are emitted by Decentrys' own AML engine.
+ */
+export const COVERAGE_SIGNAL_TYPES = 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',
+]);
+
+/**
+ * The coverage signals that say there is *no* record at all, as opposed to a
+ * thin one. Used only when the server sent no `historyStatus`: without this,
+ * demoting the signal would throw away the one thing it told us, and a subject
+ * we know nothing about would be reported as merely thinly covered.
+ */
+const NO_HISTORY_TYPES = new Set(['NO_HISTORY', 'UNKNOWN_TOKEN']);
+
+export interface NormalizedEvidence extends EvidencePayload {
+  /** Signals demoted at the boundary, kept so an integrator can see it happen. */
+  demotedSignals: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Defensive normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce an untrusted payload into the model's shape.
+ *
+ * A wallet must not crash because a field arrived as a number instead of a
+ * string, or because a proxy inserted something. Anything unusable is dropped
+ * rather than guessed at, and a dropped item is simply absent — never
+ * converted into a finding.
+ */
+export function normalizeEvidence(raw: unknown, fallback: SubjectRef): NormalizedEvidence {
+  const body = isRecord(raw) ? raw : {};
+  const demotedSignals: string[] = [];
+
+  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: ThreatSignal[] = [];
+  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);
+  }
+
+  // LIMITED is the neutral default, and deliberately so: it is the correct
+  // state for anything recently deployed and carries no accusation.
+  const declaredHistory = asHistoryStatus(body.historyStatus);
+  const historyStatus: HistoryStatus = declaredHistory ?? (noHistoryObserved ? 'NONE' : 'LIMITED');
+
+  return {
+    subject: toSubject(body.subject, fallback),
+    facts,
+    capabilities,
+    threatSignals,
+    unknowns,
+    historyStatus,
+    historyConfidence: asNumber(body.historyConfidence) ?? undefined,
+    producedAt: asString(body.producedAt) ?? new Date().toISOString(),
+    demotedSignals,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Field coercion
+// ---------------------------------------------------------------------------
+
+function toSubject(raw: unknown, fallback: SubjectRef): SubjectRef {
+  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: unknown): ObservedFact | null {
+  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) ?? new Date().toISOString(),
+  };
+}
+
+function toCapability(raw: unknown): TechnicalCapability | null {
+  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) ?? undefined,
+  };
+}
+
+function toSignal(raw: unknown): ThreatSignal | null {
+  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) ?? 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) ?? undefined,
+  };
+}
+
+function toEvidence(raw: unknown): Evidence | null {
+  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) ?? undefined,
+    txHash: asString(raw.txHash) ?? undefined,
+    contract: asString(raw.contract) ?? undefined,
+    address: asString(raw.address) ?? undefined,
+    observedAt: asString(raw.observedAt) ?? 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 : undefined,
+  };
+}
+
+function toUnknown(raw: unknown): UnknownField | null {
+  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: UnknownReason[] = ['UNKNOWN', 'INSUFFICIENT_DATA', 'PROVIDER_UNAVAILABLE', 'NOT_APPLICABLE'];
+  return {
+    field,
+    reason: reasons.includes(reason as UnknownReason) ? (reason as UnknownReason) : 'UNKNOWN',
+    statement,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function asFactValue(value: unknown): FactValue {
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  return null;
+}
+
+function asSeverity(value: unknown): ThreatSeverity {
+  const severities: ThreatSeverity[] = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+  return severities.includes(value as ThreatSeverity) ? (value as ThreatSeverity) : 'LOW';
+}
+
+function asSignalStatus(value: unknown): SignalStatus {
+  const statuses: SignalStatus[] = ['ACTIVE', 'STALE', 'RESOLVED', 'DISPUTED_FACT', 'REMOVED'];
+  return statuses.includes(value as SignalStatus) ? (value as SignalStatus) : 'ACTIVE';
+}
+
+function asHistoryStatus(value: unknown): HistoryStatus | null {
+  const statuses: HistoryStatus[] = ['ESTABLISHED', 'MODERATE', 'LIMITED', 'NONE'];
+  return statuses.includes(value as HistoryStatus) ? (value as HistoryStatus) : null;
+}
+
+function isSubjectKind(value: string | null): value is SubjectKind {
+  return value === 'address' || value === 'contract' || value === 'token'
+    || value === 'transaction' || value === 'approval' || value === 'dapp';
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+function isPresent<T>(value: T | null): value is T {
+  return value !== null;
+}