SFerrand.Common 1.0.1

dotnet add package SFerrand.Common --version 1.0.1
                    
NuGet\Install-Package SFerrand.Common -Version 1.0.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SFerrand.Common" Version="1.0.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SFerrand.Common" Version="1.0.1" />
                    
Directory.Packages.props
<PackageReference Include="SFerrand.Common" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add SFerrand.Common --version 1.0.1
                    
#r "nuget: SFerrand.Common, 1.0.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package SFerrand.Common@1.0.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=SFerrand.Common&version=1.0.1
                    
Install as a Cake Addin
#tool nuget:?package=SFerrand.Common&version=1.0.1
                    
Install as a Cake Tool

SFerrand.Common

Small, dependency-light helpers for .NET 8+, extracted from production services and rewritten to be generic, null-safe and fully tested.

dotnet add package SFerrand.Common
Area What you get
Log-safe masking (SFerrand.Common.Security) SecretObfuscator: mask secrets, URIs with credentials, connection strings, e-mails, GUIDs and API tokens while keeping them recognizable.
Banking identifiers (SFerrand.Common.Security) FinancialObfuscator: mask payment card numbers (PCI DSS display rule), IBAN and French RIB, keeping their layout.
Free-text redaction (SFerrand.Common.Security) SecretRedactor: find and mask credentials, tokens, JWTs, password= pairs, cards, IBAN, RIB, NIR and e-mails inside log lines and bodies.
Sensitive data in objects, headers and URLs (SFerrand.Common.Security) [SensitiveData] + log-safe JSON, SensitiveKeys for header/dictionary/query-string values and URLs.
French identifiers (SFerrand.Common.Security) FrenchIdentifierObfuscator: mask NIR (social security number), SIREN, SIRET and VAT number.
Check digits (SFerrand.Common.Validation) Checksums: Luhn, IBAN mod 97, RIB key, SIREN, SIRET, NIR, French VAT number.
Constant-time comparison (SFerrand.Common.Security) ConstantTime.AreEqual for tokens and signatures.
Strings (SFerrand.Common.Extensions) PascalCase / camelCase / snake_case / CONSTANT_CASE / kebab-case / COBOL-CASE / Train-Case, Base64 and Base64url helpers, diacritics removal, null/empty fallbacks.
JSON ToJsonString / ToObject shortcuts and EnumMemberJsonConverter<T> (string enums honouring [EnumMember]).
Collections (SFerrand.Common.Collections) GenericComparer<T> (compare by key) and FuncComparer<T>, bulk IList<T> operations.
Validation (SFerrand.Common.Attributes) [NotEmptyEnumerable] for any IEnumerable.
Configuration PrioritizeAppSettings() so appsettings*.json wins over other sources.

Masking secrets

Every method is fail-safe: if the input does not have the expected shape, the value is masked as a whole (only the few adaptive leading/trailing characters stay visible) rather than returned in clear, and nothing throws on malformed input. Masking is deterministic and length-preserving: it is a logging aid, not a security boundary. By default the number of visible characters adapts to the length (none up to 4 characters, 1 up to 8, 2 up to 16, 4 above) so short secrets are never exposed.

using SFerrand.Common.Security;

"aSuperMegaLongSecret".Obfuscate();                                  // aSup************cret
"postgres://app:s3cr3t-pass@db:5432/shop".ObfuscateUri();            // postgres://app:s3*******ss@db:5432/shop (password masked)
"AccountName=acme;AccountKey=averysecretkey==".ObfuscateConnectionString("AccountKey");
                                                                     // AccountName=acme;AccountKey=av************==
"jean-claude.van-damme@example.com".ObfuscateEmail();                // ****-c****e.***-d***e@example.com
"3f2504e0-4f89-11d3-9a0c-0305e82c3301".ObfuscateGuid();             // 3******0-****-11d3-****-03********01
"ghp_1234567890abcdefghijklmnop".ObfuscateToken();                 // ghp_1234******************mnop (prefix kept)

// Skip addresses that are not personal data (shared mailboxes, public domains...)
"team-platform@example.com".ObfuscateEmail(shouldSkip: e => e.StartsWith("team-"));  // unchanged

Obfuscate never reveals a whole value: if the requested leading/trailing counts would cover it, it falls back to the adaptive default.

Masking banking identifiers

FinancialObfuscator follows the same rules (fail-safe, deterministic, length-preserving) and keeps the layout of the value: spaces and hyphens stay where they are and do not count as characters. Each method has a hard ceiling on what it can reveal, whatever the arguments.

using SFerrand.Common.Security;

"4111 1111 1111 1111".ObfuscateCardNumber();                  // **** **** **** 1111      (default: last 4 digits)
"5555-5555-5555-4444".ObfuscateCardNumber(nbLeading: 6);      // 5555-55**-****-4444      (ceiling: first 6 + last 4)
"FR76 3000 6000 0112 3456 7890 189".ObfuscateIban();          // FR** **** **** **** **** ***0 189   (country + last 4)
"30006 00001 12345678901 89".ObfuscateRib();                  // 30006 ***** *********** **        (bank code only)
"30006 00001 12345678901 89".ObfuscateRib(nbTrailing: 3);     // 30006 ***** **********1 89
Method Accepts Default shows Ceiling
ObfuscateCardNumber 12 to 19 digits last 4 first 6 + last 4 (PCI DSS)
ObfuscateIban country + check digits + 11 to 30 letters/digits (15 to 34) country code + last 4 4 + 4
ObfuscateRib 5 + 5 digits, 11 letters/digits, 2 digits (23) bank code (5) 10 + 4

A value of the wrong shape (a digit too many, a letter in a card number) is masked as a whole with the generic rule instead of being treated as a card. The checksum (Luhn, mod 97) is not verified: a mistyped number is as sensitive as a valid one. A card verification code (CVV/CVC) or a PIN should never reach a log; if one does, Obfuscate() hides a 3 or 4 digit code completely.

Masking French identifiers

"1 84 12 76 451 089 46".ObfuscateNir();         // * ** ** ** *** *** **     (nothing shown by default)
"732 829 320".ObfuscateSiren();                  // *** *** 320
"732 829 320 00074".ObfuscateSiret();            // *** *** *** *0074
"FR 44 732 829 320".ObfuscateFrenchVatNumber();  // FR ** *** *** 320

The social security number (NIR) encodes sex, birth year and month, department and commune. Its ceiling therefore stops before them: at most the first character and the two key digits can ever be shown, whatever is asked. Same contract and layout handling as FinancialObfuscator.

Check digits

using SFerrand.Common.Validation;

"4111 1111 1111 1111".IsValidLuhn();                 // true
"FR14 2004 1010 0505 0001 3M02 606".IsValidIban();   // true
"20041 01005 0500013M026 06".IsValidRibKey();        // true (letters of the account are converted as the standard prescribes)
"732829320".IsValidSiren();                          // true
"35600000000001".IsValidSiret();                     // true (La Poste: digit sum a multiple of 5 instead of Luhn)
"1 84 12 76 451 089 46".IsValidNir();                // true (2A / 2B Corsican departments handled)
"FR44732829320".IsValidFrenchVatNumber();            // true

A passing check means well-formed, not "exists": a random number passes Luhn one time in ten. Use it to reject typos and to cut false positives, never as proof of identity. Every method accepts null (answer: false), ignores spaces and hyphens, and never throws. The country-specific length of an IBAN is not checked.

Masking secrets in free text

SecretRedactor reads text and masks what it recognizes, with the matching obfuscator, so the result has exactly the same length:

"Connecting to postgres://app:s3cr3t-pass@db/shop with token=abcdef123456 for ada@example.com".Redact();
// Connecting to postgres://app:s3*******ss@db/shop with token=ab********56 for ***@example.com

"Authorization: Bearer abcdefghijklmnopqrstuv failed".Redact();   // Authorization: Bearer abcd**************stuv failed
"card 4111 1111 1111 1111 expires 12/30".Redact();                // card **** **** **** 1111 expires 12/30
"pay FR76 3000 6000 0112 3456 7890 189 AND more".Redact();        // pay FR** **** **** **** **** ***0 189 AND more
Category (RedactionKinds) Recognized
UriCredentials the password of scheme://user:password@host (several URIs glued in one token are all handled)
AuthorizationHeaders the credential after Bearer, Basic, Digest, Token (16 characters or more)
Jwt JSON Web Tokens
ApiTokens GitHub (ghp_, github_pat_...), AWS access key IDs, Slack tokens
KeyValueSecrets the value of password=, "secret": , x-api-key:, client_secret=...
Iban, Rib, FrenchNir, PaymentCards numbers of the right shape and a valid check digit (cards also start with 2 to 6)
Emails addresses (skippable with ShouldSkipEmail)
var options = new RedactionOptions { Kinds = RedactionKinds.Emails | RedactionKinds.PaymentCards, RequireChecksum = false };
text.Redact(options);
  • Best effort, not a guarantee. A secret in a shape it does not know (a random password in a sentence, a token without prefix) is not found, and a named value ends at the first space, quote, &, ; or ,. When you know where the secret is, use the typed obfuscators or [SensitiveData]; use the redactor as a safety net for text you do not control.
  • Precision or recall. By default a number must pass its check digit, so timestamps, order numbers and dates are left alone. RequireChecksum = false masks anything shaped like a card, IBAN, RIB or NIR.
  • Safe on hostile input. Every pattern is bounded; the cost grows linearly with the text (tested on 400 KB of worst-case shapes).
  • Masking is idempotent: redacting an already redacted text changes nothing.

Sensitive data in objects, headers and URLs

Mark properties once, log objects without thinking about it:

public class Login
{
    public string UserName { get; set; } = "";
    [SensitiveData] public string? Password { get; set; }
    [SensitiveData(SensitiveDataKind.Email)] public string? Email { get; set; }
    [SensitiveData] public int Pin { get; set; }
}

logger.LogInformation("Login: {Login}", login.ToSafeJsonString());
// Login: {"UserName":"ada","Password":"hu**********r2","Email":"***@example.com","Pin":"***"}

A sensitive string is masked according to its SensitiveDataKind (secret, token, e-mail, URI, GUID, card, IBAN, RIB, NIR); any other type becomes "***". Normal serialization is not affected. On a positional record write [property: SensitiveData]: the attribute is deliberately refused on constructor parameters, where it would compile and silently leave the value in clear. Build options once with SensitiveDataJson.CreateOptions(template) to combine with your own settings.

For data that has no class (headers, dictionaries, URLs, form bodies), SensitiveKeys decides by name:

SensitiveKeys.IsSensitive("X-Api-Key");                                        // true
SensitiveKeys.MaskValue("Authorization", "Bearer abcdefghijklmnop");           // Bearer ab************op
"https://u:pw12345678@api.example.com/v1/items?page=2&access_token=abcdefghijklmnop#frag".ObfuscateUrl();
// https://u:pw******78@api.example.com/v1/items?page=2&access_token=ab************op#frag
"a=1&password=hunter2hunter2&sig=abcdefgh".ObfuscateQuery();                   // a=1&password=hu**********r2&sig=a******h

A name is sensitive when, ignoring case and - _ ., it contains password, secret, token, apikey, authorization, cookie, credential, session... (or is exactly sig). Parameter names are compared after URL decoding. Matching is broad on purpose: masking too much is the safe direction.

Constant-time comparison and Base64url

if (!ConstantTime.AreEqual(request.Headers["X-Token"], expectedToken))   // null is never equal to anything, null included
    return Unauthorized();

new byte[] { 0xFB, 0xFF }.ToBase64UrlString();   // -_8   (URL-safe alphabet, no padding)
"-_8".FromBase64UrlBytes();                      // { 0xFB, 0xFF }
"+/8=".IsBase64UrlString();                      // false (standard alphabet)

ConstantTime protects the content, not the length (it returns early when lengths differ): use it for fixed-size secrets such as hashes and signatures.

String conversions

Words are detected from spaces, separators, camelCase humps and acronyms, including accented letters:

using SFerrand.Common.Extensions;

"XMLHttpRequest2".ToSnakeCase();   // xml_http_request2
"hello big world".ToPascalCase();  // HelloBigWorld
"café crème".ToKebabCase();        // café-crème
"Sébastien".RemoveDiacritics();    // Sebastien
"café".ToBase64String();           // Y2Fmw6k=   (UTF-8 by default, pass an Encoding to change it)
"AAAA".IsBase64String();           // true       (strict: padded, standard alphabet, no whitespace)

Enums as strings with [EnumMember]

[JsonConverter(typeof(EnumMemberJsonConverter<State>))]
public enum State
{
    Open,
    [EnumMember(Value = "in_progress")] InProgress,
}

JsonSerializer.Serialize(State.InProgress);          // "in_progress"
JsonSerializer.Deserialize<State>("\"in_progress\""); // State.InProgress
JsonSerializer.Deserialize<State>("\"bogus\"");       // throws JsonException (no silent default)

Reading accepts the member name or the EnumMember value (case-insensitive) and defined numeric values; keys of dictionaries are supported. [Flags] combinations are not. On .NET 9+ the BCL offers [JsonStringEnumMemberName]; this converter gives the same result on .NET 8 and with the System.Runtime.Serialization attribute.

Collections

using SFerrand.Common.Collections;

var uniqueByName = users.Distinct(new GenericComparer<User>(u => u.Name));
IList<int> list = ...;
list.RemoveAll(i => i % 2 == 0);   // single pass, returns the number of removed items

FuncComparer<T> takes an optional hash function; without one it stays correct in hash sets and LINQ set operations but degrades to O(n) lookups.

Configuration

var config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .PrioritizeAppSettings()   // appsettings*.json now overrides the environment
    .Build();

Documentation

  • API reference: every public member is documented with XML comments (shipped in the package, so IntelliSense shows them).
  • Design notes: why it works this way, what was rejected, known limits.
  • Test suite: strategy, property tests, conventions.
  • Contributing, Changelog and Releasing (versioning and publication of the NuGet package).

Build and test

dotnet test

The library and its tests target net8.0 and net10.0. The tests run on both when both runtimes are installed (as in CI); otherwise the net8.0 run rolls forward to the newest runtime. Coverage and mutation-check procedures are in CONTRIBUTING.

License

MIT

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.1 90 11/4/2026

See CHANGELOG.md in the repository.