@metamask-previews/seedless-onboarding-controller 8.0.0-preview-e117c8109 → 8.0.0-preview-71413498f

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `runMigrations` method to run pending data migrations for legacy secrets ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Add `setMigrationVersion` method to set migration version directly for new users ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Add `SeedlessOnboardingMigrationVersion` enum for tracking migration versions ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Add `migrationVersion` to controller state to track applied migrations ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Add `itemId`, `dataType`, `createdAt`, and `storageVersion` storage-level properties to `SecretMetadata` ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Add `SecretMetadata.compare` static method for comparing metadata with PrimarySrp prioritization and TIMEUUID-based sorting ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Add `SecretMetadata.compareByTimestamp` static method for comparing metadata by timestamp ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Add `SecretMetadata.matchesType` static method for checking if metadata matches a given type ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Re-export `EncAccountDataType` from `@metamask/toprf-secure-backup` ([#7284](https://github.com/MetaMask/core/pull/7284))
+
+### Changed
+
+- **BREAKING:** Change `addNewSecretData` method signature to require `dataType: EncAccountDataType` instead of `type: SecretType` ([#7284](https://github.com/MetaMask/core/pull/7284))
+  - `SecretType` is now derived internally from `EncAccountDataType`
+  - Encrypted payload still includes `type` for backward compatibility with older clients
+- **BREAKING:** Remove `parseSecretsFromMetadataStore`, `fromBatch`, and `sort` methods from `SecretMetadata` ([#7284](https://github.com/MetaMask/core/pull/7284))
+  - Use `SecretMetadata.compare` or `SecretMetadata.compareByTimestamp` for sorting
+  - Use `SecretMetadata.matchesType` for filtering
+- **BREAKING:** Change `SecretMetadata.fromRawMetadata` signature to require `storageMetadata` parameter ([#7284](https://github.com/MetaMask/core/pull/7284))
+- **BREAKING:** Remove `version` getter from `SecretMetadata`; use `storageVersion` instead ([#7284](https://github.com/MetaMask/core/pull/7284))
+- `refreshAuthTokens` now coalesces concurrent calls — if a refresh is already in-flight, subsequent callers share the same promise rather than issuing duplicate HTTP requests with the same token ([#7989](https://github.com/MetaMask/core/pull/7989))
+- `refreshAuthTokens` now uses the live `state.refreshToken` value when calling `authenticate` after a successful HTTP refresh, preventing a stale-capture bug that could overwrite a concurrently-renewed token with an older one ([#7989](https://github.com/MetaMask/core/pull/7989))
+- `renewRefreshToken` now queues the old token for revocation only after `#createNewVaultWithAuthData` succeeds, ensuring tokens are not queued if vault creation fails ([#7989](https://github.com/MetaMask/core/pull/7989))
+
+### Fixed
+
+- Fix TIMEUUID sorting by extracting actual timestamps instead of using lexicographic comparison ([#7284](https://github.com/MetaMask/core/pull/7284))
+- Fixed `refreshAuthTokens` throwing the generic `FailedToRefreshJWTTokens` error for all HTTP failures — a 401 response (permanently revoked token) now throws `InvalidRefreshToken` instead, giving callers a distinct signal to distinguish permanent from transient failures ([#7989](https://github.com/MetaMask/core/pull/7989))
+
 ## [8.0.0]
 
 ### Added

package/dist/SecretMetadata.cjs

@@ -10,65 +10,40 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _SecretMetadata_data, _SecretMetadata_timestamp, _SecretMetadata_type, _SecretMetadata_version;
+var _SecretMetadata_data, _SecretMetadata_timestamp, _SecretMetadata_type, _SecretMetadata_itemId, _SecretMetadata_dataType, _SecretMetadata_createdAt, _SecretMetadata_storageVersion;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SecretMetadata = void 0;
+const toprf_secure_backup_1 = require("@metamask/toprf-secure-backup");
 const utils_1 = require("@metamask/utils");
 const constants_1 = require("./constants.cjs");
-/**
- * SecretMetadata is a class that adds metadata to the secret.
- *
- * It contains the secret and the timestamp when it was created.
- * It is used to store the secret in the metadata store.
- *
- * @example
- * ```ts
- * const secretMetadata = new SecretMetadata(secret);
- * ```
- */
+const utils_2 = require("./utils.cjs");
 class SecretMetadata {
     /**
-     * Create a new SecretMetadata instance.
-     *
-     * @param data - The secret to add metadata to.
-     * @param options - The options for the secret metadata.
-     * @param options.timestamp - The timestamp when the secret was created.
-     * @param options.type - The type of the secret.
+     * @param data - The secret data.
+     * @param options - Optional metadata. New clients should provide `dataType`.
      */
     constructor(data, options) {
         _SecretMetadata_data.set(this, void 0);
         _SecretMetadata_timestamp.set(this, void 0);
         _SecretMetadata_type.set(this, void 0);
-        _SecretMetadata_version.set(this, void 0);
+        // Storage-level metadata (not encrypted)
+        _SecretMetadata_itemId.set(this, void 0);
+        _SecretMetadata_dataType.set(this, void 0);
+        _SecretMetadata_createdAt.set(this, void 0);
+        _SecretMetadata_storageVersion.set(this, void 0);
         __classPrivateFieldSet(this, _SecretMetadata_data, data, "f");
         __classPrivateFieldSet(this, _SecretMetadata_timestamp, options?.timestamp ?? Date.now(), "f");
-        __classPrivateFieldSet(this, _SecretMetadata_type, options?.type ?? constants_1.SecretType.Mnemonic, "f");
-        __classPrivateFieldSet(this, _SecretMetadata_version, options?.version ?? constants_1.SecretMetadataVersion.V1, "f");
-    }
-    /**
-     * Create an Array of SecretMetadata instances from an array of secrets.
-     *
-     * To respect the order of the secrets, we add the index to the timestamp
-     * so that the first secret backup will have the oldest timestamp
-     * and the last secret backup will have the newest timestamp.
-     *
-     * @param batchData - The data to add metadata to.
-     * @param batchData.value - The SeedPhrase/PrivateKey to add metadata to.
-     * @param batchData.options - The options for the seed phrase metadata.
-     * @returns The SecretMetadata instances.
-     */
-    static fromBatch(batchData) {
-        const timestamp = Date.now();
-        return batchData.map((data, index) => {
-            // To respect the order of the seed phrases, we add the index to the timestamp
-            // so that the first seed phrase backup will have the oldest timestamp
-            // and the last seed phrase backup will have the newest timestamp
-            const backupCreatedAt = data.options?.timestamp ?? timestamp + index * 5;
-            return new SecretMetadata(data.value, {
-                timestamp: backupCreatedAt,
-                type: data.options?.type,
-            });
-        });
+        __classPrivateFieldSet(this, _SecretMetadata_itemId, options?.itemId, "f");
+        __classPrivateFieldSet(this, _SecretMetadata_dataType, options?.dataType, "f");
+        __classPrivateFieldSet(this, _SecretMetadata_createdAt, options?.createdAt, "f");
+        __classPrivateFieldSet(this, _SecretMetadata_storageVersion, options?.storageVersion, "f");
+        // Derive type from dataType (new clients), or use provided type (V1 compat)
+        if (options?.dataType === undefined || options?.dataType === null) {
+            __classPrivateFieldSet(this, _SecretMetadata_type, options?.type ?? constants_1.SecretType.Mnemonic, "f");
+        }
+        else {
+            __classPrivateFieldSet(this, _SecretMetadata_type, (0, utils_2.getSecretTypeFromDataType)(options.dataType), "f");
+        }
     }
     /**
      * Assert that the provided value is a valid seed phrase metadata.
@@ -86,36 +61,18 @@ class SecretMetadata {
             throw new Error(constants_1.SeedlessOnboardingControllerErrorMessage.InvalidSecretMetadata);
         }
     }
-    /**
-     * Parse the SecretMetadata from the metadata store and return the array of SecretMetadata instances.
-     *
-     * This method also sorts the secrets by timestamp in ascending order, i.e. the oldest secret will be the first element in the array.
-     *
-     * @param secretMetadataArr - The array of SecretMetadata from the metadata store.
-     * @param filterType - The type of the secret to filter.
-     * @returns The array of SecretMetadata instances.
-     */
-    static parseSecretsFromMetadataStore(secretMetadataArr, filterType) {
-        const parsedSecertMetadata = secretMetadataArr.map((metadata) => SecretMetadata.fromRawMetadata(metadata));
-        const secrets = SecretMetadata.sort(parsedSecertMetadata);
-        if (filterType) {
-            return secrets.filter((secret) => secret.type === filterType);
-        }
-        return secrets;
-    }
     /**
      * Parse and create the SecretMetadata instance from the raw metadata bytes.
      *
      * @param rawMetadata - The raw metadata.
+     * @param storageMetadata - Storage-level metadata from the metadata store.
      * @returns The parsed secret metadata.
      */
-    static fromRawMetadata(rawMetadata) {
+    static fromRawMetadata(rawMetadata, storageMetadata) {
         const serializedMetadata = (0, utils_1.bytesToString)(rawMetadata);
         const parsedMetadata = JSON.parse(serializedMetadata);
         SecretMetadata.assertIsValidSecretMetadataJson(parsedMetadata);
-        // if the type is not provided, we default to Mnemonic for the backwards compatibility
         const type = parsedMetadata.type ?? constants_1.SecretType.Mnemonic;
-        const version = parsedMetadata.version ?? constants_1.SecretMetadataVersion.V1;
         let data;
         try {
             data = (0, utils_1.base64ToBytes)(parsedMetadata.data);
@@ -126,24 +83,72 @@ class SecretMetadata {
         return new SecretMetadata(data, {
             timestamp: parsedMetadata.timestamp,
             type,
-            version,
+            ...storageMetadata,
         });
     }
     /**
-     * Sort the seed phrases by timestamp.
+     * Compare two SecretMetadata instances by timestamp.
+     *
+     * @param a - The first SecretMetadata instance.
+     * @param b - The second SecretMetadata instance.
+     * @param order - The sort order. Default is 'asc'.
+     * @returns A negative number if a < b, positive if a > b, zero if equal.
+     */
+    static compareByTimestamp(a, b, order = 'asc') {
+        return order === 'asc'
+            ? a.timestamp - b.timestamp
+            : b.timestamp - a.timestamp;
+    }
+    /**
+     * Compare two SecretMetadata instances for ordering.
      *
-     * @param data - The secret metadata array to sort.
-     * @param order - The order to sort the seed phrases. Default is `desc`.
+     * Ordering priority:
+     * 1. PrimarySrp always comes first (regardless of order direction)
+     * 2. Server-side createdAt (TIMEUUID) if both have it
+     * 3. Legacy items (null createdAt) are considered older
+     * 4. Fall back to client-side timestamp
      *
-     * @returns The sorted secret metadata array.
+     * @param a - The first SecretMetadata instance.
+     * @param b - The second SecretMetadata instance.
+     * @param order - The sort order. Default is 'asc'.
+     * @returns A negative number if a < b, positive if a > b, zero if equal.
      */
-    static sort(data, order = 'asc') {
-        return data.sort((a, b) => {
-            if (order === 'asc') {
-                return a.timestamp - b.timestamp;
-            }
-            return b.timestamp - a.timestamp;
-        });
+    static compare(a, b, order = 'asc') {
+        // PrimarySrp always comes first (regardless of order direction)
+        const aIsPrimary = a.dataType === toprf_secure_backup_1.EncAccountDataType.PrimarySrp;
+        const bIsPrimary = b.dataType === toprf_secure_backup_1.EncAccountDataType.PrimarySrp;
+        if (aIsPrimary && bIsPrimary) {
+            return 0; // Both PrimarySrp: treat as equal (handles data corruption gracefully)
+        }
+        if (aIsPrimary) {
+            return -1;
+        }
+        if (bIsPrimary) {
+            return 1;
+        }
+        // Use server-side createdAt if available (TIMEUUID requires timestamp extraction)
+        if (a.createdAt && b.createdAt) {
+            return (0, utils_2.compareTimeuuid)(a.createdAt, b.createdAt, order);
+        }
+        // Handle mixed createdAt: legacy items (null) are older
+        if (!a.createdAt && b.createdAt) {
+            return order === 'asc' ? -1 : 1; // a (legacy/older) comes before b in asc
+        }
+        if (a.createdAt && !b.createdAt) {
+            return order === 'asc' ? 1 : -1; // b (legacy/older) comes before a in asc
+        }
+        // Both null: fall back to client-side timestamp
+        return SecretMetadata.compareByTimestamp(a, b, order);
+    }
+    /**
+     * Check if a SecretMetadata instance matches the given type.
+     *
+     * @param secret - The SecretMetadata instance to check.
+     * @param type - The type to match against.
+     * @returns True if the secret matches the type.
+     */
+    static matchesType(secret, type) {
+        return secret.type === type;
     }
     get data() {
         return __classPrivateFieldGet(this, _SecretMetadata_data, "f");
@@ -154,8 +159,22 @@ class SecretMetadata {
     get type() {
         return __classPrivateFieldGet(this, _SecretMetadata_type, "f");
     }
-    get version() {
-        return __classPrivateFieldGet(this, _SecretMetadata_version, "f");
+    get itemId() {
+        return __classPrivateFieldGet(this, _SecretMetadata_itemId, "f");
+    }
+    get dataType() {
+        return __classPrivateFieldGet(this, _SecretMetadata_dataType, "f");
+    }
+    get createdAt() {
+        return __classPrivateFieldGet(this, _SecretMetadata_createdAt, "f");
+    }
+    /**
+     * The storage-level version from the SDK ('v1' or 'v2').
+     *
+     * @returns The storage-level version.
+     */
+    get storageVersion() {
+        return __classPrivateFieldGet(this, _SecretMetadata_storageVersion, "f");
     }
     /**
      * Serialize the secret metadata and convert it to a Uint8Array.
@@ -174,12 +193,11 @@ class SecretMetadata {
             data: _data,
             timestamp: __classPrivateFieldGet(this, _SecretMetadata_timestamp, "f"),
             type: __classPrivateFieldGet(this, _SecretMetadata_type, "f"),
-            version: __classPrivateFieldGet(this, _SecretMetadata_version, "f"),
         });
         // convert the serialized metadata to bytes(Uint8Array)
         return (0, utils_1.stringToBytes)(serializedMetadata);
     }
 }
 exports.SecretMetadata = SecretMetadata;
-_SecretMetadata_data = new WeakMap(), _SecretMetadata_timestamp = new WeakMap(), _SecretMetadata_type = new WeakMap(), _SecretMetadata_version = new WeakMap();
+_SecretMetadata_data = new WeakMap(), _SecretMetadata_timestamp = new WeakMap(), _SecretMetadata_type = new WeakMap(), _SecretMetadata_itemId = new WeakMap(), _SecretMetadata_dataType = new WeakMap(), _SecretMetadata_createdAt = new WeakMap(), _SecretMetadata_storageVersion = new WeakMap();
 //# sourceMappingURL=SecretMetadata.cjs.map

package/dist/SecretMetadata.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"SecretMetadata.cjs","sourceRoot":"","sources":["../src/SecretMetadata.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  base64ToBytes,\n  bytesToBase64,\n  stringToBytes,\n  bytesToString,\n} from '@metamask/utils';\n\nimport {\n  SeedlessOnboardingControllerErrorMessage,\n  SecretType,\n  SecretMetadataVersion,\n} from './constants';\nimport type { SecretDataType, SecretMetadataOptions } from './types';\n\ntype ISecretMetadata<DataType extends SecretDataType = Uint8Array> = {\n  data: DataType;\n  timestamp: number;\n  type: SecretType;\n  version: SecretMetadataVersion;\n  toBytes: () => Uint8Array;\n};\n\n/**\n * SecretMetadata type without the data and toBytes methods\n * in which the data is base64 encoded for more compacted metadata\n */\ntype SecretMetadataJson<DataType extends SecretDataType> = Omit<\n  ISecretMetadata<DataType>,\n  'data' | 'toBytes'\n> & {\n  data: string; // base64 encoded string\n};\n\n/**\n * SecretMetadata is a class that adds metadata to the secret.\n *\n * It contains the secret and the timestamp when it was created.\n * It is used to store the secret in the metadata store.\n *\n * @example\n * ```ts\n * const secretMetadata = new SecretMetadata(secret);\n * ```\n */\nexport class SecretMetadata<DataType extends SecretDataType = Uint8Array>\n  implements ISecretMetadata<DataType>\n{\n  readonly #data: DataType;\n\n  readonly #timestamp: number;\n\n  readonly #type: SecretType;\n\n  readonly #version: SecretMetadataVersion;\n\n  /**\n   * Create a new SecretMetadata instance.\n   *\n   * @param data - The secret to add metadata to.\n   * @param options - The options for the secret metadata.\n   * @param options.timestamp - The timestamp when the secret was created.\n   * @param options.type - The type of the secret.\n   */\n  constructor(data: DataType, options?: Partial<SecretMetadataOptions>) {\n    this.#data = data;\n    this.#timestamp = options?.timestamp ?? Date.now();\n    this.#type = options?.type ?? SecretType.Mnemonic;\n    this.#version = options?.version ?? SecretMetadataVersion.V1;\n  }\n\n  /**\n   * Create an Array of SecretMetadata instances from an array of secrets.\n   *\n   * To respect the order of the secrets, we add the index to the timestamp\n   * so that the first secret backup will have the oldest timestamp\n   * and the last secret backup will have the newest timestamp.\n   *\n   * @param batchData - The data to add metadata to.\n   * @param batchData.value - The SeedPhrase/PrivateKey to add metadata to.\n   * @param batchData.options - The options for the seed phrase metadata.\n   * @returns The SecretMetadata instances.\n   */\n  static fromBatch<DataType extends SecretDataType = Uint8Array>(\n    batchData: {\n      value: DataType;\n      options?: Partial<SecretMetadataOptions>;\n    }[],\n  ): SecretMetadata<DataType>[] {\n    const timestamp = Date.now();\n    return batchData.map((data, index) => {\n      // To respect the order of the seed phrases, we add the index to the timestamp\n      // so that the first seed phrase backup will have the oldest timestamp\n      // and the last seed phrase backup will have the newest timestamp\n      const backupCreatedAt = data.options?.timestamp ?? timestamp + index * 5;\n      return new SecretMetadata(data.value, {\n        timestamp: backupCreatedAt,\n        type: data.options?.type,\n      });\n    });\n  }\n\n  /**\n   * Assert that the provided value is a valid seed phrase metadata.\n   *\n   * @param value - The value to check.\n   * @throws If the value is not a valid seed phrase metadata.\n   */\n  static assertIsValidSecretMetadataJson<\n    DataType extends SecretDataType = Uint8Array,\n  >(value: unknown): asserts value is SecretMetadataJson<DataType> {\n    if (\n      typeof value !== 'object' ||\n      !value ||\n      !('data' in value) ||\n      typeof value.data !== 'string' ||\n      !('timestamp' in value) ||\n      typeof value.timestamp !== 'number'\n    ) {\n      throw new Error(\n        SeedlessOnboardingControllerErrorMessage.InvalidSecretMetadata,\n      );\n    }\n  }\n\n  /**\n   * Parse the SecretMetadata from the metadata store and return the array of SecretMetadata instances.\n   *\n   * This method also sorts the secrets by timestamp in ascending order, i.e. the oldest secret will be the first element in the array.\n   *\n   * @param secretMetadataArr - The array of SecretMetadata from the metadata store.\n   * @param filterType - The type of the secret to filter.\n   * @returns The array of SecretMetadata instances.\n   */\n  static parseSecretsFromMetadataStore<\n    DataType extends SecretDataType = Uint8Array,\n  >(\n    secretMetadataArr: Uint8Array[],\n    filterType?: SecretType,\n  ): SecretMetadata<DataType>[] {\n    const parsedSecertMetadata = secretMetadataArr.map((metadata) =>\n      SecretMetadata.fromRawMetadata<DataType>(metadata),\n    );\n\n    const secrets = SecretMetadata.sort(parsedSecertMetadata);\n\n    if (filterType) {\n      return secrets.filter((secret) => secret.type === filterType);\n    }\n\n    return secrets;\n  }\n\n  /**\n   * Parse and create the SecretMetadata instance from the raw metadata bytes.\n   *\n   * @param rawMetadata - The raw metadata.\n   * @returns The parsed secret metadata.\n   */\n  static fromRawMetadata<DataType extends SecretDataType>(\n    rawMetadata: Uint8Array,\n  ): SecretMetadata<DataType> {\n    const serializedMetadata = bytesToString(rawMetadata);\n    const parsedMetadata = JSON.parse(serializedMetadata);\n\n    SecretMetadata.assertIsValidSecretMetadataJson<DataType>(parsedMetadata);\n\n    // if the type is not provided, we default to Mnemonic for the backwards compatibility\n    const type = parsedMetadata.type ?? SecretType.Mnemonic;\n    const version = parsedMetadata.version ?? SecretMetadataVersion.V1;\n\n    let data: DataType;\n    try {\n      data = base64ToBytes(parsedMetadata.data) as DataType;\n    } catch {\n      data = parsedMetadata.data as DataType;\n    }\n\n    return new SecretMetadata<DataType>(data, {\n      timestamp: parsedMetadata.timestamp,\n      type,\n      version,\n    });\n  }\n\n  /**\n   * Sort the seed phrases by timestamp.\n   *\n   * @param data - The secret metadata array to sort.\n   * @param order - The order to sort the seed phrases. Default is `desc`.\n   *\n   * @returns The sorted secret metadata array.\n   */\n  static sort<DataType extends SecretDataType = Uint8Array>(\n    data: SecretMetadata<DataType>[],\n    order: 'asc' | 'desc' = 'asc',\n  ): SecretMetadata<DataType>[] {\n    return data.sort((a, b) => {\n      if (order === 'asc') {\n        return a.timestamp - b.timestamp;\n      }\n      return b.timestamp - a.timestamp;\n    });\n  }\n\n  get data(): DataType {\n    return this.#data;\n  }\n\n  get timestamp(): number {\n    return this.#timestamp;\n  }\n\n  get type(): SecretType {\n    return this.#type;\n  }\n\n  get version(): SecretMetadataVersion {\n    return this.#version;\n  }\n\n  /**\n   * Serialize the secret metadata and convert it to a Uint8Array.\n   *\n   * @returns The serialized SecretMetadata value in bytes.\n   */\n  toBytes(): Uint8Array {\n    let _data: unknown = this.#data;\n    if (this.#data instanceof Uint8Array) {\n      // encode the raw secret to base64 encoded string\n      // to create more compacted metadata\n      _data = bytesToBase64(this.#data);\n    }\n\n    // serialize the metadata to a JSON string\n    const serializedMetadata = JSON.stringify({\n      data: _data,\n      timestamp: this.#timestamp,\n      type: this.#type,\n      version: this.#version,\n    });\n\n    // convert the serialized metadata to bytes(Uint8Array)\n    return stringToBytes(serializedMetadata);\n  }\n}\n"]}
+{"version":3,"file":"SecretMetadata.cjs","sourceRoot":"","sources":["../src/SecretMetadata.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SecretDataItemOutput } from '@metamask/toprf-secure-backup';\nimport { EncAccountDataType } from '@metamask/toprf-secure-backup';\nimport {\n  base64ToBytes,\n  bytesToBase64,\n  stringToBytes,\n  bytesToString,\n} from '@metamask/utils';\n\nimport {\n  SeedlessOnboardingControllerErrorMessage,\n  SecretType,\n} from './constants';\nimport type { SecretDataType } from './types';\nimport { compareTimeuuid, getSecretTypeFromDataType } from './utils';\n\ntype ISecretMetadata<DataType extends SecretDataType = Uint8Array> = {\n  data: DataType;\n  timestamp: number;\n  type: SecretType;\n  toBytes: () => Uint8Array;\n};\n\n/**\n * SecretMetadata type without the data and toBytes methods\n * in which the data is base64 encoded for more compacted metadata\n */\ntype SecretMetadataJson<DataType extends SecretDataType> = Omit<\n  ISecretMetadata<DataType>,\n  'data' | 'toBytes'\n> & {\n  data: string; // base64 encoded string\n};\n\n/**\n * SecretMetadata is a class that adds metadata to the secret.\n *\n * It contains the secret and the timestamp when it was created.\n * It is used to store the secret in the metadata store.\n *\n * @example\n * ```ts\n * const secretMetadata = new SecretMetadata(secret);\n * ```\n */\n\n/**\n * Options for SecretMetadata constructor.\n *\n * New clients: provide V2 fields (`dataType`, `createdAt`, etc).\n * Reading V1 data: `timestamp` and `type` come from encrypted JSON.\n */\ntype SecretMetadataOptions = {\n  // V1 fields (from encrypted JSON payload, for backward compat)\n  timestamp?: number;\n  type?: SecretType;\n\n  // Storage-level metadata from the metadata store (not encrypted).\n  itemId?: string;\n  dataType?: EncAccountDataType;\n  createdAt?: string;\n  /**\n   * The storage-level version from the SDK ('v1' or 'v2').\n   * - 'v1': Legacy items created before dataType was introduced\n   * - 'v2': Items with dataType set (either new or migrated)\n   */\n  storageVersion?: SecretDataItemOutput['version'];\n};\n\nexport class SecretMetadata<DataType extends SecretDataType = Uint8Array>\n  implements ISecretMetadata<DataType>\n{\n  readonly #data: DataType;\n\n  readonly #timestamp: number;\n\n  readonly #type: SecretType;\n\n  // Storage-level metadata (not encrypted)\n  readonly #itemId?: string;\n\n  readonly #dataType?: EncAccountDataType;\n\n  readonly #createdAt?: string;\n\n  readonly #storageVersion?: SecretDataItemOutput['version'];\n\n  /**\n   * @param data - The secret data.\n   * @param options - Optional metadata. New clients should provide `dataType`.\n   */\n  constructor(data: DataType, options?: SecretMetadataOptions) {\n    this.#data = data;\n    this.#timestamp = options?.timestamp ?? Date.now();\n    this.#itemId = options?.itemId;\n    this.#dataType = options?.dataType;\n    this.#createdAt = options?.createdAt;\n    this.#storageVersion = options?.storageVersion;\n\n    // Derive type from dataType (new clients), or use provided type (V1 compat)\n    if (options?.dataType === undefined || options?.dataType === null) {\n      this.#type = options?.type ?? SecretType.Mnemonic;\n    } else {\n      this.#type = getSecretTypeFromDataType(options.dataType);\n    }\n  }\n\n  /**\n   * Assert that the provided value is a valid seed phrase metadata.\n   *\n   * @param value - The value to check.\n   * @throws If the value is not a valid seed phrase metadata.\n   */\n  static assertIsValidSecretMetadataJson<\n    DataType extends SecretDataType = Uint8Array,\n  >(value: unknown): asserts value is SecretMetadataJson<DataType> {\n    if (\n      typeof value !== 'object' ||\n      !value ||\n      !('data' in value) ||\n      typeof value.data !== 'string' ||\n      !('timestamp' in value) ||\n      typeof value.timestamp !== 'number'\n    ) {\n      throw new Error(\n        SeedlessOnboardingControllerErrorMessage.InvalidSecretMetadata,\n      );\n    }\n  }\n\n  /**\n   * Parse and create the SecretMetadata instance from the raw metadata bytes.\n   *\n   * @param rawMetadata - The raw metadata.\n   * @param storageMetadata - Storage-level metadata from the metadata store.\n   * @returns The parsed secret metadata.\n   */\n  static fromRawMetadata<DataType extends SecretDataType>(\n    rawMetadata: Uint8Array,\n    storageMetadata: Omit<SecretMetadataOptions, 'timestamp' | 'type'>,\n  ): SecretMetadata<DataType> {\n    const serializedMetadata = bytesToString(rawMetadata);\n    const parsedMetadata = JSON.parse(serializedMetadata);\n\n    SecretMetadata.assertIsValidSecretMetadataJson<DataType>(parsedMetadata);\n\n    const type = parsedMetadata.type ?? SecretType.Mnemonic;\n\n    let data: DataType;\n    try {\n      data = base64ToBytes(parsedMetadata.data) as DataType;\n    } catch {\n      data = parsedMetadata.data as DataType;\n    }\n\n    return new SecretMetadata<DataType>(data, {\n      timestamp: parsedMetadata.timestamp,\n      type,\n      ...storageMetadata,\n    });\n  }\n\n  /**\n   * Compare two SecretMetadata instances by timestamp.\n   *\n   * @param a - The first SecretMetadata instance.\n   * @param b - The second SecretMetadata instance.\n   * @param order - The sort order. Default is 'asc'.\n   * @returns A negative number if a < b, positive if a > b, zero if equal.\n   */\n  static compareByTimestamp<DataType extends SecretDataType = SecretDataType>(\n    a: SecretMetadata<DataType>,\n    b: SecretMetadata<DataType>,\n    order: 'asc' | 'desc' = 'asc',\n  ): number {\n    return order === 'asc'\n      ? a.timestamp - b.timestamp\n      : b.timestamp - a.timestamp;\n  }\n\n  /**\n   * Compare two SecretMetadata instances for ordering.\n   *\n   * Ordering priority:\n   * 1. PrimarySrp always comes first (regardless of order direction)\n   * 2. Server-side createdAt (TIMEUUID) if both have it\n   * 3. Legacy items (null createdAt) are considered older\n   * 4. Fall back to client-side timestamp\n   *\n   * @param a - The first SecretMetadata instance.\n   * @param b - The second SecretMetadata instance.\n   * @param order - The sort order. Default is 'asc'.\n   * @returns A negative number if a < b, positive if a > b, zero if equal.\n   */\n  static compare<DataType extends SecretDataType = SecretDataType>(\n    a: SecretMetadata<DataType>,\n    b: SecretMetadata<DataType>,\n    order: 'asc' | 'desc' = 'asc',\n  ): number {\n    // PrimarySrp always comes first (regardless of order direction)\n    const aIsPrimary = a.dataType === EncAccountDataType.PrimarySrp;\n    const bIsPrimary = b.dataType === EncAccountDataType.PrimarySrp;\n    if (aIsPrimary && bIsPrimary) {\n      return 0; // Both PrimarySrp: treat as equal (handles data corruption gracefully)\n    }\n    if (aIsPrimary) {\n      return -1;\n    }\n    if (bIsPrimary) {\n      return 1;\n    }\n    // Use server-side createdAt if available (TIMEUUID requires timestamp extraction)\n    if (a.createdAt && b.createdAt) {\n      return compareTimeuuid(a.createdAt, b.createdAt, order);\n    }\n    // Handle mixed createdAt: legacy items (null) are older\n    if (!a.createdAt && b.createdAt) {\n      return order === 'asc' ? -1 : 1; // a (legacy/older) comes before b in asc\n    }\n    if (a.createdAt && !b.createdAt) {\n      return order === 'asc' ? 1 : -1; // b (legacy/older) comes before a in asc\n    }\n    // Both null: fall back to client-side timestamp\n    return SecretMetadata.compareByTimestamp(a, b, order);\n  }\n\n  /**\n   * Check if a SecretMetadata instance matches the given type.\n   *\n   * @param secret - The SecretMetadata instance to check.\n   * @param type - The type to match against.\n   * @returns True if the secret matches the type.\n   */\n  static matchesType<DataType extends SecretDataType = SecretDataType>(\n    secret: SecretMetadata<DataType>,\n    type: SecretType,\n  ): boolean {\n    return secret.type === type;\n  }\n\n  get data(): DataType {\n    return this.#data;\n  }\n\n  get timestamp(): number {\n    return this.#timestamp;\n  }\n\n  get type(): SecretType {\n    return this.#type;\n  }\n\n  get itemId(): string | undefined {\n    return this.#itemId;\n  }\n\n  get dataType(): EncAccountDataType | undefined {\n    return this.#dataType;\n  }\n\n  get createdAt(): string | undefined {\n    return this.#createdAt;\n  }\n\n  /**\n   * The storage-level version from the SDK ('v1' or 'v2').\n   *\n   * @returns The storage-level version.\n   */\n  get storageVersion(): SecretDataItemOutput['version'] | undefined {\n    return this.#storageVersion;\n  }\n\n  /**\n   * Serialize the secret metadata and convert it to a Uint8Array.\n   *\n   * @returns The serialized SecretMetadata value in bytes.\n   */\n  toBytes(): Uint8Array {\n    let _data: unknown = this.#data;\n    if (this.#data instanceof Uint8Array) {\n      // encode the raw secret to base64 encoded string\n      // to create more compacted metadata\n      _data = bytesToBase64(this.#data);\n    }\n\n    // serialize the metadata to a JSON string\n    const serializedMetadata = JSON.stringify({\n      data: _data,\n      timestamp: this.#timestamp,\n      type: this.#type,\n    });\n\n    // convert the serialized metadata to bytes(Uint8Array)\n    return stringToBytes(serializedMetadata);\n  }\n}\n"]}

package/dist/SecretMetadata.d.cts

@@ -1,10 +1,11 @@
-import { SecretType, SecretMetadataVersion } from "./constants.cjs";
-import type { SecretDataType, SecretMetadataOptions } from "./types.cjs";
+import type { SecretDataItemOutput } from "@metamask/toprf-secure-backup";
+import { EncAccountDataType } from "@metamask/toprf-secure-backup";
+import { SecretType } from "./constants.cjs";
+import type { SecretDataType } from "./types.cjs";
 type ISecretMetadata<DataType extends SecretDataType = Uint8Array> = {
     data: DataType;
     timestamp: number;
     type: SecretType;
-    version: SecretMetadataVersion;
     toBytes: () => Uint8Array;
 };
 /**
@@ -25,33 +26,32 @@ type SecretMetadataJson<DataType extends SecretDataType> = Omit<ISecretMetadata<
  * const secretMetadata = new SecretMetadata(secret);
  * ```
  */
-export declare class SecretMetadata<DataType extends SecretDataType = Uint8Array> implements ISecretMetadata<DataType> {
-    #private;
+/**
+ * Options for SecretMetadata constructor.
+ *
+ * New clients: provide V2 fields (`dataType`, `createdAt`, etc).
+ * Reading V1 data: `timestamp` and `type` come from encrypted JSON.
+ */
+type SecretMetadataOptions = {
+    timestamp?: number;
+    type?: SecretType;
+    itemId?: string;
+    dataType?: EncAccountDataType;
+    createdAt?: string;
     /**
-     * Create a new SecretMetadata instance.
-     *
-     * @param data - The secret to add metadata to.
-     * @param options - The options for the secret metadata.
-     * @param options.timestamp - The timestamp when the secret was created.
-     * @param options.type - The type of the secret.
+     * The storage-level version from the SDK ('v1' or 'v2').
+     * - 'v1': Legacy items created before dataType was introduced
+     * - 'v2': Items with dataType set (either new or migrated)
      */
-    constructor(data: DataType, options?: Partial<SecretMetadataOptions>);
+    storageVersion?: SecretDataItemOutput['version'];
+};
+export declare class SecretMetadata<DataType extends SecretDataType = Uint8Array> implements ISecretMetadata<DataType> {
+    #private;
     /**
-     * Create an Array of SecretMetadata instances from an array of secrets.
-     *
-     * To respect the order of the secrets, we add the index to the timestamp
-     * so that the first secret backup will have the oldest timestamp
-     * and the last secret backup will have the newest timestamp.
-     *
-     * @param batchData - The data to add metadata to.
-     * @param batchData.value - The SeedPhrase/PrivateKey to add metadata to.
-     * @param batchData.options - The options for the seed phrase metadata.
-     * @returns The SecretMetadata instances.
+     * @param data - The secret data.
+     * @param options - Optional metadata. New clients should provide `dataType`.
      */
-    static fromBatch<DataType extends SecretDataType = Uint8Array>(batchData: {
-        value: DataType;
-        options?: Partial<SecretMetadataOptions>;
-    }[]): SecretMetadata<DataType>[];
+    constructor(data: DataType, options?: SecretMetadataOptions);
     /**
      * Assert that the provided value is a valid seed phrase metadata.
      *
@@ -59,36 +59,58 @@ export declare class SecretMetadata<DataType extends SecretDataType = Uint8Array
      * @throws If the value is not a valid seed phrase metadata.
      */
     static assertIsValidSecretMetadataJson<DataType extends SecretDataType = Uint8Array>(value: unknown): asserts value is SecretMetadataJson<DataType>;
-    /**
-     * Parse the SecretMetadata from the metadata store and return the array of SecretMetadata instances.
-     *
-     * This method also sorts the secrets by timestamp in ascending order, i.e. the oldest secret will be the first element in the array.
-     *
-     * @param secretMetadataArr - The array of SecretMetadata from the metadata store.
-     * @param filterType - The type of the secret to filter.
-     * @returns The array of SecretMetadata instances.
-     */
-    static parseSecretsFromMetadataStore<DataType extends SecretDataType = Uint8Array>(secretMetadataArr: Uint8Array[], filterType?: SecretType): SecretMetadata<DataType>[];
     /**
      * Parse and create the SecretMetadata instance from the raw metadata bytes.
      *
      * @param rawMetadata - The raw metadata.
+     * @param storageMetadata - Storage-level metadata from the metadata store.
      * @returns The parsed secret metadata.
      */
-    static fromRawMetadata<DataType extends SecretDataType>(rawMetadata: Uint8Array): SecretMetadata<DataType>;
+    static fromRawMetadata<DataType extends SecretDataType>(rawMetadata: Uint8Array, storageMetadata: Omit<SecretMetadataOptions, 'timestamp' | 'type'>): SecretMetadata<DataType>;
+    /**
+     * Compare two SecretMetadata instances by timestamp.
+     *
+     * @param a - The first SecretMetadata instance.
+     * @param b - The second SecretMetadata instance.
+     * @param order - The sort order. Default is 'asc'.
+     * @returns A negative number if a < b, positive if a > b, zero if equal.
+     */
+    static compareByTimestamp<DataType extends SecretDataType = SecretDataType>(a: SecretMetadata<DataType>, b: SecretMetadata<DataType>, order?: 'asc' | 'desc'): number;
     /**
-     * Sort the seed phrases by timestamp.
+     * Compare two SecretMetadata instances for ordering.
      *
-     * @param data - The secret metadata array to sort.
-     * @param order - The order to sort the seed phrases. Default is `desc`.
+     * Ordering priority:
+     * 1. PrimarySrp always comes first (regardless of order direction)
+     * 2. Server-side createdAt (TIMEUUID) if both have it
+     * 3. Legacy items (null createdAt) are considered older
+     * 4. Fall back to client-side timestamp
      *
-     * @returns The sorted secret metadata array.
+     * @param a - The first SecretMetadata instance.
+     * @param b - The second SecretMetadata instance.
+     * @param order - The sort order. Default is 'asc'.
+     * @returns A negative number if a < b, positive if a > b, zero if equal.
      */
-    static sort<DataType extends SecretDataType = Uint8Array>(data: SecretMetadata<DataType>[], order?: 'asc' | 'desc'): SecretMetadata<DataType>[];
+    static compare<DataType extends SecretDataType = SecretDataType>(a: SecretMetadata<DataType>, b: SecretMetadata<DataType>, order?: 'asc' | 'desc'): number;
+    /**
+     * Check if a SecretMetadata instance matches the given type.
+     *
+     * @param secret - The SecretMetadata instance to check.
+     * @param type - The type to match against.
+     * @returns True if the secret matches the type.
+     */
+    static matchesType<DataType extends SecretDataType = SecretDataType>(secret: SecretMetadata<DataType>, type: SecretType): boolean;
     get data(): DataType;
     get timestamp(): number;
     get type(): SecretType;
-    get version(): SecretMetadataVersion;
+    get itemId(): string | undefined;
+    get dataType(): EncAccountDataType | undefined;
+    get createdAt(): string | undefined;
+    /**
+     * The storage-level version from the SDK ('v1' or 'v2').
+     *
+     * @returns The storage-level version.
+     */
+    get storageVersion(): SecretDataItemOutput['version'] | undefined;
     /**
      * Serialize the secret metadata and convert it to a Uint8Array.
      *

package/dist/SecretMetadata.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"SecretMetadata.d.cts","sourceRoot":"","sources":["../src/SecretMetadata.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,UAAU,EACV,qBAAqB,EACtB,wBAAoB;AACrB,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,oBAAgB;AAErE,KAAK,eAAe,CAAC,QAAQ,SAAS,cAAc,GAAG,UAAU,IAAI;IACnE,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,OAAO,EAAE,MAAM,UAAU,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,KAAK,kBAAkB,CAAC,QAAQ,SAAS,cAAc,IAAI,IAAI,CAC7D,eAAe,CAAC,QAAQ,CAAC,EACzB,MAAM,GAAG,SAAS,CACnB,GAAG;IACF,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,cAAc,CAAC,QAAQ,SAAS,cAAc,GAAG,UAAU,CACtE,YAAW,eAAe,CAAC,QAAQ,CAAC;;IAUpC;;;;;;;OAOG;gBACS,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC;IAOpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,SAAS,CAAC,QAAQ,SAAS,cAAc,GAAG,UAAU,EAC3D,SAAS,EAAE;QACT,KAAK,EAAE,QAAQ,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;KAC1C,EAAE,GACF,cAAc,CAAC,QAAQ,CAAC,EAAE;IAc7B;;;;;OAKG;IACH,MAAM,CAAC,+BAA+B,CACpC,QAAQ,SAAS,cAAc,GAAG,UAAU,EAC5C,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,kBAAkB,CAAC,QAAQ,CAAC;IAehE;;;;;;;;OAQG;IACH,MAAM,CAAC,6BAA6B,CAClC,QAAQ,SAAS,cAAc,GAAG,UAAU,EAE5C,iBAAiB,EAAE,UAAU,EAAE,EAC/B,UAAU,CAAC,EAAE,UAAU,GACtB,cAAc,CAAC,QAAQ,CAAC,EAAE;IAc7B;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,SAAS,cAAc,EACpD,WAAW,EAAE,UAAU,GACtB,cAAc,CAAC,QAAQ,CAAC;IAwB3B;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CAAC,QAAQ,SAAS,cAAc,GAAG,UAAU,EACtD,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,EAChC,KAAK,GAAE,KAAK,GAAG,MAAc,GAC5B,cAAc,CAAC,QAAQ,CAAC,EAAE;IAS7B,IAAI,IAAI,IAAI,QAAQ,CAEnB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,IAAI,IAAI,UAAU,CAErB;IAED,IAAI,OAAO,IAAI,qBAAqB,CAEnC;IAED;;;;OAIG;IACH,OAAO,IAAI,UAAU;CAmBtB"}
+{"version":3,"file":"SecretMetadata.d.cts","sourceRoot":"","sources":["../src/SecretMetadata.ts"],"names":[],"mappings":"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"}