feat(cache): decide key masking with a policy the whole library can reach

[cosmin-staicu]

Closes #129. Replaces #160, which is closed: review there converged on the design problem this fixes.

The problem with the previous shape

Masking was a per-tier option. Every component that logs a key then needs those options threaded to it, and several cannot get them: the multilayer local setter logs keys at warning, the rehydration coordinator at error, and the broadcast change token at trace and debug. Keys reached logs with masking on, and each new site meant more plumbing.

The seam

IKeyMaskingPolicy answers one question, whether a key is secret, and is resolved from the container. Any component can consult it without carrying configuration.

b.AddKeyMasking("session:", "user:");   // built-in prefix policy
b.AddKeyMasking<ByValueTypeMasking>();  // or your own

• Off by default. Nothing registered resolves NullKeyMaskingPolicy, matching how every other seam here defaults.
• The context carries what a decision needs: the caller's key, the value type when the site knows it, and which provider is logging, so one policy can answer differently per tier.
• It returns a bool. Rendering stays with the library, so a policy cannot leak the value it was asked to judge. A policy that throws masks rather than taking the log call down.

Rendering makes no assumption about layout

The caller's key is spliced out of whatever the key strategy composed, found case-insensitively wherever it sits, so a prefix, a suffix, or a cluster hash tag all work. This is why the previous probe machinery is gone: with both the caller's key and the composed key in hand there is nothing to discover.

A composed key that does not contain the caller's key, from a strategy that hashes or truncates, is masked whole rather than shown.

Identifiers stay readable. A row id or a correlation GUID is not a secret, and removing it makes the line useless.

Cost

Nothing on a disabled level. The generated log methods take LoggedKey, which renders in ToString, so an unwritten line never consults the policy, never masks, and never converts a Redis key to text.

Reach

Both caches on every tier, the multilayer local setter, the rehydration coordinator, the broadcast change token and factory, and the cache event publisher: 41 log declarations and 61 call sites.

AddDistributedCache is deliberately not subject to the application's policy. Those keys belong to the consumer, so the adapter and the private tiers it configures always mask.

Verification

Solution builds with zero warnings. Full suite passes on both frameworks, 1688 tests on .NET 10 and 1667 on .NET 8, including a container test that a cache miss line follows the policy and one that the broadcast change token masks the key it waits on. One existing test changed meaning by design: the distributed adapter now masks the key in its failed-write line, and asserts that.

🤖 Generated with Claude Code

https://claude.ai/code/session_017fwLrS3Sbcen8v6iRkUaFB

[github-actions]

🔎 Maintainer heads-up: automated triage flagged this PR as potentially material, so it may need a signed CLA in addition to the DCO sign-off.

Strong signals

• adds public API surface (PublicAPI.Unshipped.txt in src/UiPath.Caching)

Other signals

• large production change (+564 lines under src/)

This is advisory only — the bot does not decide. Please judge against the CLA criteria (material, product-critical, patent-sensitive, corporate contributor, broad commercial use). Note that thresholds can be gamed by splitting PRs, so use your judgement.

• If a CLA is needed → add the cla-required label (a contributor comment with signing steps is posted automatically).
• If it is not needed → replace needs-cla-review with cla-not-required so later pushes don't re-flag it.

[Copilot]

🟡 Changes recommended

Key masking/rendering has a confirmed leak edge case (only first occurrence masked) plus confirmed avoidable allocations/string conversions on disabled log levels that conflict with the stated performance goals.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Introduces a container-resolved key-masking policy (IKeyMaskingPolicy) and routes key rendering through LoggedKey so all log sites across caches and supporting components can consistently mask potentially-secret keys (including for IDistributedCache adapter scenarios).

Changes:

• Add IKeyMaskingPolicy + built-in implementations, plus AddKeyMasking(...) builder extensions and default DI registration.
• Replace direct key logging with LoggedKey / KeyMasker across multilayer caches, Redis caches, broadcast change tokens, event publisher, rehydration coordinator, and local-memory setters.
• Add/adjust tests and documentation/changelog entries to validate and describe masking behavior and reach.

File summaries

File	Description
tests/UiPath.Caching.Tests/Logging/MaskedLogSiteTests.cs	Verifies masking reaches non-cache components (multilayer + change token).
tests/UiPath.Caching.Tests/Logging/KeyMaskingTests.cs	Unit tests for masking rules, rendering, DI defaults, and policy behavior.
tests/UiPath.Caching.Tests/Distributed/UiPathDistributedCacheTests.cs	Updates adapter test to assert keys are masked in warning logs.
src/UiPath.Caching/RehydrationCoordinator.cs	Uses LoggedKey for error logs; accepts optional KeyMasker.
src/UiPath.Caching/Redis/RedisHashCache.cs	Switches Redis hash-cache log sites to LoggedKey and passes masking policy down.
src/UiPath.Caching/Redis/RedisCacheProvider.cs	Plumbs IKeyMaskingPolicy into Redis cache instances.
src/UiPath.Caching/Redis/RedisCacheBase.cs	Creates per-provider KeyMasker and helper Logged(...) methods.
src/UiPath.Caching/Redis/RedisCache.cs	Switches Redis cache log sites to LoggedKey and threads key info where needed.
src/UiPath.Caching/PublicAPI.Unshipped.txt	Captures new public API surface and updated constructor signatures.
src/UiPath.Caching/MultilayerHashCache.cs	Switches multilayer hash-cache log sites to LoggedKey and passes masker to setter.
src/UiPath.Caching/MultilayerCacheBase.cs	Creates per-cache KeyMasker; passes it into rehydrator/event publisher; adds Logged(...) helpers.
src/UiPath.Caching/MultilayerCache.cs	Switches multilayer cache log sites (including batch-key sites) to LoggedKey(s).
src/UiPath.Caching/MemoryCacheSetter.cs	Masks keys in local-memory warning logs; accepts optional KeyMasker.
src/UiPath.Caching/Logging/PrefixKeyMaskingPolicy.cs	Adds built-in prefix-based policy (with “mask all” semantics when no prefixes).
src/UiPath.Caching/Logging/LoggedKey.cs	Adds LoggedKey/LoggedKeys wrappers deferring rendering to logger formatting.
src/UiPath.Caching/Logging/KeyMasker.cs	Adds rendering + masking logic and identifier detection.
src/UiPath.Caching/Logging/IKeyMaskingPolicy.cs	Adds IKeyMaskingPolicy, MaskingContext, and built-in null/always-mask policies.
src/UiPath.Caching/LocalMemorySetter.cs	Plumbs optional KeyMasker into memory setter base.
src/UiPath.Caching/InMemoryRedisCacheProvider.cs	Plumbs IKeyMaskingPolicy into multilayer cache instances.
src/UiPath.Caching/InMemoryCacheProvider.cs	Plumbs IKeyMaskingPolicy into multilayer cache instances.
src/UiPath.Caching/HashLocalMemorySetter.cs	Plumbs optional KeyMasker into hash memory setter base.
src/UiPath.Caching/GlobalUsings.cs	Adds global using for logging namespace.
src/UiPath.Caching/Distributed/UiPathDistributedCache.cs	Forces adapter log sites to use LoggedKey.Secret(...).
src/UiPath.Caching/Config/KeyMaskingBuilderExtensions.cs	Adds AddKeyMasking(...) registration extensions.
src/UiPath.Caching/Config/DistributedCacheCollectionExtensions.cs	Forces distributed-cache adapter backing tiers to always-mask keys.
src/UiPath.Caching/Config/CachingBuilder.cs	Registers default NullKeyMaskingPolicy in DI when none configured.
src/UiPath.Caching/CacheEventPublisher.cs	Masks cache keys in event-publisher log sites.
src/UiPath.Caching/Broadcast/ChangeTokenFactory.cs	Masks token in factory trace log; threads policy into change token.
src/UiPath.Caching/Broadcast/ChangeToken.cs	Masks key/token usages in change-token log sites.
docs/reference/settings.md	Documents key masking as a registration seam.
docs/how-to/telemetry-and-strategies.md	Adds how-to documentation for masking configuration and semantics.
CHANGELOG.md	Adds changelog entry describing key masking feature and scope.

Review details

Suppressed comments (1)

src/UiPath.Caching/Broadcast/ChangeToken.cs:123

• If cacheEvent.Data is null, this path currently logs an "ignored" message with an empty key. Using the keyless LogEventIgnored overload for the null-data case keeps logs accurate and avoids implying an empty-string key.

        if (!string.Equals(data?.Key, _key, StringComparison.OrdinalIgnoreCase))
        {
            LogEventIgnoredWithKey(Logged(data?.Key), _topic, cacheEvent.Id, cacheEvent.Source);
            return false;
        }

• Files reviewed: 32/32 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

ChangeToken feeds MaskingContext.CacheName with the topic key rather than the provider/tier name, which can break tier-aware masking policies.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 32/32 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

There are compilation-blocking namespace/import issues in newly added masking-related tests and policy code, plus a small log-message typo.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 32/32 changed files
• Comments generated: 4
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

A few newly added/updated docs/comments state that masking always preserves the first three characters, but the implementation masks keys of length ≤3 entirely, so the documentation/changelog should be aligned with the actual behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 32/32 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Several public/protected constructors were modified by adding parameters, which is binary-breaking; reintroducing the previous overloads to delegate to the new signatures would preserve runtime compatibility.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 32/32 changed files
• Comments generated: 5
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Several warning and broadcast paths discard caller-key or value-type context, allowing configured policies to leave secret keys unmasked.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

src/UiPath.Caching/MemoryCacheSetter.cs:94

• This refresh state retains EntryType, but the log wrapper drops it. Consequently, value-type-based policies receive ValueType = null and can expose the key on this warning path. Forward metadataState.EntryType to the masker.

            logger.LogWarning(ex, "Unable to refresh cache cacheKey {CacheKey}", LoggedKey.For(_masker, metadataState.CacheKey));

• Files reviewed: 32/32 changed files
• Comments generated: 4
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Selective policies and distributed change-token paths can still expose keys, and several value-type-aware sites omit required context.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (6)

src/UiPath.Caching/Redis/RedisCache.cs:957

• Logged(key) treats the physical Redis key as the policy input. With AddKeyMasking("session:"), a normal key such as app:s:session:secret does not start with the configured prefix, so this Warning still logs the complete secret. The audit path needs the caller key as well as the composed Redis key, or must fail closed when only a composed key is available.

            LogLargeValueDetected(Logged(key), valueLen);

src/UiPath.Caching/Redis/RedisHashCache.cs:967

• This has the same composed-only leak as the string cache: the prefix policy evaluates a physical key like app:h:session:secret, so session: does not match and the Warning emits the raw key. Pass the logical key into the audit path or mask composed-only keys fail-closed.

            LogLargeValueDetected(Logged(key), field, valueLen);

src/UiPath.Caching/MemoryCacheSetter.cs:52

• This warning knows entryType but omits it from MaskingContext. A documented policy such as context.ValueType == typeof(SessionData) therefore returns false and the failing key is logged verbatim.

            logger.LogWarning(ex, "Unable to set local memory for {CacheKey}", LoggedKey.For(_masker, options.CacheKey));

src/UiPath.Caching/MemoryCacheSetter.cs:94

• metadataState.EntryType is available here but is not passed to the masking policy. Value-type-based policies consequently fail to mask this warning.

            logger.LogWarning(ex, "Unable to refresh cache cacheKey {CacheKey}", LoggedKey.For(_masker, metadataState.CacheKey));

src/UiPath.Caching/Broadcast/ChangeTokenFactory.cs:42

• entryType is available but discarded: the creation log omits it, and the constructed ChangeToken stores no value type, so all of its later logs pass ValueType = null. This breaks the documented value-type policy for the entire change-token path; pass the type to both the immediate LoggedKey and the token.

            LogCreateChangeToken(topic.TopicKey, LoggedKey.For(masker, token), _sourceUri);
        }

        var acceptedEvents = KnownCacheProviderNames.InMemory.Equals(cacheName, StringComparison.OrdinalIgnoreCase) ? MemoryAcceptedEvents : null;
        return new ChangeToken<T>(token, topic, _sourceUri, _serializer, _loggerFactory.CreateLogger<ChangeToken<T>>(), _telemetryProvider, acceptedEvents, masker);

src/UiPath.Caching/Logging/KeyMasker.cs:64

• This still says three characters are always retained, but Mask returns only **** for values of length three or less. The summary should include the short-key behavior already documented elsewhere.

    /// <summary>First three characters then <c>****</c>: enough to correlate two lines, not to replay a key.</summary>

• Files reviewed: 32/32 changed files
• Comments generated: 6
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Several paths still evaluate composed keys or omit value types, allowing configured masking policies to emit raw secrets.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (10)

src/UiPath.Caching/MultilayerCache.cs:808

• These are composed cache keys, so a prefix policy is evaluated against the strategy prefix rather than the caller key. For example, AddKeyMasking("session:") does not match v2:session:... and the raw keys are logged. Pass the CacheEntryOptions collection to the existing Logged overload.

                LogSettingLocalOnlyForCacheKeys(Logged(setEntries.Select(o => o.CacheEntry.CacheKey).ToArray(), typeof(T)));

src/UiPath.Caching/MultilayerCache.cs:815

• cacheEntry.CacheKey is already strategy-composed, so treating it as the caller key bypasses prefix policies when a custom cache-key strategy prepends text. Use the options overload to evaluate the original CallerKey while rendering the composed key.

            LogReplacingCachedKey(Logged(cacheEntry.CacheKey, typeof(T)));

src/UiPath.Caching/MultilayerCache.cs:951

• This converts the options back to composed keys before masking. A policy configured for a caller prefix such as session: will not match v2:session:..., so this warning can expose every key in the failed removal. Pass the options directly so LoggedKeys retains caller/composed pairs.

                LogInnerCacheRemoveKeysError(ex, Logged(options.Select(o => o.CacheKey).ToArray(), typeof(T)));

src/UiPath.Caching/MultilayerCache.cs:1006

• The key returned by the inner cache is the composed key. Evaluating it as the caller key lets a prepended cache-key strategy defeat AddKeyMasking("session:"). Use the corresponding options entry, which still carries both CallerKey and CacheKey.

            LogFoundInnerCacheCopy(Logged(key, typeof(T)));

src/UiPath.Caching/MultilayerCache.cs:1101

• The fetched key is strategy-composed, so prefix-based masking can return false before this trace line renders it. The matching CacheEntryOptions retains the original caller key and should be used for the masking decision.

            LogFoundInnerCacheCopy(Logged(key, typeof(T)));

src/UiPath.Caching/MultilayerCache.cs:1172

• These options are reduced to their composed keys before masking, causing caller-prefix policies to miss whenever the cache-key strategy prepends or otherwise transforms the key. Pass the CacheEntryOptions values so each key is judged by CallerKey.

                    LogSettingLocalOnlyForCacheKeys(Logged(cacheEntries.Select(o => o.CacheEntry.CacheKey).ToArray(), typeof(T)));

src/UiPath.Caching/MultilayerCache.cs:1189

• This warning evaluates each composed key as if it were the caller key. With a strategy prefix, a configured secret prefix no longer matches and the failed-write warning exposes the raw keys. Keep the CacheEntryOptions objects when constructing LoggedKeys.

                LogInnerCacheSetKeysError(ex, Logged(cacheEntries.Select(o => o.CacheEntry.CacheKey).ToArray(), typeof(T)));

src/UiPath.Caching/MemoryCacheSetter.cs:54

• This warning also passes only the composed options.CacheKey to LoggedKey. A custom prefixing strategy therefore prevents a caller-prefix policy from matching and can expose the raw key on the local-memory failure path. Build the logged value from both CallerKey and the composed key.

            logger.LogWarning(ex, "Unable to set local memory for {CacheKey}", LoggedKey.For(_masker, options.CacheKey, entryType));

src/UiPath.Caching/MemoryCacheSetter.cs:96

• RefreshMetadataState.CacheKey contains only the composed key, so this warning cannot apply a policy configured for the original caller prefix. Preserve CallerKey in the refresh state and pass caller/composed values separately when rendering.

            logger.LogWarning(ex, "Unable to refresh cache cacheKey {CacheKey}", LoggedKey.For(_masker, metadataState.CacheKey, metadataState.EntryType));

src/UiPath.Caching/Broadcast/ChangeToken.cs:136

• This mismatch path logs the event's composed key as though it were the caller key. With a prefixing cache-key strategy, a policy for session: sees v2:session:..., returns false, and the ignored key is emitted verbatim. Omit it or apply conservative whole-key masking when the original caller key is unavailable.

                LogEventIgnoredWithKey(Logged(ignoredKey), _topic, cacheEvent.Id, cacheEvent.Source);

• Files reviewed: 38/38 changed files
• Comments generated: 6
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Some transformed batch and refresh keys can still leak, and reconnect scheduling retains a race that can lose resubscription.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

src/UiPath.Caching/MultilayerCache.cs:819

• cacheEntry includes both the caller and composed keys, but the composed-only wrapper never asks the policy whether this key should be masked. Consequently this batch path masks even keys that a selective policy explicitly allows; use the entry-aware overload.

            LogReplacingCachedKey(LoggedComposed(cacheEntry.CacheKey, typeof(T)));

• Files reviewed: 42/42 changed files
• Comments generated: 6
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

A reconnect retry can still collide with the active subscription callback and be delayed for the full timer period.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 43/43 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Strategy-composed keys can lose their original caller key before reaching Redis L2 logs, allowing selective masking policies to expose secrets.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 43/43 changed files
• Comments generated: 2
• Review effort level: Balanced

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
87.9% Coverage on New Code
1.3% Duplication on New Code

See analysis details on SonarQube Cloud