---
title: SAIF.NetCore.HashUtil overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: SAIF Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.HashUtil
reference_type: package
---

# 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](business-rules.md#br-hu-01-fixed-42-character-location-map-prefix)).
- 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.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

> **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`