@discretion/core 0.1.0

package/src/detect/runner.ts

@@ -0,0 +1,187 @@
+/**
+ * The Stage 1 runner: executes registered detectors over normalized text and
+ * emits candidates carrying both normalized and original-text offsets.
+ *
+ * Three responsibilities, none of which belong in individual detectors:
+ *
+ *  1. OFFSET RESOLUTION. Detectors match against normalized text; masking
+ *     edits the original. Every candidate is resolved through
+ *     `mapNormalizedSpan` here, once, so no detector can get it wrong.
+ *
+ *  2. CONFIDENCE ENFORCEMENT. SPEC.md's rule that "a pattern match without
+ *     validation is at most low confidence" is applied mechanically rather
+ *     than trusted to 145 separate authors.
+ *
+ *  3. FAIL-CLOSED ERROR HANDLING. SPEC.md non-negotiable #2: "If detection
+ *     errors, exceeds its time budget … BLOCK the send." The runner therefore
+ *     never swallows a detector exception and never returns partial results
+ *     on timeout — it throws, and the caller blocks.
+ *
+ * Overlap between candidates is NOT resolved here. SPEC.md assigns that to
+ * Stage 4 fusion ("Resolve overlapping candidates: prefer the more specific
+ * type, then higher calibrated confidence, then longer span"), which needs
+ * calibrated scores this stage cannot produce.
+ */
+
+import type { NormalizationResult } from '../types.js';
+import { mapNormalizedSpan } from '../offsetMap.js';
+import { allDetectors, detectorsForRegion } from './registry.js';
+import { CONFIDENCE } from './types.js';
+import type { ContextSignal, Detector, RegionCode, Stage1Candidate, ValidationContext } from './types.js';
+
+/** Thrown when detection exceeds its time budget. Callers must fail closed. */
+export class DetectionTimeoutError extends Error {
+  constructor(
+    readonly budgetMs: number,
+    readonly elapsedMs: number,
+  ) {
+    super(`Stage 1 detection exceeded its ${budgetMs}ms budget (took ${elapsedMs}ms).`);
+    this.name = 'DetectionTimeoutError';
+  }
+}
+
+/** Thrown when a detector itself throws. Names the detector; never the value. */
+export class DetectorError extends Error {
+  constructor(
+    readonly detectorId: string,
+    override readonly cause: unknown,
+  ) {
+    super(`Detector "${detectorId}" threw during validation.`);
+    this.name = 'DetectorError';
+  }
+}
+
+export interface Stage1Options {
+  /**
+   * Restrict to detectors applicable to this region, plus all GLOBAL ones.
+   * Omit to run every detector, which is the right default — a user pasting a
+   * foreign colleague's identifier still deserves protection.
+   */
+  readonly region?: RegionCode;
+  /** The user's default region, passed to validators for ambiguous formats
+   *  such as phone numbers. */
+  readonly defaultRegion?: RegionCode;
+  /** Explicit detector set, overriding the registry. For focused tests. */
+  readonly detectors?: readonly Detector[];
+  /** Wall-clock budget in milliseconds. Exceeding it throws. */
+  readonly budgetMs?: number;
+  /** Stage 3 evidence, per candidate span. Absent until M7. */
+  readonly contextFor?: (start: number, end: number) => ContextSignal | undefined;
+}
+
+/**
+ * Run Stage 1 over an already-normalized text.
+ *
+ * Takes the whole `NormalizationResult` rather than a bare string because the
+ * offset map is not optional: a candidate without a correct original-text span
+ * cannot be masked, and accepting a string would let a caller forget it.
+ */
+export function runStage1(
+  normalization: NormalizationResult,
+  options: Stage1Options = {},
+): Stage1Candidate[] {
+  const { normalizedText, offsetMap } = normalization;
+  const detectors =
+    options.detectors ?? (options.region === undefined ? allDetectors() : detectorsForRegion(options.region));
+
+  const started = Date.now();
+  const candidates: Stage1Candidate[] = [];
+
+  for (const detector of detectors) {
+    if (options.budgetMs !== undefined) {
+      const elapsed = Date.now() - started;
+      if (elapsed > options.budgetMs) throw new DetectionTimeoutError(options.budgetMs, elapsed);
+    }
+    collectFrom(detector, normalizedText, offsetMap, options, candidates);
+  }
+
+  return candidates;
+}
+
+/** Run one detector over the text, appending every surviving candidate. */
+function collectFrom(
+  detector: Detector,
+  text: string,
+  offsetMap: Int32Array,
+  options: Stage1Options,
+  out: Stage1Candidate[],
+): void {
+  // Clone the pattern so `lastIndex` is never shared between scans. Module-
+  // scope /g regexes that keep state across calls are a classic source of
+  // intermittent, order-dependent misses.
+  const pattern = new RegExp(detector.pattern.source, detector.pattern.flags);
+  pattern.lastIndex = 0;
+
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(text)) !== null) {
+    // A zero-length match would spin forever; step past it.
+    if (match[0].length === 0) {
+      pattern.lastIndex += 1;
+      continue;
+    }
+
+    const matchStart = match.index;
+    const matchEnd = matchStart + match[0].length;
+
+    const context = options.contextFor?.(matchStart, matchEnd);
+    const ctx: ValidationContext = {
+      text,
+      start: matchStart,
+      end: matchEnd,
+      match,
+      ...(options.defaultRegion !== undefined ? { defaultRegion: options.defaultRegion } : {}),
+      ...(context !== undefined ? { context } : {}),
+    };
+
+    let result;
+    try {
+      result = detector.validate(ctx);
+    } catch (cause) {
+      // Fail closed: surface the fault rather than dropping the candidate and
+      // reporting a clean scan of text that was never fully examined.
+      throw new DetectorError(detector.id, cause);
+    }
+
+    if (!result.valid) continue;
+
+    // A validator may narrow the span to exclude anchoring context that the
+    // pattern needed but which must not be masked.
+    const start = result.span?.start ?? matchStart;
+    const end = result.span?.end ?? matchEnd;
+    if (!(start >= 0 && start < end && end <= text.length)) {
+      throw new DetectorError(
+        detector.id,
+        new Error(`validator returned an out-of-range span [${start}, ${end}) for text of length ${text.length}`),
+      );
+    }
+
+    const original = mapNormalizedSpan(offsetMap, start, end);
+
+    let confidence = result.confidence ?? detector.baseConfidence;
+    // SPEC.md: detectors that "require context boost" cannot exceed low
+    // confidence until Stage 3 supplies the signal. This is what stops
+    // GENERIC_SECRET from firing on entropy alone.
+    if (detector.requiresContext === true && context === undefined) {
+      confidence = Math.min(confidence, CONFIDENCE.LOW);
+    }
+    confidence = Math.min(Math.max(confidence, 0), 1);
+
+    const matchedText = text.slice(start, end);
+
+    out.push({
+      text: matchedText,
+      type: detector.entityType,
+      start,
+      end,
+      originalStart: original.start,
+      originalEnd: original.end,
+      rawConfidence: confidence,
+      stage: 'stage1-validated-identifier',
+      detectorId: detector.id,
+      sensitive: result.sensitive ?? true,
+      canonical: result.canonical ?? matchedText,
+      ...(result.metadata !== undefined ? { metadata: result.metadata } : {}),
+      ...(result.validator !== undefined ? { validatorPassed: result.validator } : {}),
+    });
+  }
+}

package/src/detect/types.ts

@@ -0,0 +1,296 @@
+/**
+ * The Stage 1 detector contract.
+ *
+ * SPEC.md, Stage 1: "Structure this as a registry: each detector declares its
+ * id, entity type, supported regions, candidate pattern, validator function,
+ * and base confidence. Adding a new national identifier must require touching
+ * exactly one new file."
+ *
+ * That last sentence is the design constraint everything here answers to.
+ * A new detector is one file that builds a `Detector` object and calls
+ * `registerDetector`. It does not edit a union type (EntityType models
+ * national identifiers as families precisely so it never has to — see
+ * ARCHITECTURE.md D4), a central list, or this file.
+ *
+ * THE CENTRAL RULE. SPEC.md: "Regex is only the candidate generator.
+ * Emission at high confidence requires passing a validator. A pattern match
+ * without validation is at most low confidence." The runner enforces this
+ * mechanically rather than trusting each detector to remember it: a detector
+ * cannot emit above `CONFIDENCE.LOW` unless its validator returned success,
+ * and one that declares `requiresContext` cannot exceed `CONFIDENCE.LOW` at
+ * all until Stage 3 supplies the missing signal.
+ */
+
+import type { EntityType } from '../types.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Confidence
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Named confidence levels shared by every detector.
+ *
+ * These are RAW, detector-local scores, not calibrated probabilities. Stage 4
+ * calibrates them against the eval corpus so that 0.8 empirically means ~80%
+ * precision; until then they are only meaningfully ordered, not absolute.
+ * Detectors use these constants rather than bare numbers so that recalibrating
+ * the scale is one edit here instead of a sweep across 145 files.
+ */
+export const CONFIDENCE = {
+  /** A pattern matched but nothing corroborates it. The ceiling for an
+   *  unvalidated match, and for anything awaiting a Stage 3 context signal. */
+  LOW: 0.3,
+  /** A structural check passed, but the format is weak enough that false
+   *  positives are expected (short identifiers, no checksum). */
+  MEDIUM: 0.6,
+  /** A real checksum or structural validator passed. The normal ceiling. */
+  HIGH: 0.85,
+  /** Reserved for formats that are self-verifying to the point that a false
+   *  positive is implausible — SPEC.md names a valid passport MRZ, "every
+   *  field is checksummed; treat a valid MRZ as maximum confidence". */
+  MAXIMUM: 0.99,
+} as const;
+
+export type ConfidenceLevel = (typeof CONFIDENCE)[keyof typeof CONFIDENCE];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Regions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * An ISO 3166-1 alpha-2 country code, or `GLOBAL` for detectors that are not
+ * jurisdiction-specific (email, IP address, JWT, credit card).
+ *
+ * Kept as a widened string rather than a closed union so adding a country
+ * genuinely touches one file. The registry validates the shape at
+ * registration time.
+ */
+export type RegionCode = string;
+
+/** The sentinel region for detectors that apply everywhere. */
+export const GLOBAL_REGION = 'GLOBAL';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context (Stage 3 hook)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Evidence from a candidate's surroundings.
+ *
+ * Stage 3 does not exist yet (it arrives in M7), so this is always `undefined`
+ * during M2. It is defined now, and threaded through `ValidationContext`, so
+ * that detectors which SPEC.md says "require context boost" —
+ * GENERIC_SECRET, POSTAL_CODE, STREET_ADDRESS — can be written once with
+ * their context branch in place, rather than being rewritten when Stage 3
+ * lands.
+ *
+ * SPEC.md on GENERIC_SECRET: "Require a Shannon entropy threshold AND an
+ * assignment-context signal (see Stage 3)". The entropy half is implemented
+ * in M2; `assignment` below is the half that stays dormant.
+ */
+export interface ContextSignal {
+  /** A nearby label matched a trigger lexicon entry ("SSN:", "IBAN", "kimlik"). */
+  readonly trigger?: string;
+  /** The candidate sits on the value side of an assignment or key-value pair
+   *  (`api_key = …`, a JSON key, a .env line, a CSV column header). */
+  readonly assignment?: boolean;
+  /** Negative evidence: documentation example, test fixture, lorem ipsum,
+   *  a UUID in a log line. Actively suppresses rather than merely failing to
+   *  boost. */
+  readonly negative?: boolean;
+  /** Detected document type, which shifts weights (code raises secret
+   *  sensitivity and lowers person-name sensitivity). */
+  readonly documentType?: string;
+}
+
+/**
+ * What a validator is given alongside the matched text.
+ *
+ * Carries the surrounding text because several validators genuinely need it:
+ * a passport MRZ spans multiple lines and must look at its siblings, and an
+ * IP address must know whether it is inside a URL.
+ */
+export interface ValidationContext {
+  /** The full normalized text the runner is scanning. */
+  readonly text: string;
+  /** Start offset of the match within `text` (inclusive). */
+  readonly start: number;
+  /** End offset of the match within `text` (exclusive). */
+  readonly end: number;
+  /** The regex match that produced this candidate, including capture groups. */
+  readonly match: RegExpExecArray;
+  /** The user's configured default region, used for ambiguous formats such as
+   *  phone numbers. `undefined` when unset. */
+  readonly defaultRegion?: RegionCode;
+  /** Stage 3 evidence. Always `undefined` in M2. */
+  readonly context?: ContextSignal;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation results
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The match is not an instance of this entity type. It is not emitted. */
+export interface ValidationFailure {
+  readonly valid: false;
+  /** Why it failed, for eval error analysis. Never contains the value itself. */
+  readonly reason: string;
+}
+
+/** The match is an instance of this entity type. */
+export interface ValidationSuccess {
+  readonly valid: true;
+  /**
+   * Confidence for this specific match, overriding the detector's
+   * `baseConfidence`. Use when one detector's certainty varies by case — a
+   * public/reserved IP range is a weaker signal than a routable address.
+   */
+  readonly confidence?: number;
+  /**
+   * Canonical form of the value: separators stripped, case normalized. Later
+   * milestones key the vault on this so that `4111 1111 1111 1111` and
+   * `4111-1111-1111-1111` resolve to one entry.
+   */
+  readonly canonical?: string;
+  /**
+   * Whether this value is actually sensitive.
+   *
+   * SPEC.md requires known test values to be "matched but classified as
+   * non-sensitive" — the documentation IBAN GB82WEST…, the Visa test card
+   * 4111…, reserved example domains. They are detected so the eval corpus can
+   * assert they were seen, and marked non-sensitive so they are never masked.
+   * Defaults to `true`.
+   */
+  readonly sensitive?: boolean;
+  /**
+   * Scheme details for Stage 4 fusion and M4 substitution. For a national
+   * identifier this carries the concrete scheme and country, which is how the
+   * family design stays extensible: `{ scheme: 'tckn', country: 'TR' }`.
+   */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /**
+   * Name of the validator that passed, surfaced in `EntityExplanation
+   * .validatorPassed`. SPEC.md: every emitted entity carries an explanation
+   * of "which validator passed".
+   */
+  readonly validator?: string;
+  /**
+   * Narrow the span to a sub-range of the regex match, in offsets relative to
+   * the full scanned text. Patterns often need leading context to anchor
+   * (a label, a delimiter) that must not be masked along with the value.
+   */
+  readonly span?: { readonly start: number; readonly end: number };
+}
+
+export type ValidationResult = ValidationSuccess | ValidationFailure;
+
+/** Convenience constructor for the common failure case. */
+export function invalid(reason: string): ValidationFailure {
+  return { valid: false, reason };
+}
+
+/** Convenience constructor for the common success case. */
+export function valid(fields: Omit<ValidationSuccess, 'valid'> = {}): ValidationSuccess {
+  return { valid: true, ...fields };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The detector
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface Detector {
+  /**
+   * Stable, unique, kebab-case identifier — `"national-id-tr-tckn"`,
+   * `"credit-card"`, `"iban"`. Appears in `Candidate.detectorId`, in eval
+   * error analysis, and in regression-gate config, so it must not churn.
+   */
+  readonly id: string;
+
+  /** The entity type emitted. For national schemes this is the FAMILY
+   *  (`NATIONAL_ID`), with the concrete scheme carried in metadata. */
+  readonly entityType: EntityType;
+
+  /** Jurisdictions this detector applies to, or `[GLOBAL_REGION]`. */
+  readonly regions: readonly RegionCode[];
+
+  /**
+   * The candidate generator. Must carry the `g` flag; the runner never
+   * mutates it, cloning per scan so a shared `lastIndex` cannot leak state
+   * between calls — a notorious source of intermittent misses with `/g`
+   * regexes held at module scope.
+   *
+   * Patterns should over-generate. Precision is the validator's job.
+   */
+  readonly pattern: RegExp;
+
+  /**
+   * Confidence when the validator passes and no per-match confidence is
+   * returned. The runner clamps this to `CONFIDENCE.LOW` when
+   * `requiresContext` is set and no context signal is present.
+   */
+  readonly baseConfidence: number;
+
+  /**
+   * Decide whether a match is genuinely an instance of `entityType`.
+   *
+   * Detectors with a real checksum return failure for a wrong checksum, and
+   * the candidate is dropped — a mistyped SSN is not a low-confidence SSN, it
+   * is not an SSN. Detectors for formats with no checksum (drivers' licences,
+   * postal codes) return success at a low confidence instead.
+   */
+  validate(ctx: ValidationContext): ValidationResult;
+
+  /**
+   * This detector cannot reach its base confidence without Stage 3 evidence.
+   *
+   * SPEC.md marks GENERIC_SECRET, POSTAL_CODE and STREET_ADDRESS this way.
+   * Until Stage 3 exists the runner caps them at `CONFIDENCE.LOW`, which is
+   * what keeps GENERIC_SECRET from "firing on entropy alone".
+   */
+  readonly requiresContext?: boolean;
+
+  /**
+   * Human-readable description, shown in the options UI's per-entity toggles
+   * and in eval reports.
+   */
+  readonly description: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Runner output
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A Stage 1 candidate, extending the shared `Candidate` with the original-text
+ * span.
+ *
+ * `Candidate.start`/`end` are offsets into the NORMALIZED text, which is the
+ * M1 contract every offset-map invariant is written against. Substitution
+ * however edits the ORIGINAL text, so the runner resolves both up front via
+ * `mapNormalizedSpan` and carries them together. Recorded as ARCHITECTURE.md
+ * D7: the alternative — redefining `Candidate.start` to mean original offsets
+ * — would silently invalidate the M1 offset-map tests.
+ */
+export interface Stage1Candidate {
+  readonly text: string;
+  readonly type: EntityType;
+  /** Start offset in the NORMALIZED text (inclusive). */
+  readonly start: number;
+  /** End offset in the NORMALIZED text (exclusive). */
+  readonly end: number;
+  /** Start offset in the ORIGINAL text (inclusive), via the Stage 0 map. */
+  readonly originalStart: number;
+  /** End offset in the ORIGINAL text (exclusive), via the Stage 0 map. */
+  readonly originalEnd: number;
+  readonly rawConfidence: number;
+  readonly stage: 'stage1-validated-identifier';
+  readonly detectorId: string;
+  /** False for known test/documentation values, which are detected but must
+   *  never be masked. */
+  readonly sensitive: boolean;
+  /** Canonical form, separators stripped and case normalized. */
+  readonly canonical: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /** Which validator passed, for the entity explanation. */
+  readonly validatorPassed?: string;
+}

package/src/encoding/base58.ts

@@ -0,0 +1,85 @@
+/**
+ * Base58 and base58check (Bitcoin alphabet).
+ *
+ * Decoding goes through BigInt — short inputs, validation-only, and the
+ * arithmetic formulation is obviously faithful to the definition. Leading
+ * '1' characters map to leading zero bytes, which matters: the Bitcoin
+ * genesis address starts with one.
+ */
+
+import { sha256d } from '../crypto/sha256.js';
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+const VALUES: ReadonlyMap<string, bigint> = new Map(
+  [...ALPHABET].map((ch, i) => [ch, BigInt(i)]),
+);
+
+/** Decode base58 to bytes; null on any non-alphabet character. */
+export function base58Decode(s: string): Uint8Array | null {
+  if (s.length === 0) return null;
+  let acc = 0n;
+  for (const ch of s) {
+    const v = VALUES.get(ch);
+    if (v === undefined) return null;
+    acc = acc * 58n + v;
+  }
+  const body: number[] = [];
+  while (acc > 0n) {
+    body.push(Number(acc & 0xffn));
+    acc >>= 8n;
+  }
+  body.reverse();
+  let leadingZeros = 0;
+  for (const ch of s) {
+    if (ch !== '1') break;
+    leadingZeros++;
+  }
+  return Uint8Array.from([...new Array<number>(leadingZeros).fill(0), ...body]);
+}
+
+/** Encode bytes as base58. */
+export function base58Encode(bytes: Uint8Array): string {
+  let acc = 0n;
+  for (const b of bytes) acc = (acc << 8n) | BigInt(b);
+  let out = '';
+  while (acc > 0n) {
+    out = ALPHABET[Number(acc % 58n)]! + out;
+    acc /= 58n;
+  }
+  for (const b of bytes) {
+    if (b !== 0) break;
+    out = '1' + out;
+  }
+  return out;
+}
+
+export interface Base58CheckResult {
+  /** The version byte. */
+  readonly version: number;
+  /** Payload between the version byte and the checksum. */
+  readonly payload: Uint8Array;
+}
+
+/**
+ * Decode and verify a base58check string: version ‖ payload ‖ first four
+ * bytes of SHA-256d(version ‖ payload). Null when the checksum fails.
+ */
+export function base58CheckDecode(s: string): Base58CheckResult | null {
+  const bytes = base58Decode(s);
+  if (bytes === null || bytes.length < 5) return null;
+  const body = bytes.slice(0, bytes.length - 4);
+  const checksum = bytes.slice(bytes.length - 4);
+  const expected = sha256d(body);
+  for (let i = 0; i < 4; i++) {
+    if (checksum[i] !== expected[i]) return null;
+  }
+  return { version: body[0]!, payload: body.slice(1) };
+}
+
+/** Encode version ‖ payload with its base58check checksum. */
+export function base58CheckEncode(version: number, payload: Uint8Array): string {
+  const body = Uint8Array.from([version, ...payload]);
+  const checksum = sha256d(body).slice(0, 4);
+  return base58Encode(Uint8Array.from([...body, ...checksum]));
+}

package/src/encoding/base58monero.ts

@@ -0,0 +1,90 @@
+/**
+ * Monero's base58 variant.
+ *
+ * Monero does NOT use Bitcoin's stream base58: it encodes fixed 8-byte
+ * blocks as exactly 11 characters (padding with the alphabet's zero, '1'),
+ * with a shorter final block whose decoded size is determined by its
+ * encoded length. The alphabet itself is Bitcoin's. A standard address is
+ * 95 characters = 8 full blocks + one 7-character tail, decoding to 69
+ * bytes: network byte ‖ two 32-byte keys ‖ 4-byte Keccak-256 checksum.
+ */
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const VALUES: ReadonlyMap<string, bigint> = new Map(
+  [...ALPHABET].map((ch, i) => [ch, BigInt(i)]),
+);
+
+const FULL_ENCODED = 11;
+const FULL_DECODED = 8;
+
+/** decoded byte count for a partial block, indexed by encoded length. */
+const PARTIAL_DECODED: readonly (number | null)[] = [
+  0, null, 1, 2, 3, 4, null, 5, 6, 7, null,
+];
+
+function decodeBlock(block: string, decodedSize: number): Uint8Array | null {
+  let acc = 0n;
+  for (const ch of block) {
+    const v = VALUES.get(ch);
+    if (v === undefined) return null;
+    acc = acc * 58n + v;
+  }
+  const max = 1n << BigInt(8 * decodedSize);
+  if (acc >= max) return null; // overflows the declared block size
+  const out = new Uint8Array(decodedSize);
+  for (let i = decodedSize - 1; i >= 0; i--) {
+    out[i] = Number(acc & 0xffn);
+    acc >>= 8n;
+  }
+  return out;
+}
+
+/** Decode a Monero base58 string to bytes; null on malformed input. */
+export function moneroBase58Decode(s: string): Uint8Array | null {
+  if (s.length === 0) return null;
+  const fullBlocks = Math.floor(s.length / FULL_ENCODED);
+  const tailLength = s.length % FULL_ENCODED;
+  const tailDecoded = PARTIAL_DECODED[tailLength];
+  if (tailDecoded === null || tailDecoded === undefined) return null;
+
+  const out = new Uint8Array(fullBlocks * FULL_DECODED + tailDecoded);
+  for (let i = 0; i < fullBlocks; i++) {
+    const block = decodeBlock(s.slice(i * FULL_ENCODED, (i + 1) * FULL_ENCODED), FULL_DECODED);
+    if (block === null) return null;
+    out.set(block, i * FULL_DECODED);
+  }
+  if (tailLength > 0) {
+    const block = decodeBlock(s.slice(fullBlocks * FULL_ENCODED), tailDecoded);
+    if (block === null) return null;
+    out.set(block, fullBlocks * FULL_DECODED);
+  }
+  return out;
+}
+
+/** Encoded char count for a partial block, indexed by decoded length. */
+const PARTIAL_ENCODED: readonly number[] = [0, 2, 3, 5, 6, 7, 9, 10];
+
+function encodeBlock(bytes: Uint8Array, encodedSize: number): string {
+  let acc = 0n;
+  for (const b of bytes) acc = (acc << 8n) | BigInt(b);
+  let out = '';
+  for (let i = 0; i < encodedSize; i++) {
+    out = ALPHABET[Number(acc % 58n)]! + out;
+    acc /= 58n;
+  }
+  return out;
+}
+
+/** Encode bytes in Monero's block-wise base58. */
+export function moneroBase58Encode(bytes: Uint8Array): string {
+  const fullBlocks = Math.floor(bytes.length / FULL_DECODED);
+  const tail = bytes.length % FULL_DECODED;
+  let out = '';
+  for (let i = 0; i < fullBlocks; i++) {
+    out += encodeBlock(bytes.slice(i * FULL_DECODED, (i + 1) * FULL_DECODED), FULL_ENCODED);
+  }
+  if (tail > 0) {
+    out += encodeBlock(bytes.slice(fullBlocks * FULL_DECODED), PARTIAL_ENCODED[tail]!);
+  }
+  return out;
+}