fa-redact 0.1.0__py3-none-any.whl

fa_redact/__init__.py

@@ -0,0 +1,37 @@
+"""fa-redact: Privacy-first Persian/Iranian PII redaction and pseudonymization toolkit.
+
+This package is currently in early development.
+"""
+
+from fa_redact.detectors import (
+    IranianMobileNumberDetector,
+    IranianNationalIDDetector,
+)
+from fa_redact.models import Detection
+from fa_redact.normalization import (
+    normalize_digits,
+    normalize_letters,
+    normalize_text,
+)
+from fa_redact.pipeline import detect
+from fa_redact.protocols import Detector
+from fa_redact.pseudonymization import PseudonymizationSession
+from fa_redact.redaction import redact
+from fa_redact.validators import is_valid_mobile_number, is_valid_national_id
+
+__version__: str = "0.1.0"
+__all__: list[str] = [
+    "__version__",
+    "Detection",
+    "Detector",
+    "IranianMobileNumberDetector",
+    "IranianNationalIDDetector",
+    "PseudonymizationSession",
+    "detect",
+    "is_valid_mobile_number",
+    "is_valid_national_id",
+    "normalize_digits",
+    "normalize_letters",
+    "normalize_text",
+    "redact",
+]

fa_redact/detectors/__init__.py

@@ -0,0 +1,8 @@
+"""Identifier detectors for fa-redact."""
+
+from __future__ import annotations
+
+from fa_redact.detectors.mobile import IranianMobileNumberDetector
+from fa_redact.detectors.national_id import IranianNationalIDDetector
+
+__all__ = ["IranianMobileNumberDetector", "IranianNationalIDDetector"]

fa_redact/detectors/mobile.py

@@ -0,0 +1,62 @@
+"""Detector for Iranian mobile phone numbers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from fa_redact.models import Detection
+from fa_redact.validators.mobile import is_valid_mobile_number
+
+_ENTITY_TYPE: str = "IR_MOBILE"
+_CANDIDATE_PATTERN: re.Pattern[str] = re.compile(
+    r"(?<![0-9+])(?:\+98[0-9]{10}|0098[0-9]{10}|0[0-9]{10})(?![0-9])"
+)
+
+
+class IranianMobileNumberDetector:
+    """Detects prefix-valid Iranian mobile numbers in text.
+
+    Scans position-preserving normalized text for compact domestic and international
+    mobile candidates, validates them against official 2026 CRA NDC mobile prefixes,
+    and returns Detection instances preserving both raw and normalized representations.
+    """
+
+    def detect(
+        self,
+        original_text: str,
+        normalized_text: str,
+    ) -> Sequence[Detection]:
+        """Detect Iranian mobile numbers across source texts.
+
+        Args:
+            original_text: Raw input text.
+            normalized_text: Position-preserving normalized text of identical length.
+
+        Returns:
+            List of detected Detection instances in textual order.
+
+        Raises:
+            ValueError: If original_text and normalized_text differ in length.
+        """
+        if len(original_text) != len(normalized_text):
+            raise ValueError(
+                f"original_text length ({len(original_text)}) must equal "
+                f"normalized_text length ({len(normalized_text)})"
+            )
+
+        detections: list[Detection] = []
+        for match in _CANDIDATE_PATTERN.finditer(normalized_text):
+            candidate = match.group(0)
+            if is_valid_mobile_number(candidate):
+                detections.append(
+                    Detection.from_texts(
+                        type=_ENTITY_TYPE,
+                        original_text=original_text,
+                        normalized_text=normalized_text,
+                        start=match.start(),
+                        end=match.end(),
+                    )
+                )
+
+        return detections

fa_redact/detectors/national_id.py

@@ -0,0 +1,60 @@
+"""Detector for Iranian individual National IDs (Code Melli)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from fa_redact.models import Detection
+from fa_redact.validators.national_id import is_valid_national_id
+
+_ENTITY_TYPE: str = "IR_NATIONAL_ID"
+_CANDIDATE_PATTERN: re.Pattern[str] = re.compile(r"(?<![0-9])[0-9]{10}(?![0-9])")
+
+
+class IranianNationalIDDetector:
+    """Detects checksum-valid Iranian National IDs (Code Melli) in text.
+
+    Scans position-preserving normalized text for 10-digit candidate sequences,
+    validates their modulo-11 checksums, and constructs Detection instances
+    preserving both original raw and normalized representations.
+    """
+
+    def detect(
+        self,
+        original_text: str,
+        normalized_text: str,
+    ) -> Sequence[Detection]:
+        """Detect Iranian National IDs across source texts.
+
+        Args:
+            original_text: Raw input text.
+            normalized_text: Position-preserving normalized text of identical length.
+
+        Returns:
+            List of detected Detection instances in textual order.
+
+        Raises:
+            ValueError: If original_text and normalized_text differ in length.
+        """
+        if len(original_text) != len(normalized_text):
+            raise ValueError(
+                f"original_text length ({len(original_text)}) must equal "
+                f"normalized_text length ({len(normalized_text)})"
+            )
+
+        detections: list[Detection] = []
+        for match in _CANDIDATE_PATTERN.finditer(normalized_text):
+            candidate = match.group(0)
+            if is_valid_national_id(candidate):
+                detections.append(
+                    Detection.from_texts(
+                        type=_ENTITY_TYPE,
+                        original_text=original_text,
+                        normalized_text=normalized_text,
+                        start=match.start(),
+                        end=match.end(),
+                    )
+                )
+
+        return detections

fa_redact/models.py

@@ -0,0 +1,103 @@
+"""Data models for detected identifiers and PII in fa-redact."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Detection:
+    """Represents an immutable detected identifier span in text.
+
+    Preserves both the original raw string representation and the
+    position-preserving normalized representation.
+
+    Attributes:
+        type: Extensible entity identifier type (e.g., 'IR_NATIONAL_ID', 'PATIENT_ID').
+        start: Inclusive start character offset in original text.
+        end: Exclusive end character offset in original text.
+        value: Exact substring extracted from original text.
+        normalized_value: Exact substring extracted from normalized text.
+    """
+
+    type: str
+    start: int
+    end: int
+    value: str
+    normalized_value: str
+
+    def __post_init__(self) -> None:
+        """Validate detection field invariants."""
+        if not isinstance(self.type, str) or not self.type.strip():
+            raise ValueError("type must be a non-empty, non-whitespace string")
+        if self.start < 0:
+            raise ValueError(f"start must be >= 0, got {self.start}")
+        if self.end <= self.start:
+            raise ValueError(
+                f"end ({self.end}) must be strictly greater than start ({self.start})"
+            )
+        expected_len = self.end - self.start
+        if len(self.value) != expected_len:
+            raise ValueError(
+                f"len(value) ({len(self.value)}) does not match "
+                f"span length ({expected_len})"
+            )
+        if len(self.normalized_value) != expected_len:
+            raise ValueError(
+                f"len(normalized_value) ({len(self.normalized_value)}) "
+                f"does not match span length ({expected_len})"
+            )
+
+    @classmethod
+    def from_texts(
+        cls,
+        *,
+        type: str,
+        original_text: str,
+        normalized_text: str,
+        start: int,
+        end: int,
+    ) -> Detection:
+        """Safely construct a Detection by slicing source texts.
+
+        Extracts `value` from `original_text[start:end]` and `normalized_value`
+        from `normalized_text[start:end]`.
+
+        Args:
+            type: Extensible entity identifier type.
+            original_text: Raw input text.
+            normalized_text: Position-preserving normalized text of equal length.
+            start: Inclusive start character index.
+            end: Exclusive end character index.
+
+        Returns:
+            Immutable Detection with slices from original and normalized texts.
+
+        Raises:
+            ValueError: If texts differ in length, offsets are invalid, or
+                offsets fall outside string boundaries.
+        """
+        if len(original_text) != len(normalized_text):
+            raise ValueError(
+                f"original_text length ({len(original_text)}) must equal "
+                f"normalized_text length ({len(normalized_text)})"
+            )
+        if start < 0 or end > len(original_text):
+            raise ValueError(
+                f"Offsets [{start}:{end}] are out of bounds [0:{len(original_text)}]"
+            )
+        if end <= start:
+            raise ValueError(
+                f"end ({end}) must be strictly greater than start ({start})"
+            )
+
+        value = original_text[start:end]
+        normalized_value = normalized_text[start:end]
+
+        return cls(
+            type=type,
+            start=start,
+            end=end,
+            value=value,
+            normalized_value=normalized_value,
+        )

fa_redact/normalization.py

@@ -0,0 +1,102 @@
+"""Position-preserving Persian and Arabic-Indic text normalization.
+
+This module provides deterministic, 1-to-1 Unicode code point transformations
+designed to normalize digits and common Arabic letter variants without altering
+character positions or string length.
+
+Architectural Invariant:
+    For every string `s`, the following holds:
+        len(normalize_digits(s)) == len(s)
+        len(normalize_letters(s)) == len(s)
+        len(normalize_text(s)) == len(s)
+
+This invariant ensures that character offsets (start/end indices) computed on
+normalized text map 1-to-1 to the original input text.
+"""
+
+from __future__ import annotations
+
+# Mapping Persian (Extended Arabic-Indic) digits and Arabic-Indic digits to ASCII digits
+_PERSIAN_DIGITS = "۰۱۲۳۴۵۶۷۸۹"
+_ARABIC_INDIC_DIGITS = "٠١٢٣٤٥٦٧٨٩"
+_ASCII_DIGITS = "0123456789"
+
+_DIGIT_TRANSLATION_TABLE: dict[int, int] = str.maketrans(
+    _PERSIAN_DIGITS + _ARABIC_INDIC_DIGITS,
+    _ASCII_DIGITS + _ASCII_DIGITS,
+)
+
+# Mapping Arabic letter variants to Persian standard code points
+# ي (U+064A) -> ی (U+06CC)
+# ك (U+0643) -> ک (U+06A9)
+_ARABIC_LETTERS = "يك"
+_PERSIAN_LETTERS = "یک"
+
+_LETTER_TRANSLATION_TABLE: dict[int, int] = str.maketrans(
+    _ARABIC_LETTERS,
+    _PERSIAN_LETTERS,
+)
+
+# Combined translation table for all supported 1-to-1 normalizations
+_ALL_TRANSLATION_TABLE: dict[int, int] = {
+    **_DIGIT_TRANSLATION_TABLE,
+    **_LETTER_TRANSLATION_TABLE,
+}
+
+
+def normalize_digits(text: str) -> str:
+    """Normalize Persian and Arabic-Indic digits to ASCII digits.
+
+    Transforms:
+        ۰-۹ (U+06F0..U+06F9) -> 0-9 (U+0030..U+0039)
+        ٠-٩ (U+0660..U+0669) -> 0-9 (U+0030..U+0039)
+
+    Guarantees:
+        len(normalize_digits(text)) == len(text)
+
+    Args:
+        text: Input string.
+
+    Returns:
+        String with all Persian and Arabic-Indic digits replaced by ASCII digits.
+    """
+    return text.translate(_DIGIT_TRANSLATION_TABLE)
+
+
+def normalize_letters(text: str) -> str:
+    """Normalize common Arabic letter variants to Persian code points.
+
+    Transforms only:
+        ي (U+064A ARABIC LETTER YEH) -> ی (U+06CC ARABIC LETTER FARSI YEH)
+        ك (U+0643 ARABIC LETTER KAF) -> ک (U+06A9 ARABIC LETTER KEHEH)
+
+    Other Arabic characters (such as ى, ة, ۀ, ؤ, إ, أ) remain unchanged.
+
+    Guarantees:
+        len(normalize_letters(text)) == len(text)
+
+    Args:
+        text: Input string.
+
+    Returns:
+        String with supported Arabic letter variants replaced by Persian equivalents.
+    """
+    return text.translate(_LETTER_TRANSLATION_TABLE)
+
+
+def normalize_text(text: str) -> str:
+    """Apply position-preserving normalization (digits and supported letters).
+
+    Combines digit normalization (Persian and Arabic-Indic -> ASCII) and
+    letter normalization (ي -> ی, ك -> ک).
+
+    Guarantees:
+        len(normalize_text(text)) == len(text)
+
+    Args:
+        text: Input string.
+
+    Returns:
+        Normalized string with identical length and preserved character offsets.
+    """
+    return text.translate(_ALL_TRANSLATION_TABLE)

fa_redact/pipeline.py

@@ -0,0 +1,61 @@
+"""High-level detection pipeline for fa-redact."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from fa_redact.detectors.mobile import IranianMobileNumberDetector
+from fa_redact.detectors.national_id import IranianNationalIDDetector
+from fa_redact.models import Detection
+from fa_redact.normalization import normalize_text
+from fa_redact.protocols import Detector
+
+_DEFAULT_DETECTORS: tuple[Detector, ...] = (
+    IranianNationalIDDetector(),
+    IranianMobileNumberDetector(),
+)
+
+
+def detect(
+    text: str,
+    *,
+    detectors: Sequence[Detector] | None = None,
+) -> list[Detection]:
+    """Detect Iranian PII entities in text using built-in or custom detectors.
+
+    Applies position-preserving normalization at the pipeline boundary and runs
+    each configured detector, returning detected entity spans sorted deterministically
+    by character offset.
+
+    Args:
+        text: Input string to scan for PII.
+        detectors: Sequence of Detector instances to execute. If None (default),
+            uses all built-in detectors (IranianNationalIDDetector,
+            IranianMobileNumberDetector). If an explicit empty sequence (e.g. `[]`),
+            no detectors are executed and an empty list is returned.
+
+    Returns:
+        List of Detection instances sorted by `(start, end, type)`.
+
+    Raises:
+        TypeError: If `text` is not a string.
+    """
+    if not isinstance(text, str):
+        raise TypeError(f"text must be a str, got {type(text).__name__}")
+
+    if detectors is None:
+        active_detectors: Sequence[Detector] = _DEFAULT_DETECTORS
+    else:
+        active_detectors = detectors
+
+    if not active_detectors:
+        return []
+
+    normalized_text = normalize_text(text)
+    detections: list[Detection] = []
+
+    for detector in active_detectors:
+        detections.extend(detector.detect(text, normalized_text))
+
+    detections.sort(key=lambda d: (d.start, d.end, d.type))
+    return detections

fa_redact/protocols.py

@@ -0,0 +1,33 @@
+"""Protocols defining structural contracts for fa-redact components."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from fa_redact.models import Detection
+
+
+class Detector(Protocol):
+    """Structural interface for identifier detectors.
+
+    Detectors receive both the raw original text and the position-preserving
+    normalized text (guaranteed to have the exact same length), and return a
+    sequence of detected entity spans whose offsets map identically onto both.
+    """
+
+    def detect(
+        self,
+        original_text: str,
+        normalized_text: str,
+    ) -> Sequence[Detection]:
+        """Detect identifier spans across source texts.
+
+        Args:
+            original_text: Original, unmodified input text.
+            normalized_text: Position-preserving normalized text of identical length.
+
+        Returns:
+            Sequence of detected Detection instances.
+        """
+        ...

fa_redact/pseudonymization.py

@@ -0,0 +1,166 @@
+"""Stateful pseudonymization sessions with stable mappings and safe restoration."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from fa_redact.pipeline import detect
+from fa_redact.protocols import Detector
+
+_PLACEHOLDER_PATTERN = re.compile(r"\[[^\[\]\r\n]+_[1-9][0-9]*\]")
+
+
+class PseudonymizationSession:
+    """Stateful pseudonymization session for Iranian PII.
+
+    Maintains a local-only mapping between detected PII identities and stable,
+    typed placeholders across multiple messages or conversation turns. Allows
+    safe restoration of placeholders in downstream AI/LLM responses.
+    """
+
+    def __init__(self) -> None:
+        self._identity_to_placeholder: dict[tuple[str, str], str] = {}
+        self._placeholder_to_value: dict[str, str] = {}
+        self._counters_by_type: dict[str, int] = {}
+        self._reserved_placeholders: set[str] = set()
+
+    @property
+    def mapping(self) -> dict[str, str]:
+        """Return a shallow copy of the placeholder-to-value mapping.
+
+        The returned mapping contains original sensitive PII values and must
+        be treated as sensitive data.
+        """
+        return self._placeholder_to_value.copy()
+
+    def pseudonymize(
+        self,
+        text: str,
+        *,
+        detectors: Sequence[Detector] | None = None,
+    ) -> str:
+        """Pseudonymize detected PII in text using stable, typed placeholders.
+
+        Identities are tracked across calls on this session. If an identifier
+        with the same entity type and normalized value was previously observed,
+        its existing placeholder is reused. New identifiers receive subsequent
+        per-type indices and record their first-observed raw representation for
+        future restoration.
+
+        Args:
+            text: Input string to pseudonymize.
+            detectors: Optional sequence of Detector instances to execute. If None,
+                uses default built-in detectors. If `[]`, no detectors run.
+
+        Returns:
+            The pseudonymized string with detected spans replaced by placeholders.
+
+        Raises:
+            TypeError: If `text` is not a string.
+            ValueError: If `text` contains a placeholder already assigned by this
+                session, or if detected spans overlap.
+        """
+        if not isinstance(text, str):
+            raise TypeError(f"text must be a str, got {type(text).__name__}")
+
+        # Extract placeholder-shaped literal tokens from input
+        literal_tokens = set(_PLACEHOLDER_PATTERN.findall(text))
+
+        # Check for conflicts with existing mapped placeholders in this session
+        assigned_keys = set(self._placeholder_to_value.keys())
+        conflicts = sorted(literal_tokens & assigned_keys)
+        if conflicts:
+            raise ValueError(
+                "Input contains a placeholder already assigned by this "
+                f"session: {conflicts[0]}"
+            )
+
+        # Work on isolated copies to guarantee atomic updates
+        temp_reserved_placeholders = self._reserved_placeholders.copy()
+        temp_reserved_placeholders.update(literal_tokens)
+        temp_identity_to_placeholder = self._identity_to_placeholder.copy()
+        temp_placeholder_to_value = self._placeholder_to_value.copy()
+        temp_counters_by_type = self._counters_by_type.copy()
+        assigned_placeholders = assigned_keys.copy()
+
+        detections = detect(text, detectors=detectors)
+        if not detections:
+            # Commit reserved literals even when no PII is detected
+            self._reserved_placeholders = temp_reserved_placeholders
+            return text
+
+        # Validate that detections do not overlap, nest, or duplicate
+        for i in range(1, len(detections)):
+            prev = detections[i - 1]
+            curr = detections[i]
+            if curr.start < prev.end:
+                raise ValueError(
+                    f"Overlapping detections at spans [{prev.start}:{prev.end}] "
+                    f"({prev.type}) and [{curr.start}:{curr.end}] ({curr.type})"
+                )
+
+        pieces: list[str] = []
+        cursor = 0
+
+        for d in detections:
+            identity = (d.type, d.normalized_value)
+            placeholder: str | None = temp_identity_to_placeholder.get(identity)
+            if placeholder is None:
+                counter = temp_counters_by_type.get(d.type, 0)
+                while True:
+                    counter += 1
+                    candidate = f"[{d.type}_{counter}]"
+                    if (
+                        candidate not in text
+                        and candidate not in assigned_placeholders
+                        and candidate not in temp_reserved_placeholders
+                    ):
+                        placeholder = candidate
+                        break
+                temp_counters_by_type[d.type] = counter
+                temp_identity_to_placeholder[identity] = placeholder
+                # Record first observed raw representation for restoration:
+                temp_placeholder_to_value[placeholder] = d.value
+                assigned_placeholders.add(placeholder)
+
+            assert placeholder is not None
+            pieces.append(text[cursor : d.start])
+            pieces.append(placeholder)
+            cursor = d.end
+
+        pieces.append(text[cursor:])
+        result = "".join(pieces)
+
+        # Commit state atomically
+        self._reserved_placeholders = temp_reserved_placeholders
+        self._identity_to_placeholder = temp_identity_to_placeholder
+        self._placeholder_to_value = temp_placeholder_to_value
+        self._counters_by_type = temp_counters_by_type
+        return result
+
+    def restore(self, text: str) -> str:
+        """Restore mapped placeholders in text to their original raw values.
+
+        Performs a single-pass regex replacement of exact known placeholders to
+        prevent cascading restoration. Unrecognized placeholders remain untouched.
+
+        Args:
+            text: Input string (e.g. LLM response) containing placeholders.
+
+        Returns:
+            The restored string with known placeholders replaced.
+
+        Raises:
+            TypeError: If `text` is not a string.
+        """
+        if not isinstance(text, str):
+            raise TypeError(f"text must be a str, got {type(text).__name__}")
+
+        if not self._placeholder_to_value or not text:
+            return text
+
+        # Sort descending by length for defensive matching
+        patterns = sorted(self._placeholder_to_value.keys(), key=len, reverse=True)
+        pattern = re.compile("|".join(re.escape(p) for p in patterns))
+        return pattern.sub(lambda m: self._placeholder_to_value[m.group(0)], text)

fa_redact/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 (inline type annotations).

fa_redact/redaction.py

@@ -0,0 +1,37 @@
+"""Safe placeholder-based redaction for fa-redact."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from fa_redact.protocols import Detector
+from fa_redact.pseudonymization import PseudonymizationSession
+
+
+def redact(
+    text: str,
+    *,
+    detectors: Sequence[Detector] | None = None,
+) -> str:
+    """Redact detected Iranian PII using typed, referentially-consistent placeholders.
+
+    Runs the detection pipeline and replaces identified spans with deterministic,
+    typed placeholders (e.g. `[IR_NATIONAL_ID_1]`, `[IR_MOBILE_1]`). Within a single
+    call, repeated occurrences of the same identifier (matching entity type and
+    normalized value) receive the same placeholder.
+
+    Args:
+        text: Input string to redact.
+        detectors: Optional sequence of Detector instances to execute. If None,
+            uses all default built-in detectors. If an explicit empty sequence
+            (e.g. `[]`), no detectors run and the original text is returned unchanged.
+
+    Returns:
+        The redacted string with detected spans replaced by placeholders.
+
+    Raises:
+        TypeError: If `text` is not a string.
+        ValueError: If any detected spans overlap, are nested, or are exact duplicates.
+    """
+    session = PseudonymizationSession()
+    return session.pseudonymize(text, detectors=detectors)

fa_redact/validators/__init__.py

@@ -0,0 +1,8 @@
+"""Validation functions for Iranian identifiers."""
+
+from __future__ import annotations
+
+from fa_redact.validators.mobile import is_valid_mobile_number
+from fa_redact.validators.national_id import is_valid_national_id
+
+__all__ = ["is_valid_mobile_number", "is_valid_national_id"]

fa_redact/validators/mobile.py

@@ -0,0 +1,119 @@
+"""Iranian Mobile Number validation based on the 2026 CRA numbering plan."""
+
+from __future__ import annotations
+
+from fa_redact.normalization import normalize_digits
+
+# Official Mobile services NDC prefixes from the 2026 CRA/ITU-T Numbering Plan snapshot.
+# Ranges such as 94... (fixed/non-geographical) and 9950... (public trunk) are excluded.
+_MOBILE_NDC_PREFIXES: tuple[str, ...] = (
+    "900",
+    "901",
+    "902",
+    "903",
+    "904",
+    "905",
+    "91",
+    "920",
+    "921",
+    "922",
+    "923",
+    "93",
+    "990",
+    "991",
+    "992",
+    "993",
+    "994",
+    "99510",
+    "99550",
+    "996",
+    "9981",
+    "9982",
+    "99830",
+    "99831",
+    "99832",
+    "99888",
+    "99900",
+    "99901",
+    "99902",
+    "99903",
+    "9991",
+    "99921",
+    "99930",
+    "99931",
+    "99932",
+    "99933",
+    "99934",
+    "9995",
+    "99969",
+    "99977",
+    "9998",
+    "9999",
+)
+
+
+def _extract_nsn(normalized: str) -> str | None:
+    """Extract the 10-digit NSN from compact phone strings.
+
+    Args:
+        normalized: Digit-normalized input string.
+
+    Returns:
+        10-digit NSN string starting with '9', or None if the format is invalid.
+    """
+    if normalized.startswith("+989") and len(normalized) == 13:
+        nsn = normalized[3:]
+        if nsn.isascii() and nsn.isdigit():
+            return nsn
+    elif normalized.startswith("00989") and len(normalized) == 14:
+        nsn = normalized[4:]
+        if nsn.isascii() and nsn.isdigit():
+            return nsn
+    elif (
+        normalized.startswith("09")
+        and not normalized.startswith("00")
+        and len(normalized) == 11
+    ):
+        nsn = normalized[1:]
+        if nsn.isascii() and nsn.isdigit():
+            return nsn
+
+    return None
+
+
+def is_valid_mobile_number(value: str) -> bool:
+    """Validate whether a string is a valid Iranian mobile phone number.
+
+    Accepts compact representations using ASCII digits, Persian digits (۰-۹),
+    Arabic-Indic digits (٠-٩), or mixed sets:
+        - Domestic: '09xxxxxxxxx' (11 digits)
+        - International plus: '+989xxxxxxxxx' (13 characters)
+        - International dial prefix: '00989xxxxxxxxx' (14 characters)
+
+    Validation rules:
+        - Requires an exact compact representation (no spaces, hyphens, or separators).
+        - Extracts the 10-digit National Significant Number (NSN).
+        - Validates the NSN against the official 2026 CRA Mobile services NDC prefixes.
+        - Rejects fixed non-geographical numbers (e.g. 094...), public trunk ranges,
+          and unlisted prefix allocations.
+
+    Note:
+        Prefix validation verifies structural allocation according to the bundled
+        2026 CRA National Numbering Plan snapshot. It does not verify subscriber
+        ownership, active SIM status, or carrier identity.
+
+    Args:
+        value: Candidate mobile number string.
+
+    Returns:
+        True if the candidate represents a valid mobile number format; False otherwise.
+    """
+    if not isinstance(value, str):
+        return False
+
+    normalized = normalize_digits(value)
+    nsn = _extract_nsn(normalized)
+    if nsn is None:
+        return False
+
+    return any(nsn.startswith(prefix) for prefix in _MOBILE_NDC_PREFIXES)

fa_redact/validators/national_id.py

@@ -0,0 +1,47 @@
+"""Iranian National ID (Code Melli) validation."""
+
+from __future__ import annotations
+
+from fa_redact.normalization import normalize_digits
+
+
+def is_valid_national_id(value: str) -> bool:
+    """Validate the checksum structure of an Iranian individual National ID.
+
+    Accepts 10-character strings consisting of ASCII digits, Persian digits (۰-۹),
+    Arabic-Indic digits (٠-٩), or mixed representations thereof.
+
+    Strict validation policy:
+        - Exact length of 10 characters required.
+        - No whitespace, separators, hyphens, or non-digit characters allowed.
+        - No 8/9-digit zero-padding performed.
+        - Rejects all identical/repeated digit patterns ('0000000000'..'9999999999').
+        - Validates the standard modulo-11 weighted check digit.
+
+    Note:
+        Checksum validity confirms structural mathematical integrity only. It does NOT
+        verify whether the ID has actually been issued or belongs to a real individual.
+
+    Args:
+        value: Candidate national ID string.
+
+    Returns:
+        True if the candidate has a valid 10-digit format and correct check digit;
+        False otherwise.
+    """
+    if not isinstance(value, str) or len(value) != 10:
+        return False
+
+    normalized = normalize_digits(value)
+    if not (normalized.isascii() and normalized.isdigit()):
+        return False
+
+    # Reject repeated-digit pseudo-values (0000000000, 1111111111, ..., 9999999999)
+    if len(set(normalized)) == 1:
+        return False
+
+    total = sum(int(normalized[i]) * (10 - i) for i in range(9))
+    remainder = total % 11
+    expected_check_digit = remainder if remainder < 2 else 11 - remainder
+
+    return int(normalized[9]) == expected_check_digit

fa_redact-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: fa-redact
+Version: 0.1.0
+Summary: A privacy-first Python toolkit for Persian/Iranian PII redaction and pseudonymization, designed especially for healthcare and AI applications.
+Author: fa-redact contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mehdimt1980/fa-redact
+Project-URL: Repository, https://github.com/mehdimt1980/fa-redact
+Project-URL: Issues, https://github.com/mehdimt1980/fa-redact/issues
+Keywords: persian,farsi,pii,redaction,anonymization,pseudonymization,privacy,healthcare
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# fa-redact
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`fa-redact` is a lightweight, privacy-first Python toolkit for Persian/Iranian Personally Identifiable Information (PII) detection, redaction, and pseudonymization, designed especially for healthcare and AI/LLM applications.
+
+> **Status: v0.1.0 Release Candidate (Alpha)**  
+> This package provides position-preserving Persian text normalization, immutable `Detection` data models, strict Iranian National ID (Code Melli) and Mobile Number validators and detectors, high-level `detect()` orchestration, stateless placeholder-based `redact()`, and stateful `PseudonymizationSession` with safe restoration for AI/LLM workflows.
+
+---
+
+## Quick Start
+
+### 1. Detect PII
+Identify sensitive spans with exact source offsets and normalized representations:
+
+```python
+from fa_redact import detect
+
+text = "بیمار با کد ملی ۱۲۳۴۵۶۷۸۹۱ و شماره ۰۹۱۲۳۴۵۶۷۸۹ مراجعه کرد."
+detections = detect(text)
+
+for d in detections:
+    print(f"Type: {d.type} | Value: {d.value} | Span: [{d.start}:{d.end}]")
+```
+
+### 2. Redact PII (Stateless)
+Sanitize text into safe, typed placeholders with fresh counter numbering:
+
+```python
+from fa_redact import redact
+
+text = "کد ملی: ۱۲۳۴۵۶۷۸۹۱، تماس: ۰۹۱۲۳۴۵۶۷۸۹، تماس دوم: 09123456789"
+safe_text = redact(text)
+print(safe_text)
+# Output: "کد ملی: [IR_NATIONAL_ID_1]، تماس: [IR_MOBILE_1]، تماس دوم: [IR_MOBILE_1]"
+```
+
+### 3. Stateful Pseudonymization & AI/LLM Restoration
+Maintain consistent entity mappings across conversation turns and restore placeholders locally:
+
+```python
+from fa_redact import PseudonymizationSession
+
+session = PseudonymizationSession()
+
+# 1. Pseudonymize prompt locally before sending to external LLM:
+prompt = "کد ملی بیمار ۱۲۳۴۵۶۷۸۹۱ و شماره تماس ۰۹۱۲۳۴۵۶۷۸۹ است."
+safe_prompt = session.pseudonymize(prompt)
+print(safe_prompt)
+# Output: "کد ملی بیمار [IR_NATIONAL_ID_1] و شماره تماس [IR_MOBILE_1] است."
+
+# 2. Send ONLY safe_prompt to external LLM. Simulated LLM response:
+llm_response = "جهت پیگیری بیمار با [IR_MOBILE_1] هماهنگ شد."
+
+# 3. Restore placeholders locally within your trusted boundary:
+restored = session.restore(llm_response)
+print(restored)
+# Output: "جهت پیگیری بیمار با ۰۹۱۲۳۴۵۶۷۸۹ هماهنگ شد."
+```
+
+---
+
+## Installation
+
+### Future PyPI Release
+Once v0.1.0 is published to PyPI:
+
+```bash
+pip install fa-redact
+```
+
+### Development Installation
+For development or installing from source:
+
+```bash
+git clone https://github.com/mehdimt1980/fa-redact.git
+cd fa-redact
+pip install -e ".[dev]"
+```
+
+---
+
+## Detailed Capabilities
+
+### 1. Stateful Pseudonymization Sessions
+The `PseudonymizationSession` class manages state across multi-turn workflows:
+- **Local Sensitive Mapping**: `session.mapping` holds `{placeholder: original_pii}`. Keep this mapping strictly inside your local trusted environment; never transmit it to external AI services.
+- **First-Observed Representative Restoration**: For each unique identity `(type, normalized_value)`, the session records the first-observed raw string as its semantic restoration target.
+- **Non-Cascading Single-Pass Restoration**: `restore()` performs an escaped single-pass substitution, preventing recursive evaluation if restored values contain placeholder-like text.
+- **Cross-Call Collision Safety**: Generated placeholders automatically avoid colliding with literal placeholder-shaped tokens seen in current or previous inputs within the session.
+- **Unknown Placeholders**: Unmapped placeholders (e.g., `[IR_MOBILE_999]`) are left untouched without error.
+
+> [!WARNING]
+> **Sensitive Data Notice**: `session.mapping` contains original PII. Treat it as sensitive data and protect it accordingly.
+>
+> **Scope Limitation**: `fa-redact` detects and redacts only the PII types supported by its enabled detectors (Iranian National IDs and Iranian Mobile Numbers in v0.1.0). It does not provide complete automated clinical de-identification.
+
+### 2. Position-Preserving Normalization
+`fa-redact` provides pure, deterministic normalization where each Unicode character maps 1-to-1 to a normalized code point (`len(normalized) == len(original)`), guaranteeing that character offsets remain identical to the original input text:
+
+```python
+from fa_redact import normalize_digits, normalize_letters, normalize_text
+
+# Normalizes Persian (۰-۹) and Arabic-Indic (٠-٩) digits to ASCII (0-9)
+normalize_digits("کد بیمار: ۱۲۳٤٥")
+# Returns: "کد بیمار: 12345"
+
+# Normalizes Arabic letter variants (ي -> ی, ك -> ک)
+normalize_letters("پزشك و دكتر")
+# Returns: "پزشک و دکتر"
+
+# Full position-preserving normalization
+normalize_text("كد ملي: ۰۰۱٢٣٤٥٦٧٨")
+# Returns: "کد ملی: 0012345678"
+```
+
+### 3. Detection Data Model & Pipeline
+The immutable `Detection` dataclass represents identified spans:
+
+```python
+from fa_redact import Detection, IranianNationalIDDetector, detect, normalize_text
+
+# Using custom detector list:
+detections = detect("کد ملی: ۱۲۳۴۵۶۷۸۹۱", detectors=[IranianNationalIDDetector()])
+for d in detections:
+    assert d.type == "IR_NATIONAL_ID"
+    assert d.value == "۱۲۳۴۵۶۷۸۹۱"
+    assert d.normalized_value == "1234567891"
+```
+
+### 4. Iranian National ID Validation & Detection
+Validate and detect Iranian National IDs (Code Melli / `کد ملی`) with strict modulo-11 checksum verification:
+
+```python
+from fa_redact import IranianNationalIDDetector, is_valid_national_id
+
+# Algorithmic test vectors not sourced from personal data
+is_valid_national_id("1234567891")  # True
+is_valid_national_id("۱۲۳۴۵۶۷۸۹۱")  # True (Persian digits)
+is_valid_national_id("1234567890")  # False (invalid check digit)
+is_valid_national_id("1111111111")  # False (repeated digits rejected)
+```
+
+> **Verification Notice**: Checksum validation verifies mathematical structure only without querying official registries. These values are algorithmic test vectors not sourced from personal or patient records. Checksum validity does not establish whether an identifier has been officially issued to an individual.
+
+### 5. Iranian Mobile Number Validation & Detection
+Validate and detect Iranian mobile numbers against official Communications Regulatory Authority (CRA) mobile NDC prefixes:
+
+```python
+from fa_redact import IranianMobileNumberDetector, is_valid_mobile_number
+
+# Domestic, +98 international, and 0098 international formats
+is_valid_mobile_number("09123456789")  # True (domestic)
+is_valid_mobile_number("۰۹۱۲۳۴۵۶۷۸۹")  # True (Persian digits)
+is_valid_mobile_number("+989123456789")  # True (+98 format)
+is_valid_mobile_number("00989351234567")  # True (0098 format)
+is_valid_mobile_number("09412345678")  # False (fixed non-geographical)
+```
+
+> **Numbering Plan Notice**: Prefix classification is based on the official Communications Regulatory Authority (CRA) National Numbering Plan (published via ITU Operational Bulletin No. 1340). Prefix validation confirms structural allocation only and does not verify subscriber ownership, active SIM status, or carrier identity.
+
+---
+
+## Privacy-Safe Test-Data Policy
+
+All test fixtures, examples, and documentation in `fa-redact` are constructed from **synthetic test vectors, algorithmic patterns, and non-personal sample data**. No real patient records, clinical charts, credentials, or personal datasets are used or included in the repository.
+
+---
+
+## Important Disclaimers
+
+- **Not Production Clinical Software**: `fa-redact` is an experimental, early-stage open-source library and is **not** certified as a medical device or approved for production clinical decision-making.
+- **No Inherent Regulatory Compliance**: Use of this library does not automatically ensure compliance with HIPAA, GDPR, or local privacy regulations. Organizations remain responsible for verifying that their data pipelines meet applicable legal and privacy standards.
+- **No Identity Verification**: Validation functions verify format and mathematical structure only; they do not query government registries or authenticate individuals.
+
+---
+
+## Development & Quality Checks
+
+Run the automated test suite:
+```bash
+python -m pytest
+```
+
+Check code formatting and linting:
+```bash
+ruff check .
+ruff format --check .
+```
+
+Run static type checking:
+```bash
+mypy src
+mypy tests
+```
+
+Build and validate distribution packages:
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+For release procedures and PyPI publishing setup, see [RELEASING.md](RELEASING.md).
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

fa_redact-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+fa_redact/__init__.py,sha256=sPYQpisDvMnmtkgOLxHzONoKfuZSOkdjcS1lJiSo-8Q,1006
+fa_redact/models.py,sha256=WB7EDndMQhLoVYU84unRkY4IgIvZaREJRrHEaAT9iOE,3588
+fa_redact/normalization.py,sha256=-XAdKifmLrY2rrOUfP3SvaDHmjW7HJ5nWQJB7u1BgZo,3071
+fa_redact/pipeline.py,sha256=tgyF-RN_R96PUAHR2dkc4CNZxx88cxoOHzPH2wS5CQA,1961
+fa_redact/protocols.py,sha256=ErL5xuuYVFnx4mPPxZz0h0pxOa5rVbuCM56nNWFLQn4,970
+fa_redact/pseudonymization.py,sha256=469WbmnN3fTdcqGPyRmGc8FeVCVjXKpsbSHcb_tIMOE,6709
+fa_redact/py.typed,sha256=JTMQ3X5TErayUJWJNlQV9q9Zsq86cF22FslLGORWvEw,53
+fa_redact/redaction.py,sha256=Yeu8uOK_ytKFFLgrRDAYQww2Q6Pq8lSvWV-a2kTyUGs,1352
+fa_redact/detectors/__init__.py,sha256=ztke_TzGUMkRtlkne1UFHd_BzTR3sTdNUvF9XHR8i9M,288
+fa_redact/detectors/mobile.py,sha256=Za7VI3MymooMMmdgJfzN_Q6igxnvkaEZIG-tv7Hsj6I,2095
+fa_redact/detectors/national_id.py,sha256=TjX6c5TYWbNXUSYD_-DD9lu0AsbZMLsGui2Z5FwwvS0,2049
+fa_redact/validators/__init__.py,sha256=rAoHznaBEH5bZM1pqNtgrB6ZSZcoT8hXnwfHb6cw0do,280
+fa_redact/validators/mobile.py,sha256=sFbjgFQm8v4eWvf_AXkBEtjNwtRMi7Yu0VYCBjk3pbQ,3210
+fa_redact/validators/national_id.py,sha256=iu_ff2y_x2xpSKs4n6cus2KedFkk-rhOMov2yHiaGmA,1710
+fa_redact-0.1.0.dist-info/licenses/LICENSE,sha256=rYBqj0XvcIjFPLx41dUw9ugfDXNWusbW83Wmg6ErM90,1079
+fa_redact-0.1.0.dist-info/METADATA,sha256=hxKWnxqlSBkiYememicjBq-V2KMi6bkrwINopPilGK0,10457
+fa_redact-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fa_redact-0.1.0.dist-info/top_level.txt,sha256=26_kVCc8Rti8OXHj8SyjRZhNtRNm9t3sW02EPpX0ycA,10
+fa_redact-0.1.0.dist-info/RECORD,,

fa_redact-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fa_redact-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fa-redact contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fa_redact-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fa_redact