refactor: improve GatorPermissionsController permission storage and syncronisation (#7847)

## Explanation

Makes the following changes to the `GatorPermissionsController` to
improve storage and syncronisation of permissions data with Profile Sync
service:
- constructor now accepts a configuration object, including
`supportedPermissionTypes` and optional `gatorPermissionsProviderSnapId`
and `maxSyncIntervalMs`.
- adds `lastSyncedTimestamp` (default -1); set when a sync completes
successfully so `initialize()` can decide when to sync again.
- `initialize()` call after construction; triggers a sync if no sync has
run yet or cached data is older than the configured interval.
- `fetchAndUpdateGatorPermissions()` now returns `Promise<void>`;
callers should read from controller state. Concurrent calls share the
same in-flight sync and no longer trigger duplicate operations.
- removes the `GatorPermissionsMap` JSON-serialized state (and related
types and utils); permissions are now stored in state as a simple array.
Sync is done by calling the gator permissions Snap via RPC.
- removes `enableGatorPermissions()` / `disableGatorPermissions()` and
related actions; the controller is used as the single source for gator
permissions when instantiated.
- removes support for the "custom" permission type from the public API
and types.
- renames "Sanitized" permissions to "PermissionInfo" for clarity (this
is the information required to show the permission in the UI)

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [x] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Breaking API/state-shape changes and new sync caching logic can affect
downstream consumers and initial data freshness if integration
assumptions differ.
> 
> **Overview**
> Refactors `GatorPermissionsController` to be config-driven and to
store permissions as a flat `state.grantedPermissions` array (sanitized
for UI) instead of a serialized `GatorPermissionsMap`.
> 
> Adds `initialize()` with `lastSyncedTimestamp` + configurable
`maxSyncIntervalMs` to control when an initial/stale sync happens, and
changes `fetchAndUpdateGatorPermissions()` to return `Promise<void>`
while deduplicating concurrent sync calls.
> 
> Removes `enableGatorPermissions`/`disableGatorPermissions`, related
actions/types/utils, and drops public support for “custom” permission
types; introduces `executeSnapRpc` and updates docs/tests accordingly
(including new error unit tests).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
993b214. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: jeffsmale90

packages/gator-permissions-controller/CHANGELOG.md

@@ -9,7 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Bump `@metamask/transaction-controller` from `^62.11.0` to `^62.17.0` ([#7775](https://github.com/MetaMask/core/pull/7775), [#7802](https://github.com/MetaMask/core/pull/7802), [#7832](https://github.com/MetaMask/core/pull/7832), [#7854](https://github.com/MetaMask/core/pull/7854), [#7872](https://github.com/MetaMask/core/pull/7872)), ([#7897](https://github.com/MetaMask/core/pull/7897))
+- **BREAKING:** Refactor `GatorPermissionsController`: simplified config, permission storage, and public API ([#7847](https://github.com/MetaMask/core/pull/7847))
+  - Constructor now requires `config`, internal configuration is removed from controller state
+  - New `initialize()` function performs a syncronisation process if required when the controller is first initialized
+  - Replaces `gatorPermissionsMapSerialized` with `grantedPermissions` property in internal state, replaces related types, and utility functions
+  - `fetchAndUpdateGatorPermissions()` no longer accepts parameters and resolves to `void`
+  - `getPendingRevocations` / `pendingRevocations` getter replaced by `isPendingRevocation(permissionContext)`; list on `state.pendingRevocations`
+- Bump `@metamask/transaction-controller` from `^62.11.0` to `^62.17.0` ([#7775](https://github.com/MetaMask/core/pull/7775), [#7802](https://github.com/MetaMask/core/pull/7802), [#7832](https://github.com/MetaMask/core/pull/7832), [#7854](https://github.com/MetaMask/core/pull/7854), [#7872](https://github.com/MetaMask/core/pull/7872)), ([#7897](https://github.com/MetaMask/core/pull/7897))>>>>>>> Stashed changes
 
 ## [1.1.2]
 

packages/gator-permissions-controller/README.md

@@ -17,13 +17,21 @@ or
 ```typescript
 import { GatorPermissionsController } from '@metamask/gator-permissions-controller';
 
-// Create the controller
+// Create the controller with required config
 const gatorPermissionsController = new GatorPermissionsController({
   messenger: yourMessenger,
+  config: {
+    supportedPermissionTypes: [
+      'native-token-stream',
+      'native-token-periodic',
+      'erc20-token-stream',
+      'erc20-token-periodic',
+      'erc20-token-revocation',
+    ],
+    // Optional: override the default gator permissions provider Snap id
+    // gatorPermissionsProviderSnapId: 'npm:@metamask/gator-permissions-snap',
+  },
 });
-
-// Enable the feature (requires authentication)
-gatorPermissionsController.enableGatorPermissions();
 ```
 
 ### Fetch from Profile Sync
@@ -33,12 +41,9 @@ gatorPermissionsController.enableGatorPermissions();
 const permissions =
   await gatorPermissionsController.fetchAndUpdateGatorPermissions();
 
-// Fetch permissions with optional filter params
-const filteredPermissions =
-  await gatorPermissionsController.fetchAndUpdateGatorPermissions({
-    origin: 'https://example.com',
-    chainId: '0x1',
-  });
+// Fetch permissions and update internal state
+const permissions =
+  await gatorPermissionsController.fetchAndUpdateGatorPermissions();
 ```
 
 ## Contributing