Codergies.VerifyNation 1.0.3

🇹🇷 VerifyNation

VerifyNation is a modern, extensible, and lightweight .NET library for validating Turkish Republic Identity Numbers (TCKN).

✨ Features

• 🔢 Standard TCKN algorithmic validation
• 🔍 Length and first digit checks
• 🚫 Blacklist/✅ Whitelist support
• 🔗 Pipeline/chain support: stop on first error or collect all errors
• 🌐 Internationalization (i18n) for error messages (TR/EN)
• 🧩 Easily add your own custom rules (custom rule API)
• ⚡ Async validation support
• 🧰 Easy integration with Dependency Injection
• 🧪 100% test coverage and real-world scenarios

📦 Installation

dotnet add package VerifyNation

🚀 Basic Usage

using Codergies.VerifyNation;

var validator = new TcknValidator(RuleFactory.CreateTcknRules());
var result = validator.Validate("10000000146");

if (result.IsValid)
    Console.WriteLine("TCKN is valid!");
else
    Console.WriteLine("TCKN is invalid: " + string.Join(", ", result.ErrorMessages));

🛠️ Advanced Usage

1. 💉 Dependency Injection Integration

using Codergies.VerifyNation.Extensions;

services.AddTcknValidator(); // In Startup.cs or Program.cs

// In your Controller or Service:
public class MyService
{
    private readonly IValidator<string> _tcknValidator;
    public MyService(IValidator<string> tcknValidator) => _tcknValidator = tcknValidator;

    public void ValidateTckn(string tckn)
    {
        var result = _tcknValidator.Validate(tckn);
        // ...
    }
}

2. 🔗 Pipeline/Chain Mode

Control whether rules are executed sequentially and stop at the first error, or always collect all errors:

var validator = new TcknValidator(RuleFactory.CreateTcknRules());
validator.PipelineMode = ValidationPipelineMode.StopOnFirstFailure; // Stops at the first error

var result = validator.Validate("12345678901");
if (!result.IsValid)
    Console.WriteLine($"First error: {result.Errors[0].Message}");

3. 🚫✅ Blacklist/Whitelist Rules

using Codergies.VerifyNation.Rules;

var blacklist = new[] { "12345678901", "11111111111" };
var validator = new TcknValidator(RuleFactory.CreateTcknRules());
validator.AddRule(new BlacklistValidationRule(blacklist));

var result = validator.Validate("12345678901"); // Returns blacklist error

var whitelist = new[] { "10000000146" };
validator.AddRule(new WhitelistValidationRule(whitelist));
var result2 = validator.Validate("99999999999"); // Returns whitelist error

4. 🌐 Internationalization (i18n) for Error Messages

var resultTr = validator.Validate("123", "tr"); // Error messages in Turkish
var resultEn = validator.Validate("123", "en"); // Error messages in English

5. ⚡ Async Validation

var result = await validator.ValidateAsync("10000000146");

6. 🧩 Add Your Own Custom Rule

public class CustomAlwaysFailRule : IValidationRule<string>
{
    public string Name => "CustomAlwaysFail";
    public string ErrorMessage => "Always fails.";
    public string ErrorCode => "ERR_CUSTOM_FAIL";
    public bool Validate(IValidationContext context, string input) => false;
    public Task<bool> ValidateAsync(IValidationContext context, string input, CancellationToken cancellationToken = default) => Task.FromResult(false);
    public string GetErrorMessage(string culture = null) => ErrorMessage;
}

var validator = new TcknValidator(RuleFactory.CreateTcknRules());
validator.AddRule(new CustomAlwaysFailRule());
var result = validator.Validate("10000000146"); // Returns custom rule error

7. 🏛️ NVI (e-Devlet) TCKN Verification Rule

You can validate a TCKN against the official Turkish government (NVI) service, verifying not only the number but also the person's name, surname, and birth year:

using Codergies.VerifyNation.Rules;

var nviRule = new NviTcknValidationRule("YASIN", "KAYA", 1990);
var validator = new TcknValidator(RuleFactory.CreateTcknRules());
validator.AddRule(nviRule);

var result = await validator.ValidateAsync("10000000146");
if (result.IsValid)
    Console.WriteLine("TCKN is valid and verified by NVI!");
else
    Console.WriteLine("TCKN is invalid or not verified by NVI.");

⚠️ Note:

• This rule requires the user's name, surname, and birth year.
• The NVI service may have IP restrictions and is intended for official use.
• Always handle exceptions and sensitive data with care.

8. 🏢 KPSv2 (WS-Trust/SAML) Enterprise-Grade TCKN Validation

Why KPSv2?

🚀 Enterprise & Government Ready!

• Integrate with the official Turkish KPSv2 (Kimlik Paylaşım Sistemi) for the highest level of identity verification.
• Supports advanced WS-Trust, SAML, and XML Signature (HMAC/X.509) security standards.
• Designed for banks, telecom, insurance, and all regulated industries.
• Fully extensible: plug in your own signing logic, keys, and certificates.

Supported Signature Types

• None: Use for test/dev or if your environment does not require token signing.
• HmacSha1: For environments requiring HMAC-SHA1 XMLDSIG signatures.
• X509: For environments requiring X.509 certificate-based XMLDSIG signatures.

Sample Usage

using Codergies.VerifyNation.Rules;
using System.Security.Cryptography.X509Certificates;

// Example: No signature (test/dev)
var kpsRuleNone = new Kpsv2TcknValidationRule(
    stsEndpoint: "https://sts.example.com/STSService.svc",
    serviceEndpoint: "https://kpsv2.example.com/Service.svc",
    username: "your-username",
    password: "your-password",
    ad: "YASIN",
    soyad: "KAYA",
    dogumYili: 1990,
    signatureType: Kpsv2SignatureType.None
);

// Example: HMAC-SHA1 signature
var hmacKey = Convert.FromBase64String("your-base64-hmac-key");
var kpsRuleHmac = new Kpsv2TcknValidationRule(
    stsEndpoint: "https://sts.example.com/STSService.svc",
    serviceEndpoint: "https://kpsv2.example.com/Service.svc",
    username: "your-username",
    password: "your-password",
    ad: "YASIN",
    soyad: "KAYA",
    dogumYili: 1990,
    signatureType: Kpsv2SignatureType.HmacSha1,
    hmacKey: hmacKey
);

// Example: X.509 certificate signature
var cert = new X509Certificate2("path-to-cert.pfx", "cert-password");
var kpsRuleX509 = new Kpsv2TcknValidationRule(
    stsEndpoint: "https://sts.example.com/STSService.svc",
    serviceEndpoint: "https://kpsv2.example.com/Service.svc",
    username: "your-username",
    password: "your-password",
    ad: "YASIN",
    soyad: "KAYA",
    dogumYili: 1990,
    signatureType: Kpsv2SignatureType.X509,
    certificate: cert
);

// Add to your validator pipeline
var validator = new TcknValidator(RuleFactory.CreateTcknRules());
validator.AddRule(kpsRuleNone); // or kpsRuleHmac, kpsRuleX509

var result = await validator.ValidateAsync("10000000146");
if (result.IsValid)
    Console.WriteLine("TCKN is valid and verified by KPSv2!");
else
    Console.WriteLine("TCKN is invalid or not verified by KPSv2.");

💡 Tip:

• Plug in your own XMLDSIG logic for HMAC or X.509 as needed for your environment.
• All cryptographic operations are extensible and ready for enterprise security requirements.
• This rule is ideal for regulated industries and government integrations.

📋 ValidationResult & Error Details

Each validation result provides both simple error messages (ErrorMessages) and detailed error objects (Errors):

foreach (var error in result.Errors)
{
    Console.WriteLine($"Code: {error.Code}, Message: {error.Message}");
}

🧩 Extensibility & Advanced API

Write Your Own Validator or Rule

• Implement IValidator<T> or IValidationRule<T> for custom validation logic.
• Use IValidationContext to share data between rules.

Manage Rule Chain at Runtime

• Use AddRule, RemoveRule, ClearRules to manage the rule chain dynamically.
• Use the Rules property to inspect the current rules.

🏗️ Built-in Rules

• LengthValidationRule: Checks if TCKN is 11 digits and all are numeric.
• FirstDigitValidationRule: Checks if the first digit is not 0.
• AlgorithmicValidationRule: Checks TCKN algorithmic validity.
• BlacklistValidationRule: Fails if TCKN is in a blacklist.
• WhitelistValidationRule: Fails if TCKN is not in a whitelist.

You can combine these or add your own!

🧪 Test Coverage

• All core and advanced scenarios are covered by unit tests.
• Tests are located in tests/Codergies.VerifyNation.Tests/.
• Features like pipeline, blacklist/whitelist, custom rules, i18n, and async validation are all tested.

🤖 CI/CD & Automatic Versioning

• This project uses GitHub Actions for continuous integration, testing, and NuGet publishing.
• Version numbers are automatically generated from git tags using MinVer.
• To release a new version, simply push a tag like v1.2.3 to the repository. The pipeline will:
  • Build and test the project
  • Create a NuGet package with the correct version
  • Publish the package to NuGet.org automatically

📄 License & Contribution

• Open source under the MIT License.
• Contributions are welcome! Please open an issue or submit a pull request.

For more examples and details, see the test folder and the source code.