Skip to content

SAIF.NetCore.HashUtil overview

Documentation context: Packaged Component (NuGet)

SAIF.NetCore.HashUtil is a dependency-free, implementation-layer utility library that provides reversible, non-cryptographic obfuscation of a create timestamp inside an existing hash string, plus the exception type a consumer throws when it decides a recovered timestamp has expired. It takes no package dependency on SAIF.NetCore.ServiceContracts or SAIF.NetCore.Common, contradicting Architecture.md's group-level UtilGroup -.-> Foundation diagram edge, and reaches consuming applications only transitively, through a single documented implementation-to-implementation NuGet reference from SAIF.NetCore.SystemHash.

Purpose

  • Salt a caller-supplied hash string by hex-encoding a create date into seven positionally-random insertion points and return a location map prefixed to the salted body; the map is a fixed 42 characters only while each entry's unpadded body-length field stays two digits, a condition SaltHash does not validate (SaltShaker.SaltHash, see BR-HU-01).
  • De-salt a previously salted hash string by walking the location map in reverse insertion order, removing and decoding each date part, and recovering the original create date (SaltShaker.BlandHash).
  • Define SystemHashExpiredException, the exception type a consumer throws when it decides a recovered create date has expired.
  • It is consumed, via a NuGet package reference, only by SAIF.NetCore.SystemHash, which owns the actual lifetime/expiry decision.

Responsibilities

  • Provide a stateful salting/de-salting primitive — each SaltShaker instance retains its constructor-supplied _dateParts and a per-instance Random (_random) across calls — with no DI registration, no hosting, and no configuration surface. The observed in-repo consumer constructs a fresh SaltShaker per salt/de-salt operation rather than reusing or sharing an instance.*
  • Carry a location map ahead of the salted body so the original insertion points and the embedded create-date parts can be recovered in reverse order.
  • Define the SystemHashExpiredException exception type, without itself ever throwing it or evaluating expiry.

Key components

  • SaltShaker: owns the salting/de-salting algorithm, the per-instance Random used for insertion positions and pad characters, and the internal hex encode/decode helpers. Instances are stateful and not documented as thread-safe or safe to share across calls.*
  • SystemHashExpiredException: a plain System.Exception subtype that only carries constructor parameters (nowDate, hashDate); it has no serialization constructor and no parameterless/message constructors.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • src/SAIF.NetCore.HashUtil/SAIF.NetCore.HashUtil/SaltShaker.cs
  • src/SAIF.NetCore.HashUtil/SAIF.NetCore.HashUtil/SystemHashExpiredException.cs
  • src/SAIF.NetCore.HashUtil/SAIF.NetCore.HashUtil/SAIF.NetCore.HashUtil.csproj
  • Architecture.md