Description

Problem

The redux-persist-filesystem-storage library has two problematic behaviors when handling arbitrary keys in StorageService:

1. Slashes (/) create subdirectories: Keys containing slashes are stored in subdirectories, making them unreachable via getAllKeys. This breaks the clear method for affected keys.

2. Hyphens (-) get corrupted: The library's internal fromFileName function converts hyphens to colons (:), meaning keys like simple-key are returned as simple:key by getAllKeys. This causes a permanent mismatch between stored keys and returned keys.

Solution

This PR introduces URI-style encoding for problematic characters in both namespace and key portions of storage keys:

• / → %2F (prevents subdirectory creation)
• - → %2D (prevents hyphen-to-colon corruption)
• % → %25 (prevents double-encoding issues)

The encoding is applied via shared utility functions (encodeStorageKey/decodeStorageKey) used by both:

• mobileStorageAdapter in storage-service-init.ts
• Migration 118 which stores snap source code

Backward Compatibility

This change is backward compatible and will NOT break existing production keys.

• Existing keys like storageService:TokenListController:tokensChainsCache:0x1 are unaffected because:
  • The namespace (TokenListController) has no special characters → encoding produces identical output
  • Colons (:) are not encoded - they pass through unchanged
  • The key portion (tokensChainsCache:0x1) contains no hyphens or slashes
• Strings without -, /, or % characters produce identical output when encoded
• This means all current production keys work exactly as before, while future keys with special characters will be handled correctly

Examples

# No special characters → unchanged (backward compatible)
storageService:TokenListController:tokensChainsCache:0x1 → storageService:TokenListController:tokensChainsCache:0x1

# Snap ID with slashes and hyphens → encoded
storageService:SnapController:npm:@metamask/bip32-keyring-snap → storageService:SnapController:npm:@metamask%2Fbip32%2Dkeyring%2Dsnap

# Namespace with hyphen → encoded
storageService:Some-Controller:some-key → storageService:Some%2DController:some%2Dkey

# Key with slashes → encoded (prevents subdirectory creation)
storageService:TestController:nested/path/key → storageService:TestController:nested%2Fpath%2Fkey

Files Changed

Changelog

CHANGELOG entry: null

Related issues

Refs: StorageService key handling issues with redux-persist-filesystem-storage

Manual testing steps

Feature: StorageService key encoding

  Scenario: Keys with hyphens are stored and retrieved correctly
    Given the app is running

    When StorageService stores a key containing hyphens (e.g., "npm:@metamask/bip32-keyring-snap")
    Then the key is encoded as "npm:@metamask%2Fbip32%2Dkeyring%2Dsnap" on disk
    And getAllKeys returns the original key "npm:@metamask/bip32-keyring-snap"
    And getItem with the original key returns the stored data

  Scenario: Keys with slashes are stored and retrieved correctly
    Given the app is running

    When StorageService stores a key containing slashes (e.g., "nested/path/key")
    Then the key is stored as a single file (not in subdirectories)
    And getAllKeys returns the original key "nested/path/key"
    And clear removes the key correctly

  Scenario: Existing keys with colons remain unchanged
    Given existing production keys like "storageService:TokenListController:tokensChainsCache:0x1"

    When the app starts with this fix
    Then the existing keys are still accessible
    And no migration is required for existing data

Screenshots/Recordings

N/A - No UI changes

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.