feat: more PII parsers

Author: ClaudiuCeia

README.md

@@ -110,7 +110,7 @@ npx jsr add @claudiu-ceia/ts-duckling
 
 ### Extract entities
 
-Call `Duckling()` with no arguments to use **all 15 built-in parsers**:
+Call `Duckling()` with no arguments to use **all 18 built-in parsers**:
 
 ```ts
 import { Duckling } from "@claudiu-ceia/ts-duckling";
@@ -362,23 +362,33 @@ const entities = Duckling([Email.parser, Hashtag.parser]).extract(
 
 ## Supported entities
 
-| Entity          | Kind          | Example match                             | Notes                                 |
-| --------------- | ------------- | ----------------------------------------- | ------------------------------------- |
-| **Time**        | `time`        | `tomorrow at 3pm`, `2024-01-15T10:30:00Z` | Relative, day-of-week, ISO timestamps |
-| **Range**       | `range`       | `2020-2024`, `20°C to 30°C`               | Time, year, and temperature ranges    |
-| **Temperature** | `temperature` | `72°F`, `20 celsius`                      | Fahrenheit and Celsius                |
-| **Quantity**    | `quantity`    | `5 kg`, `100 miles`                       | Units of measurement                  |
-| **Location**    | `location`    | `United States`, `Germany`                | Countries (dataset-backed)            |
-| **URL**         | `url`         | `https://example.com/path`                | Full URLs with TLD validation         |
-| **Email**       | `email`       | `user@example.com`                        | Standard email addresses              |
-| **Institution** | `institution` | `University of Oxford`                    | Known institutions                    |
-| **Language**    | `language`    | `English`, `Japanese`                     | Language names (dataset-backed)       |
-| **Phone**       | `phone`       | `+14155552671`                            | E.164-ish phone numbers               |
-| **IP address**  | `ip_address`  | `192.168.1.1`, `::1`                      | IPv4 + IPv6 full form                 |
-| **SSN**         | `ssn`         | `123-45-6789`                             | US Social Security Numbers            |
-| **Credit card** | `credit_card` | `4111111111111111`                        | Luhn-validated card numbers           |
-| **UUID**        | `uuid`        | `550e8400-e29b-41d4-a716-446655440000`    | RFC 4122 UUIDs                        |
-| **API key**     | `api_key`     | `sk-abc123...`, `AKIA...`                 | Common provider prefixes              |
+| Entity          | Kind           | Example matches                                           |
+| --------------- | -------------- | --------------------------------------------------------- |
+| **Time**        | `time`         | `tomorrow at 3pm`, `next Friday`, `2024-01-15T10:30:00Z`  |
+| **Range**       | `range`        | `2020-2024`, `20°C to 30°C`, `Monday to Friday`           |
+| **Temperature** | `temperature`  | `72°F`, `20 celsius`, `-5°C`                               |
+| **Quantity**    | `quantity`     | `5 kg`, `100 miles`, `3,500.00`                            |
+| **Location**    | `location`     | `United States`, `Germany`, `Japan`                        |
+| **URL**         | `url`          | `https://example.com/path?q=1`                             |
+| **Institution** | `institution`  | `University of Oxford`, `New York City Hall`               |
+| **Language**    | `language`     | `English`, `Japanese`, `Portuguese`                        |
+
+### PII
+
+Available via `PIIParsers` for targeted redaction with `Duckling(PIIParsers).redact(…)`.
+
+| Entity          | Kind           | Example matches                                           |
+| --------------- | -------------- | --------------------------------------------------------- |
+| **Email**       | `email`        | `user@example.com`, `first.last@company.io`                |
+| **Phone**       | `phone`        | `+14155552671`, `+44 20 7123 4567`, `(415) 555-2671`      |
+| **IP address**  | `ip`           | `192.168.1.1`, `2001:db8::1`, `::1`                       |
+| **SSN**         | `ssn`          | `123-45-6789`                                              |
+| **Credit card** | `credit_card`  | `4111 1111 1111 1111`, `5500-0000-0000-0004`               |
+| **UUID**        | `uuid`         | `550e8400-e29b-41d4-a716-446655440000`                     |
+| **API key**     | `api_key`      | `sk-proj-abc123…`, `ghp_abc123…`, `AKIA…`                  |
+| **IBAN**        | `iban`         | `GB29NWBK60161331926819`, `DE89 3704 0044 0532 0130 00`    |
+| **MAC address** | `mac_address`  | `00:1A:2B:3C:4D:5E`, `001A.2B3C.4D5E`                     |
+| **JWT**         | `jwt`          | `eyJhbGciOiJIUzI1NiIs…`                                   |
 
 ## API reference
 
@@ -405,7 +415,7 @@ function Duckling<T>(parsers: ParserTuple<T>): {
 };
 ```
 
-Creates an extractor/renderer/redactor. Without arguments, uses all 15 built-in
+Creates an extractor/renderer/redactor. Without arguments, uses all 18 built-in
 parsers and returns `AnyEntity[]`. When given an explicit parser array, the
 return type narrows to the union of those entity types.
 
@@ -550,7 +560,7 @@ replace the span.
 
 ### `AnyEntity`
 
-Union of all 15 built-in entity types. This is the return element type of
+Union of all 18 built-in entity types. This is the return element type of
 `Duckling().extract(...)`.
 
 ### `PIIEntity`

mod.ts

@@ -32,6 +32,9 @@ import { SSN, type SSNEntity } from "./src/SSN.ts";
 import { CreditCard, type CreditCardEntity } from "./src/CreditCard.ts";
 import { UUID, type UUIDEntity } from "./src/UUID.ts";
 import { ApiKey, type ApiKeyEntity } from "./src/ApiKey.ts";
+import { IBAN, type IBANEntity } from "./src/IBAN.ts";
+import { MACAddress, type MACAddressEntity } from "./src/MACAddress.ts";
+import { JWT, type JWTEntity } from "./src/JWT.ts";
 
 /**
  * Union of all entity types produced by the built-in parsers.
@@ -55,7 +58,10 @@ export type AnyEntity =
   | SSNEntity
   | CreditCardEntity
   | UUIDEntity
-  | ApiKeyEntity;
+  | ApiKeyEntity
+  | IBANEntity
+  | MACAddressEntity
+  | JWTEntity;
 
 const DefaultParsers: [Parser<AnyEntity>, ...Parser<AnyEntity>[]] = [
   Range.parser,
@@ -73,13 +79,17 @@ const DefaultParsers: [Parser<AnyEntity>, ...Parser<AnyEntity>[]] = [
   CreditCard.parser,
   UUID.parser,
   ApiKey.parser,
+  IBAN.parser,
+  MACAddress.parser,
+  JWT.parser,
 ];
 
 /**
  * Union of entity types considered Personally Identifiable Information (PII).
  *
  * Covers: email addresses, phone numbers, IP addresses, Social Security
- * Numbers, credit card numbers, UUIDs, and API keys.
+ * Numbers, credit card numbers, UUIDs, API keys, IBANs, MAC addresses,
+ * and JWTs.
  */
 export type PIIEntity =
   | EmailEntity
@@ -88,7 +98,10 @@ export type PIIEntity =
   | SSNEntity
   | CreditCardEntity
   | UUIDEntity
-  | ApiKeyEntity;
+  | ApiKeyEntity
+  | IBANEntity
+  | MACAddressEntity
+  | JWTEntity;
 
 /**
  * Pre-built parser tuple targeting PII entities.
@@ -112,6 +125,9 @@ export const PIIParsers: ParserTuple<
     CreditCardEntity,
     UUIDEntity,
     ApiKeyEntity,
+    IBANEntity,
+    MACAddressEntity,
+    JWTEntity,
   ]
 > = [
   Email.parser,
@@ -121,6 +137,9 @@ export const PIIParsers: ParserTuple<
   CreditCard.parser,
   UUID.parser,
   ApiKey.parser,
+  IBAN.parser,
+  MACAddress.parser,
+  JWT.parser,
 ];
 
 type NonEmptyArray<T> = [T, ...T[]];
@@ -483,3 +502,6 @@ export * from "./src/UUID.ts";
 export * from "./src/Institution.ts";
 export * from "./src/Language.ts";
 export * from "./src/ApiKey.ts";
+export * from "./src/IBAN.ts";
+export * from "./src/MACAddress.ts";
+export * from "./src/JWT.ts";

src/Email.ts

@@ -49,7 +49,7 @@ export const Email: EmailLanguage = createLanguage<EmailLanguage>({
       seq(
         map(
           manyTill(
-            any(letter(), digit(), str("."), str("-"), str("-"), str("+")),
+            any(letter(), digit(), str("."), str("-"), str("+"), str("_")),
             str("@"),
           ),
           (p) => p.join(""),

src/IBAN.ts

@@ -0,0 +1,224 @@
+import {
+  type Context,
+  createLanguage,
+  many1,
+  map,
+  optional,
+  regex,
+  repeat,
+  seq,
+  str,
+} from "@claudiu-ceia/combine";
+import type { Parser } from "@claudiu-ceia/combine";
+import { dot } from "./common.ts";
+import { ent, type Entity } from "./Entity.ts";
+import { guard } from "./guard.ts";
+
+/**
+ * IBAN entity (International Bank Account Number).
+ */
+export type IBANEntity = Entity<
+  "iban",
+  {
+    iban: string;
+    country: string;
+  }
+>;
+
+/**
+ * Helper for constructing an `IBANEntity`.
+ */
+export const iban = (
+  value: IBANEntity["value"],
+  before: Context,
+  after: Context,
+): IBANEntity => {
+  return ent(value, "iban", before, after);
+};
+
+// IBAN lengths per country (ISO 13616).
+// https://www.swift.com/standards/data-standards/iban-international-bank-account-number
+const IBAN_LENGTHS: Record<string, number> = {
+  AL: 28,
+  AD: 24,
+  AT: 20,
+  AZ: 28,
+  BH: 22,
+  BY: 28,
+  BE: 16,
+  BA: 20,
+  BR: 29,
+  BG: 22,
+  CR: 22,
+  HR: 21,
+  CY: 28,
+  CZ: 24,
+  DK: 18,
+  DO: 28,
+  TL: 23,
+  EG: 29,
+  SV: 28,
+  EE: 20,
+  FO: 18,
+  FI: 18,
+  FR: 27,
+  GE: 22,
+  DE: 22,
+  GI: 23,
+  GR: 27,
+  GL: 18,
+  GT: 28,
+  HU: 28,
+  IS: 26,
+  IQ: 23,
+  IE: 22,
+  IL: 23,
+  IT: 27,
+  JO: 30,
+  KZ: 20,
+  XK: 20,
+  KW: 30,
+  LV: 21,
+  LB: 28,
+  LY: 25,
+  LI: 21,
+  LT: 20,
+  LU: 20,
+  MK: 19,
+  MT: 31,
+  MR: 27,
+  MU: 30,
+  MC: 27,
+  MD: 24,
+  ME: 22,
+  NL: 18,
+  NO: 15,
+  PK: 24,
+  PS: 29,
+  PL: 28,
+  PT: 25,
+  QA: 29,
+  RO: 24,
+  LC: 32,
+  SM: 27,
+  ST: 25,
+  SA: 24,
+  RS: 22,
+  SC: 31,
+  SK: 24,
+  SI: 19,
+  ES: 24,
+  SD: 18,
+  SE: 24,
+  CH: 21,
+  TN: 24,
+  TR: 26,
+  UA: 29,
+  AE: 23,
+  GB: 22,
+  VA: 22,
+  VG: 24,
+};
+
+/**
+ * Validate IBAN checksum using the ISO 7064 Mod 97-10 algorithm.
+ */
+const ibanChecksum = (raw: string): boolean => {
+  const normalized = raw.replace(/\s/g, "").toUpperCase();
+  // Move first 4 chars to end
+  const rearranged = normalized.slice(4) + normalized.slice(0, 4);
+  // Convert letters to numbers (A=10, B=11, ..., Z=35)
+  let numStr = "";
+  for (const ch of rearranged) {
+    const code = ch.charCodeAt(0);
+    if (code >= 65 && code <= 90) {
+      numStr += (code - 55).toString();
+    } else {
+      numStr += ch;
+    }
+  }
+  // Mod 97 on the large number (process in chunks to avoid BigInt)
+  let remainder = 0;
+  for (let i = 0; i < numStr.length; i++) {
+    remainder = (remainder * 10 + parseInt(numStr[i], 10)) % 97;
+  }
+  return remainder === 1;
+};
+
+const isValidIBAN = (raw: string): boolean => {
+  const normalized = raw.replace(/\s/g, "").toUpperCase();
+  const country = normalized.slice(0, 2);
+  const expectedLen = IBAN_LENGTHS[country];
+  if (!expectedLen) return false;
+  if (normalized.length !== expectedLen) return false;
+  return ibanChecksum(raw);
+};
+
+// Leaf tokens
+const upperLetter = regex(/[A-Z]/, "uppercase letter");
+const ibanDigit = regex(/\d/, "digit");
+const alphanumGroup = regex(/[A-Z0-9]{1,4}/, "BBAN group");
+
+type IBANLanguage = {
+  /** Country code: 2 uppercase letters */
+  Country: Parser<string>;
+  /** Check digits: exactly 2 digits */
+  CheckDigits: Parser<string>;
+  /** BBAN body: groups of 1-4 alphanumeric chars, optionally space-separated */
+  BBAN: Parser<string>;
+  /** Full IBAN: country + check + BBAN, validated */
+  Raw: Parser<string>;
+  Full: Parser<IBANEntity>;
+  parser: Parser<IBANEntity>;
+};
+
+/**
+ * IBAN parser language.
+ *
+ * Structure: `CC` `DD` `BBAN...` where CC is the country code, DD the check
+ * digits, and BBAN is 3-8 groups of 1-4 alphanumeric characters (optionally
+ * space-separated). Validated with ISO 7064 Mod 97-10 checksum and per-country
+ * length checks.
+ */
+export const IBAN: IBANLanguage = createLanguage<IBANLanguage>({
+  // Two uppercase letters
+  Country: () => map(repeat(2, upperLetter), (letters) => letters.join("")),
+
+  // Two digits
+  CheckDigits: () => map(repeat(2, ibanDigit), (digits) => digits.join("")),
+
+  // BBAN: multiple groups of 1-4 alphanumerics with optional spaces between.
+  // Each group is preceded by an optional space, so the first group handles
+  // the space between check digits and BBAN in the spaced form (GB29 NWBK...).
+  // `many` stays at the last successful group — it does NOT consume a trailing
+  // space when the next group fails (lowercase text like "please").
+  BBAN: () =>
+    map(
+      many1(seq(optional(str(" ")), alphanumGroup)),
+      (parts) => parts.map(([, g]) => g).join(""),
+    ),
+
+  // Assemble and validate
+  Raw: (s) =>
+    guard(
+      map(
+        seq(s.Country, s.CheckDigits, s.BBAN),
+        (_, b, a) => b.text.substring(b.index, a.index),
+      ),
+      isValidIBAN,
+    ),
+
+  Full: (s) =>
+    map(s.Raw, (raw, b, a) => {
+      const normalized = raw.replace(/\s/g, "").toUpperCase();
+      return iban(
+        {
+          iban: normalized,
+          country: normalized.slice(0, 2),
+        },
+        b,
+        a,
+      );
+    }),
+  parser: (s) => dot(s.Full),
+});