{
  "bicim": "maskele-agent-contract",
  "sozlesmeSurumu": "1.0.0",
  "uygulamaSurumu": "1.1.0",
  "kuralSurumu": "2026.07.26",
  "ad": "Maskele",
  "amac": "Türkçe serbest metinde desteklenen kişisel veri adaylarını yerel ve deterministik olarak bulmak ve tam, kısmi veya çağıran-sağlayıcılı token ile redakte etmek.",
  "entrypoint": {
    "tur": "yerel-es-modul",
    "yol": "./motor/pii.js",
    "ag": "Çekirdek modül ağ çağrısı yapmaz."
  },
  "enumlar": {
    "mod": [
      "tam",
      "kismi",
      "tokenize"
    ],
    "bulguTuru": [
      "tckn",
      "iban",
      "telefon",
      "plaka",
      "eposta",
      "krediKarti"
    ]
  },
  "ortakTipler": {
    "Bulgu": {
      "tur": {
        "tip": "string",
        "enumRef": "bulguTuru",
        "zorunlu": true
      },
      "deger": {
        "tip": "string",
        "zorunlu": true,
        "gizlilik": "Maskelenmemiş ham eşleşmedir."
      },
      "baslangic": {
        "tip": "integer",
        "minimum": 0,
        "zorunlu": true,
        "birim": "JavaScript UTF-16 kod birimi; başlangıç dahil, bitiş hariç"
      },
      "bitis": {
        "tip": "integer",
        "minimum": 0,
        "zorunlu": true,
        "birim": "JavaScript UTF-16 kod birimi; başlangıç dahil, bitiş hariç"
      }
    },
    "MaskelemeSonucu": {
      "metin": {
        "tip": "string",
        "zorunlu": true,
        "aciklama": "Seçilen moda göre redakte edilmiş metin."
      },
      "bulgular": {
        "tip": "array",
        "ogeRef": "Bulgu",
        "zorunlu": true,
        "aciklama": "Başlangıca göre sıralı ham bulgular."
      }
    }
  },
  "operasyonlar": {
    "metniMaskele": {
      "export": "metniMaskele",
      "imza": "metniMaskele(metin, mod = \"tam\", tokenSaglayici?)",
      "girdiler": {
        "metin": {
          "tip": "string",
          "zorunlu": true,
          "bosOlabilir": true
        },
        "mod": {
          "tip": "string",
          "enumRef": "mod",
          "zorunlu": false,
          "varsayilan": "tam"
        },
        "tokenSaglayici": {
          "tip": "function",
          "zorunluKosulu": "mod === \"tokenize\"",
          "imza": "(tur: bulguTuru, deger: string) => string",
          "gereksinimler": [
            "Senkron çalışmalıdır.",
            "Boş olmayan bir string döndürmelidir.",
            "Dönen string ham deger'i aynen içermemelidir."
          ],
          "gizlilik": "Sağlayıcıya ham PII verilir; saklama ve aktarım sorumluluğu çağırandadır."
        }
      },
      "ciktiRef": "MaskelemeSonucu"
    },
    "piiTespitEt": {
      "export": "piiTespitEt",
      "imza": "piiTespitEt(metin)",
      "girdiler": {
        "metin": {
          "tip": "string",
          "zorunlu": true,
          "bosOlabilir": true
        }
      },
      "cikti": {
        "tip": "array",
        "ogeRef": "Bulgu"
      }
    },
    "tcknGecerliMi": {
      "export": "tcknGecerliMi",
      "imza": "tcknGecerliMi(deger)",
      "cikti": "boolean"
    },
    "ibanGecerliMi": {
      "export": "ibanGecerliMi",
      "imza": "ibanGecerliMi(deger)",
      "cikti": "boolean"
    },
    "luhnGecerliMi": {
      "export": "luhnGecerliMi",
      "imza": "luhnGecerliMi(deger)",
      "cikti": "boolean"
    },
    "asciiKatla": {
      "export": "asciiKatla",
      "imza": "asciiKatla(deger)",
      "cikti": "string",
      "uyari": "TR IBAN doğrulamasında kullanılmaz; yasak Türkçe harfler IBAN için reddedilir."
    }
  },
  "hatalar": [
    {
      "tur": "TypeError",
      "kosul": "metin string değil",
      "mesaj": "metin bir string olmalıdır"
    },
    {
      "tur": "TypeError",
      "kosul": "mod enum dışında",
      "mesaj": "Geçersiz maskeleme modu"
    },
    {
      "tur": "TypeError",
      "kosul": "tokenize modunda sağlayıcı yok veya function değil",
      "mesaj": "Tokenize modu token sağlayıcı ister"
    },
    {
      "tur": "TypeError",
      "kosul": "token sağlayıcı boş, string olmayan veya ham değeri içeren sonuç döndürür",
      "mesaj": "Token sağlayıcı ham değeri içermeyen, boş olmayan bir string döndürmelidir"
    },
    {
      "tur": "SaglayiciHatasi",
      "kosul": "tokenSaglayici hata fırlatır",
      "mesaj": "Hata değiştirilmeden çağırana iletilir."
    }
  ],
  "kapsam": {
    "tckn": "Bitişik veya 3-3-3-2 boşluk/tire gruplu 11 rakam; ilk hane ve iki kontrol eşitliği.",
    "iban": "TR + 2 kontrol rakamı + 5 rakamlı sağlayıcı kodu + rezerv 0 + 16 büyük ASCII A-Z/0-9; bitişik veya dörtlü gösterim ve MOD 97-10.",
    "telefon": "Coğrafi 2XX/3XX/4XX, geniş mobil 5XX ve coğrafi olmayan 800/811/822/850/888/898/900 ailelerinde 3+7 haneli adaylar.",
    "plaka": "01-81 il kodu ve Karayolları Trafik Yönetmeliği madde 55(a) ana gövde kombinasyonlarına uyan adaylar.",
    "eposta": "Sınırlı serbest-metin e-posta sezgiseli; SMTP veya DNS doğrulaması değildir.",
    "krediKarti": "10-19 haneli Luhn-geçerli aday; kart ağı veya hesap doğrulaması değildir."
  },
  "gizlilikVeKapsamUyarilari": [
    "Çekirdek API ağ çağrısı ve kalıcı depolama yapmaz.",
    "bulgular[].deger ham PII içerir; loglamayın veya gereksiz saklamayın.",
    "Web arayüzünün tokenize modu geri eşlemeyi aynı origin localStorage alanında ham PII ile kalıcı tutar; görünür silme düğmesi kullanılmalıdır.",
    "Telefon ve plaka sonuçları adaydır; tahsis, sahiplik veya resmî geçerlilik kanıtı değildir.",
    "TCKN, IBAN ve Luhn checksum geçişi kimlik, hesap veya kart gerçekliğini kanıtlamaz.",
    "Kısmi maske çıktısı hâlâ kişisel veri olabilir.",
    "Çekirdek API boyut sınırı koymaz; web arayüzü dosya ve işleme girdisini 10 MB ile sınırlar.",
    "PDF, DOCX, XLSX, görüntü/OCR, VKN, YKN, pasaport ve posta adresi kapsam dışıdır.",
    "Tek bir regex veya checksum sistemi bütün kişisel verileri hatasız bulamaz; çıktı insan incelemesi gerektirir."
  ],
  "kayitlar": {
    "skalerRuleset": "./veri/ruleset-2026.07.26.json",
    "davranisKapsami": "./veri/davranis-2026.07.26.json",
    "insanOkurKunye": "./KUNYE.md",
    "apiBelgesi": "./maskele-API.md"
  }
}