feat: Add Multichain API to @metamask/multichain

packages/multichain/package.json

@@ -51,13 +51,18 @@
     "@metamask/controller-utils": "^11.4.4",
     "@metamask/eth-json-rpc-filters": "^9.0.0",
     "@metamask/rpc-errors": "^7.0.1",
+    "@metamask/safe-event-emitter": "^3.0.0",
     "@metamask/utils": "^10.0.0",
+    "@open-rpc/schema-utils-js": "^2.0.5",
+    "jsonschema": "^1.4.1",
     "lodash": "^4.17.21"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^3.4.4",
+    "@metamask/json-rpc-engine": "^10.0.1",
     "@metamask/network-controller": "^22.1.1",
     "@metamask/permission-controller": "^11.0.4",
+    "@open-rpc/meta-schema": "^1.14.6",
     "@types/jest": "^27.4.1",
     "deepmerge": "^4.2.2",
     "jest": "^27.5.1",

packages/multichain/src/adapters/caip-permission-adapter-middleware.test.ts

@@ -0,0 +1,148 @@
+import { providerErrors } from '@metamask/rpc-errors';
+import type { JsonRpcRequest } from '@metamask/utils';
+
+import {
+  Caip25CaveatType,
+  Caip25EndowmentPermissionName,
+} from '../caip25Permission';
+import { caipPermissionAdapterMiddleware } from './caip-permission-adapter-middleware';
+
+const baseRequest = {
+  id: 1,
+  jsonrpc: '2.0' as const,
+  origin: 'http://test.com',
+  networkClientId: 'mainnet',
+  method: 'eth_call',
+  params: {
+    foo: 'bar',
+  },
+};
+
+const createMockedHandler = () => {
+  const next = jest.fn();
+  const end = jest.fn();
+  const getCaveat = jest.fn().mockReturnValue({
+    value: {
+      requiredScopes: {
+        'eip155:1': {
+          methods: ['eth_call'],
+          notifications: [],
+          accounts: [],
+        },
+        'eip155:5': {
+          methods: ['eth_chainId'],
+          notifications: [],
+          accounts: [],
+        },
+      },
+      optionalScopes: {
+        'eip155:1': {
+          methods: ['net_version'],
+          notifications: [],
+          accounts: [],
+        },
+        wallet: {
+          methods: ['wallet_watchAsset'],
+          notifications: [],
+          accounts: [],
+        },
+        unhandled: {
+          methods: ['foobar'],
+          notifications: [],
+          accounts: [],
+        },
+      },
+      isMultichainOrigin: true,
+    },
+  });
+  const getNetworkConfigurationByNetworkClientId = jest
+    .fn()
+    .mockImplementation((networkClientId: string) => {
+      const chainId =
+        {
+          mainnet: '0x1',
+          goerli: '0x5',
+        }[networkClientId] || '0x999';
+      return {
+        chainId,
+      };
+    });
+  const handler = (
+    request: JsonRpcRequest & {
+      networkClientId: string;
+      origin: string;
+    },
+  ) =>
+    caipPermissionAdapterMiddleware(request, {}, next, end, {
+      getCaveat,
+      getNetworkConfigurationByNetworkClientId,
+    });
+
+  return {
+    next,
+    end,
+    getCaveat,
+    getNetworkConfigurationByNetworkClientId,
+    handler,
+  };
+};
+
+describe('CaipPermissionAdapterMiddleware', () => {
+  it('gets the authorized scopes from the CAIP-25 endowment permission', async () => {
+    const { handler, getCaveat } = createMockedHandler();
+    await handler(baseRequest);
+    expect(getCaveat).toHaveBeenCalledWith(
+      'http://test.com',
+      Caip25EndowmentPermissionName,
+      Caip25CaveatType,
+    );
+  });
+
+  it('allows the request when there is no CAIP-25 endowment permission', async () => {
+    const { handler, getCaveat, next } = createMockedHandler();
+    getCaveat.mockImplementation(() => {
+      throw new Error('permission not found');
+    });
+    await handler(baseRequest);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('allows the request when the CAIP-25 endowment permission was not granted from the multichain API', async () => {
+    const { handler, getCaveat, next } = createMockedHandler();
+    getCaveat.mockReturnValue({
+      value: {
+        isMultichainOrigin: false,
+      },
+    });
+    await handler(baseRequest);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('gets the chainId for the request networkClientId', async () => {
+    const { handler, getNetworkConfigurationByNetworkClientId } =
+      createMockedHandler();
+    await handler(baseRequest);
+    expect(getNetworkConfigurationByNetworkClientId).toHaveBeenCalledWith(
+      'mainnet',
+    );
+  });
+
+  describe('when the CAIP-25 endowment permission was granted over the multichain API', () => {
+    it('throws an error if the requested method is not authorized for the scope specified in the request', async () => {
+      const { handler, end } = createMockedHandler();
+
+      await handler({
+        ...baseRequest,
+        method: 'unauthorized_method',
+      });
+      expect(end).toHaveBeenCalledWith(providerErrors.unauthorized());
+    });
+
+    it('allows the request if the requested scope method is authorized in the current scope', async () => {
+      const { handler, next } = createMockedHandler();
+
+      await handler(baseRequest);
+      expect(next).toHaveBeenCalled();
+    });
+  });
+});

packages/multichain/src/adapters/caip-permission-adapter-middleware.ts

@@ -0,0 +1,79 @@
+import type {
+  NetworkConfiguration,
+  NetworkClientId,
+} from '@metamask/network-controller';
+import type { Caveat } from '@metamask/permission-controller';
+import { providerErrors } from '@metamask/rpc-errors';
+import type { JsonRpcRequest } from '@metamask/utils';
+
+import type { Caip25CaveatValue } from '../caip25Permission';
+import {
+  Caip25CaveatType,
+  Caip25EndowmentPermissionName,
+} from '../caip25Permission';
+import { Eip1193OnlyMethods, KnownWalletScopeString } from '../scope/constants';
+import type { InternalScopeString } from '../scope/types';
+import { getSessionScopes } from './caip-permission-adapter-session-scopes';
+
+/**
+ * Middleware to handle CAIP-25 permission requests.
+ *
+ * @param request - The request object.
+ * @param _response - The response object. Unused.
+ * @param next - The next middleware function.
+ * @param end - The end function.
+ * @param hooks - The hooks object.
+ * @param hooks.getCaveat - Function to retrieve a caveat.
+ * @param hooks.getNetworkConfigurationByNetworkClientId - Function to retrieve a network configuration.
+ */
+export async function caipPermissionAdapterMiddleware(
+  request: JsonRpcRequest & {
+    networkClientId: NetworkClientId;
+    origin: string;
+  },
+  _response: unknown,
+  next: () => Promise<void>,
+  end: (error?: Error) => void,
+  hooks: {
+    getCaveat: (
+      ...args: unknown[]
+    ) => Caveat<typeof Caip25CaveatType, Caip25CaveatValue>;
+    getNetworkConfigurationByNetworkClientId: (
+      networkClientId: NetworkClientId,
+    ) => NetworkConfiguration;
+  },
+) {
+  const { networkClientId, method } = request;
+
+  let caveat;
+  try {
+    caveat = hooks.getCaveat(
+      request.origin,
+      Caip25EndowmentPermissionName,
+      Caip25CaveatType,
+    );
+  } catch (err) {
+    // noop
+  }
+  if (!caveat?.value?.isMultichainOrigin) {
+    return next();
+  }
+
+  const { chainId } =
+    hooks.getNetworkConfigurationByNetworkClientId(networkClientId);
+
+  const scope: InternalScopeString = `eip155:${parseInt(chainId, 16)}`;
+
+  const sessionScopes = getSessionScopes(caveat.value);
+
+  if (
+    !sessionScopes[scope]?.methods?.includes(method) &&
+    !sessionScopes[KnownWalletScopeString.Eip155]?.methods?.includes(method) &&
+    !sessionScopes.wallet?.methods?.includes(method) &&
+    !Eip1193OnlyMethods.includes(method)
+  ) {
+    return end(providerErrors.unauthorized());
+  }
+
+  return next();
+}

packages/multichain/src/adapters/caip-permission-adapter-session-scopes.test.ts

@@ -0,0 +1,116 @@
+import {
+  KnownNotifications,
+  KnownRpcMethods,
+  KnownWalletNamespaceRpcMethods,
+  KnownWalletRpcMethods,
+} from '../scope/constants';
+import {
+  getInternalScopesObject,
+  getSessionScopes,
+} from './caip-permission-adapter-session-scopes';
+
+describe('CAIP-25 session scopes adapters', () => {
+  describe('getInternalScopesObject', () => {
+    it('returns an InternalScopesObject with only the accounts from each NormalizedScopeObject', () => {
+      const result = getInternalScopesObject({
+        'wallet:eip155': {
+          methods: ['foo', 'bar'],
+          notifications: ['baz'],
+          accounts: ['wallet:eip155:0xdead'],
+        },
+        'eip155:1': {
+          methods: ['eth_call'],
+          notifications: ['eth_subscription'],
+          accounts: ['eip155:1:0xdead', 'eip155:1:0xbeef'],
+        },
+      });
+
+      expect(result).toStrictEqual({
+        'wallet:eip155': {
+          accounts: ['wallet:eip155:0xdead'],
+        },
+        'eip155:1': {
+          accounts: ['eip155:1:0xdead', 'eip155:1:0xbeef'],
+        },
+      });
+    });
+  });
+
+  describe('getSessionScopes', () => {
+    it('returns a NormalizedScopesObject for the wallet scope', () => {
+      const result = getSessionScopes({
+        requiredScopes: {},
+        optionalScopes: {
+          wallet: {
+            accounts: [],
+          },
+        },
+      });
+
+      expect(result).toStrictEqual({
+        wallet: {
+          methods: KnownWalletRpcMethods,
+          notifications: [],
+          accounts: [],
+        },
+      });
+    });
+
+    it('returns a NormalizedScopesObject for the wallet:eip155 scope', () => {
+      const result = getSessionScopes({
+        requiredScopes: {},
+        optionalScopes: {
+          'wallet:eip155': {
+            accounts: ['wallet:eip155:0xdeadbeef'],
+          },
+        },
+      });
+
+      expect(result).toStrictEqual({
+        'wallet:eip155': {
+          methods: KnownWalletNamespaceRpcMethods.eip155,
+          notifications: [],
+          accounts: ['wallet:eip155:0xdeadbeef'],
+        },
+      });
+    });
+
+    it('returns a NormalizedScopesObject with empty methods and notifications for scope with wallet namespace and unknown reference', () => {
+      const result = getSessionScopes({
+        requiredScopes: {},
+        optionalScopes: {
+          'wallet:foobar': {
+            accounts: ['wallet:foobar:0xdeadbeef'],
+          },
+        },
+      });
+
+      expect(result).toStrictEqual({
+        'wallet:foobar': {
+          methods: [],
+          notifications: [],
+          accounts: ['wallet:foobar:0xdeadbeef'],
+        },
+      });
+    });
+
+    it('returns a NormalizedScopesObject for a eip155 namespaced scope', () => {
+      const result = getSessionScopes({
+        requiredScopes: {},
+        optionalScopes: {
+          'eip155:1': {
+            accounts: ['eip155:1:0xdeadbeef'],
+          },
+        },
+      });
+
+      expect(result).toStrictEqual({
+        'eip155:1': {
+          methods: KnownRpcMethods.eip155,
+          notifications: KnownNotifications.eip155,
+          accounts: ['eip155:1:0xdeadbeef'],
+        },
+      });
+    });
+  });
+});