feat: KYC controller

.github/CODEOWNERS

@@ -76,6 +76,9 @@
 ## Product Safety Team
 /packages/phishing-controller    @MetaMask/product-safety
 
+## Universal KYC Team
+/packages/kyc-controller    @MetaMask/universal-kyc
+
 ## Swaps-Bridge Team
 /packages/bridge-controller           @MetaMask/swaps-engineers
 /packages/bridge-status-controller    @MetaMask/swaps-engineers

README.md

@@ -426,6 +426,12 @@ linkStyle default opacity:0.5
   keyring_controller --> base_controller;
   keyring_controller --> controller_utils;
   keyring_controller --> messenger;
+  kyc_controller --> base_controller;
+  kyc_controller --> base_data_service;
+  kyc_controller --> controller_utils;
+  kyc_controller --> geolocation_controller;
+  kyc_controller --> messenger;
+  kyc_controller --> profile_sync_controller;
   logging_controller --> base_controller;
   logging_controller --> messenger;
   message_manager --> base_controller;

codeowners.ts

@@ -514,6 +514,10 @@ function buildTeamSections(): CodeownersSection[] {
       title: 'Product Safety Team',
       rules: [buildRuleForPackage('phishing-controller')],
     },
+    {
+      title: 'Universal KYC Team',
+      rules: [buildRuleForPackage('kyc-controller')],
+    },
     {
       title: 'Swaps-Bridge Team',
       rules: [

eslint.config.mjs

@@ -314,6 +314,15 @@ const config = createConfig([
       'no-restricted-globals': 'off',
     },
   },
+  {
+    // The UKYC test-token minter is a dev-only Node CLI, so it may use Node
+    // builtins and globals unlike the platform-agnostic package source.
+    files: ['packages/kyc-controller/scripts/**/*.ts'],
+    rules: {
+      'import-x/no-nodejs-modules': 'off',
+      'no-restricted-globals': 'off',
+    },
+  },
   {
     files: [
       'packages/wallet-cli/src/**/*.test.{js,ts}',

packages/kyc-controller/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial release of the `@metamask/kyc-controller` package for managing KYC / identity verification state across MetaMask clients ([#9781](https://github.com/MetaMask/core/pull/9781))
+- Initial release of the `@metamask/kyc-controller` package: a platform-agnostic controller and data service for orchestrating KYC / identity verification across MetaMask clients ([#9615](https://github.com/MetaMask/core/pull/9615))
+  - `KycController` owns the end-to-end flow: the KYC state machine, the MoonPay Check/Auth hosted-frame message protocol, X25519 credential decryption, and SumSub orchestration through an injected `KycSumSubLauncher` adapter (keeping the controller SDK-free). It performs the authenticated Universal KYC (UKYC) HTTP calls (disclaimers, sessions, kyc-required, wrapping-key, JWKS, UKYC session/journey/status polling) with `superstruct` response validation and `createServicePolicy` resilience, sourcing the bearer token and geolocation through the messenger.
+  - Passing an optional `product` (`ramps` or `card`) makes the controller automatically run the KYC-required check and chain into the SumSub sub-flow after authentication, with generation/phase guards so `reset()` and stale frame messages cannot corrupt state.
 
 [Unreleased]: https://github.com/MetaMask/core/

packages/kyc-controller/README.md

@@ -1,4 +1,4 @@
-# `@metamask/kyc-controller`
+# KYC Controller `@metamask/kyc-controller`
 
 Shared KYC / identity verification controller used across MetaMask clients
 
@@ -10,6 +10,14 @@ or
 
 `npm install @metamask/kyc-controller`
 
+## Development
+
+To rebuild the package automatically whenever you change a source file, run the `build:watch` script from core repository root folder:
+
+`yarn workspace @metamask/kyc-controller run build:watch`
+
+This watches `src/**/*.ts` and re-runs the build on each change (it also performs an initial build on start), which is useful when developing against a client that consumes this package locally.
+
 ## Contributing
 
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

packages/kyc-controller/package.json

@@ -42,24 +42,45 @@
     "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
     "build:all": "ts-bridge --project tsconfig.build.json --verbose --clean",
     "build:docs": "typedoc",
+    "build:watch": "yarn build && chokidar 'src/**/*.ts' -c 'ts-bridge --project tsconfig.build.json --verbose --no-references' --initial",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/kyc-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/kyc-controller",
     "lint:tsconfigs": "tsx ../../scripts/lint-tsconfigs/lint-tsconfigs.mts",
     "lint:tsconfigs:fix": "tsx ../../scripts/lint-tsconfigs/lint-tsconfigs.mts --fix",
-    "messenger-action-types:check": "tsx ../../packages/messenger-cli/src/cli.ts --formatter oxfmt --check",
-    "messenger-action-types:generate": "tsx ../../packages/messenger-cli/src/cli.ts --formatter oxfmt --generate",
+    "messenger-action-types:check": "tsx ../../packages/messenger-cli/src/cli.ts --formatter oxfmt --esm --check",
+    "messenger-action-types:generate": "tsx ../../packages/messenger-cli/src/cli.ts --formatter oxfmt --esm --generate",
+    "mint:ukyc-token": "tsx scripts/mint-ukyc-test-token.ts",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
     "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
   },
+  "dependencies": {
+    "@metamask/base-controller": "^9.1.0",
+    "@metamask/base-data-service": "^0.1.3",
+    "@metamask/controller-utils": "^12.3.0",
+    "@metamask/geolocation-controller": "^1.0.0",
+    "@metamask/messenger": "^2.0.0",
+    "@metamask/profile-sync-controller": "^29.0.0",
+    "@metamask/superstruct": "^3.4.1",
+    "@metamask/utils": "^11.11.0",
+    "@noble/ciphers": "^1.3.0",
+    "@noble/curves": "^1.9.2",
+    "@noble/hashes": "^1.8.0",
+    "@scure/base": "^1.2.6",
+    "@tanstack/query-core": "^4.43.0",
+    "reselect": "^5.1.1",
+    "tweetnacl": "^1.0.3"
+  },
   "devDependencies": {
     "@metamask/auto-changelog": "^6.1.0",
     "@ts-bridge/cli": "^0.6.4",
     "@types/jest": "^30.0.0",
+    "chokidar-cli": "^3.0.0",
     "deepmerge": "^4.2.2",
     "jest": "^30.4.2",
+    "nock": "^13.3.1",
     "ts-jest": "^29.4.11",
     "tsx": "^4.20.5",
     "typedoc": "^0.25.13",

packages/kyc-controller/scripts/mint-ukyc-test-token.ts

@@ -0,0 +1,108 @@
+/**
+ * CLI to mint a UKYC `storage_access_token` for testing UKYC Storage.
+ *
+ * All real logic lives in the tested `mintUkycTestToken`; this is a thin
+ * argument-parsing wrapper that prints the result as JSON.
+ *
+ * Usage (from the package root, via the `mint:ukyc-token` script):
+ *   yarn workspace @metamask/kyc-controller run mint:ukyc-token -- \
+ *     --operations read,write --expires-in 4h [--secret <hex>] \
+ *     [--presenter client|idos-relay] [--session-id <id>]
+ *
+ * Reuse the printed `localUserSecret` (pass it back via --secret) to keep the
+ * same `storageId` and controlling key across runs.
+ */
+import process from 'node:process';
+
+import type {
+  UkycStorageOperation,
+  UkycTokenPresenter,
+} from '../src/ukyc/storageAccessToken.js';
+import { mintUkycTestToken } from '../src/ukyc/testToken.js';
+import type { MintUkycTestTokenParams } from '../src/ukyc/testToken.js';
+
+/**
+ * Parses `--flag value` and `--flag=value` pairs into a map. Flags without a
+ * following value are treated as booleans (`"true"`).
+ *
+ * @param argv - Raw CLI arguments (typically `process.argv.slice(2)`).
+ * @returns The parsed flags keyed by name (without the leading `--`).
+ */
+function parseFlags(argv: string[]): Record<string, string> {
+  const flags: Record<string, string> = {};
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      i += 1;
+      continue;
+    }
+    const body = arg.slice(2);
+    const eq = body.indexOf('=');
+    if (eq !== -1) {
+      flags[body.slice(0, eq)] = body.slice(eq + 1);
+      i += 1;
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith('--')) {
+      flags[body] = next;
+      i += 2;
+    } else {
+      flags[body] = 'true';
+      i += 1;
+    }
+  }
+  return flags;
+}
+
+/**
+ * Parses a duration like `4h`, `30m`, `90s`, or a bare number of seconds.
+ *
+ * @param value - The duration string.
+ * @returns The duration in milliseconds.
+ */
+function parseDurationMs(value: string): number {
+  const match = /^(\d+)(s|m|h|d)?$/u.exec(value);
+  if (!match) {
+    throw new Error(`invalid --expires-in duration: ${value}`);
+  }
+  const amount = Number(match[1]);
+  const unitMs = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+  return amount * unitMs[(match[2] ?? 's') as keyof typeof unitMs];
+}
+
+const flags = parseFlags(process.argv.slice(2));
+
+const params: MintUkycTestTokenParams = {};
+
+if (flags.secret) {
+  params.localUserSecret = flags.secret;
+}
+if (flags.operations) {
+  params.operations = flags.operations
+    .split(',')
+    .map((op) => op.trim()) as UkycStorageOperation[];
+}
+if (flags.presenter) {
+  params.presenter = flags.presenter as UkycTokenPresenter;
+}
+if (flags['session-id']) {
+  params.sessionId = flags['session-id'];
+}
+if (flags['issued-at']) {
+  params.issuedAt = new Date(flags['issued-at']);
+}
+if (flags['expires-at']) {
+  params.expiresAt = new Date(flags['expires-at']);
+} else if (flags['expires-in']) {
+  const issuedAt = params.issuedAt ?? new Date();
+  params.issuedAt = issuedAt;
+  params.expiresAt = new Date(
+    issuedAt.getTime() + parseDurationMs(flags['expires-in']),
+  );
+}
+
+const result = mintUkycTestToken(params);
+
+console.log(JSON.stringify(result, null, 2));