feat(seedless-onboarding): add dataType support for secret data items #7284

huggingbot · 2025-12-02T08:17:21Z

Explanation

The metadata service now supports a dataType column for categorizing secret data (PrimarySrp, ImportedSrp, ImportedPrivateKey). This enables clients to distinguish between different types of backed-up secrets

Changes include:

Add dataType parameter to insert operations
Add updateSecretDataItem and batchUpdateSecretDataItems for updating existing items
Update fetchAllSecretData to return storage metadata (itemId, dataType) alongside secret data
Refactor SecretMetadata to separate local metadata from storage-level metadata

References

https://consensyssoftware.atlassian.net/browse/SL-350

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

- Add dataType parameter to createToprfKeyAndBackupSeedPhrase and addNewSecretData - Add updateSecretDataItem and batchUpdateSecretDataItems methods - Update fetchAllSecretData to return SecretDataItemWithMetadata[]

lwin-kyaw · 2025-12-02T10:52:51Z

packages/seedless-onboarding-controller/src/types.ts

+  /**
+   * The client-assigned data type classification.
+   */
+  dataType?: EncAccountDataType;


Why do we need this extra type SecretMetadata already has it has type

type is in encrypted data, which the server can't access to
data_type is a server-side column
the server needs to know the type of key for the deletion api: we're preventing clients from deleting the default srp

lwin-kyaw · 2025-12-02T10:53:21Z

packages/seedless-onboarding-controller/src/types.ts

+  /**
+   * The server-assigned item ID for this row.
+   */
+  itemId?: string;


Should add to the SecretMetadata instead of creating another wrapping types

itemId is not part of the secret data, hence it shouldn't belong inside SecretMetadata. Only data, timestamp, type and version are part of SecretMetadata

lwin-kyaw · 2025-12-02T10:54:12Z

packages/seedless-onboarding-controller/src/types.ts

+/**
+ * A secret data item with storage-level metadata from the metadata store.
+ */
+export type SecretDataItemWithMetadata<


Please add the required metadata to the SecretMetadata class instead of creating another type defs.

The purpose the metadata class is to store and do things with extra non-secret data.

itemId and dataType are not part of the secret data. They belong outside of it, hence the wrapper type SecretDataItemWithMetadata is introduced.

The purpose the metadata class is to store and do things with extra non-secret data.

by the metadata class, did u mean the SecretMetadata class?

moved itemId and dataType here

lwin-kyaw · 2025-12-02T10:55:23Z

packages/seedless-onboarding-controller/src/index.ts

 export { SecretMetadata } from './SecretMetadata';
 export { RecoveryError } from './errors';
+
+export { EncAccountDataType } from '@metamask/toprf-secure-backup';


Not sure why we export this, but this should not be determined from the users (ext or mobile).

it's exported so clients can use it in createToprfKeyAndBackupSeedPhrase, addNewSecretData, updateSecretDataItem and batchUpdateSecretDataItems. The clients do determine the type of secret, e.g. in addNewSecretData, there's a type param of type SecretType where the client can decide if it's a mnemonic or privateKey

lwin-kyaw · 2025-12-02T11:16:47Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

    password: string,
    seedPhrase: Uint8Array,
    keyringId: string,
+    dataType: EncAccountDataType = EncAccountDataType.PrimarySrp,


createToprfKeyAndBackupSeedPhrase only used for new users scenario, this param should not be exposed at all and type is always primary.

lwin-kyaw · 2025-12-02T11:17:12Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

    type: SecretType,
    options?: {
      keyringId?: string;
+      dataType?: EncAccountDataType;


we have type field in 2nd param, we don't need new field here.

SecretType and EncAccountDataType are slightly different:

SecretType only has 2 types: SRP or private key; EncAccountDataType has 3: Primary SRP, imported SRP, imported private key

Even if we were to extend SecretType to include a primary SRP, using string values should be avoided to protect user privacy when data is transmitted to the server

we can attempt to migrate SecretType from string to number, making it essentially the same as EncAccountDataType. Though they are essentially different things, and in the future we might want to remove type from the encrypted data since we will use dataType as the source of truth. What do u think?

If we intend to do the migration at the unlock and rehydration, during this addNewSecretData method call, we can assume that the user data is already migrated. Hence, we don't need both SecretType and EncAccountDataType to be present.

We can use EncAccountDataType type for 2nd param type.

lwin-kyaw · 2025-12-02T11:19:03Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

+   * @param params.dataType - The data type to set for the item.
+   * @returns A promise that resolves when the update is complete.
+   */
+  async updateSecretDataItem(params: {


Can we specify why and when we need to call this? since in the clients, update* is not something we usually do with SRPs

it's used to migrate existing users to update the data_type column in the metadata service. Currently the server doesn't know the type of secret (it's encrypted). It needs to know for the deletion API to work: to prevent clients from deleting the default SRP

added more notes here

Imo, I don't think we should expose this method. This is purely internal controller logic. Rather than adding migration code to the client sides (ext/mobile), we should handle this internally inside the controller package (with proper versioning).

lwin-kyaw · 2025-12-02T11:19:42Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

+   * @param params.updates - Array of objects containing itemId and fields to update.
+   * @returns A promise that resolves when all updates are complete.
+   */
+  async batchUpdateSecretDataItems(params: {


added more notes here

lwin-kyaw · 2025-12-02T11:24:40Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

      // validate the primary secret data is a mnemonic (SRP)
-      const primarySecret = secrets[0];
-      if (primarySecret.type !== SecretType.Mnemonic) {
+      if (!SecretMetadata.matchesType(results[0].secret, SecretType.Mnemonic)) {


Since we have Primary type, why don't we use here?

fixed here
now we're validating both the .type in the encrypted data and also dataType

lwin-kyaw · 2025-12-02T11:25:09Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

    authKeyPair: KeyPair;
    options?: {
      keyringId?: string;
+      dataType?: EncAccountDataType;


we already have type in the params object. Please use it.

related question and answer here: #7284 (comment)

…ckupSeedPhrase method

…gController

…legacy data

… PrimarySrp first, then createdAt

…etadata - Add itemId, dataType, createdAt properties to SecretMetadata class - Remove SecretDataItemWithMetadata wrapper type - Update fetchAllSecretData to return SecretMetadata[] directly - Add tests for storage metadata properties

…EUUID sorting TIMEUUID strings are not lexicographically sortable. Replace localeCompare with compareTimeuuid utility that extracts and compares actual timestamps.

huggingbot · 2025-12-08T05:21:39Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

+      );
+
+      // Sort: PrimarySrp first, then by createdAt/timestamp (oldest first)
+      results.sort((a, b) => {


sorting is required here even though /get in metadata already does sorting because we need this for the migration since dataType and createdAt could be null thus we'll need a fallback to use the client-side timestamp

lwin-kyaw · 2025-12-17T14:18:55Z

packages/seedless-onboarding-controller/src/SecretMetadata.ts

    this.#data = data;
    this.#timestamp = options?.timestamp ?? Date.now();
    this.#type = options?.type ?? SecretType.Mnemonic;
    this.#version = options?.version ?? SecretMetadataVersion.V1;


We should maintain the metadata type version with this.

The existing (old) items will have version number SecretMetadataVersion.V1 after decryption. We can do the increment on version number (V2) for new structure.

lwin-kyaw · 2025-12-17T14:21:37Z

packages/seedless-onboarding-controller/src/SecretMetadata.ts

+    storageMetadata?: StorageMetadata,
  ): SecretMetadata<DataType> {
    const serializedMetadata = bytesToString(rawMetadata);
    const parsedMetadata = JSON.parse(serializedMetadata);


Please update the SecretMetadata.assertIsValidSecretMetadataJson with the new structure.

lwin-kyaw · 2025-12-17T14:24:56Z

packages/seedless-onboarding-controller/src/SecretMetadata.ts

-    });
+  ): number {
+    return order === 'asc'
+      ? a.timestamp - b.timestamp


shouldn't this be compared using the server timestamp (createdAt?)

lwin-kyaw · 2025-12-17T14:29:27Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

    type: SecretType,
    options?: {
      keyringId?: string;
+      dataType?: EncAccountDataType;


If we intend to do the migration at the unlock and rehydration, during this addNewSecretData method call, we can assume that the user data is already migrated. Hence, we don't need both SecretType and EncAccountDataType to be present.

We can use EncAccountDataType type for 2nd param type.

lwin-kyaw · 2025-12-17T14:30:44Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

+   * @param params.dataType - The data type to set for the item.
+   * @returns A promise that resolves when the update is complete.
+   */
+  async updateSecretDataItem(params: {


Imo, I don't think we should expose this method. This is purely internal controller logic. Rather than adding migration code to the client sides (ext/mobile), we should handle this internally inside the controller package (with proper versioning).

lwin-kyaw · 2025-12-17T14:31:53Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

+   * @param params.updates - Array of objects containing itemId and dataType to assign.
+   * @returns A promise that resolves when all updates are complete.
+   */
+  async batchUpdateSecretDataItems(params: {


Please move the migration logics to internal scope.

lwin-kyaw · 2025-12-17T14:48:46Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

+      );
+
+      // Sort: PrimarySrp first, then by createdAt/timestamp (oldest first)
+      results.sort((a, b) => {


Why don't we move the whole logic into SecretMetadata class?

lwin-kyaw · 2025-12-17T14:49:48Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

+      });
+
+      // Validate the first item is the primary SRP
+      const firstItem = results[0];


I think we can refactor this logics into SecretMetadata class.

lwin-kyaw · 2025-12-17T14:51:31Z

packages/seedless-onboarding-controller/src/SeedlessOnboardingController.ts

+      const isDataTypePrimary =
+        firstItem.dataType === undefined || // Legacy data (before dataType was introduced)
+        firstItem.dataType === EncAccountDataType.PrimarySrp;
+      const isMnemonic = SecretMetadata.matchesType(


After the migration, this become invalid right? We won't have the type anymore and we will be relying on the EncAccountDataType.PrimarySrp.

So, this will incorrectly result in false and the below error will be thrown.

feat(seedless-onboarding): add dataType support for secret data items

611556b

- Add dataType parameter to createToprfKeyAndBackupSeedPhrase and addNewSecretData - Add updateSecretDataItem and batchUpdateSecretDataItems methods - Update fetchAllSecretData to return SecretDataItemWithMetadata[]

lwin-kyaw requested changes Dec 2, 2025

View reviewed changes

huggingbot added 7 commits December 2, 2025 20:09

refactor: Removed default dataType parameter from createToprfKeyAndBa…

85275f5

…ckupSeedPhrase method

refactor: update documentation for secret data item methods

fc73107

refactor: enhance primary secret data validation in SeedlessOnboardin…

3afa879

…gController

fix: Update sorting mechanism to prioritize PrimarySrp dataType over …

90d642b

…legacy data

feat(seedless-onboarding-controller): add createdAt field and sort by…

ac52a76

… PrimarySrp first, then createdAt

fix(seedless-onboarding-controller): use timestamp extraction for TIM…

2885314

…EUUID sorting TIMEUUID strings are not lexicographically sortable. Replace localeCompare with compareTimeuuid utility that extracts and compares actual timestamps.

huggingbot commented Dec 8, 2025

View reviewed changes

huggingbot added 3 commits December 16, 2025 12:41

chore: Update version

3e2b477

Merge branch 'main' into feat/data-type

f0b9638

chore: Update CHANGELOG and remove deprecated methods in SecretMetadata

ebcc4e0

lwin-kyaw added team-onboarding area-onboarding labels Dec 17, 2025

lwin-kyaw reviewed Dec 17, 2025

View reviewed changes

fix: improve sorting logic for secret data with mixed createdAt values

b279fa5

Uh oh!

feat(seedless-onboarding): add dataType support for secret data items #7284

Are you sure you want to change the base?

feat(seedless-onboarding): add dataType support for secret data items #7284

Uh oh!

Conversation

huggingbot commented Dec 2, 2025

Explanation

References

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huggingbot Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huggingbot Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huggingbot Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huggingbot Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huggingbot Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

huggingbot Dec 2, 2025 •

edited

Loading

huggingbot Dec 2, 2025 •

edited

Loading

huggingbot Dec 2, 2025 •

edited

Loading

huggingbot Dec 2, 2025 •

edited

Loading

huggingbot Dec 2, 2025 •

edited

Loading