@discretion/core 0.1.0

package/src/detect/detectors/contact/ipv6.ts

@@ -0,0 +1,188 @@
+/**
+ * IP_ADDRESS (IPv6) — full parse with compression, zone ids and v4-mapped
+ * tails, plus scope classification.
+ *
+ * The candidate pattern is deliberately loose — hex-and-colon runs are easy
+ * to over-match and hard to precisely match with one regex (compressed
+ * forms, embedded IPv4, zones). Precision comes from `parseIpv6`, a strict
+ * parser that either produces exactly eight 16-bit groups or rejects. Times
+ * ("12:30:45"), MACs ("aa:bb:cc:dd:ee:ff") and C++ scope operators
+ * ("std::vector") all fail the parse or the pattern's look-arounds.
+ *
+ * The all-zero address `::` is rejected outright rather than classified:
+ * a bare double colon appears in too many non-address contexts to report.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+type Ipv6Scope =
+  | 'global'
+  | 'loopback'
+  | 'link-local'
+  | 'unique-local'
+  | 'multicast'
+  | 'documentation'
+  | 'v4-mapped'
+  | '6to4';
+
+interface ParsedIpv6 {
+  readonly groups: readonly number[];
+  readonly zone?: string;
+}
+
+/** Strict parse to eight groups, or null. */
+function parseIpv6(input: string): ParsedIpv6 | null {
+  let s = input;
+  let zone: string | undefined;
+
+  const pct = s.indexOf('%');
+  if (pct >= 0) {
+    zone = s.slice(pct + 1);
+    s = s.slice(0, pct);
+    if (zone.length === 0) return null;
+  }
+
+  // Embedded IPv4 tail → two trailing hex groups.
+  let v4Groups: number[] | null = null;
+  if (s.includes('.')) {
+    const lastColon = s.lastIndexOf(':');
+    if (lastColon < 0) return null;
+    const tail = s.slice(lastColon + 1);
+    const parts = tail.split('.');
+    if (parts.length !== 4) return null;
+    const octets: number[] = [];
+    for (const p of parts) {
+      if (!/^\d{1,3}$/.test(p)) return null;
+      const v = Number(p);
+      if (v > 255) return null;
+      octets.push(v);
+    }
+    v4Groups = [(octets[0]! << 8) | octets[1]!, (octets[2]! << 8) | octets[3]!];
+    s = s.slice(0, lastColon + 1); // keep the colon: "::ffff:" stays parseable
+  }
+
+  const splitGroups = (part: string): number[] | null => {
+    if (part === '') return [];
+    const out: number[] = [];
+    for (const g of part.split(':')) {
+      if (!/^[0-9A-Fa-f]{1,4}$/.test(g)) return null;
+      out.push(parseInt(g, 16));
+    }
+    return out;
+  };
+
+  let groups: number[];
+  const compressionIndex = s.indexOf('::');
+  if (compressionIndex >= 0) {
+    if (s.indexOf('::', compressionIndex + 1) >= 0) return null; // two '::'
+    let head = s.slice(0, compressionIndex);
+    let tail = s.slice(compressionIndex + 2);
+    if (head.endsWith(':')) head = head.slice(0, -1);
+    if (tail.endsWith(':')) tail = tail.slice(0, -1);
+    const headGroups = splitGroups(head);
+    const tailGroups = splitGroups(tail);
+    if (headGroups === null || tailGroups === null) return null;
+    const tailAll = v4Groups === null ? tailGroups : [...tailGroups, ...v4Groups];
+    const fixed = headGroups.length + tailAll.length;
+    if (fixed > 7) return null; // '::' must compress at least one group
+    groups = [...headGroups, ...new Array<number>(8 - fixed).fill(0), ...tailAll];
+  } else {
+    let body = s;
+    if (v4Groups !== null) {
+      if (!body.endsWith(':')) return null;
+      body = body.slice(0, -1);
+    }
+    const parsed = splitGroups(body);
+    if (parsed === null) return null;
+    const all = v4Groups === null ? parsed : [...parsed, ...v4Groups];
+    if (all.length !== 8) return null;
+    groups = all;
+  }
+
+  return zone === undefined ? { groups } : { groups, zone };
+}
+
+function classify(g: readonly number[]): Ipv6Scope | 'unspecified' {
+  if (g.every((x) => x === 0)) return 'unspecified';
+  if (g.slice(0, 7).every((x) => x === 0) && g[7] === 1) return 'loopback';
+  const g0 = g[0]!;
+  if ((g0 & 0xffc0) === 0xfe80) return 'link-local';
+  if ((g0 & 0xfe00) === 0xfc00) return 'unique-local';
+  if ((g0 & 0xff00) === 0xff00) return 'multicast';
+  if (g0 === 0x2001 && g[1] === 0x0db8) return 'documentation';
+  if (g.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff) return 'v4-mapped';
+  if (g0 === 0x2002) return '6to4';
+  return 'global';
+}
+
+/** RFC 5952 canonical text: lowercase hex, longest zero run compressed. */
+function canonicalIpv6(groups: readonly number[]): string {
+  let bestStart = -1;
+  let bestLen = 0;
+  let i = 0;
+  while (i < 8) {
+    if (groups[i] === 0) {
+      let j = i;
+      while (j < 8 && groups[j] === 0) j++;
+      if (j - i > bestLen) {
+        bestLen = j - i;
+        bestStart = i;
+      }
+      i = j;
+    } else {
+      i++;
+    }
+  }
+  const hex = groups.map((g) => g.toString(16));
+  if (bestLen < 2) return hex.join(':');
+  const head = hex.slice(0, bestStart).join(':');
+  const tail = hex.slice(bestStart + bestLen).join(':');
+  return `${head}::${tail}`;
+}
+
+function validateIpv6(ctx: ValidationContext): ValidationResult {
+  const parsed = parseIpv6(ctx.match[0]);
+  if (parsed === null) return invalid('not a parseable IPv6 address');
+
+  const scope = classify(parsed.groups);
+  if (scope === 'unspecified') return invalid('unspecified address');
+
+  const canonical = canonicalIpv6(parsed.groups);
+
+  if (scope === 'documentation') {
+    return valid({
+      canonical,
+      sensitive: false,
+      confidence: CONFIDENCE.MEDIUM,
+      metadata: { version: 6, scope },
+      validator: 'ipv6-parse',
+    });
+  }
+  const strong = scope === 'global' || scope === '6to4' || scope === 'v4-mapped';
+  return valid({
+    canonical,
+    confidence: strong ? CONFIDENCE.HIGH : scope === 'multicast' ? CONFIDENCE.LOW : CONFIDENCE.MEDIUM,
+    metadata: {
+      version: 6,
+      scope,
+      ...(parsed.zone !== undefined ? { zone: parsed.zone } : {}),
+    },
+    validator: 'ipv6-parse',
+  });
+}
+
+registerDetector({
+  id: 'ip-v6',
+  entityType: 'IP_ADDRESS',
+  regions: [GLOBAL_REGION],
+  // Loose harvest: needs a colon early (two colons total guaranteed by the
+  // parser), hex/colon body, optional v4 tail and zone. Look-arounds keep it
+  // out of words, times and scope operators.
+  pattern:
+    /(?<![\w:.])(?=[0-9A-Fa-f]{0,4}:[0-9A-Fa-f]{0,4}:)[0-9A-Fa-f:]{2,45}(?:\.\d{1,3}(?:\.\d{1,3}){2})?(?:%[0-9A-Za-z._~-]{1,16})?(?![\w:])/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'IPv6 addresses (compressed, zoned, v4-mapped) with strict parsing and scope classification.',
+  validate: validateIpv6,
+});

package/src/detect/detectors/contact/mac.ts

@@ -0,0 +1,68 @@
+/**
+ * MAC_ADDRESS — colon, hyphen and Cisco dotted notations.
+ *
+ * A MAC has no checksum, but its shape — six hex octets with a CONSISTENT
+ * separator, or three dotted quads — is distinctive enough that structural
+ * validation carries high confidence. The separator consistency is enforced
+ * in the pattern via a backreference; mixed separators do not match at all.
+ *
+ * The broadcast (ff:ff:…) and null (00:00:…) addresses are well-known
+ * constants that identify no device: detected, classified non-sensitive,
+ * mirroring SPEC.md's treatment of known test values.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function validateMac(ctx: ValidationContext): ValidationResult {
+  // A six-group run inside a longer separated sequence (an IPv6 address, a
+  // long hex dump) is a fragment, not a MAC. \b cannot see separators.
+  const before = ctx.start >= 2 ? ctx.text.slice(ctx.start - 2, ctx.start) : '';
+  if (/[0-9A-Fa-f][:-]$/.test(before)) return invalid('fragment of a longer sequence');
+  const after = ctx.text.slice(ctx.end, ctx.end + 2);
+  if (/^[:-][0-9A-Fa-f]/.test(after)) return invalid('fragment of a longer sequence');
+
+  const raw = ctx.match[0];
+  const hex = raw.replace(/[^0-9A-Fa-f]/g, '');
+  if (hex.length !== 12) return invalid('not six octets');
+  const bytes: number[] = [];
+  for (let i = 0; i < 12; i += 2) bytes.push(parseInt(hex.slice(i, i + 2), 16));
+
+  const canonical = bytes.map((b) => b.toString(16).padStart(2, '0')).join(':');
+  const notation = raw.includes(':') ? 'colon' : raw.includes('-') ? 'hyphen' : 'cisco-dotted';
+
+  const allFF = bytes.every((b) => b === 0xff);
+  const allZero = bytes.every((b) => b === 0);
+  if (allFF || allZero) {
+    return valid({
+      canonical,
+      sensitive: false,
+      confidence: CONFIDENCE.LOW,
+      metadata: { notation, special: allFF ? 'broadcast' : 'null' },
+      validator: 'mac-structural',
+    });
+  }
+
+  const b0 = bytes[0]!;
+  return valid({
+    canonical,
+    metadata: {
+      notation,
+      multicast: (b0 & 0x01) !== 0,
+      locallyAdministered: (b0 & 0x02) !== 0,
+    },
+    validator: 'mac-structural',
+  });
+}
+
+registerDetector({
+  id: 'mac-address',
+  entityType: 'MAC_ADDRESS',
+  regions: [GLOBAL_REGION],
+  pattern:
+    /\b(?:[0-9A-Fa-f]{2}([:-])(?:[0-9A-Fa-f]{2}\1){4}[0-9A-Fa-f]{2}|[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4})\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'MAC addresses in colon, hyphen, or Cisco dotted notation; broadcast/null non-sensitive.',
+  validate: validateMac,
+});

package/src/detect/detectors/contact/phone.ts

@@ -0,0 +1,81 @@
+/**
+ * PHONE — libphonenumber-js with the FULL metadata bundle.
+ *
+ * SPEC.md: "use libphonenumber-js with the full metadata bundle, not the
+ * minimal one. Never hand-roll phone regex. Parse and validate, with region
+ * inference from surrounding text and a user-set default region."
+ *
+ * The regex below is a candidate harvester only — it collects digit runs with
+ * phone-ish punctuation and hands them to libphonenumber, which is the
+ * validator. Region inference from SURROUNDING TEXT is a Stage 3 concern
+ * (trigger lexicons carry language/region evidence); in M2 the sources of
+ * region are the number's own +prefix or the user's configured default.
+ *
+ * Known false-positive shapes are rejected before parsing: year ranges
+ * ("2019-2023") and calendar dates, both of which are 8-digit runs that
+ * genuinely validate as subscriber numbers in 8-digit national plans
+ * (Denmark's 20 19 20 23 is a real mobile shape). The date guard is cheap
+ * and kills the whole class.
+ */
+
+import { parsePhoneNumberFromString } from 'libphonenumber-js/max';
+import type { CountryCode } from 'libphonenumber-js/max';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+/** "2019-2023", "1999/2001" — year ranges, never phone numbers. */
+const YEAR_RANGE = /^(?:19|20)\d{2}\s?[-/]\s?(?:19|20)\d{2}$/;
+
+/** Calendar dates: 2023-08-26, 26/08/2023, 08.26.23 and friends. */
+const DATE_LIKE = /^(?:\d{4}[-/.]\d{1,2}[-/.]\d{1,4}|\d{1,2}[-/.]\d{1,2}[-/.]\d{2,4})$/;
+
+function validatePhone(ctx: ValidationContext): ValidationResult {
+  const raw = ctx.match[0];
+
+  const trimmed = raw.trim();
+  if (YEAR_RANGE.test(trimmed)) return invalid('year range');
+  if (DATE_LIKE.test(trimmed)) return invalid('date-like');
+
+  const digitCount = raw.replace(/\D/g, '').length;
+  // E.164 caps national significant numbers at 15 digits; anything shorter
+  // than 7 is a short code or fragment we do not report.
+  if (digitCount < 7) return invalid('too few digits');
+  if (digitCount > 16) return invalid('too many digits');
+
+  const hasPlus = trimmed.startsWith('+');
+
+  let parsed;
+  if (hasPlus) {
+    parsed = parsePhoneNumberFromString(trimmed);
+  } else if (ctx.defaultRegion !== undefined) {
+    parsed = parsePhoneNumberFromString(trimmed, ctx.defaultRegion as CountryCode);
+  } else {
+    // A national-format number with no region context cannot be validated,
+    // and emitting unvalidated digit runs is the false-positive machine
+    // SPEC.md forbids. Stage 3's trigger evidence will widen this later.
+    return invalid('national format with no region context');
+  }
+
+  if (parsed === undefined || !parsed.isValid()) return invalid('not a valid number for any plan');
+
+  return valid({
+    canonical: parsed.number,
+    metadata: {
+      ...(parsed.country !== undefined ? { country: parsed.country } : {}),
+      countryCallingCode: parsed.countryCallingCode,
+      viaDefaultRegion: !hasPlus,
+    },
+    validator: 'libphonenumber-isvalid',
+  });
+}
+
+registerDetector({
+  id: 'phone',
+  entityType: 'PHONE',
+  regions: [GLOBAL_REGION],
+  pattern: /[+(]?\d[\d \t()./-]{4,22}\d/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Phone numbers in all international formats, validated by libphonenumber (full metadata).',
+  validate: validatePhone,
+});

package/src/detect/detectors/contact/urlCredentials.ts

@@ -0,0 +1,124 @@
+/**
+ * URL_WITH_CREDENTIALS — userinfo passwords and credential-bearing query
+ * parameters.
+ *
+ * SPEC.md: "URL_WITH_CREDENTIALS — userinfo components or tokens in query
+ * parameters."
+ *
+ * Two shapes, one detector:
+ *   • scheme://user:password@host…      (userinfo with a password)
+ *   • scheme://…?token=…&…              (a credential-named query parameter)
+ *
+ * The emitted span is the WHOLE URL, not just the secret. Masking only the
+ * password would leave "https://admin:…@internal.corp.com" — still leaking
+ * the username and the internal host — and M4's surrogate substitution can
+ * replace a whole URL with a same-shape fake, which it cannot do for a URL
+ * with a hole in it. The credential's location travels in metadata.
+ *
+ * A bare username without a password (git@github.com style) is NOT a
+ * credential; ubiquitous and public. Template placeholders (${VAR},
+ * YOUR_API_KEY) are detected but non-sensitive, mirroring test values.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+/** Parameter names that are credentials whenever they carry a real value. */
+const STRONG_PARAMS = new Set([
+  'token', 'accesstoken', 'authtoken', 'idtoken', 'refreshtoken', 'apitoken', 'sastoken',
+  'apikey', 'secret', 'clientsecret', 'privatekey', 'password', 'passwd', 'pwd',
+  'authorization', 'bearer', 'credential', 'credentials',
+]);
+
+/**
+ * Names too generic to trust alone ("?key=north", "?sig=v2"): the value must
+ * itself look like key material — long and drawn from token alphabets.
+ */
+const WEAK_PARAMS = new Set(['key', 'auth', 'sig', 'signature', 'session', 'sessionid', 'code']);
+
+const WEAK_VALUE_SHAPE = /^[A-Za-z0-9+/_.=~%-]{16,}$/;
+
+/** Obvious template/placeholder values: detected, non-sensitive. */
+function isPlaceholder(value: string): boolean {
+  if (/^\$\{[^}]*\}$/.test(value) || /^\{\{[^}]*\}\}$/.test(value)) return true;
+  if (/^<[^>]*>$/.test(value)) return true;
+  if (/^(?:x+|X+|\*+|\.+)$/.test(value)) return true;
+  if (/^YOUR[_-]/i.test(value) || /[_-]HERE$/i.test(value)) return true;
+  if (/^(?:changeme|placeholder|redacted|example|dummy|sample|test)$/i.test(value)) return true;
+  return false;
+}
+
+/** RFC 2606/6761 documentation hosts → the whole URL is a doc example. */
+function isReservedHost(host: string): boolean {
+  const h = host.toLowerCase().replace(/:\d+$/, '');
+  if (h === 'localhost' || h.endsWith('.localhost')) return true;
+  if (/(^|\.)example\.(com|net|org)$/.test(h)) return true;
+  return /\.(test|invalid|example)$/.test(h);
+}
+
+function validateUrlCredentials(ctx: ValidationContext): ValidationResult {
+  const raw = ctx.match[0];
+  const schemeEnd = raw.indexOf('://');
+  if (schemeEnd < 0) return invalid('no scheme');
+  const rest = raw.slice(schemeEnd + 3);
+
+  // Userinfo form: user:password@host…
+  const slash = rest.search(/[/?#]/);
+  const authority = slash < 0 ? rest : rest.slice(0, slash);
+  const at = authority.lastIndexOf('@');
+  if (at > 0) {
+    const userinfo = authority.slice(0, at);
+    const host = authority.slice(at + 1);
+    const colon = userinfo.indexOf(':');
+    if (colon <= 0 || colon === userinfo.length - 1) {
+      return invalid('userinfo has no password');
+    }
+    const password = userinfo.slice(colon + 1);
+    const placeholder = isPlaceholder(password) || isReservedHost(host);
+    return valid({
+      sensitive: !placeholder,
+      metadata: { kind: 'userinfo', host },
+      validator: 'url-credential-structural',
+    });
+  }
+
+  // Query-parameter form.
+  const paramPattern = /[?&]([A-Za-z0-9_-]+)=([^\s&"'<>]+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = paramPattern.exec(raw)) !== null) {
+    const name = m[1]!.toLowerCase().replace(/[_-]/g, '');
+    const value = m[2]!;
+    const strong = STRONG_PARAMS.has(name);
+    const weak = WEAK_PARAMS.has(name);
+    if (!strong && !weak) continue;
+    if (strong && value.length < 6) continue;
+    if (weak && !WEAK_VALUE_SHAPE.test(value)) continue;
+
+    const host = authority;
+    const placeholder = isPlaceholder(value) || isReservedHost(host);
+    return valid({
+      sensitive: !placeholder,
+      metadata: { kind: 'query', param: m[1]!, host },
+      validator: 'url-credential-structural',
+    });
+  }
+
+  return invalid('no credential-bearing component');
+}
+
+registerDetector({
+  id: 'url-with-credentials',
+  entityType: 'URL_WITH_CREDENTIALS',
+  regions: [GLOBAL_REGION],
+  // Commas and pipes terminate the URI. RFC 3986 permits a comma as a
+  // sub-delimiter, but in the shapes URIs actually appear in — CSV rows,
+  // pipe-delimited logs, markdown table cells — an unencoded one is a FIELD
+  // boundary, and swallowing it made this span eat the neighbouring cells.
+  // That is not merely a mislabelled span: masking OVERWRITES the span, so an
+  // over-long one destroys the user's adjacent data.
+  pattern: /\b[A-Za-z][A-Za-z0-9+.-]{1,15}:\/\/[^\s"'<>,|]{3,700}/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'URLs carrying credentials in userinfo or query parameters; whole-URL span.',
+  validate: validateUrlCredentials,
+});

package/src/detect/detectors/crypto/ada.ts

@@ -0,0 +1,52 @@
+/**
+ * CRYPTO_WALLET: Cardano.
+ *
+ * Shelley addresses ('addr1…') are bech32 with a REAL checksum — verified
+ * here with the length limit raised past BIP-173's 90 characters, which
+ * Cardano exceeds by design — so they earn HIGH. Byron-era addresses
+ * ('Ae2…', 'DdzFF…') wrap their CRC in a CBOR envelope; verifying it would
+ * mean parsing CBOR for a legacy format, so Byron validates structurally
+ * (base58-decodable with the known prefix) at MEDIUM. The asymmetry is
+ * deliberate and stated here rather than hidden.
+ */
+
+import { base58Decode } from '../../../encoding/base58.js';
+import { bech32Decode } from '../../../encoding/bech32.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function validateAda(ctx: ValidationContext): ValidationResult {
+  const raw = ctx.match[0];
+
+  if (raw.toLowerCase().startsWith('addr1')) {
+    const decoded = bech32Decode(raw, 130);
+    if (decoded === null) return invalid('bech32 checksum failed');
+    if (decoded.hrp !== 'addr') return invalid('not the Cardano hrp');
+    return valid({
+      canonical: raw.toLowerCase(),
+      metadata: { chain: 'ada', era: 'shelley' },
+      validator: 'bech32',
+    });
+  }
+
+  const bytes = base58Decode(raw);
+  if (bytes === null) return invalid('not base58');
+  if (bytes.length < 30) return invalid('too short for a Byron address');
+  return valid({
+    canonical: raw,
+    confidence: CONFIDENCE.MEDIUM,
+    metadata: { chain: 'ada', era: 'byron' },
+    validator: 'byron-structural',
+  });
+}
+
+registerDetector({
+  id: 'crypto-ada',
+  entityType: 'CRYPTO_WALLET',
+  regions: [GLOBAL_REGION],
+  pattern: /\b(?:addr1[02-9ac-hj-np-z]{20,110}|(?:Ae2|DdzFF)[1-9A-HJ-NP-Za-km-z]{20,120})\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Cardano addresses: Shelley bech32 checksummed at HIGH, Byron structural at MEDIUM.',
+  validate: validateAda,
+});

package/src/detect/detectors/crypto/btc.ts

@@ -0,0 +1,77 @@
+/**
+ * CRYPTO_WALLET: Bitcoin.
+ *
+ * Three address families, all checksum-verified:
+ *   • base58check version 0x00 (P2PKH, '1…') and 0x05 (P2SH, '3…')
+ *   • bech32 'bc1q…' — segwit v0, program exactly 20 or 32 bytes
+ *   • bech32m 'bc1p…' — segwit v1+ (taproot), program 2–40 bytes
+ * The v0/v1 encoding split is BIP-350's rule: a v0 address closed with
+ * bech32m (or v1 with bech32) is INVALID, not merely unusual.
+ *
+ * The genesis address is treated like a documentation value: it appears in
+ * every Bitcoin tutorial and identifies no user.
+ */
+
+import { base58CheckDecode } from '../../../encoding/base58.js';
+import { bech32Decode, convertBits } from '../../../encoding/bech32.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+const WELL_KNOWN: ReadonlySet<string> = new Set([
+  '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', // genesis block coinbase
+]);
+
+function validateBtc(ctx: ValidationContext): ValidationResult {
+  const raw = ctx.match[0];
+
+  if (raw[0] === '1' || raw[0] === '3') {
+    const decoded = base58CheckDecode(raw);
+    if (decoded === null) return invalid('base58check checksum failed');
+    if (decoded.version !== 0x00 && decoded.version !== 0x05) {
+      return invalid('not a Bitcoin version byte');
+    }
+    if (decoded.payload.length !== 20) return invalid('payload is not a hash160');
+    return valid({
+      canonical: raw,
+      sensitive: !WELL_KNOWN.has(raw),
+      metadata: { chain: 'btc', kind: decoded.version === 0x00 ? 'p2pkh' : 'p2sh' },
+      validator: 'base58check',
+    });
+  }
+
+  const decoded = bech32Decode(raw);
+  if (decoded === null) return invalid('bech32 checksum failed');
+  if (decoded.hrp !== 'bc') return invalid('not the Bitcoin hrp');
+  if (decoded.data.length === 0) return invalid('empty witness data');
+  const version = decoded.data[0]!;
+  if (version > 16) return invalid('witness version out of range');
+  const program = convertBits(decoded.data.slice(1), 5, 8, false);
+  if (program === null || program.length < 2 || program.length > 40) {
+    return invalid('malformed witness program');
+  }
+  if (version === 0) {
+    if (decoded.encoding !== 'bech32') return invalid('segwit v0 requires bech32');
+    if (program.length !== 20 && program.length !== 32) {
+      return invalid('v0 program must be 20 or 32 bytes');
+    }
+  } else if (decoded.encoding !== 'bech32m') {
+    return invalid('segwit v1+ requires bech32m');
+  }
+
+  return valid({
+    canonical: raw.toLowerCase(),
+    metadata: { chain: 'btc', kind: version === 0 ? 'segwit-v0' : `segwit-v${version}` },
+    validator: decoded.encoding,
+  });
+}
+
+registerDetector({
+  id: 'crypto-btc',
+  entityType: 'CRYPTO_WALLET',
+  regions: [GLOBAL_REGION],
+  pattern: /\b(?:[13][1-9A-HJ-NP-Za-km-z]{25,34}|(?:bc1|BC1)[0-9A-Za-z]{11,87})\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Bitcoin addresses: base58check P2PKH/P2SH and BIP-173/350 segwit, all checksummed.',
+  validate: validateBtc,
+});

package/src/detect/detectors/crypto/dot.ts

@@ -0,0 +1,42 @@
+/**
+ * CRYPTO_WALLET: Polkadot.
+ *
+ * SS58 closes with the first two bytes of blake2b-512("SS58PRE" ‖ payload).
+ * Blake2b is not among the bundled hash primitives, and Polkadot would be
+ * its only consumer, so per the recorded decision (ARCHITECTURE.md D9) this
+ * detector validates STRUCTURALLY at MEDIUM: base58 decodes to exactly 35
+ * bytes (1 network + 32 key + 2 checksum) with the Polkadot network byte
+ * 0x00 — which is also why the address always starts with '1'. The checksum
+ * bytes are present but unverified; the confidence cap says so.
+ */
+
+import { base58Decode } from '../../../encoding/base58.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function validateDot(ctx: ValidationContext): ValidationResult {
+  const raw = ctx.match[0];
+  const bytes = base58Decode(raw);
+  if (bytes === null) return invalid('not base58');
+  if (bytes.length !== 35) return invalid('not an SS58 account envelope');
+  if (bytes[0] !== 0x00) return invalid('not the Polkadot network prefix');
+
+  return valid({
+    canonical: raw,
+    metadata: { chain: 'dot', checksum: 'unverified' },
+    validator: 'ss58-structural',
+  });
+}
+
+registerDetector({
+  id: 'crypto-dot',
+  entityType: 'CRYPTO_WALLET',
+  regions: [GLOBAL_REGION],
+  // Network byte 0x00 → leading '1'; 35 bytes → 45–51 chars, disjoint from
+  // the Bitcoin P2PKH length range (26–35) that shares the prefix.
+  pattern: /\b1[1-9A-HJ-NP-Za-km-z]{44,50}\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Polkadot SS58 addresses, structural (blake2b checksum unverified - ARCHITECTURE.md D9).',
+  validate: validateDot,
+});