euredact 0.3.9 → 0.5.0

package/dist/esm/cloud/client.js

@@ -0,0 +1,239 @@
+/**
+ * [CLOUD EXTENSION] The cloud client.
+ *
+ * Speaks to the euRedact inference service: a deterministic rules engine
+ * followed by a fine-tuned model asked only *what did the rules miss?* The
+ * service returns both the redacted document and located spans, so this
+ * module's job is transport and translation, not detection.
+ *
+ * Three things it hides from the caller:
+ *
+ * - **Whether the document finished inside the service's sync window.** A short
+ *   document comes back on the original request; a long one, or one arriving
+ *   while a GPU node is cold, returns a job handle and is polled. Callers
+ *   should never write that branch, so `redact()` resolves either way.
+ * - **Retries.** Every request carries an `Idempotency-Key`, so a retry after a
+ *   timeout cannot produce a second job or a second usage row.
+ * - **`Retry-After`.** When the service says how long to wait, that is obeyed
+ *   rather than second-guessed with a backoff curve.
+ *
+ * Zero dependencies, like the rest of the package: this uses the platform's
+ * own `fetch`.
+ */
+import { getConfig, } from "./config.js";
+import { CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./errors.js";
+import { canonicalType, DetectionSource, EntityType, } from "../types.js";
+const RETRY_STATUS = new Set([429, 500, 502, 503, 504]);
+const MAX_BACKOFF_MS = 30_000;
+function requireFetch(supplied) {
+    const impl = supplied ?? globalThis.fetch;
+    if (typeof impl !== "function") {
+        throw new NotConfiguredError("the cloud tier needs a global fetch. Node 18+ provides one; on Node 16 " +
+            "supply one via the fetchImpl option or install a polyfill.");
+    }
+    return impl;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function retryAfterMs(headers) {
+    const raw = headers?.get("Retry-After");
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    // The HTTP-date form is legal too; fall back to backoff rather than parse it.
+    return Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : null;
+}
+/**
+ * Full jitter. A synchronised retry storm from many clients is how a
+ * recovering service is knocked back over.
+ */
+function backoffMs(attempt, retryAfter) {
+    if (retryAfter !== null)
+        return Math.min(retryAfter, MAX_BACKOFF_MS);
+    return Math.min(MAX_BACKOFF_MS, Math.random() * 2 ** attempt * 1000);
+}
+function uuid() {
+    const c = globalThis.crypto;
+    if (c && typeof c.randomUUID === "function")
+        return c.randomUUID();
+    return `idem-${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+}
+/**
+ * Canon name -> EntityType, tolerating one this build has not heard of.
+ *
+ * An unknown type is passed through as a plain string rather than dropped:
+ * `Detection.entityType` is `EntityType | string` precisely so a client one
+ * release behind the service does not silently lose a whole category of PII.
+ */
+function toEntityType(raw) {
+    const canonical = canonicalType(raw);
+    const known = Object.values(EntityType).includes(canonical);
+    return known ? canonical : canonical;
+}
+/**
+ * Map the service's offsets, which count code points, onto this SDK's, which
+ * count UTF-16 units.
+ *
+ * The two agree until the first character outside the BMP — an emoji, say —
+ * after which every service offset is short by one unit per such character.
+ * Returns the identity when the text has none, which is the common case and
+ * costs one regex test.
+ */
+function codePointOffsets(text) {
+    if (!/[\uD800-\uDBFF]/.test(text))
+        return cp => cp;
+    const units = [];
+    let i = 0;
+    for (const ch of text) {
+        units.push(i);
+        i += ch.length;
+    }
+    units.push(i);
+    return cp => units[Math.min(cp, units.length - 1)];
+}
+function toResult(payload, text) {
+    const offset = codePointOffsets(text);
+    const detections = (payload.entities ?? []).map(span => ({
+        entityType: toEntityType(span.type),
+        start: offset(span.start),
+        end: offset(span.end),
+        text: span.text,
+        source: span.source === "model" ? DetectionSource.CLOUD : DetectionSource.RULES,
+        country: null,
+        confidence: span.confidence ?? "high",
+    }));
+    detections.sort((a, b) => a.start - b.start || b.end - a.end);
+    return {
+        redactedText: payload.redacted_text ?? text,
+        detections,
+        source: "cloud",
+        degraded: false,
+        inferredCountries: [],
+        evidence: [],
+        detectionMode: "declared",
+        tokens: {},
+        exempted: [],
+    };
+}
+export class CloudClient {
+    config;
+    constructor(config) {
+        const resolved = config ?? getConfig();
+        if (resolved === null)
+            throw new NotConfiguredError();
+        this.config = resolved;
+    }
+    headers(idempotencyKey) {
+        return {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "Content-Type": "application/json",
+            // A retry after a timeout must not create a second job or a second usage
+            // row. The key is per logical document, not per attempt.
+            "Idempotency-Key": idempotencyKey,
+            ...this.config.headers,
+        };
+    }
+    raiseFor(status, payload) {
+        const message = payload.error ?? `HTTP ${status}`;
+        const detail = payload.detail ?? {};
+        if (status === 401)
+            throw new CloudError(`authentication failed: ${message}`, status);
+        if (status === 413)
+            throw new TooLargeError(message, status, detail);
+        if (status === 429)
+            throw new QuotaExceededError(message, status, detail);
+        throw new CloudError(message, status, detail);
+    }
+    async redact(text, options) {
+        const doFetch = requireFetch(options.fetchImpl);
+        const key = options.idempotencyKey ?? uuid();
+        const body = JSON.stringify({
+            text,
+            country: options.country.toUpperCase(),
+            language: options.language ?? "",
+            priority: options.priority ?? "interactive",
+            rules_only: options.rulesOnly ?? false,
+        });
+        let attempt = 0;
+        for (;;) {
+            let response;
+            let payload = {};
+            try {
+                response = await this.withTimeout(doFetch, `${this.config.baseUrl}/v1/redact`, {
+                    method: "POST",
+                    headers: this.headers(key),
+                    body,
+                });
+                payload = await readJson(response);
+            }
+            catch (e) {
+                if (attempt >= this.config.maxRetries) {
+                    throw new CloudError(`cloud request failed: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            if (response) {
+                if (response.status === 202) {
+                    // Outlived the sync window. Location is where the answer will appear;
+                    // polling it is this client's job, not the caller's.
+                    const location = response.headers.get("Location") ??
+                        payload.location ??
+                        `/v1/jobs/${payload.job_id ?? ""}`;
+                    return toResult(await this.poll(doFetch, location, key), text);
+                }
+                if (response.status === 200)
+                    return toResult(payload, text);
+                if (!RETRY_STATUS.has(response.status) || attempt >= this.config.maxRetries) {
+                    this.raiseFor(response.status, payload);
+                }
+            }
+            await sleep(backoffMs(attempt, retryAfterMs(response?.headers)));
+            attempt++;
+        }
+    }
+    async poll(doFetch, location, key) {
+        const url = location.startsWith("http")
+            ? location
+            : `${this.config.baseUrl}${location}`;
+        const deadline = Date.now() + this.config.pollTimeoutMs;
+        let delay = 500;
+        for (;;) {
+            const response = await this.withTimeout(doFetch, url, {
+                method: "GET",
+                headers: this.headers(key),
+            });
+            const payload = await readJson(response);
+            if (response.status === 200 && payload.redacted_text !== undefined) {
+                return payload;
+            }
+            if (response.status !== 200 && !RETRY_STATUS.has(response.status)) {
+                this.raiseFor(response.status, payload);
+            }
+            if (Date.now() >= deadline) {
+                throw new CloudError(`document did not complete within ${Math.round(this.config.pollTimeoutMs / 1000)}s (${url})`);
+            }
+            const after = retryAfterMs(response.headers);
+            await sleep(after ?? delay);
+            delay = Math.min(delay * 1.5, 5000);
+        }
+    }
+    async withTimeout(doFetch, url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            return await doFetch(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+async function readJson(response) {
+    try {
+        const data = await response.json();
+        return data && typeof data === "object" ? data : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/esm/cloud/config.d.ts

@@ -0,0 +1,43 @@
+/** [CLOUD EXTENSION] Cloud tier configuration. */
+export declare const DEFAULT_BASE_URL = "https://api.euredact.dev";
+/**
+ * How long to wait for a single document. The service holds a connection open
+ * for its sync window and then hands back a job handle, so this has to exceed
+ * that window or the client abandons requests the service is about to answer.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 90000;
+/**
+ * Total wall-clock budget for a document that outlives the sync window and has
+ * to be polled. Cold-starting a GPU node and loading an ~18 GB checkpoint takes
+ * minutes, and an async job absorbs that invisibly — but not forever.
+ */
+export declare const DEFAULT_POLL_TIMEOUT_MS = 900000;
+export declare const DEFAULT_MAX_RETRIES = 3;
+export interface CloudConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+    pollTimeoutMs: number;
+    maxRetries: number;
+    /** Extra headers, for a proxy or a self-hosted deployment. */
+    headers: Record<string, string>;
+}
+export interface ConfigureOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    pollTimeoutMs?: number;
+    maxRetries?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Configure the cloud tier.
+ *
+ * Falls back to `EUREDACT_API_KEY` and `EUREDACT_BASE_URL` so a key never has
+ * to be written into source to get started.
+ */
+export declare function configure(options?: ConfigureOptions): CloudConfig;
+/** The active configuration, or null. Never throws. */
+export declare function getConfig(): CloudConfig | null;
+/** Forget the configuration. Mainly for tests. */
+export declare function reset(): void;

package/dist/esm/cloud/config.js

@@ -0,0 +1,51 @@
+/** [CLOUD EXTENSION] Cloud tier configuration. */
+export const DEFAULT_BASE_URL = "https://api.euredact.dev";
+/**
+ * How long to wait for a single document. The service holds a connection open
+ * for its sync window and then hands back a job handle, so this has to exceed
+ * that window or the client abandons requests the service is about to answer.
+ */
+export const DEFAULT_TIMEOUT_MS = 90_000;
+/**
+ * Total wall-clock budget for a document that outlives the sync window and has
+ * to be polled. Cold-starting a GPU node and loading an ~18 GB checkpoint takes
+ * minutes, and an async job absorbs that invisibly — but not forever.
+ */
+export const DEFAULT_POLL_TIMEOUT_MS = 900_000;
+export const DEFAULT_MAX_RETRIES = 3;
+let config = null;
+/** Read an env var where there is an environment to read. Browsers have none. */
+function env(name) {
+    const proc = globalThis.process;
+    return proc?.env?.[name];
+}
+/**
+ * Configure the cloud tier.
+ *
+ * Falls back to `EUREDACT_API_KEY` and `EUREDACT_BASE_URL` so a key never has
+ * to be written into source to get started.
+ */
+export function configure(options = {}) {
+    const apiKey = options.apiKey ?? env("EUREDACT_API_KEY") ?? "";
+    if (!apiKey) {
+        throw new Error("no API key: pass configure({ apiKey }) or set EUREDACT_API_KEY");
+    }
+    config = {
+        apiKey,
+        baseUrl: (options.baseUrl ?? env("EUREDACT_BASE_URL") ?? DEFAULT_BASE_URL)
+            .replace(/\/+$/, ""),
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        pollTimeoutMs: options.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS,
+        maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+        headers: { ...(options.headers ?? {}) },
+    };
+    return config;
+}
+/** The active configuration, or null. Never throws. */
+export function getConfig() {
+    return config;
+}
+/** Forget the configuration. Mainly for tests. */
+export function reset() {
+    config = null;
+}

package/dist/esm/cloud/errors.d.ts

@@ -0,0 +1,32 @@
+/** [CLOUD EXTENSION] Errors the cloud tier can raise. */
+export declare class CloudError extends Error {
+    readonly status?: number;
+    readonly detail: Record<string, unknown>;
+    constructor(message: string, status?: number, detail?: Record<string, unknown>);
+}
+/**
+ * Raised when the cloud tier is used without configuration.
+ *
+ * Deliberately an error rather than a quiet fallback to rules-only output.
+ * `mode: "cloud"` that silently returns rules-only results is the worst failure
+ * this library can have: the caller believes names, employers and diagnoses
+ * were checked, sees a plausible redacted document, and ships it with the PII
+ * still in it.
+ */
+export declare class NotConfiguredError extends CloudError {
+    constructor(message?: string);
+}
+/** 429 after retries were exhausted. */
+export declare class QuotaExceededError extends CloudError {
+    constructor(message: string, status?: number, detail?: Record<string, unknown>);
+}
+/**
+ * 413. The document is over the service's input cap.
+ *
+ * Permanent and not retryable. The model has never seen a chunk boundary, so
+ * the service refuses oversized input rather than splitting it and changing the
+ * accuracy story silently.
+ */
+export declare class TooLargeError extends CloudError {
+    constructor(message: string, status?: number, detail?: Record<string, unknown>);
+}

package/dist/esm/cloud/errors.js

@@ -0,0 +1,48 @@
+/** [CLOUD EXTENSION] Errors the cloud tier can raise. */
+export class CloudError extends Error {
+    status;
+    detail;
+    constructor(message, status, detail) {
+        super(message);
+        this.name = "CloudError";
+        this.status = status;
+        this.detail = detail ?? {};
+    }
+}
+/**
+ * Raised when the cloud tier is used without configuration.
+ *
+ * Deliberately an error rather than a quiet fallback to rules-only output.
+ * `mode: "cloud"` that silently returns rules-only results is the worst failure
+ * this library can have: the caller believes names, employers and diagnoses
+ * were checked, sees a plausible redacted document, and ships it with the PII
+ * still in it.
+ */
+export class NotConfiguredError extends CloudError {
+    constructor(message) {
+        super(message ??
+            "Cloud tier not configured. Call euredact.configure({ apiKey }) first, " +
+                "or set EUREDACT_API_KEY.");
+        this.name = "NotConfiguredError";
+    }
+}
+/** 429 after retries were exhausted. */
+export class QuotaExceededError extends CloudError {
+    constructor(message, status, detail) {
+        super(message, status, detail);
+        this.name = "QuotaExceededError";
+    }
+}
+/**
+ * 413. The document is over the service's input cap.
+ *
+ * Permanent and not retryable. The model has never seen a chunk boundary, so
+ * the service refuses oversized input rather than splitting it and changing the
+ * accuracy story silently.
+ */
+export class TooLargeError extends CloudError {
+    constructor(message, status, detail) {
+        super(message, status, detail);
+        this.name = "TooLargeError";
+    }
+}

package/dist/esm/cloud/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * [CLOUD EXTENSION] Cloud tier — rules engine plus a fine-tuned model.
+ *
+ * The rule engine catches what has a shape: IBANs, national IDs, phone
+ * numbers, anything with a checksum. It cannot catch what does not — a
+ * person's name, an employer, a diagnosis, a job title. Those are what the
+ * cloud tier adds, and the `EntityType` members marked `[CLOUD EXTENSION]` are
+ * exactly that gap.
+ *
+ * ```ts
+ * import { configure, redactAsync } from "euredact";
+ *
+ * configure({ apiKey: "erk_..." });
+ * const result = await redactAsync(text, { countries: ["BE"], mode: "cloud" });
+ * ```
+ */
+export { CloudClient, type CloudRedactOptions } from "./client.js";
+export { configure, getConfig, reset, DEFAULT_BASE_URL, type CloudConfig, type ConfigureOptions, } from "./config.js";
+export { CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./errors.js";

package/dist/esm/cloud/index.js

@@ -0,0 +1,19 @@
+/**
+ * [CLOUD EXTENSION] Cloud tier — rules engine plus a fine-tuned model.
+ *
+ * The rule engine catches what has a shape: IBANs, national IDs, phone
+ * numbers, anything with a checksum. It cannot catch what does not — a
+ * person's name, an employer, a diagnosis, a job title. Those are what the
+ * cloud tier adds, and the `EntityType` members marked `[CLOUD EXTENSION]` are
+ * exactly that gap.
+ *
+ * ```ts
+ * import { configure, redactAsync } from "euredact";
+ *
+ * configure({ apiKey: "erk_..." });
+ * const result = await redactAsync(text, { countries: ["BE"], mode: "cloud" });
+ * ```
+ */
+export { CloudClient } from "./client.js";
+export { configure, getConfig, reset, DEFAULT_BASE_URL, } from "./config.js";
+export { CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./errors.js";

package/dist/esm/index.d.ts

@@ -1,13 +1,21 @@
-export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES } from "./types.js";
-export type { Detection, RedactResult, PatternDef, CountryConfig, CountryEvidence } from "./types.js";
+export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES, canonicalType } from "./types.js";
+export type { Detection, Exemption, RedactResult, PatternDef, CountryConfig, CountryEvidence } from "./types.js";
 export { DocumentContext } from "./rules/context.js";
-export { EuRedact, type RedactOptions } from "./sdk.js";
+export { EuRedact, restore, type RedactOptions } from "./sdk.js";
 export { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 export { setBicRegistry, getBicRegistry, SEED_BIC6_PREFIXES, type BicRegistryProvider } from "./rules/bicRegistry.js";
+export { configure, getConfig, CloudClient, CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, type CloudConfig, type ConfigureOptions, type CloudRedactOptions, } from "./cloud/index.js";
 import { type RedactOptions } from "./sdk.js";
 import type { RedactResult } from "./types.js";
 export declare function availableCountries(): string[];
 export declare function redact(text: string, options?: RedactOptions): RedactResult;
+/**
+ * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
+ *
+ * `mode: "rules"` resolves immediately with exactly what `redact()` returns,
+ * so a caller that may or may not use the cloud tier can hold one code path.
+ */
+export declare function redactAsync(text: string, options?: RedactOptions): Promise<RedactResult>;
 export declare function addCustomPattern(name: string, pattern: string): void;
 export declare function clear(): void;
 export declare function redactBatch(texts: string[], options?: RedactOptions): RedactResult[];

package/dist/esm/index.js

@@ -1,8 +1,9 @@
-export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES } from "./types.js";
+export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES, canonicalType } from "./types.js";
 export { DocumentContext } from "./rules/context.js";
-export { EuRedact } from "./sdk.js";
+export { EuRedact, restore } from "./sdk.js";
 export { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 export { setBicRegistry, getBicRegistry, SEED_BIC6_PREFIXES } from "./rules/bicRegistry.js";
+export { configure, getConfig, CloudClient, CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./cloud/index.js";
 import { EuRedact } from "./sdk.js";
 import { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 let _instance = null;
@@ -17,6 +18,15 @@ export function availableCountries() {
 export function redact(text, options) {
     return getInstance().redact(text, options);
 }
+/**
+ * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
+ *
+ * `mode: "rules"` resolves immediately with exactly what `redact()` returns,
+ * so a caller that may or may not use the cloud tier can hold one code path.
+ */
+export function redactAsync(text, options) {
+    return getInstance().redactAsync(text, options);
+}
 export function addCustomPattern(name, pattern) {
     getInstance().addCustomPattern(name, pattern);
 }

package/dist/esm/rules/countries/index.js

@@ -96,7 +96,14 @@ const SHARED = {
         // is Unicode-aware) matched local parts like "petras_ž@..." while this one
         // did not. \p{L}\p{N} with the `u` flag restores parity; the leading guard
         // is a Unicode-safe word boundary.
-        p(EntityType.EMAIL, String.raw `(?<![\p{L}\p{N}._%+\-])[\p{L}\p{N}._%+\-]+@(?:[\p{L}\p{N}\-]+\.)+\p{L}{2,}\b`),
+        // The apostrophe is allowed only between word characters: it belongs in a
+        // local part, but putting it in the class would let the match absorb a
+        // quote from the surrounding text, while leaving it out made
+        // `johno'neill@outlook.ie` mask as `johno'[EMAIL]` (issue rules-engine#10).
+        // The second lookbehind refuses to start a match after `<word-char>'`,
+        // which is a match already in progress; without it every apostrophe was a
+        // fresh start offset and the scan went quadratic. Mirrors Python.
+        p(EntityType.EMAIL, String.raw `(?<![\p{L}\p{N}._%+\-])(?<![\p{L}\p{N}._%+\-]')[\p{L}\p{N}._%+\-]+(?:'[\p{L}\p{N}._%+\-]+)*@(?:[\p{L}\p{N}\-]+\.)+\p{L}{2,}\b`),
         // IBAN (any country) — structure + mod-97 only. Country-specific IBAN
         // patterns still exist and win on identical spans; this one guarantees an
         // IBAN is never missed just because its country was not requested.
@@ -106,7 +113,11 @@ const SHARED = {
         // "+43 664 8213 907" was invisible to the Austrian pattern, which expects
         // an unbroken subscriber number. A leading "+" is self-identifying, so
         // this is deliberately not country-gated.
-        p(EntityType.PHONE, String.raw `\+\d{1,3}(?:[\s\-/]?\(?\d{1,4}\)?){2,7}`, "e164", "International phone number (E.164) — any country"),
+        // Parentheses are matched as a pair inside one group: `\(?...\)?` let the
+        // closing parenthesis of the surrounding text join the number, so
+        // "Call (+32 475 12 34 56) today." also masked the ")" (issue
+        // rules-engine#3). Mirrors the Python pattern character for character.
+        p(EntityType.PHONE, String.raw `\+\d{1,3}(?:[\s\-/]?(?:\(\d{1,4}\)|\d{1,4})){2,7}`, "e164", "International phone number (E.164) — any country"),
         p(EntityType.BIC, String.raw `\b[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?\b`, "bic"),
         // Space-separated form: "RZBA AT WW", "NICA BE BB". Written as a separate
         // pattern requiring a space between *every* group, rather than making the
@@ -117,7 +128,15 @@ const SHARED = {
         p(EntityType.CREDIT_CARD, String.raw `\b(?:4[0-9]{3}[\s\-]?[0-9]{4}[\s\-]?[0-9]{4}[\s\-]?[0-9]{4}|5[1-5][0-9]{2}[\s\-]?[0-9]{4}[\s\-]?[0-9]{4}[\s\-]?[0-9]{4}|3[47][0-9]{2}[\s\-]?[0-9]{6}[\s\-]?[0-9]{5})\b`, "luhn"),
         p(EntityType.VIN, String.raw `\b[A-HJ-NPR-Z0-9]{17}\b`, "vin"),
         p(EntityType.IP_ADDRESS, String.raw `\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b`),
-        p(EntityType.IPV6_ADDRESS, String.raw `\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b|\b(?:[0-9a-fA-F]{1,4}:){1,7}:\b|\b(?:[0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}\b|\b::(?:[0-9a-fA-F]{1,4}:){0,5}[0-9a-fA-F]{1,4}\b`),
+        // Branch order is load-bearing: alternation is leftmost-first, not
+        // longest-match, so the form that consumes most is tried first, and the
+        // IPv4-embedded branches lead because every group of a dotted quad is
+        // also valid hex. `\b` is the wrong anchor around ":" (a non-word
+        // character), which is why `::1` and `2001:db8::` were not detected at
+        // all. A bare "::" is deliberately not matched. Mirrors the Python
+        // pattern character for character -- see the comment there
+        // (issue rules-engine#5).
+        p(EntityType.IPV6_ADDRESS, String.raw `(?<![0-9A-Za-z_:.])(?:(?:[0-9A-Fa-f]{1,4}:){6}(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])|(?:[0-9A-Fa-f]{1,4}:){1,5}:(?:[0-9A-Fa-f]{1,4}:)*(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])|::(?:[0-9A-Fa-f]{1,4}:)*(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])|(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,7}(?::[0-9A-Fa-f]{1,4}){1,7}|(?:[0-9A-Fa-f]{1,4}:){1,7}:|:(?::[0-9A-Fa-f]{1,4}){1,7})(?:%[0-9A-Za-z][0-9A-Za-z._-]*)?(?![0-9A-Za-z_:])`),
         p(EntityType.MAC_ADDRESS, String.raw `\b(?:[0-9a-fA-F]{2}[:\-]){5}[0-9a-fA-F]{2}\b`, null, "colon/dash"),
         p(EntityType.MAC_ADDRESS, String.raw `\b[0-9a-fA-F]{4}\.[0-9a-fA-F]{4}\.[0-9a-fA-F]{4}\b`, null, "Cisco"),
         p(EntityType.IMEI, String.raw `\b\d{15}\b`, "imei"),
@@ -221,12 +240,12 @@ const DE = {
     patterns: [
         p(EntityType.TAX_ID, String.raw `\b[1-9]\d{10}\b`, "german_tax_id"),
         p(EntityType.TAX_ID, String.raw `\b[1-9]\d[\s.]?\d{3}[\s.]?\d{3}[\s.]?\d{3}\b`, "german_tax_id"),
-        p(EntityType.NATIONAL_ID, String.raw `\b[CFGHJKLMNPRTVWXYZ][0-9A-Z]{8,9}\b`, null, "", ["Personalausweis", "Personalausweisnummer", "Ausweis", "Ausweisnummer", "Ausweis-Nr", "identity card", "Identitätskarte", "Perso", "PA-Nummer"], true),
+        p(EntityType.NATIONAL_ID, String.raw `\b[CFGHJKLMNPRTVWXYZ][0-9CFGHJKLMNPRTVWXYZ]{8}\d?\b`, null, "", ["Personalausweis", "Personalausweisnummer", "Ausweis", "Ausweisnummer", "Ausweis-Nr", "identity card", "Identitätskarte", "Perso", "PA-Nummer"], true),
         p(EntityType.IBAN, String.raw `\bDE\d{2}\s?\d{4}\s?\d{4}\s?\d{4}\s?\d{4}\s?\d{2}\b`, "iban"),
         p(EntityType.VAT, String.raw `\bDE\s?\d{9}\b`, "vat_de"),
         p(EntityType.PHONE, String.raw `\b0[1-9]\d{1,4}[\s/\-]?\d{3,8}\b`),
         p(EntityType.PHONE, String.raw `\+49\s?\d{2,5}[\s/\-]?\d{3,8}\b`),
-        p(EntityType.PASSPORT, String.raw `\b[CFGHJK][0-9A-Z]{8,9}\b`, null, "", ["Reisepass", "passport", "Passnummer", "Reisepassnummer", "Reisepass Nummer", "Reisepass-Nr", "Pass Nr"], true),
+        p(EntityType.PASSPORT, String.raw `\b[CFGHJK][0-9CFGHJKLMNPRTVWXYZ]{8}\d?\b`, null, "", ["Reisepass", "passport", "Passnummer", "Reisepassnummer", "Reisepass Nummer", "Reisepass-Nr", "Pass Nr"], true),
         // The separator after the city code is mandatory. When it was optional, a
         // contiguous letter run split across both groups and the hyphen was
         // consumed as the *second* separator, so any "LETTERS-DIGITS" token