feat: protocol API

packages/snaps-controllers/src/snaps/SnapController.test.tsx

@@ -1728,7 +1728,7 @@
   });
 
   // This isn't stable in CI unfortunately
   it.skip('throws if the Snap is terminated while executing', async () => {
     const { manifest, sourceCode, svgIcon } =
       await getMockSnapFilesWithUpdatedChecksum({
         sourceCode: `
@@ -5014,7 +5014,7 @@
           [MOCK_SNAP_ID]: {},
         }),
       ).rejects.toThrow(
-        'A snap must request at least one of the following permissions: endowment:rpc, endowment:transaction-insight, endowment:cronjob, endowment:name-lookup, endowment:lifecycle-hooks, endowment:keyring, endowment:page-home, endowment:signature-insight.',
+        'A snap must request at least one of the following permissions: endowment:rpc, endowment:transaction-insight, endowment:cronjob, endowment:name-lookup, endowment:lifecycle-hooks, endowment:keyring, endowment:page-home, endowment:signature-insight, endowment:protocol.',
       );
 
       controller.destroy();

packages/snaps-execution-environments/coverage.json

@@ -1,5 +1,5 @@
 {
-  "branches": 80,
+  "branches": 80.13,
   "functions": 90.06,
   "lines": 90.77,
   "statements": 90.15

packages/snaps-execution-environments/src/common/BaseSnapExecutor.test.browser.ts

@@ -1449,6 +1449,39 @@ describe('BaseSnapExecutor', () => {
     });
   });
 
+  it('supports onProtocolRequest export', async () => {
+    const CODE = `
+      module.exports.onProtocolRequest = ({ request }) => request.params[0];
+    `;
+
+    const executor = new TestSnapExecutor();
+    await executor.executeSnap(1, MOCK_SNAP_ID, CODE, []);
+
+    expect(await executor.readCommand()).toStrictEqual({
+      jsonrpc: '2.0',
+      id: 1,
+      result: 'OK',
+    });
+
+    await executor.writeCommand({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'snapRpc',
+      params: [
+        MOCK_SNAP_ID,
+        HandlerType.OnProtocolRequest,
+        MOCK_ORIGIN,
+        { jsonrpc: '2.0', method: 'foo', params: ['bar'] },
+      ],
+    });
+
+    expect(await executor.readCommand()).toStrictEqual({
+      id: 2,
+      jsonrpc: '2.0',
+      result: 'bar',
+    });
+  });
+
   it('supports onHomePage export', async () => {
     const CODE = `
       module.exports.onHomePage = () => ({ content: { type: 'panel', children: [] }});

packages/snaps-execution-environments/src/common/commands.ts

@@ -76,6 +76,7 @@ export function getHandlerArguments(
     }
     case HandlerType.OnRpcRequest:
     case HandlerType.OnKeyringRequest:
+    case HandlerType.OnProtocolRequest:
       return { origin, request };
 
     case HandlerType.OnCronjob:

packages/snaps-rpc-methods/jest.config.js

@@ -10,7 +10,7 @@ module.exports = deepmerge(baseConfig, {
   ],
   coverageThreshold: {
     global: {
-      branches: 91.21,
+      branches: 90.95,
       functions: 96.96,
       lines: 97.51,
       statements: 96.97,

packages/snaps-rpc-methods/src/endowments/enum.ts

@@ -10,4 +10,5 @@ export enum SnapEndowments {
   LifecycleHooks = 'endowment:lifecycle-hooks',
   Keyring = 'endowment:keyring',
   HomePage = 'endowment:page-home',
+  Protocol = 'endowment:protocol',
 }

packages/snaps-rpc-methods/src/endowments/index.ts

@@ -26,6 +26,7 @@ import {
   nameLookupEndowmentBuilder,
 } from './name-lookup';
 import { networkAccessEndowmentBuilder } from './network-access';
+import { getProtocolCaveatMapper, protocolEndowmentBuilder } from './protocol';
 import {
   getRpcCaveatMapper,
   rpcCaveatSpecifications,
@@ -55,6 +56,7 @@ export const endowmentPermissionBuilders = {
   [nameLookupEndowmentBuilder.targetName]: nameLookupEndowmentBuilder,
   [lifecycleHooksEndowmentBuilder.targetName]: lifecycleHooksEndowmentBuilder,
   [keyringEndowmentBuilder.targetName]: keyringEndowmentBuilder,
+  [protocolEndowmentBuilder.targetName]: protocolEndowmentBuilder,
   [homePageEndowmentBuilder.targetName]: homePageEndowmentBuilder,
   [signatureInsightEndowmentBuilder.targetName]:
     signatureInsightEndowmentBuilder,
@@ -88,6 +90,9 @@ export const endowmentCaveatMappers: Record<
   [keyringEndowmentBuilder.targetName]: createMaxRequestTimeMapper(
     getKeyringCaveatMapper,
   ),
+  [protocolEndowmentBuilder.targetName]: createMaxRequestTimeMapper(
+    getProtocolCaveatMapper,
+  ),
   [signatureInsightEndowmentBuilder.targetName]: createMaxRequestTimeMapper(
     getSignatureInsightCaveatMapper,
   ),
@@ -106,6 +111,7 @@ export const handlerEndowments: Record<HandlerType, string | null> = {
   [HandlerType.OnKeyringRequest]: keyringEndowmentBuilder.targetName,
   [HandlerType.OnHomePage]: homePageEndowmentBuilder.targetName,
   [HandlerType.OnSignature]: signatureInsightEndowmentBuilder.targetName,
+  [HandlerType.OnProtocolRequest]: protocolEndowmentBuilder.targetName,
   [HandlerType.OnUserInput]: null,
 };
 
@@ -117,3 +123,8 @@ export { getChainIdsCaveat, getLookupMatchersCaveat } from './name-lookup';
 export { getKeyringCaveatOrigins } from './keyring';
 export { getMaxRequestTimeCaveat } from './caveats';
 export { getCronjobCaveatJobs } from './cronjob';
+export {
+  getProtocolCaveatChainIds,
+  getProtocolCaveatOrigins,
+  getProtocolCaveatRpcMethods,
+} from './protocol';

packages/snaps-rpc-methods/src/endowments/protocol.test.ts

@@ -0,0 +1,131 @@
+import { PermissionType, SubjectType } from '@metamask/permission-controller';
+import { SnapCaveatType } from '@metamask/snaps-utils';
+
+import { SnapEndowments } from './enum';
+import {
+  getProtocolCaveatChainIds,
+  getProtocolCaveatMapper,
+  getProtocolCaveatOrigins,
+  protocolEndowmentBuilder,
+} from './protocol';
+
+describe('endowment:protocol', () => {
+  it('builds the expected permission specification', () => {
+    const specification = protocolEndowmentBuilder.specificationBuilder({});
+    expect(specification).toStrictEqual({
+      permissionType: PermissionType.Endowment,
+      targetName: SnapEndowments.Protocol,
+      endowmentGetter: expect.any(Function),
+      allowedCaveats: [
+        SnapCaveatType.KeyringOrigin,
+        SnapCaveatType.ChainIds,
+        SnapCaveatType.MaxRequestTime,
+      ],
+      subjectTypes: [SubjectType.Snap],
+      validator: expect.any(Function),
+    });
+
+    expect(specification.endowmentGetter()).toBeUndefined();
+  });
+
+  describe('validator', () => {
+    it('throws if the caveat is not a "keyringOrigin" and "chainIds"', () => {
+      const specification = protocolEndowmentBuilder.specificationBuilder({});
+
+      expect(() =>
+        specification.validator({
+          // @ts-expect-error Missing other required permission types.
+          caveats: undefined,
+        }),
+      ).toThrow('Expected the following caveats: "keyringOrigin", "chainIds".');
+
+      expect(() =>
+        // @ts-expect-error Missing other required permission types.
+        specification.validator({
+          caveats: [{ type: 'foo', value: 'bar' }],
+        }),
+      ).toThrow(
+        'Expected the following caveats: "keyringOrigin", "chainIds", "maxRequestTime", received "foo".',
+      );
+
+      expect(() =>
+        // @ts-expect-error Missing other required permission types.
+        specification.validator({
+          caveats: [
+            { type: 'keyringOrigin', value: { allowedOrgins: ['foo.com'] } },
+          ],
+        }),
+      ).toThrow('Expected the following caveats: "keyringOrigin", "chainIds".');
+
+      expect(() =>
+        // @ts-expect-error Missing other required permission types.
+        specification.validator({
+          caveats: [
+            { type: 'keyringOrigin', value: { allowedOrgins: ['foo.com'] } },
+            { type: 'keyringOrigin', value: { allowedOrgins: ['bar.com'] } },
+          ],
+        }),
+      ).toThrow('Duplicate caveats are not allowed.');
+    });
+  });
+});
+
+describe('getProtocolCaveatMapper', () => {
+  it('maps a value to a caveat', () => {
+    expect(
+      getProtocolCaveatMapper({
+        allowedOrigins: ['foo.com'],
+        chains: ['bip122:000000000019d6689c085ae165831e93'],
+      }),
+    ).toStrictEqual({
+      caveats: [
+        {
+          type: SnapCaveatType.ChainIds,
+          value: ['bip122:000000000019d6689c085ae165831e93'],
+        },
+        {
+          type: SnapCaveatType.KeyringOrigin,
+          value: { allowedOrigins: ['foo.com'] },
+        },
+      ],
+    });
+  });
+
+  it('returns null if the input is null', () => {
+    expect(getProtocolCaveatMapper(null)).toStrictEqual({
+      caveats: null,
+    });
+  });
+});
+
+describe('getProtocolCaveatOrigins', () => {
+  it('returns the origins from the caveat', () => {
+    expect(
+      // @ts-expect-error Missing other required permission types.
+      getProtocolCaveatOrigins({
+        caveats: [
+          {
+            type: SnapCaveatType.KeyringOrigin,
+            value: { allowedOrigins: ['foo.com'] },
+          },
+        ],
+      }),
+    ).toStrictEqual({ allowedOrigins: ['foo.com'] });
+  });
+});
+
+describe('getProtocolCaveatChainIds', () => {
+  it('returns the chain ids from the caveat', () => {
+    expect(
+      // @ts-expect-error Missing other required permission types.
+      getProtocolCaveatChainIds({
+        caveats: [
+          {
+            type: SnapCaveatType.ChainIds,
+            value: ['bip122:000000000019d6689c085ae165831e93'],
+          },
+        ],
+      }),
+    ).toStrictEqual(['bip122:000000000019d6689c085ae165831e93']);
+  });
+});