SecureStorage

Warning: Every tool in this suite is Critical because it can expose or mutate secrets. Keep the allow-list narrow and only enable this suite when you explicitly need secure-storage inspection or repair. You must not ever distribute these tools in a release build.

Install

dotnet add package Ansight.Tools.SecureStorage --prerelease

Register the Suite

using Ansight;
using Ansight.Tools.SecureStorage;

var options = Options.CreateBuilder()
    .WithSecureStorageTools(secure =>
    {
        secure.WithStorageIdentifier("MyApp");
        secure.AllowKeys("session_token", "refresh_token");
    })
    .WithAllToolAccess()
    .Build();

All secure-storage operations require WithAllToolAccess() or a custom critical-enabled ToolGuard.

When using the Ansight or Ansight.Maui all-in-one packages, configure secure-storage access inside the setup callback:

using Ansight;
using Ansight.Tools.SecureStorage;

var options = Options.CreateBuilder()
    .WithAnsightSdk(ansight =>
    {
        ansight.WithSecureStorageTools(secure =>
        {
            secure.WithStorageIdentifier("MyApp");
            secure.AllowKeyPrefix("ansight.secure.");
        });
    })
    .Build();

Use the same WithSecureStorageTools(...) call inside UseAnsight<App>(...) for MAUI. The all-in-one setup skips the default secure-storage registration when the callback registers the suite, so the configured storage identifier and key allow-list are the active secure-storage policy. Full tool access is applied before the callback, so the callback can still narrow the guard.

Registration API

WithSecureStorageTools(): registers the suite with no key access until you allow-list keys.
WithSecureStorageTools(secure => ...): configures storage selection and key allow-lists.
WithStorageIdentifier(...): set both the Android encrypted-preferences name and Apple Keychain service together.
WithAndroidStore(...): override the Android encrypted-preferences name.
WithAppleService(...): override the Apple Keychain service.
AllowKey(...) / AllowKeys(...): allow specific keys.
AllowKeyPrefix(...) / AllowKeyPrefixes(...): allow groups of keys by prefix.

Specific Concerns

This suite is deny-all by default.
You must explicitly allow keys or key prefixes.
Values may contain credentials, tokens, or other secrets.
All secure-storage tools use ToolPolicy.Critical, including reads, and stay blocked unless you use WithAllToolAccess() or a critical-enabled custom ToolGuard.
On Android, the package pulls in AndroidX Security Crypto support.

Available registration constraints:

WithStorageIdentifier(...)
WithAndroidStore(...)
WithAppleService(...)
AllowKey(...) / AllowKeys(...)
AllowKeyPrefix(...) / AllowKeyPrefixes(...)

WithStorageIdentifier(...) sets both the Android encrypted-preferences name and the Apple Keychain service unless you override them separately.

Tool Matrix

Name	Id	Policy	Description
`Get Secure Storage Value`	`secure.get_value`	`Critical`	Reads a decrypted value from the configured secure storage backend.
`Set Secure Storage Value`	`secure.set_value`	`Critical`	Writes a value into the configured secure storage backend.
`Remove Secure Storage Key`	`secure.remove_key`	`Critical`	Deletes a value from the configured secure storage backend.

Get Secure Storage Value

Arguments:

key: required secure-storage key

Returns:

store
key
exists
value
capturedAtUtc

Example:

{
  "toolId": "secure.get_value",
  "arguments": {
    "key": "session_token"
  }
}

Set Secure Storage Value

Arguments:

key: required secure-storage key
value: required secure-storage value

Returns:

store
key
updated
capturedAtUtc

Example:

{
  "toolId": "secure.set_value",
  "arguments": {
    "key": "session_token",
    "value": "redacted-token"
  }
}

Remove Secure Storage Key

Arguments:

key: required secure-storage key

Returns:

store
key
removed
capturedAtUtc

Example:

{
  "toolId": "secure.remove_key",
  "arguments": {
    "key": "session_token"
  }
}