feat: Add onActive and onInactive lifecycle hooks

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

@@ -10,6 +10,7 @@ import type {
   Caveat,
   SubjectPermissions,
   ValidPermission,
+  CaveatConstraint,
 } from '@metamask/permission-controller';
 import { SubjectType } from '@metamask/permission-controller';
 import { providerErrors, rpcErrors } from '@metamask/rpc-errors';
@@ -10336,7 +10337,11 @@ describe('SnapController', () => {
 
         rootMessenger.registerActionHandler(
           'PermissionController:getPermissions',
-          (origin) => {
+          (
+            origin,
+          ): SubjectPermissions<
+            ValidPermission<TargetName, CaveatConstraint>
+          > => {
             if (origin === MOCK_SNAP_ID) {
               return {
                 [SnapEndowments.LifecycleHooks]:
@@ -10443,7 +10448,7 @@ describe('SnapController', () => {
         await sleep(10);
 
         expect(consoleErrorSpy).toHaveBeenCalledWith(
-          `Error when calling \`onStart\` lifecycle hook for Snap "npm:@metamask/example-snap": Test error in lifecycle hook.`,
+          `Error calling lifecycle hook "onStart" for Snap "npm:@metamask/example-snap": Test error in lifecycle hook.`,
         );
 
         snapController.destroy();
@@ -12369,4 +12374,178 @@ describe('SnapController', () => {
       snapController.destroy();
     });
   });
+
+  describe('SnapController:setActive', () => {
+    it('calls the `onActive` lifecycle hook for all Snaps when called with `true`', async () => {
+      const rootMessenger = getControllerMessenger();
+      const messenger = getSnapControllerMessenger(rootMessenger);
+
+      rootMessenger.registerActionHandler(
+        'PermissionController:hasPermission',
+        () => true,
+      );
+
+      rootMessenger.registerActionHandler(
+        'PermissionController:getPermissions',
+        (
+          origin,
+        ): SubjectPermissions<ValidPermission<string, CaveatConstraint>> => {
+          if (origin === MOCK_SNAP_ID) {
+            return {
+              [SnapEndowments.LifecycleHooks]: MOCK_LIFECYCLE_HOOKS_PERMISSION,
+            };
+          }
+
+          return {};
+        },
+      );
+
+      const manifest = getSnapManifest({
+        initialPermissions: {
+          [SnapEndowments.LifecycleHooks]: {},
+        },
+      });
+
+      const snapController = getSnapController(
+        getSnapControllerOptions({
+          messenger,
+          state: {
+            snaps: getPersistedSnapsState(getPersistedSnapObject({ manifest })),
+          },
+        }),
+      );
+
+      messenger.call('SnapController:setActive', true);
+      await sleep(10);
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        2,
+        'PermissionController:hasPermission',
+        MOCK_SNAP_ID,
+        SnapEndowments.LifecycleHooks,
+      );
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        3,
+        'PermissionController:hasPermission',
+        MOCK_SNAP_ID,
+        SnapEndowments.LifecycleHooks,
+      );
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        4,
+        'PermissionController:getPermissions',
+        MOCK_SNAP_ID,
+      );
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        5,
+        'ExecutionService:executeSnap',
+        expect.any(Object),
+      );
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        6,
+        'ExecutionService:handleRpcRequest',
+        MOCK_SNAP_ID,
+        {
+          handler: HandlerType.OnActive,
+          origin: METAMASK_ORIGIN,
+          request: {
+            jsonrpc: '2.0',
+            id: expect.any(String),
+            method: HandlerType.OnActive,
+          },
+        },
+      );
+
+      snapController.destroy();
+    });
+
+    it('calls the `onInactive` lifecycle hook for all Snaps when called with `false`', async () => {
+      const rootMessenger = getControllerMessenger();
+      const messenger = getSnapControllerMessenger(rootMessenger);
+
+      rootMessenger.registerActionHandler(
+        'PermissionController:hasPermission',
+        () => true,
+      );
+
+      rootMessenger.registerActionHandler(
+        'PermissionController:getPermissions',
+        (
+          origin,
+        ): SubjectPermissions<ValidPermission<string, CaveatConstraint>> => {
+          if (origin === MOCK_SNAP_ID) {
+            return {
+              [SnapEndowments.LifecycleHooks]: MOCK_LIFECYCLE_HOOKS_PERMISSION,
+            };
+          }
+
+          return {};
+        },
+      );
+
+      const manifest = getSnapManifest({
+        initialPermissions: {
+          [SnapEndowments.LifecycleHooks]: {},
+        },
+      });
+
+      const snapController = getSnapController(
+        getSnapControllerOptions({
+          messenger,
+          state: {
+            snaps: getPersistedSnapsState(getPersistedSnapObject({ manifest })),
+          },
+        }),
+      );
+
+      messenger.call('SnapController:setActive', false);
+      await sleep(10);
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        2,
+        'PermissionController:hasPermission',
+        MOCK_SNAP_ID,
+        SnapEndowments.LifecycleHooks,
+      );
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        3,
+        'PermissionController:hasPermission',
+        MOCK_SNAP_ID,
+        SnapEndowments.LifecycleHooks,
+      );
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        4,
+        'PermissionController:getPermissions',
+        MOCK_SNAP_ID,
+      );
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        5,
+        'ExecutionService:executeSnap',
+        expect.any(Object),
+      );
+
+      expect(messenger.call).toHaveBeenNthCalledWith(
+        6,
+        'ExecutionService:handleRpcRequest',
+        MOCK_SNAP_ID,
+        {
+          handler: HandlerType.OnInactive,
+          origin: METAMASK_ORIGIN,
+          request: {
+            jsonrpc: '2.0',
+            id: expect.any(String),
+            method: HandlerType.OnInactive,
+          },
+        },
+      );
+
+      snapController.destroy();
+    });
+  });
 });

packages/snaps-controllers/src/snaps/SnapController.ts

@@ -479,6 +479,11 @@ export type IsMinimumPlatformVersion = {
   handler: SnapController['isMinimumPlatformVersion'];
 };
 
+export type SetActive = {
+  type: `${typeof controllerName}:setActive`;
+  handler: SnapController['setActive'];
+};
+
 export type SnapControllerGetStateAction = ControllerGetStateAction<
   typeof controllerName,
   SnapControllerState
@@ -507,7 +512,8 @@ export type SnapControllerActions =
   | GetSnapFile
   | SnapControllerGetStateAction
   | StopAllSnaps
-  | IsMinimumPlatformVersion;
+  | IsMinimumPlatformVersion
+  | SetActive;
 
 // Controller Messenger Events
 
@@ -1293,37 +1299,21 @@ export class SnapController extends BaseController<
       `${controllerName}:isMinimumPlatformVersion`,
       (...args) => this.isMinimumPlatformVersion(...args),
     );
+
+    this.messagingSystem.registerActionHandler(
+      `${controllerName}:setActive`,
+      (...args) => this.setActive(...args),
+    );
   }
 
   /**
    * Initialise the SnapController.
    *
    * Currently this method calls the `onStart` lifecycle hook for all
-   * installed Snaps.
+   * runnable Snaps.
    */
   init() {
-    const snaps = this.getRunnableSnaps();
-    for (const { id } of snaps) {
-      const hasLifecycleHooksEndowment = this.messagingSystem.call(
-        'PermissionController:hasPermission',
-        id,
-        SnapEndowments.LifecycleHooks,
-      );
-
-      if (!hasLifecycleHooksEndowment) {
-        continue;
-      }
-
-      this.#callLifecycleHook(METAMASK_ORIGIN, id, HandlerType.OnStart).catch(
-        (error) => {
-          logError(
-            `Error when calling \`onStart\` lifecycle hook for Snap "${id}": ${getErrorMessage(
-              error,
-            )}`,
-          );
-        },
-      );
-    }
+    this.#callLifecycleHooks(METAMASK_ORIGIN, HandlerType.OnStart);
   }
 
   #handlePreinstalledSnaps(preinstalledSnaps: PreinstalledSnap[]) {
@@ -3713,6 +3703,20 @@ export class SnapController extends BaseController<
     }
   }
 
+  /**
+   * Set the active state of the client. This will trigger the `onActive` or
+   * `onInactive` lifecycle hooks for all Snaps.
+   *
+   * @param active - A boolean indicating whether the client is active or not.
+   */
+  setActive(active: boolean) {
+    if (active) {
+      this.#callLifecycleHooks(METAMASK_ORIGIN, HandlerType.OnActive);
+    } else {
+      this.#callLifecycleHooks(METAMASK_ORIGIN, HandlerType.OnInactive);
+    }
+  }
+
   /**
    * Determine the execution timeout for a given handler permission.
    *
@@ -4451,6 +4455,36 @@ export class SnapController extends BaseController<
     return true;
   }
 
+  /**
+   * Call a lifecycle hook for all runnable Snaps.
+   *
+   * @param origin - The origin of the request.
+   * @param handler - The lifecycle hook to call. This should be one of the
+   * supported lifecycle hooks.
+   */
+  #callLifecycleHooks(origin: string, handler: HandlerType) {
+    const snaps = this.getRunnableSnaps();
+    for (const { id } of snaps) {
+      const hasLifecycleHooksEndowment = this.messagingSystem.call(
+        'PermissionController:hasPermission',
+        id,
+        SnapEndowments.LifecycleHooks,
+      );
+
+      if (!hasLifecycleHooksEndowment) {
+        continue;
+      }
+
+      this.#callLifecycleHook(origin, id, handler).catch((error) => {
+        logError(
+          `Error calling lifecycle hook "${handler}" for Snap "${id}": ${getErrorMessage(
+            error,
+          )}`,
+        );
+      });
+    }
+  }
+
   /**
    * Call a lifecycle hook on a snap, if the snap has the
    * `endowment:lifecycle-hooks` permission. If the snap does not have the

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

@@ -1899,6 +1899,8 @@ describe('BaseSnapExecutor', () => {
       HandlerType.OnInstall,
       HandlerType.OnUpdate,
       HandlerType.OnStart,
+      HandlerType.OnActive,
+      HandlerType.OnInactive,
     ];
 
     for (const handler of LIFECYCLE_HOOKS) {

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

@@ -129,6 +129,8 @@ export function getHandlerArguments(
     case HandlerType.OnInstall:
     case HandlerType.OnUpdate:
     case HandlerType.OnStart:
+    case HandlerType.OnActive:
+    case HandlerType.OnInactive:
       return { origin };
 
     case HandlerType.OnHomePage:

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

@@ -122,6 +122,8 @@ export const handlerEndowments: Record<HandlerType, string | null> = {
   [HandlerType.OnInstall]: lifecycleHooksEndowmentBuilder.targetName,
   [HandlerType.OnUpdate]: lifecycleHooksEndowmentBuilder.targetName,
   [HandlerType.OnStart]: lifecycleHooksEndowmentBuilder.targetName,
+  [HandlerType.OnActive]: lifecycleHooksEndowmentBuilder.targetName,
+  [HandlerType.OnInactive]: lifecycleHooksEndowmentBuilder.targetName,
   [HandlerType.OnKeyringRequest]: keyringEndowmentBuilder.targetName,
   [HandlerType.OnHomePage]: homePageEndowmentBuilder.targetName,
   [HandlerType.OnSettingsPage]: settingsPageEndowmentBuilder.targetName,

packages/snaps-utils/src/handlers/exports.test.ts

@@ -22,6 +22,8 @@ describe('SNAP_EXPORT_NAMES', () => {
       'onInstall',
       'onUpdate',
       'onStart',
+      'onActive',
+      'onInactive',
       'onNameLookup',
       'onKeyringRequest',
       'onHomePage',

packages/snaps-utils/src/handlers/exports.ts

@@ -72,6 +72,20 @@ export const SNAP_EXPORTS = {
       return typeof snapExport === 'function';
     },
   },
+  [HandlerType.OnActive]: {
+    type: HandlerType.OnActive,
+    required: false,
+    validator: (snapExport: unknown): snapExport is OnStartHandler => {
+      return typeof snapExport === 'function';
+    },
+  },
+  [HandlerType.OnInactive]: {
+    type: HandlerType.OnInactive,
+    required: false,
+    validator: (snapExport: unknown): snapExport is OnStartHandler => {
+      return typeof snapExport === 'function';
+    },
+  },
   [HandlerType.OnKeyringRequest]: {
     type: HandlerType.OnKeyringRequest,
     required: true,

packages/snaps-utils/src/handlers/types.ts

@@ -36,6 +36,8 @@ export enum HandlerType {
   OnInstall = 'onInstall',
   OnUpdate = 'onUpdate',
   OnStart = 'onStart',
+  OnActive = 'onActive',
+  OnInactive = 'onInactive',
   OnNameLookup = 'onNameLookup',
   OnKeyringRequest = 'onKeyringRequest',
   OnHomePage = 'onHomePage',