diff --git a/CHANGELOG.md b/CHANGELOG.md
index f660614..7af1f40 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,3 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+
+### Added
+
+- `WalterEgo.Core`: alter ego model (`HoneyToken`) with a mandatory placement, a decoy class (generic or unique)
+ and severity defaults derived from the class.
+- `WalterEgo.Core`: immutable token registry (`ITokenRegistry`) with allocation-free lookups by identifier and by
+ raw value.
+- `WalterEgo.Core`: keyed digests of decoy values (`ISecretHasher`, `SecretDigest`): HMAC-SHA256 with a mandatory
+ key of at least 32 bytes and one derived subkey per trigger domain, so reading the configuration does not reveal
+ which values are decoys.
diff --git a/src/WalterEgo.Core/Domain/DecoyClass.cs b/src/WalterEgo.Core/Domain/DecoyClass.cs
new file mode 100644
index 0000000..dc730b3
--- /dev/null
+++ b/src/WalterEgo.Core/Domain/DecoyClass.cs
@@ -0,0 +1,19 @@
+namespace WalterEgo;
+
+///
+/// How much a trip of an alter ego can be trusted.
+///
+public enum DecoyClass
+{
+ ///
+ /// A well-known decoy that any scanner finds without a leak, such as /.env or admin.
+ /// Its trips signal reconnaissance and carry low confidence.
+ ///
+ Generic = 1,
+
+ ///
+ /// A decoy that can only be found through the place where it was planted.
+ /// Its trips signal that this place leaked and carry high confidence.
+ ///
+ Unique = 2,
+}
diff --git a/src/WalterEgo.Core/Domain/HoneyToken.cs b/src/WalterEgo.Core/Domain/HoneyToken.cs
new file mode 100644
index 0000000..90b248d
--- /dev/null
+++ b/src/WalterEgo.Core/Domain/HoneyToken.cs
@@ -0,0 +1,153 @@
+using System.Collections.Frozen;
+
+namespace WalterEgo;
+
+///
+/// An alter ego: a fake asset that no legitimate user has a reason to touch. A trip of an alter ego tells where
+/// it was planted () and how much the trip can be trusted ().
+///
+///
+/// An instance only carries metadata. The decoy values that trip the alter ego are never part of it, so it can be
+/// copied into events, logs and alert channels safely. Instances are immutable and always valid.
+///
+public sealed record HoneyToken
+{
+ ///
+ /// Creates an alter ego.
+ ///
+ /// The identifier of the alter ego.
+ /// The kind of asset the alter ego imitates.
+ /// Whether the alter ego is a generic decoy or a unique one.
+ ///
+ /// Where the alter ego was planted, such as "LEGACY_KEY variable in the CI of the orders repository". Up to 512
+ /// characters, not blank, without control characters or line separators.
+ ///
+ /// The severity of a trip of the alter ego.
+ ///
+ /// A readable name. Up to 128 characters, not blank, without control characters or line separators. When
+ /// , the identifier is used.
+ ///
+ ///
+ /// An optional description. Up to 1024 characters, without control characters or line separators.
+ ///
+ ///
+ /// Optional tags. Up to 16 entries; keys are lowercase slugs of up to 32 characters; values are not blank, have up
+ /// to 128 characters and no control characters or line separators. The entries are copied.
+ ///
+ /// Any argument breaks the rules above, is the default
+ /// value, or an enumeration argument is not a defined value.
+ public HoneyToken(
+ HoneyTokenId id,
+ HoneyTokenKind kind,
+ DecoyClass decoyClass,
+ string placement,
+ Severity severity,
+ string? name = null,
+ string? description = null,
+ IReadOnlyDictionary? tags = null)
+ {
+ if (id.IsDefault)
+ {
+ throw new ArgumentException("The identifier is required.", nameof(id));
+ }
+
+ ThrowIfUndefined(HoneyTokenRules.IsDefined(kind), nameof(kind));
+ ThrowIfUndefined(HoneyTokenRules.IsDefined(decoyClass), nameof(decoyClass));
+ ThrowIfUndefined(HoneyTokenRules.IsDefined(severity), nameof(severity));
+ ThrowIfInvalid(HoneyTokenRules.CheckPlacement(placement), nameof(placement));
+ ThrowIfInvalid(HoneyTokenRules.CheckName(name), nameof(name));
+ ThrowIfInvalid(HoneyTokenRules.CheckDescription(description), nameof(description));
+
+ // The copy is validated, not the argument, so a dictionary that changes after the check cannot slip invalid
+ // tags in.
+ var frozenTags = tags?.ToFrozenDictionary(StringComparer.Ordinal);
+ ThrowIfInvalid(HoneyTokenRules.CheckTags(frozenTags), nameof(tags));
+
+ Id = id;
+ Kind = kind;
+ Class = decoyClass;
+ Placement = placement;
+ Severity = severity;
+ Name = name ?? id.Value;
+ Description = description;
+ Tags = frozenTags ?? FrozenDictionary.Empty;
+ }
+
+ /// Gets the identifier of the alter ego.
+ public HoneyTokenId Id { get; }
+
+ /// Gets the kind of asset the alter ego imitates.
+ public HoneyTokenKind Kind { get; }
+
+ /// Gets whether the alter ego is a generic decoy or a unique one.
+ public DecoyClass Class { get; }
+
+ /// Gets the readable name, which is the identifier when no name was given.
+ public string Name { get; }
+
+ /// Gets where the alter ego was planted.
+ public string Placement { get; }
+
+ /// Gets the optional description.
+ public string? Description { get; }
+
+ /// Gets the severity of a trip of the alter ego.
+ public Severity Severity { get; }
+
+ /// Gets the tags, compared by ordinal keys. Empty when no tags were given.
+ public IReadOnlyDictionary Tags { get; }
+
+ ///
+ /// Compares two alter egos by all their values, including the content of .
+ ///
+ /// The alter ego to compare with.
+ /// when both alter egos have the same values.
+ public bool Equals(HoneyToken? other) =>
+ other is not null
+ && Id == other.Id
+ && Kind == other.Kind
+ && Class == other.Class
+ && Severity == other.Severity
+ && string.Equals(Name, other.Name, StringComparison.Ordinal)
+ && string.Equals(Placement, other.Placement, StringComparison.Ordinal)
+ && string.Equals(Description, other.Description, StringComparison.Ordinal)
+ && TagsEqual(Tags, other.Tags);
+
+ ///
+ public override int GetHashCode() =>
+ HashCode.Combine(Id, Kind, Class, Severity, Name, Placement, Description, Tags.Count);
+
+ private static bool TagsEqual(IReadOnlyDictionary left, IReadOnlyDictionary right)
+ {
+ if (left.Count != right.Count)
+ {
+ return false;
+ }
+
+ foreach (var (key, value) in left)
+ {
+ if (!right.TryGetValue(key, out var otherValue) || !string.Equals(value, otherValue, StringComparison.Ordinal))
+ {
+ return false;
+ }
+ }
+
+ return true;
+ }
+
+ private static void ThrowIfUndefined(bool isDefined, string parameterName)
+ {
+ if (!isDefined)
+ {
+ throw new ArgumentException("The value is not defined in its enumeration.", parameterName);
+ }
+ }
+
+ private static void ThrowIfInvalid(string? error, string parameterName)
+ {
+ if (error is not null)
+ {
+ throw new ArgumentException(error, parameterName);
+ }
+ }
+}
diff --git a/src/WalterEgo.Core/Domain/HoneyTokenId.cs b/src/WalterEgo.Core/Domain/HoneyTokenId.cs
new file mode 100644
index 0000000..e848944
--- /dev/null
+++ b/src/WalterEgo.Core/Domain/HoneyTokenId.cs
@@ -0,0 +1,63 @@
+using System.Diagnostics.CodeAnalysis;
+
+namespace WalterEgo;
+
+///
+/// Identifies an alter ego. The identifier is chosen by the user, must stay the same across restarts and is
+/// included in every alert about the alter ego.
+///
+///
+/// A valid identifier has 1 to 64 characters, starts with a lowercase ASCII letter or digit and contains only
+/// lowercase ASCII letters, digits, -, . and _. Identifiers compare ordinally.
+/// The default value is not a valid identifier and is rejected wherever an identifier is required.
+///
+public readonly record struct HoneyTokenId
+{
+ private readonly string? _value;
+
+ ///
+ /// Creates an identifier.
+ ///
+ /// The identifier text.
+ /// is not a valid identifier.
+ public HoneyTokenId(string value)
+ {
+ if (!HoneyTokenRules.IsSlug(value, HoneyTokenRules.MaxIdLength))
+ {
+ throw new ArgumentException(HoneyTokenRules.InvalidIdMessage, nameof(value));
+ }
+
+ _value = value;
+ }
+
+ ///
+ /// Gets the identifier text, or an empty string for the default value.
+ ///
+ public string Value => _value ?? string.Empty;
+
+ internal bool IsDefault => _value is null;
+
+ ///
+ /// Tries to create an identifier.
+ ///
+ /// The identifier text.
+ /// The identifier, or the default value when is not valid.
+ /// when is a valid identifier.
+ public static bool TryCreate([NotNullWhen(true)] string? value, out HoneyTokenId id)
+ {
+ if (!HoneyTokenRules.IsSlug(value, HoneyTokenRules.MaxIdLength))
+ {
+ id = default;
+ return false;
+ }
+
+ id = new HoneyTokenId(value);
+ return true;
+ }
+
+ ///
+ /// Returns the identifier text.
+ ///
+ /// The identifier text, or an empty string for the default value.
+ public override string ToString() => Value;
+}
diff --git a/src/WalterEgo.Core/Domain/HoneyTokenKind.cs b/src/WalterEgo.Core/Domain/HoneyTokenKind.cs
new file mode 100644
index 0000000..177c4f2
--- /dev/null
+++ b/src/WalterEgo.Core/Domain/HoneyTokenKind.cs
@@ -0,0 +1,28 @@
+namespace WalterEgo;
+
+///
+/// The kind of asset an alter ego imitates.
+///
+public enum HoneyTokenKind
+{
+ /// An HTTP route that no legitimate client calls.
+ Endpoint = 1,
+
+ /// A username or e-mail address that belongs to nobody.
+ User = 2,
+
+ /// An API key in the application's own format that never authorizes anything.
+ ApiKey = 3,
+
+ /// A fictitious database row.
+ Row = 4,
+
+ /// A configuration entry that carries a beacon or another decoy value.
+ Config = 5,
+
+ /// A session token, such as a JWT or a cookie, that never validates.
+ SessionToken = 6,
+
+ /// A file that carries decoy credentials or a beacon.
+ File = 7,
+}
diff --git a/src/WalterEgo.Core/Domain/HoneyTokenRules.cs b/src/WalterEgo.Core/Domain/HoneyTokenRules.cs
new file mode 100644
index 0000000..35fc61e
--- /dev/null
+++ b/src/WalterEgo.Core/Domain/HoneyTokenRules.cs
@@ -0,0 +1,108 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+
+namespace WalterEgo;
+
+internal static class HoneyTokenRules
+{
+ internal const int MaxIdLength = 64;
+ internal const int MaxNameLength = 128;
+ internal const int MaxPlacementLength = 512;
+ internal const int MaxDescriptionLength = 1024;
+ internal const int MaxTagCount = 16;
+ internal const int MaxTagKeyLength = 32;
+ internal const int MaxTagValueLength = 128;
+
+ internal const string InvalidIdMessage =
+ "The identifier must have 1 to 64 characters, start with a lowercase ASCII letter or digit and contain only lowercase ASCII letters, digits, '-', '.' and '_'.";
+
+ internal static bool IsSlug([NotNullWhen(true)] string? value, int maxLength)
+ {
+ if (string.IsNullOrEmpty(value) || value.Length > maxLength || !IsLowercaseAlphanumeric(value[0]))
+ {
+ return false;
+ }
+
+ foreach (var c in value.AsSpan(1))
+ {
+ if (!IsLowercaseAlphanumeric(c) && c is not ('-' or '.' or '_'))
+ {
+ return false;
+ }
+ }
+
+ return true;
+ }
+
+ internal static bool IsDefined(HoneyTokenKind kind) => kind is >= HoneyTokenKind.Endpoint and <= HoneyTokenKind.File;
+
+ internal static bool IsDefined(DecoyClass decoyClass) => decoyClass is DecoyClass.Generic or DecoyClass.Unique;
+
+ internal static bool IsDefined(Severity severity) => severity is >= Severity.Low and <= Severity.Critical;
+
+ internal static bool IsDefined(TriggerDomain domain) => domain is >= TriggerDomain.ApiKey and <= TriggerDomain.RequestPath;
+
+ internal static string? CheckPlacement(string? placement) =>
+ CheckText(placement, "The placement", MaxPlacementLength, allowBlank: false);
+
+ internal static string? CheckName(string? name) =>
+ name is null ? null : CheckText(name, "The name", MaxNameLength, allowBlank: false);
+
+ internal static string? CheckDescription(string? description) =>
+ description is null ? null : CheckText(description, "The description", MaxDescriptionLength, allowBlank: true);
+
+ internal static string? CheckTags(IReadOnlyDictionary? tags)
+ {
+ if (tags is null)
+ {
+ return null;
+ }
+
+ if (tags.Count > MaxTagCount)
+ {
+ return "An alter ego can have at most 16 tags.";
+ }
+
+ foreach (var (key, value) in tags)
+ {
+ if (!IsSlug(key, MaxTagKeyLength))
+ {
+ return "Tag keys must have 1 to 32 characters, start with a lowercase ASCII letter or digit and contain only lowercase ASCII letters, digits, '-', '.' and '_'.";
+ }
+
+ if (CheckText(value, "Each tag value", MaxTagValueLength, allowBlank: false) is { } error)
+ {
+ return error;
+ }
+ }
+
+ return null;
+ }
+
+ private static string? CheckText(string? text, string subject, int maxLength, bool allowBlank)
+ {
+ if (text is null || (!allowBlank && string.IsNullOrWhiteSpace(text)))
+ {
+ return $"{subject} must not be empty or white space.";
+ }
+
+ if (text.Length > maxLength)
+ {
+ return $"{subject} must have at most {maxLength} characters.";
+ }
+
+ // Line and paragraph separators are rejected with the control characters because they also break
+ // log lines and message layouts in alert channels.
+ foreach (var c in text)
+ {
+ if (char.GetUnicodeCategory(c) is UnicodeCategory.Control or UnicodeCategory.LineSeparator or UnicodeCategory.ParagraphSeparator)
+ {
+ return $"{subject} must not contain control characters or line separators.";
+ }
+ }
+
+ return null;
+ }
+
+ private static bool IsLowercaseAlphanumeric(char c) => char.IsAsciiLetterLower(c) || char.IsAsciiDigit(c);
+}
diff --git a/src/WalterEgo.Core/Domain/Severity.cs b/src/WalterEgo.Core/Domain/Severity.cs
new file mode 100644
index 0000000..b3c7117
--- /dev/null
+++ b/src/WalterEgo.Core/Domain/Severity.cs
@@ -0,0 +1,19 @@
+namespace WalterEgo;
+
+///
+/// The severity of a trip.
+///
+public enum Severity
+{
+ /// Low severity, the default for generic decoys.
+ Low = 1,
+
+ /// Medium severity.
+ Medium = 2,
+
+ /// High severity, the default for unique decoys.
+ High = 3,
+
+ /// Critical severity.
+ Critical = 4,
+}
diff --git a/src/WalterEgo.Core/Domain/TriggerDomain.cs b/src/WalterEgo.Core/Domain/TriggerDomain.cs
new file mode 100644
index 0000000..6d0880d
--- /dev/null
+++ b/src/WalterEgo.Core/Domain/TriggerDomain.cs
@@ -0,0 +1,19 @@
+namespace WalterEgo;
+
+///
+/// Where a sensor looks for a decoy value. The same value produces a different digest in each domain.
+///
+public enum TriggerDomain
+{
+ /// The value of an API key presented to the application.
+ ApiKey = 1,
+
+ /// A username or e-mail address used in a sign-in attempt.
+ Username = 2,
+
+ /// A session token, such as a bearer token or a session cookie.
+ SessionToken = 3,
+
+ /// The path of an HTTP request, such as a beacon or a unique honey endpoint.
+ RequestPath = 4,
+}
diff --git a/src/WalterEgo.Core/PublicAPI.Unshipped.txt b/src/WalterEgo.Core/PublicAPI.Unshipped.txt
index 7dc5c58..abc899d 100644
--- a/src/WalterEgo.Core/PublicAPI.Unshipped.txt
+++ b/src/WalterEgo.Core/PublicAPI.Unshipped.txt
@@ -1 +1,68 @@
#nullable enable
+WalterEgo.DecoyClass
+WalterEgo.DecoyClass.Generic = 1 -> WalterEgo.DecoyClass
+WalterEgo.DecoyClass.Unique = 2 -> WalterEgo.DecoyClass
+WalterEgo.HoneyToken
+WalterEgo.HoneyToken.$() -> WalterEgo.HoneyToken!
+WalterEgo.HoneyToken.Class.get -> WalterEgo.DecoyClass
+WalterEgo.HoneyToken.Description.get -> string?
+override WalterEgo.HoneyToken.Equals(object? obj) -> bool
+WalterEgo.HoneyToken.Equals(WalterEgo.HoneyToken? other) -> bool
+override WalterEgo.HoneyToken.GetHashCode() -> int
+WalterEgo.HoneyToken.HoneyToken(WalterEgo.HoneyTokenId id, WalterEgo.HoneyTokenKind kind, WalterEgo.DecoyClass decoyClass, string! placement, WalterEgo.Severity severity, string? name = null, string? description = null, System.Collections.Generic.IReadOnlyDictionary? tags = null) -> void
+WalterEgo.HoneyToken.Id.get -> WalterEgo.HoneyTokenId
+WalterEgo.HoneyToken.Kind.get -> WalterEgo.HoneyTokenKind
+WalterEgo.HoneyToken.Name.get -> string!
+static WalterEgo.HoneyToken.operator !=(WalterEgo.HoneyToken? left, WalterEgo.HoneyToken? right) -> bool
+static WalterEgo.HoneyToken.operator ==(WalterEgo.HoneyToken? left, WalterEgo.HoneyToken? right) -> bool
+WalterEgo.HoneyToken.Placement.get -> string!
+WalterEgo.HoneyToken.Severity.get -> WalterEgo.Severity
+WalterEgo.HoneyToken.Tags.get -> System.Collections.Generic.IReadOnlyDictionary!
+override WalterEgo.HoneyToken.ToString() -> string!
+WalterEgo.HoneyTokenId
+~override WalterEgo.HoneyTokenId.Equals(object obj) -> bool
+WalterEgo.HoneyTokenId.Equals(WalterEgo.HoneyTokenId other) -> bool
+override WalterEgo.HoneyTokenId.GetHashCode() -> int
+WalterEgo.HoneyTokenId.HoneyTokenId() -> void
+WalterEgo.HoneyTokenId.HoneyTokenId(string! value) -> void
+static WalterEgo.HoneyTokenId.operator !=(WalterEgo.HoneyTokenId left, WalterEgo.HoneyTokenId right) -> bool
+static WalterEgo.HoneyTokenId.operator ==(WalterEgo.HoneyTokenId left, WalterEgo.HoneyTokenId right) -> bool
+override WalterEgo.HoneyTokenId.ToString() -> string!
+static WalterEgo.HoneyTokenId.TryCreate(string? value, out WalterEgo.HoneyTokenId id) -> bool
+WalterEgo.HoneyTokenId.Value.get -> string!
+WalterEgo.HoneyTokenKind
+WalterEgo.HoneyTokenKind.ApiKey = 3 -> WalterEgo.HoneyTokenKind
+WalterEgo.HoneyTokenKind.Config = 5 -> WalterEgo.HoneyTokenKind
+WalterEgo.HoneyTokenKind.Endpoint = 1 -> WalterEgo.HoneyTokenKind
+WalterEgo.HoneyTokenKind.File = 7 -> WalterEgo.HoneyTokenKind
+WalterEgo.HoneyTokenKind.Row = 4 -> WalterEgo.HoneyTokenKind
+WalterEgo.HoneyTokenKind.SessionToken = 6 -> WalterEgo.HoneyTokenKind
+WalterEgo.HoneyTokenKind.User = 2 -> WalterEgo.HoneyTokenKind
+WalterEgo.ISecretHasher
+WalterEgo.ISecretHasher.ComputeDigest(WalterEgo.TriggerDomain domain, System.ReadOnlySpan value) -> WalterEgo.SecretDigest
+WalterEgo.ITokenRegistry
+WalterEgo.ITokenRegistry.HasTriggers(WalterEgo.TriggerDomain domain) -> bool
+WalterEgo.ITokenRegistry.Tokens.get -> System.Collections.Generic.IReadOnlyList!
+WalterEgo.ITokenRegistry.TryGet(WalterEgo.HoneyTokenId id, out WalterEgo.HoneyToken? token) -> bool
+WalterEgo.ITokenRegistry.TryMatch(WalterEgo.TriggerDomain domain, System.ReadOnlySpan value, out WalterEgo.HoneyToken? token) -> bool
+WalterEgo.SecretDigest
+override WalterEgo.SecretDigest.Equals(object? obj) -> bool
+WalterEgo.SecretDigest.Equals(WalterEgo.SecretDigest other) -> bool
+override WalterEgo.SecretDigest.GetHashCode() -> int
+const WalterEgo.SecretDigest.Length = 32 -> int
+static WalterEgo.SecretDigest.operator !=(WalterEgo.SecretDigest left, WalterEgo.SecretDigest right) -> bool
+static WalterEgo.SecretDigest.operator ==(WalterEgo.SecretDigest left, WalterEgo.SecretDigest right) -> bool
+static WalterEgo.SecretDigest.Parse(System.ReadOnlySpan text) -> WalterEgo.SecretDigest
+WalterEgo.SecretDigest.SecretDigest() -> void
+override WalterEgo.SecretDigest.ToString() -> string!
+static WalterEgo.SecretDigest.TryParse(System.ReadOnlySpan text, out WalterEgo.SecretDigest digest) -> bool
+WalterEgo.Severity
+WalterEgo.Severity.Critical = 4 -> WalterEgo.Severity
+WalterEgo.Severity.High = 3 -> WalterEgo.Severity
+WalterEgo.Severity.Low = 1 -> WalterEgo.Severity
+WalterEgo.Severity.Medium = 2 -> WalterEgo.Severity
+WalterEgo.TriggerDomain
+WalterEgo.TriggerDomain.ApiKey = 1 -> WalterEgo.TriggerDomain
+WalterEgo.TriggerDomain.RequestPath = 4 -> WalterEgo.TriggerDomain
+WalterEgo.TriggerDomain.SessionToken = 3 -> WalterEgo.TriggerDomain
+WalterEgo.TriggerDomain.Username = 2 -> WalterEgo.TriggerDomain
diff --git a/src/WalterEgo.Core/Registry/HoneyTokenRegistration.cs b/src/WalterEgo.Core/Registry/HoneyTokenRegistration.cs
new file mode 100644
index 0000000..d2d6bd5
--- /dev/null
+++ b/src/WalterEgo.Core/Registry/HoneyTokenRegistration.cs
@@ -0,0 +1,18 @@
+namespace WalterEgo;
+
+// Raw input for the registry builder. Every field may be invalid; the builder reports what is wrong instead of
+// throwing, so a configuration with several mistakes is fixed in one pass.
+internal sealed record HoneyTokenRegistration(string? Id, HoneyTokenKind Kind, string? Placement)
+{
+ public DecoyClass? Class { get; init; }
+
+ public Severity? Severity { get; init; }
+
+ public string? Name { get; init; }
+
+ public string? Description { get; init; }
+
+ public IReadOnlyDictionary? Tags { get; init; }
+
+ public IReadOnlyList Triggers { get; init; } = [];
+}
diff --git a/src/WalterEgo.Core/Registry/HoneyTrigger.cs b/src/WalterEgo.Core/Registry/HoneyTrigger.cs
new file mode 100644
index 0000000..0716005
--- /dev/null
+++ b/src/WalterEgo.Core/Registry/HoneyTrigger.cs
@@ -0,0 +1,3 @@
+namespace WalterEgo;
+
+internal readonly record struct HoneyTrigger(TriggerDomain Domain, SecretDigest Digest);
diff --git a/src/WalterEgo.Core/Registry/ITokenRegistry.cs b/src/WalterEgo.Core/Registry/ITokenRegistry.cs
new file mode 100644
index 0000000..52d9ebb
--- /dev/null
+++ b/src/WalterEgo.Core/Registry/ITokenRegistry.cs
@@ -0,0 +1,47 @@
+using System.Diagnostics.CodeAnalysis;
+
+namespace WalterEgo;
+
+///
+/// The immutable set of alter egos of the application, built once at startup.
+///
+///
+/// The registry stores only keyed digests of decoy values, never the values themselves. Lookups never throw because
+/// of their arguments and do not allocate for values of up to 1024 UTF-8 bytes (longer values use pooled buffers),
+/// so sensors can call them on every request. Instances are safe for concurrent use.
+///
+public interface ITokenRegistry
+{
+ ///
+ /// Gets every alter ego, ordered by identifier (ordinal).
+ ///
+ IReadOnlyList Tokens { get; }
+
+ ///
+ /// Finds an alter ego by identifier.
+ ///
+ /// The identifier.
+ /// The alter ego, or when none has .
+ /// when an alter ego has .
+ bool TryGet(HoneyTokenId id, [NotNullWhen(true)] out HoneyToken? token);
+
+ ///
+ /// Tells whether any alter ego has a trigger in a domain. When it returns , a sensor can
+ /// skip that domain entirely.
+ ///
+ /// The domain.
+ /// when at least one alter ego has a trigger in .
+ bool HasTriggers(TriggerDomain domain);
+
+ ///
+ /// Finds the alter ego tripped by a value seen in a domain.
+ ///
+ /// Where the value was seen.
+ ///
+ /// The value as seen by the sensor, after the normalization of its domain. It is hashed and compared with the
+ /// stored digests; the value itself is not kept.
+ ///
+ /// The alter ego, or when the value is not a decoy.
+ /// when is a decoy value in .
+ bool TryMatch(TriggerDomain domain, ReadOnlySpan value, [NotNullWhen(true)] out HoneyToken? token);
+}
diff --git a/src/WalterEgo.Core/Registry/RegistryError.cs b/src/WalterEgo.Core/Registry/RegistryError.cs
new file mode 100644
index 0000000..0e095cf
--- /dev/null
+++ b/src/WalterEgo.Core/Registry/RegistryError.cs
@@ -0,0 +1,6 @@
+namespace WalterEgo;
+
+// TokenId is null when the identifier itself is invalid; the message then points to the position of the entry.
+internal sealed record RegistryError(string? TokenId, string Message);
+
+internal sealed record TokenRegistryBuildResult(TokenRegistry? Registry, IReadOnlyList Errors);
diff --git a/src/WalterEgo.Core/Registry/TokenRegistry.cs b/src/WalterEgo.Core/Registry/TokenRegistry.cs
new file mode 100644
index 0000000..68f7c65
--- /dev/null
+++ b/src/WalterEgo.Core/Registry/TokenRegistry.cs
@@ -0,0 +1,55 @@
+using System.Collections.Frozen;
+using System.Diagnostics.CodeAnalysis;
+
+namespace WalterEgo;
+
+internal sealed class TokenRegistry : ITokenRegistry
+{
+ private readonly ISecretHasher _hasher;
+ private readonly FrozenDictionary _byId;
+
+ // Indexed by the numeric value of TriggerDomain; null when no alter ego has a trigger in that domain.
+ private readonly FrozenDictionary?[] _byDomain = new FrozenDictionary?[(int)TriggerDomain.RequestPath + 1];
+
+ internal TokenRegistry(ISecretHasher hasher, IReadOnlyList<(HoneyToken Token, IReadOnlyList Triggers)> entries)
+ {
+ _hasher = hasher;
+ _byId = entries.ToFrozenDictionary(entry => entry.Token.Id, entry => entry.Token);
+ Tokens = Array.AsReadOnly([.. entries.Select(entry => entry.Token).OrderBy(token => token.Id.Value, StringComparer.Ordinal)]);
+
+ foreach (var group in entries.SelectMany(entry => entry.Triggers, (entry, trigger) => (trigger, entry.Token)).GroupBy(pair => pair.trigger.Domain))
+ {
+ _byDomain[(int)group.Key] = group.ToFrozenDictionary(pair => pair.trigger.Digest, pair => pair.Token);
+ }
+ }
+
+ public IReadOnlyList Tokens { get; }
+
+ public bool TryGet(HoneyTokenId id, [NotNullWhen(true)] out HoneyToken? token)
+ {
+ if (id.IsDefault)
+ {
+ token = null;
+ return false;
+ }
+
+ return _byId.TryGetValue(id, out token);
+ }
+
+ public bool HasTriggers(TriggerDomain domain) => Index(domain) is not null;
+
+ public bool TryMatch(TriggerDomain domain, ReadOnlySpan value, [NotNullWhen(true)] out HoneyToken? token)
+ {
+ // Returning before hashing keeps requests cheap when a domain has no decoys.
+ if (value.IsEmpty || Index(domain) is not { } index)
+ {
+ token = null;
+ return false;
+ }
+
+ return index.TryGetValue(_hasher.ComputeDigest(domain, value), out token);
+ }
+
+ private FrozenDictionary? Index(TriggerDomain domain) =>
+ HoneyTokenRules.IsDefined(domain) ? _byDomain[(int)domain] : null;
+}
diff --git a/src/WalterEgo.Core/Registry/TokenRegistryBuilder.cs b/src/WalterEgo.Core/Registry/TokenRegistryBuilder.cs
new file mode 100644
index 0000000..0cbc084
--- /dev/null
+++ b/src/WalterEgo.Core/Registry/TokenRegistryBuilder.cs
@@ -0,0 +1,175 @@
+using System.Collections.Frozen;
+
+namespace WalterEgo;
+
+internal static class TokenRegistryBuilder
+{
+ public static TokenRegistryBuildResult Build(ISecretHasher hasher, IEnumerable registrations)
+ {
+ List errors = [];
+ List<(HoneyToken Token, IReadOnlyList Triggers)> entries = [];
+ HashSet ids = [];
+ Dictionary triggerOwners = [];
+ var position = 0;
+
+ foreach (var registration in registrations)
+ {
+ position++;
+ if (!HoneyTokenId.TryCreate(registration.Id, out var id))
+ {
+ errors.Add(new(null, $"The alter ego at position {position} has an invalid identifier. {HoneyTokenRules.InvalidIdMessage}"));
+ continue;
+ }
+
+ if (!ids.Add(id))
+ {
+ errors.Add(new(id.Value, "The identifier is used by more than one alter ego."));
+ continue;
+ }
+
+ // Inputs are read once, so what is validated is exactly what gets indexed.
+ HoneyTrigger[] triggers = [.. registration.Triggers ?? []];
+ var tags = registration.Tags?.ToFrozenDictionary(StringComparer.Ordinal);
+
+ var errorCount = errors.Count;
+ CheckSharedTriggers(id, triggers, triggerOwners, errors);
+ if (Validate(id, registration, triggers, tags, errors) is { } token && errors.Count == errorCount)
+ {
+ entries.Add((token, triggers));
+ }
+ }
+
+ return errors.Count > 0
+ ? new TokenRegistryBuildResult(null, errors)
+ : new TokenRegistryBuildResult(new TokenRegistry(hasher, entries), []);
+ }
+
+ private static HoneyToken? Validate(
+ HoneyTokenId id,
+ HoneyTokenRegistration registration,
+ HoneyTrigger[] triggers,
+ IReadOnlyDictionary? tags,
+ List errors)
+ {
+ var errorCount = errors.Count;
+ void Fail(string message) => errors.Add(new(id.Value, message));
+
+ var kind = registration.Kind;
+ var kindIsDefined = HoneyTokenRules.IsDefined(kind);
+ if (!kindIsDefined)
+ {
+ Fail("The kind is not defined.");
+ }
+
+ DecoyClass? decoyClass = registration.Class;
+ if (decoyClass is { } givenClass && !HoneyTokenRules.IsDefined(givenClass))
+ {
+ Fail("The class is not defined.");
+ }
+ else if (decoyClass is null && kindIsDefined)
+ {
+ if (kind is HoneyTokenKind.Endpoint or HoneyTokenKind.User)
+ {
+ Fail($"A {kind} alter ego needs an explicit class, because it can be either a generic or a unique decoy.");
+ }
+ else
+ {
+ decoyClass = DecoyClass.Unique;
+ }
+ }
+
+ var severity = registration.Severity;
+ if (severity is { } givenSeverity && !HoneyTokenRules.IsDefined(givenSeverity))
+ {
+ Fail("The severity is not defined.");
+ }
+
+ AddIfInvalid(HoneyTokenRules.CheckPlacement(registration.Placement));
+ AddIfInvalid(HoneyTokenRules.CheckName(registration.Name));
+ AddIfInvalid(HoneyTokenRules.CheckDescription(registration.Description));
+ AddIfInvalid(HoneyTokenRules.CheckTags(tags));
+
+ HashSet seen = [];
+ foreach (var trigger in triggers)
+ {
+ if (!HoneyTokenRules.IsDefined(trigger.Domain))
+ {
+ Fail("A trigger has an undefined domain.");
+ }
+ else if (kindIsDefined && !AcceptsDomain(kind, trigger.Domain))
+ {
+ Fail($"A {kind} alter ego does not accept {trigger.Domain} triggers.");
+ }
+
+ if (trigger.Digest.IsDefault)
+ {
+ Fail("A trigger has an uninitialized digest.");
+ }
+
+ if (!seen.Add(trigger))
+ {
+ Fail("A trigger is repeated.");
+ }
+ }
+
+ if (kindIsDefined && triggers.Length < MinimumTriggers(kind))
+ {
+ Fail($"A {kind} alter ego needs at least one trigger.");
+ }
+
+ if (errors.Count > errorCount || decoyClass is not { } resolvedClass)
+ {
+ return null;
+ }
+
+ return new HoneyToken(
+ id,
+ kind,
+ resolvedClass,
+ registration.Placement!,
+ severity ?? (resolvedClass is DecoyClass.Generic ? Severity.Low : Severity.High),
+ registration.Name,
+ registration.Description,
+ tags);
+
+ void AddIfInvalid(string? error)
+ {
+ if (error is not null)
+ {
+ Fail(error);
+ }
+ }
+ }
+
+ private static void CheckSharedTriggers(
+ HoneyTokenId id,
+ HoneyTrigger[] triggers,
+ Dictionary triggerOwners,
+ List errors)
+ {
+ foreach (var trigger in triggers)
+ {
+ if (!HoneyTokenRules.IsDefined(trigger.Domain) || trigger.Digest.IsDefault)
+ {
+ continue;
+ }
+
+ if (!triggerOwners.TryAdd(trigger, id) && triggerOwners[trigger] != id)
+ {
+ errors.Add(new(id.Value, $"A {trigger.Domain} trigger is shared with the alter ego '{triggerOwners[trigger]}'."));
+ }
+ }
+ }
+
+ private static bool AcceptsDomain(HoneyTokenKind kind, TriggerDomain domain) => kind switch
+ {
+ HoneyTokenKind.Endpoint => domain is TriggerDomain.RequestPath,
+ HoneyTokenKind.User => domain is TriggerDomain.Username,
+ HoneyTokenKind.ApiKey => domain is TriggerDomain.ApiKey,
+ HoneyTokenKind.SessionToken => domain is TriggerDomain.SessionToken,
+ HoneyTokenKind.Config or HoneyTokenKind.File => true,
+ _ => false,
+ };
+
+ private static int MinimumTriggers(HoneyTokenKind kind) => kind is HoneyTokenKind.Endpoint or HoneyTokenKind.Row ? 0 : 1;
+}
diff --git a/src/WalterEgo.Core/Secrets/HmacSecretHasher.cs b/src/WalterEgo.Core/Secrets/HmacSecretHasher.cs
new file mode 100644
index 0000000..4e62d98
--- /dev/null
+++ b/src/WalterEgo.Core/Secrets/HmacSecretHasher.cs
@@ -0,0 +1,81 @@
+using System.Buffers;
+using System.Diagnostics;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace WalterEgo;
+
+internal sealed class HmacSecretHasher : ISecretHasher
+{
+ internal const int MinimumKeyLength = 32;
+
+ private const int SubkeyLength = 32;
+ private const int StackBufferLength = 1024;
+
+ // Indexed by the numeric value of TriggerDomain; index 0 stays empty.
+ private readonly byte[][] _subkeys = new byte[(int)TriggerDomain.RequestPath + 1][];
+
+ public HmacSecretHasher(ReadOnlySpan key)
+ {
+ if (key.Length < MinimumKeyLength)
+ {
+ throw new ArgumentException("The HMAC key must have at least 32 bytes.", nameof(key));
+ }
+
+ // Only the derived subkeys are kept, so the key itself never stays in memory owned by the hasher.
+ ReadOnlySpan domains = [TriggerDomain.ApiKey, TriggerDomain.Username, TriggerDomain.SessionToken, TriggerDomain.RequestPath];
+ foreach (var domain in domains)
+ {
+ var subkey = new byte[SubkeyLength];
+ HKDF.DeriveKey(HashAlgorithmName.SHA256, key, subkey, salt: [], info: Info(domain));
+ _subkeys[(int)domain] = subkey;
+ }
+ }
+
+ public SecretDigest ComputeDigest(TriggerDomain domain, ReadOnlySpan value)
+ {
+ if (!HoneyTokenRules.IsDefined(domain))
+ {
+ throw new ArgumentOutOfRangeException(nameof(domain), domain, "The trigger domain is not defined.");
+ }
+
+ if (value.IsEmpty)
+ {
+ throw new ArgumentException("The value must not be empty.", nameof(value));
+ }
+
+ var byteCount = Encoding.UTF8.GetByteCount(value);
+ byte[]? rented = null;
+ Span utf8 = byteCount <= StackBufferLength
+ ? stackalloc byte[StackBufferLength]
+ : rented = ArrayPool.Shared.Rent(byteCount);
+ utf8 = utf8[..byteCount];
+
+ try
+ {
+ Encoding.UTF8.GetBytes(value, utf8);
+ Span digest = stackalloc byte[SecretDigest.Length];
+ HMACSHA256.HashData(_subkeys[(int)domain], utf8, digest);
+ return SecretDigest.FromBytes(digest);
+ }
+ finally
+ {
+ // Sensors hash every value they see, so the buffer may hold the real secret of a legitimate user.
+ CryptographicOperations.ZeroMemory(utf8);
+ if (rented is not null)
+ {
+ ArrayPool.Shared.Return(rented);
+ }
+ }
+ }
+
+ // These labels are part of every digest: changing one invalidates all digests already planted in its domain.
+ private static ReadOnlySpan Info(TriggerDomain domain) => domain switch
+ {
+ TriggerDomain.ApiKey => "walterego/v1/api-key"u8,
+ TriggerDomain.Username => "walterego/v1/username"u8,
+ TriggerDomain.SessionToken => "walterego/v1/session-token"u8,
+ TriggerDomain.RequestPath => "walterego/v1/request-path"u8,
+ _ => throw new UnreachableException(),
+ };
+}
diff --git a/src/WalterEgo.Core/Secrets/ISecretHasher.cs b/src/WalterEgo.Core/Secrets/ISecretHasher.cs
new file mode 100644
index 0000000..9f4f43f
--- /dev/null
+++ b/src/WalterEgo.Core/Secrets/ISecretHasher.cs
@@ -0,0 +1,23 @@
+namespace WalterEgo;
+
+///
+/// Computes the keyed digest of a decoy value.
+///
+///
+/// A subkey is derived from a secret key for each , so the same value has a different
+/// digest in each domain, and nobody without the key can compute a digest or test whether a value is a decoy.
+/// The value is hashed as UTF-8 exactly as given, with invalid UTF-16 replaced by U+FFFD. Any normalization, such
+/// as the case of a username, must happen before.
+///
+public interface ISecretHasher
+{
+ ///
+ /// Computes the digest of a value.
+ ///
+ /// Where the value is looked for.
+ /// The value to hash.
+ /// The digest of in .
+ /// is empty.
+ /// is not a defined value.
+ SecretDigest ComputeDigest(TriggerDomain domain, ReadOnlySpan value);
+}
diff --git a/src/WalterEgo.Core/Secrets/SecretDigest.cs b/src/WalterEgo.Core/Secrets/SecretDigest.cs
new file mode 100644
index 0000000..e1cd285
--- /dev/null
+++ b/src/WalterEgo.Core/Secrets/SecretDigest.cs
@@ -0,0 +1,127 @@
+using System.Buffers;
+using System.Buffers.Binary;
+using System.Buffers.Text;
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+using System.Security.Cryptography;
+
+namespace WalterEgo;
+
+///
+/// A keyed digest (HMAC-SHA256) of a decoy value. The token registry stores digests instead of decoy values, so
+/// reading the configuration does not reveal which values are decoys.
+///
+///
+/// The canonical text form is the 32 bytes in base64url without padding: exactly 43 characters. Comparing two
+/// digests takes the same time whatever their bytes are.
+///
+public readonly struct SecretDigest : IEquatable
+{
+ /// The number of bytes in a digest.
+ public const int Length = 32;
+
+ private const int TextLength = 43;
+
+ private static readonly SearchValues Base64UrlAlphabet =
+ SearchValues.Create("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_");
+
+ private readonly DigestBytes _bytes;
+
+ private SecretDigest(ReadOnlySpan bytes) => bytes.CopyTo(_bytes);
+
+ internal bool IsDefault => AsSpan().IndexOfAnyExcept((byte)0) < 0;
+
+ ///
+ /// Reads a digest from its canonical text form.
+ ///
+ /// 43 base64url characters, without padding or white space.
+ /// The digest.
+ /// is not the canonical text form of a digest.
+ public static SecretDigest Parse(ReadOnlySpan text) =>
+ TryParse(text, out var digest)
+ ? digest
+ : throw new FormatException("A digest must be written as 43 base64url characters, without padding or white space.");
+
+ ///
+ /// Tries to read a digest from its canonical text form.
+ ///
+ /// 43 base64url characters, without padding or white space.
+ /// The digest, or the default value when is not canonical.
+ /// when is the canonical text form of a digest.
+ public static bool TryParse(ReadOnlySpan text, out SecretDigest digest)
+ {
+ digest = default;
+ if (text.Length != TextLength || text.ContainsAnyExcept(Base64UrlAlphabet))
+ {
+ return false;
+ }
+
+ // The OperationStatus overload is used because TryDecodeFromChars throws on some malformed inputs.
+ Span bytes = stackalloc byte[Length];
+ if (Base64Url.DecodeFromChars(text, bytes, out _, out var bytesWritten) != OperationStatus.Done || bytesWritten != Length)
+ {
+ return false;
+ }
+
+ // Re-encoding rejects texts whose unused trailing bits are not zero, so each digest has a single text form.
+ Span canonical = stackalloc char[TextLength];
+ if (!Base64Url.TryEncodeToChars(bytes, canonical, out var charsWritten) || !canonical[..charsWritten].SequenceEqual(text))
+ {
+ return false;
+ }
+
+ digest = new SecretDigest(bytes);
+ return true;
+ }
+
+ internal static SecretDigest FromBytes(ReadOnlySpan bytes)
+ {
+ if (bytes.Length != Length)
+ {
+ throw new ArgumentException("A digest has exactly 32 bytes.", nameof(bytes));
+ }
+
+ return new SecretDigest(bytes);
+ }
+
+ [UnscopedRef]
+ internal ReadOnlySpan AsSpan() => _bytes;
+
+ ///
+ /// Compares two digests in constant time.
+ ///
+ /// The digest to compare with.
+ /// when both digests have the same bytes.
+ public bool Equals(SecretDigest other) => CryptographicOperations.FixedTimeEquals(AsSpan(), other.AsSpan());
+
+ ///
+ public override bool Equals([NotNullWhen(true)] object? obj) => obj is SecretDigest other && Equals(other);
+
+ // HMAC output is uniform and an attacker cannot choose it without the key, so the first bytes are a good hash.
+ ///
+ public override int GetHashCode() => BinaryPrimitives.ReadInt32LittleEndian(AsSpan());
+
+ ///
+ /// Returns the canonical text form of the digest.
+ ///
+ /// 43 base64url characters, without padding.
+ public override string ToString() => Base64Url.EncodeToString(AsSpan());
+
+ /// Compares two digests in constant time.
+ /// The first digest.
+ /// The second digest.
+ /// when both digests have the same bytes.
+ public static bool operator ==(SecretDigest left, SecretDigest right) => left.Equals(right);
+
+ /// Compares two digests in constant time.
+ /// The first digest.
+ /// The second digest.
+ /// when the digests have different bytes.
+ public static bool operator !=(SecretDigest left, SecretDigest right) => !left.Equals(right);
+
+ [InlineArray(Length)]
+ private struct DigestBytes
+ {
+ private byte _element;
+ }
+}
diff --git a/src/WalterEgo.Core/WalterEgo.Core.csproj b/src/WalterEgo.Core/WalterEgo.Core.csproj
index 82586b0..27bf1ed 100644
--- a/src/WalterEgo.Core/WalterEgo.Core.csproj
+++ b/src/WalterEgo.Core/WalterEgo.Core.csproj
@@ -7,6 +7,7 @@
+
diff --git a/tests/WalterEgo.Benchmarks/TokenRegistryBenchmarks.cs b/tests/WalterEgo.Benchmarks/TokenRegistryBenchmarks.cs
new file mode 100644
index 0000000..21f650d
--- /dev/null
+++ b/tests/WalterEgo.Benchmarks/TokenRegistryBenchmarks.cs
@@ -0,0 +1,42 @@
+using BenchmarkDotNet.Attributes;
+
+namespace WalterEgo.Benchmarks;
+
+[MemoryDiagnoser]
+public class TokenRegistryBenchmarks
+{
+ private const string DecoyKey = "fictional-key-0050";
+ private const string LegitimateKey = "a-real-key-presented-by-a-legitimate-client-0123456789";
+
+ private TokenRegistry _registry = null!;
+ private HoneyTokenId _id;
+
+ [GlobalSetup]
+ public void Setup()
+ {
+ // Fictitious key, only used to build the benchmark registry.
+ byte[] key = [.. Enumerable.Range(0, 32).Select(i => (byte)i)];
+ var hasher = new HmacSecretHasher(key);
+ var registrations = Enumerable.Range(0, 100).Select(i =>
+ new HoneyTokenRegistration($"key-{i:D3}", HoneyTokenKind.ApiKey, $"fictional placement {i}")
+ {
+ Triggers = [new HoneyTrigger(TriggerDomain.ApiKey, hasher.ComputeDigest(TriggerDomain.ApiKey, $"fictional-key-{i:D4}"))],
+ });
+
+ _registry = TokenRegistryBuilder.Build(hasher, registrations).Registry
+ ?? throw new InvalidOperationException("The benchmark registry is invalid.");
+ _id = new HoneyTokenId("key-050");
+ }
+
+ [Benchmark(Baseline = true)]
+ public bool TryMatchWithoutMatch() => _registry.TryMatch(TriggerDomain.ApiKey, LegitimateKey, out _);
+
+ [Benchmark]
+ public bool TryMatchWithMatch() => _registry.TryMatch(TriggerDomain.ApiKey, DecoyKey, out _);
+
+ [Benchmark]
+ public bool TryMatchInEmptyDomain() => _registry.TryMatch(TriggerDomain.RequestPath, "/orders/42", out _);
+
+ [Benchmark]
+ public bool TryGetById() => _registry.TryGet(_id, out _);
+}
diff --git a/tests/WalterEgo.Benchmarks/WalterEgo.Benchmarks.csproj b/tests/WalterEgo.Benchmarks/WalterEgo.Benchmarks.csproj
index b0ac756..1268259 100644
--- a/tests/WalterEgo.Benchmarks/WalterEgo.Benchmarks.csproj
+++ b/tests/WalterEgo.Benchmarks/WalterEgo.Benchmarks.csproj
@@ -8,4 +8,8 @@
+
+
+
+
diff --git a/tests/WalterEgo.Benchmarks/packages.lock.json b/tests/WalterEgo.Benchmarks/packages.lock.json
index 39b8dde..ace19eb 100644
--- a/tests/WalterEgo.Benchmarks/packages.lock.json
+++ b/tests/WalterEgo.Benchmarks/packages.lock.json
@@ -171,6 +171,9 @@
"type": "Transitive",
"resolved": "4.7.0",
"contentHash": "VybpaOQQhqE6siHppMktjfGBw1GCwvCqiufqmP8F1nj7fTUNtW35LOEt3UZTEsECfo+ELAl/9o9nJx3U91i7vA=="
+ },
+ "walterego.core": {
+ "type": "Project"
}
}
}
diff --git a/tests/WalterEgo.Core.Tests/ChangingCollections.cs b/tests/WalterEgo.Core.Tests/ChangingCollections.cs
new file mode 100644
index 0000000..6567602
--- /dev/null
+++ b/tests/WalterEgo.Core.Tests/ChangingCollections.cs
@@ -0,0 +1,44 @@
+using System.Collections;
+using System.Diagnostics.CodeAnalysis;
+
+namespace WalterEgo.Core.Tests;
+
+// Collections that return different content after the first enumeration, to prove that inputs are read once.
+internal sealed class ChangingList(IReadOnlyList first, IReadOnlyList later) : IReadOnlyList
+{
+ private int _reads;
+
+ private IReadOnlyList Current => _reads == 0 ? first : later;
+
+ public int Count => Current.Count;
+
+ public T this[int index] => Current[index];
+
+ public IEnumerator GetEnumerator() => (_reads++ == 0 ? first : later).GetEnumerator();
+
+ IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
+}
+
+internal sealed class ChangingDictionary(IReadOnlyDictionary first, IReadOnlyDictionary later)
+ : IReadOnlyDictionary
+{
+ private int _reads;
+
+ private IReadOnlyDictionary Current => _reads == 0 ? first : later;
+
+ public int Count => Current.Count;
+
+ public IEnumerable Keys => Current.Keys;
+
+ public IEnumerable Values => Current.Values;
+
+ public string this[string key] => Current[key];
+
+ public bool ContainsKey(string key) => Current.ContainsKey(key);
+
+ public bool TryGetValue(string key, [MaybeNullWhen(false)] out string value) => Current.TryGetValue(key, out value);
+
+ public IEnumerator> GetEnumerator() => (_reads++ == 0 ? first : later).GetEnumerator();
+
+ IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
+}
diff --git a/tests/WalterEgo.Core.Tests/HmacSecretHasherTests.cs b/tests/WalterEgo.Core.Tests/HmacSecretHasherTests.cs
new file mode 100644
index 0000000..206a397
--- /dev/null
+++ b/tests/WalterEgo.Core.Tests/HmacSecretHasherTests.cs
@@ -0,0 +1,119 @@
+namespace WalterEgo.Core.Tests;
+
+public sealed class HmacSecretHasherTests
+{
+ private const string DecoyValue = "fictional-decoy-0001";
+
+ // Computed outside .NET with a hand-written RFC 5869 HKDF over Python's hmac and hashlib modules:
+ // subkey = HKDF-SHA256(ikm = bytes 0..31, salt = empty, info = "walterego/v1/