korea-fixtures 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# korea-fixtures
+
+Deterministic, **checksum-valid-but-fake** Korean test data + validators — for tests, fixtures, and
+demos. Seeded and reproducible. **Zero dependencies.** (`kfix` CLI + a tiny library.)
+
+```bash
+npx kfix gen brn --seed 42 --count 3
+#  332-81-02957
+#  299-85-28847
+#  874-05-50925   (re-run with the same seed -> byte-identical)
+
+npx kfix validate brn 124-81-00997
+#  {"valid":false,"type":"brn","failedCheck":"checkDigit","expected":8,"actual":7}
+```
+
+## Why
+
+Korean developers need *valid-format* test fixtures — 사업자등록번호, 계좌번호, 카드번호 — every day,
+and today they copy-paste checksum gists per identifier. The major fakers don't cover them: Faker
+(`ko_KR`), faker-js (`ko`), and Datafaker (`ko.yml`) ship Korean names but **no business-registration
+number, no account number, no checksums**. This is that missing piece: one seeded package that both
+**generates** correct-by-construction fake identifiers and **validates** them with "which check failed"
+diagnostics — the deterministic, dependency-free shape that CI fixtures want.
+
+The checksum algorithms are pinned against real public entities (Samsung Electronics
+사업자등록번호 `124-81-00998`, 법인등록번호 `130111-0006246`; the Luhn vector `4242…4242`).
+
+## Supported identifiers
+
+| type | generate | validate | check |
+|---|:--:|:--:|---|
+| `brn` — 사업자등록번호 | ✅ | ✅ | weighted mod-10 + half-carry |
+| `corp` — 법인등록번호 | ✅ | ✅ | alternating 1/2 weights, mod-10 |
+| `card` — 카드번호 | ✅ | ✅ | Luhn |
+| `account` — 계좌번호 | ✅ | ✅ | 14 banks, longest-prefix detection (best-effort, no national checksum) |
+| `card` issuers | ✅ | ✅ | 8 Korean issuers, Luhn always correct |
+| `phone` — 휴대폰 | ✅ | ✅ | format (010/011/016-019) |
+| `postal` — 우편번호 | ✅ | ✅ | 5-digit (post-2015), format-only |
+| `plate` — 차량번호 | ✅ | ✅ | 12가3456 / 123가4567, valid plate syllable |
+| `address` — 도로명주소 | ✅ | ✅ | format-only |
+| `rrn` — 주민등록번호 | ❌ **validate-only** | ✅ | mod-11 + date/gender |
+
+> **주민등록번호 generation is intentionally unsupported.** RRNs identify real people; we validate
+> them (typo/format checks) but never fabricate them. That posture is a feature, not a gap.
+
+## Library
+
+```js
+import { generate, validate } from "korea-fixtures";
+
+generate("brn", { seed: 42, count: 1000 }); // -> [{ type, value:"332-81-02957", raw }, ...] reproducible
+validate("account", "3333-12-3456789");      // -> { valid, type, bank, bankName } | { valid:false, failedCheck }
+```
+
+Seeds may be numbers or strings (e.g. a release tag); the same seed always yields identical output,
+so generated datasets are golden-pinnable in CI.
+
+**TypeScript:** types ship with the package (`index.d.ts`) — `generate`, `validate`, the `GenerateType`
+/ `ValidateType` unions, and the result shapes are fully typed, no `@types` needed.
+
+## Honest scope
+
+- **Account formats are best-effort.** Most Korean bank accounts have no public checksum, so `account`
+  validity means "matches a known bank's prefix + length". The bank table is small and easy to override
+  — not authoritative.
+- **Card BINs are plausible, not issuer-authoritative** (the Luhn check digit is always correct).
+- This is a **library first** — correct-by-construction breadth + determinism + bidirectional
+  diagnostics. A paid fixture-pack / CI service could layer on top later.
+
+## Develop
+
+```bash
+node --test      # 20 tests: golden checksums + round-trip + determinism + identifier formats + .d.ts sync
+```
+
+Zero runtime dependencies; published files are `src/`, `bin/`, `index.d.ts`, `README.md` (see `files`).
+
+MIT.

package/bin/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { generate, validate, GENERATE_TYPES, VALIDATE_TYPES } from "../src/index.js";
+
+function opt(args, name, def) {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : def;
+}
+
+function usage() {
+  console.log(`korea-fixtures (kfix) — deterministic, checksum-valid-but-fake Korean test data
+
+  kfix gen <type> [--seed S] [--count N]   generate identifiers (reproducible per seed)
+  kfix validate <type> <value>             validate one identifier (JSON result)
+  kfix types                               list supported types
+
+  generate: ${GENERATE_TYPES.join(", ")}
+  validate: ${VALIDATE_TYPES.join(", ")}   (rrn is validate-only by design)`);
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+try {
+  if (cmd === "gen" || cmd === "generate") {
+    const type = rest[0];
+    if (!type) { usage(); process.exit(2); }
+    const seed = opt(rest, "seed", "0");
+    const count = parseInt(opt(rest, "count", "1"), 10);
+    for (const item of generate(type, { seed, count })) console.log(item.value);
+  } else if (cmd === "validate") {
+    const [type, value] = rest;
+    if (!type || value === undefined) { usage(); process.exit(2); }
+    const result = validate(type, value);
+    console.log(JSON.stringify(result));
+    process.exit(result.valid ? 0 : 1);
+  } else if (cmd === "types") {
+    console.log("generate:", GENERATE_TYPES.join(", "));
+    console.log("validate:", VALIDATE_TYPES.join(", "));
+  } else {
+    usage();
+    process.exit(cmd ? 2 : 0);
+  }
+} catch (e) {
+  console.error("error:", e.message);
+  process.exit(2);
+}

package/index.d.ts

@@ -0,0 +1,78 @@
+// Type declarations for korea-fixtures.
+
+/** Identifiers that can be generated (RRN is excluded — validate-only). */
+export type GenerateType =
+  | "brn"
+  | "corp"
+  | "card"
+  | "phone"
+  | "account"
+  | "postal"
+  | "plate"
+  | "address";
+
+/** Identifiers that can be validated (includes rrn). */
+export type ValidateType = GenerateType | "rrn";
+
+export interface GeneratedItem {
+  type: GenerateType;
+  /** Formatted identifier (e.g. "124-81-00998"). */
+  value: string;
+  /** Digits-only / unformatted form. */
+  raw: string;
+  /** present for type "account". */
+  bank?: string;
+  bankName?: string;
+  /** present for type "card". */
+  issuer?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  type: ValidateType;
+  /** which check failed when valid === false (e.g. "checkDigit", "length", "luhn", "month"). */
+  failedCheck?: string;
+  expected?: number;
+  actual?: number | string;
+  /** present for a valid "account". */
+  bank?: string;
+  bankName?: string;
+  /** advisory note (e.g. for rrn / format-only types). */
+  note?: string;
+}
+
+export interface GenerateOptions {
+  /** number or string seed; the same seed always yields identical output. Default 0. */
+  seed?: number | string;
+  /** how many to generate. Default 1. */
+  count?: number;
+}
+
+export interface Bank {
+  code: string;
+  name: string;
+  clearingCode?: string;
+  prefixes: string[];
+  length: number;
+}
+
+/** Generate `count` checksum-valid-but-fake identifiers of `type`, reproducibly from `seed`. */
+export function generate(type: GenerateType, options?: GenerateOptions): GeneratedItem[];
+
+/** Validate one identifier; returns the verdict with "which check failed" diagnostics. */
+export function validate(type: ValidateType, value: string): ValidationResult;
+
+export const GENERATE_TYPES: GenerateType[];
+export const VALIDATE_TYPES: ValidateType[];
+export const BANKS: Bank[];
+
+/** Seeded deterministic PRNG. */
+export function makeRng(seed: number | string): () => number;
+
+export namespace checksum {
+  function toDigits(value: string | number): number[];
+  function brnCheck(digits: number[]): number;
+  function corpCheck(digits: number[]): number;
+  function rrnCheck(digits: number[]): number;
+  function luhnCheck(digits: number[]): number;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "korea-fixtures",
+  "version": "0.1.0",
+  "description": "Deterministic, checksum-valid-but-fake Korean test data (사업자등록번호·법인등록번호·계좌번호·카드·휴대폰·우편번호·차량번호) + validators. Seeded & reproducible. Zero dependencies. TypeScript types included.",
+  "type": "module",
+  "license": "MIT",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "bin": {
+    "kfix": "./bin/cli.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "keywords": [
+    "korea",
+    "korean",
+    "test-data",
+    "fixtures",
+    "faker",
+    "mock",
+    "사업자등록번호",
+    "계좌번호",
+    "checksum",
+    "deterministic"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trevi00/korea-fixtures.git"
+  },
+  "bugs": {
+    "url": "https://github.com/trevi00/korea-fixtures/issues"
+  },
+  "homepage": "https://github.com/trevi00/korea-fixtures#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/banks.js

@@ -0,0 +1,31 @@
+// Best-effort Korean bank account formats. NOTE: most Korean bank accounts have NO public checksum,
+// so account "validity" here means "matches a known bank's prefix + digit length", not a checksum.
+// These prefixes/lengths are curated best-effort and intentionally easy to override — pass your own
+// table to generate/validate if you need authoritative formats. `code` follows the common 표준코드.
+export const BANKS = [
+  { code: "kb", name: "KB국민", clearingCode: "004", prefixes: ["604", "607", "904"], length: 12 },
+  { code: "shinhan", name: "신한", clearingCode: "088", prefixes: ["110"], length: 12 },
+  { code: "woori", name: "우리", clearingCode: "020", prefixes: ["1002"], length: 13 },
+  { code: "hana", name: "하나", clearingCode: "081", prefixes: ["3"], length: 14 },
+  { code: "nonghyup", name: "농협", clearingCode: "011", prefixes: ["301", "302", "351", "356"], length: 13 },
+  { code: "ibk", name: "IBK기업", clearingCode: "003", prefixes: ["010", "012"], length: 14 },
+  { code: "sc", name: "SC제일", clearingCode: "023", prefixes: ["100"], length: 11 },
+  { code: "suhyup", name: "수협", clearingCode: "007", prefixes: ["1010"], length: 13 },
+  { code: "post", name: "우체국", clearingCode: "071", prefixes: ["0"], length: 14 },
+  { code: "kakaobank", name: "카카오뱅크", clearingCode: "090", prefixes: ["3333", "7979"], length: 13 },
+  { code: "tossbank", name: "토스뱅크", clearingCode: "092", prefixes: ["1000", "1001"], length: 12 },
+  { code: "kbank", name: "케이뱅크", clearingCode: "089", prefixes: ["100"], length: 12 },
+  { code: "busan", name: "부산", clearingCode: "032", prefixes: ["101", "201"], length: 13 },
+  { code: "daegu", name: "iM뱅크(대구)", clearingCode: "031", prefixes: ["508"], length: 12 },
+];
+
+export function findBank(code, banks = BANKS) {
+  return banks.find((b) => b.code === code);
+}
+
+/** Longest prefix of `bank` that `raw` starts with, or -1 if none. */
+export function matchedPrefixLength(bank, raw) {
+  let best = -1;
+  for (const p of bank.prefixes) if (raw.startsWith(p) && p.length > best) best = p.length;
+  return best;
+}

package/src/checksum.js

@@ -0,0 +1,49 @@
+// Korean identifier checksums. Algorithms verified against real public entities:
+//   사업자등록번호 124-81-00998 (Samsung Electronics) -> check 8
+//   법인등록번호   130111-0006246 (Samsung Electronics) -> check 6
+//   Luhn          4242424242424242 -> check 2
+// Each `*Check` returns the expected final check digit for the leading digits.
+
+export function toDigits(value) {
+  return String(value).replace(/\D/g, "").split("").map(Number);
+}
+
+/** 사업자등록번호 (BRN): 10 digits, weighted mod-10 with a half-carry on the 9th digit. */
+export function brnCheck(d) {
+  const w = [1, 3, 7, 1, 3, 7, 1, 3, 5];
+  let sum = 0;
+  for (let i = 0; i < 9; i++) sum += d[i] * w[i];
+  sum += Math.floor((d[8] * 5) / 10);
+  return (10 - (sum % 10)) % 10;
+}
+
+/** 법인등록번호 (corporate registration): 13 digits, alternating 1/2 weights, mod-10. */
+export function corpCheck(d) {
+  const w = [1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2];
+  let sum = 0;
+  for (let i = 0; i < 12; i++) sum += d[i] * w[i];
+  return (10 - (sum % 10)) % 10;
+}
+
+/** 주민등록번호 (RRN): 13 digits, mod-11. Validation only — generation is intentionally unsupported. */
+export function rrnCheck(d) {
+  const w = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5];
+  let sum = 0;
+  for (let i = 0; i < 12; i++) sum += d[i] * w[i];
+  return (11 - (sum % 11)) % 10;
+}
+
+/** Luhn check digit for a card number (over all but the last digit). */
+export function luhnCheck(d) {
+  let sum = 0;
+  const body = d.slice(0, -1);
+  for (let i = 0; i < body.length; i++) {
+    let x = body[body.length - 1 - i];
+    if (i % 2 === 0) {
+      x *= 2;
+      if (x > 9) x -= 9;
+    }
+    sum += x;
+  }
+  return (10 - (sum % 10)) % 10;
+}

package/src/generate.js

@@ -0,0 +1,106 @@
+// Generators: each produces a checksum-valid-but-FAKE Korean identifier from a seeded rng.
+// 주민등록번호 (RRN) is intentionally absent — it is validation-only (see validate.js / README).
+import { digits, intBelow, pick } from "./prng.js";
+import { brnCheck, corpCheck, luhnCheck, toDigits } from "./checksum.js";
+import { BANKS } from "./banks.js";
+
+// Plausible 사업자등록번호 middle pair (개인 01-79 / 영리법인 81-88 등). Fake but well-formed.
+const BRN_MIDDLE = ["81", "82", "83", "85", "86", "01", "02", "05"];
+
+// Best-effort Korean issuer BIN prefixes (fake-but-plausible; not authoritative). Luhn is always correct.
+const CARD_ISSUERS = [
+  { name: "신한카드", bin: "4045" },
+  { name: "삼성카드", bin: "5365" },
+  { name: "KB국민카드", bin: "5444" },
+  { name: "현대카드", bin: "4061" },
+  { name: "롯데카드", bin: "5121" },
+  { name: "우리카드", bin: "4673" },
+  { name: "하나카드", bin: "5251" },
+  { name: "BC카드", bin: "9446" },
+];
+
+const SIDO = ["서울특별시", "부산광역시", "인천광역시", "경기도 성남시", "대전광역시"];
+const GU = ["강남구", "서초구", "마포구", "분당구", "유성구"];
+const ROAD = ["테헤란로", "세종대로", "양재천로", "판교역로", "대학로"];
+
+// License-plate Korean syllables actually used on modern plates (must match validate.js).
+const PLATE_CHARS = "가나다라마거너더러머버서어저고노도로모보소오조구누두루무부수우주바사아자하허호".split("");
+
+export function genBrn(rng) {
+  const nine = digits(rng, 3) + pick(rng, BRN_MIDDLE) + digits(rng, 4); // 9 digits
+  const d = toDigits(nine);
+  const check = brnCheck(d);
+  const raw = nine + check;
+  return { type: "brn", value: `${raw.slice(0, 3)}-${raw.slice(3, 5)}-${raw.slice(5)}`, raw };
+}
+
+export function genCorp(rng) {
+  const twelve = digits(rng, 12);
+  const check = corpCheck(toDigits(twelve));
+  const raw = twelve + check;
+  return { type: "corp", value: `${raw.slice(0, 6)}-${raw.slice(6)}`, raw };
+}
+
+export function genCard(rng) {
+  const issuer = pick(rng, CARD_ISSUERS);
+  const body = issuer.bin + digits(rng, 11); // 15 digits, missing the check digit
+  const check = luhnCheck(toDigits(body + "0"));
+  const raw = body + check;
+  return {
+    type: "card", issuer: issuer.name,
+    value: raw.replace(/(\d{4})(?=\d)/g, "$1-"), raw,
+  };
+}
+
+export function genPhone(rng) {
+  const raw = "010" + digits(rng, 8);
+  return { type: "phone", value: `${raw.slice(0, 3)}-${raw.slice(3, 7)}-${raw.slice(7)}`, raw };
+}
+
+export function genAccount(rng, banks = BANKS) {
+  const bank = pick(rng, banks);
+  const prefix = pick(rng, bank.prefixes);
+  const raw = (prefix + digits(rng, Math.max(0, bank.length - prefix.length))).slice(0, bank.length);
+  return { type: "account", bank: bank.code, bankName: bank.name, value: raw, raw };
+}
+
+export function genAddress(rng) {
+  const value = `${pick(rng, SIDO)} ${pick(rng, GU)} ${pick(rng, ROAD)} ${1 + intBelow(rng, 300)}`;
+  return { type: "address", value, raw: value };
+}
+
+export function genPostal(rng) {
+  // 5-digit postal code (post-2015). Plausible range, format-only.
+  const raw = String(1000 + intBelow(rng, 62000)).padStart(5, "0");
+  return { type: "postal", value: raw, raw };
+}
+
+export function genPlate(rng) {
+  const head = digits(rng, 2 + intBelow(rng, 2)); // 2 or 3 leading digits
+  const syllable = pick(rng, PLATE_CHARS);
+  const tail = digits(rng, 4);
+  const raw = `${head}${syllable}${tail}`;
+  return { type: "plate", value: raw, raw };
+}
+
+export const GENERATORS = {
+  brn: genBrn,
+  corp: genCorp,
+  card: genCard,
+  phone: genPhone,
+  account: genAccount,
+  postal: genPostal,
+  plate: genPlate,
+  address: genAddress,
+};
+
+export function generateOne(type, rng) {
+  const g = GENERATORS[type];
+  if (!g) {
+    if (type === "rrn") {
+      throw new Error("rrn generation is intentionally unsupported (validation only) — see README");
+    }
+    throw new Error(`unknown type: ${type} (known: ${Object.keys(GENERATORS).join(", ")})`);
+  }
+  return g(rng);
+}

package/src/index.js

@@ -0,0 +1,29 @@
+// korea-fixtures — deterministic, checksum-valid-but-fake Korean test data + validators.
+import { makeRng } from "./prng.js";
+import { generateOne, GENERATORS } from "./generate.js";
+import { validateOne, VALIDATORS } from "./validate.js";
+
+/** Types that can be generated (RRN is deliberately excluded — validate-only). */
+export const GENERATE_TYPES = Object.keys(GENERATORS);
+/** Types that can be validated (includes rrn). */
+export const VALIDATE_TYPES = Object.keys(VALIDATORS);
+
+/**
+ * Generate `count` checksum-valid-but-fake identifiers of `type`, reproducibly from `seed`.
+ * Returns an array of objects: { type, value, raw, ...meta }.
+ */
+export function generate(type, { seed = 0, count = 1 } = {}) {
+  const rng = makeRng(seed);
+  const out = [];
+  for (let i = 0; i < count; i++) out.push(generateOne(type, rng));
+  return out;
+}
+
+/** Validate a single identifier; returns { valid, type, failedCheck?, expected?, actual? }. */
+export function validate(type, value) {
+  return validateOne(type, value);
+}
+
+export { makeRng } from "./prng.js";
+export * as checksum from "./checksum.js";
+export { BANKS } from "./banks.js";

package/src/prng.js

@@ -0,0 +1,46 @@
+// Seeded deterministic PRNG (mulberry32) — same seed => byte-identical output, so generated
+// datasets are reproducible and golden-pinnable in CI. No dependency on Math.random().
+
+export function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function next() {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Turn an arbitrary string/number seed into a 32-bit integer seed (deterministic). */
+export function hashSeed(seed) {
+  if (typeof seed === "number") return seed >>> 0;
+  const s = String(seed ?? "");
+  let h = 2166136261 >>> 0; // FNV-1a
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+export function makeRng(seed) {
+  return mulberry32(hashSeed(seed));
+}
+
+/** Integer in [0, n). */
+export function intBelow(rng, n) {
+  return Math.floor(rng() * n);
+}
+
+/** A string of `count` random decimal digits. */
+export function digits(rng, count) {
+  let out = "";
+  for (let i = 0; i < count; i++) out += intBelow(rng, 10);
+  return out;
+}
+
+/** Pick a random element. */
+export function pick(rng, arr) {
+  return arr[intBelow(rng, arr.length)];
+}

package/src/validate.js

@@ -0,0 +1,112 @@
+// Validators: pure functions identifier -> { valid, type, failedCheck?, expected?, actual? }.
+// Bidirectional with generate.js (a generated value always validates), plus RRN validation
+// (generation of RRN is unsupported by design; validation is provided).
+import { toDigits, brnCheck, corpCheck, rrnCheck, luhnCheck } from "./checksum.js";
+import { BANKS, matchedPrefixLength } from "./banks.js";
+
+// License-plate Korean syllables actually used on modern Korean plates.
+const PLATE_CHARS = "가나다라마거너더러머버서어저고노도로모보소오조구누두루무부수우주바사아자하허호";
+
+function bad(type, failedCheck, extra = {}) {
+  return { valid: false, type, failedCheck, ...extra };
+}
+
+export function validateBrn(value) {
+  const d = toDigits(value);
+  if (d.length !== 10) return bad("brn", "length", { expected: 10, actual: d.length });
+  const exp = brnCheck(d);
+  if (exp !== d[9]) return bad("brn", "checkDigit", { expected: exp, actual: d[9] });
+  return { valid: true, type: "brn" };
+}
+
+export function validateCorp(value) {
+  const d = toDigits(value);
+  if (d.length !== 13) return bad("corp", "length", { expected: 13, actual: d.length });
+  const exp = corpCheck(d);
+  if (exp !== d[12]) return bad("corp", "checkDigit", { expected: exp, actual: d[12] });
+  return { valid: true, type: "corp" };
+}
+
+/** 주민등록번호 — validation only. Checks length, date, gender digit, and the mod-11 check digit. */
+export function validateRrn(value) {
+  const d = toDigits(value);
+  if (d.length !== 13) return bad("rrn", "length", { expected: 13, actual: d.length });
+  const month = d[2] * 10 + d[3];
+  const day = d[4] * 10 + d[5];
+  if (month < 1 || month > 12) return bad("rrn", "month", { actual: month });
+  if (day < 1 || day > 31) return bad("rrn", "day", { actual: day });
+  if (d[6] < 1 || d[6] > 8) return bad("rrn", "genderDigit", { actual: d[6] });
+  const exp = rrnCheck(d);
+  if (exp !== d[12]) return bad("rrn", "checkDigit", { expected: exp, actual: d[12] });
+  return { valid: true, type: "rrn", note: "validation only; generation unsupported by design" };
+}
+
+export function validateCard(value) {
+  const d = toDigits(value);
+  if (d.length < 13 || d.length > 19) return bad("card", "length", { actual: d.length });
+  const exp = luhnCheck(d);
+  if (exp !== d[d.length - 1]) return bad("card", "luhn", { expected: exp, actual: d[d.length - 1] });
+  return { valid: true, type: "card" };
+}
+
+export function validatePhone(value) {
+  const raw = toDigits(value).join("");
+  if (!/^01[016789]\d{7,8}$/.test(raw)) return bad("phone", "format", { actual: raw });
+  return { valid: true, type: "phone" };
+}
+
+export function validateAccount(value, banks = BANKS) {
+  const raw = toDigits(value).join("");
+  // Among banks whose length matches, pick the one with the LONGEST matching prefix (most specific).
+  let best = null;
+  let bestLen = -1;
+  for (const b of banks) {
+    if (b.length !== raw.length) continue;
+    const len = matchedPrefixLength(b, raw);
+    if (len > bestLen) {
+      bestLen = len;
+      best = b;
+    }
+  }
+  if (!best || bestLen < 0) return bad("account", "noMatchingBankFormat", { actual: raw });
+  return { valid: true, type: "account", bank: best.code, bankName: best.name };
+}
+
+export function validatePostal(value) {
+  const raw = toDigits(value).join("");
+  if (raw.length !== 5) return bad("postal", "length", { expected: 5, actual: raw.length });
+  return { valid: true, type: "postal", note: "format-only (5-digit, post-2015)" };
+}
+
+export function validatePlate(value) {
+  const s = String(value || "").replace(/\s/g, "");
+  // 2-3 digits + one plate syllable + 4 digits, e.g. 12가3456 / 123가4567
+  const m = /^(\d{2,3})([가-힣])(\d{4})$/.exec(s);
+  if (!m) return bad("plate", "format", { actual: s });
+  if (!PLATE_CHARS.includes(m[2])) return bad("plate", "syllable", { actual: m[2] });
+  return { valid: true, type: "plate", note: "format-only" };
+}
+
+export function validateAddress(value) {
+  const s = String(value || "").trim();
+  if (!s) return bad("address", "empty");
+  return { valid: true, type: "address", note: "format-only (no checksum)" };
+}
+
+export const VALIDATORS = {
+  brn: validateBrn,
+  corp: validateCorp,
+  rrn: validateRrn,
+  card: validateCard,
+  phone: validatePhone,
+  account: validateAccount,
+  postal: validatePostal,
+  plate: validatePlate,
+  address: validateAddress,
+};
+
+export function validateOne(type, value) {
+  const v = VALIDATORS[type];
+  if (!v) throw new Error(`unknown type: ${type} (known: ${Object.keys(VALIDATORS).join(", ")})`);
+  return v(value);
+}