Skip to content

Commit 420b2e3

Browse files
V00D00-childV00D00-child
authored
feat: add gator permissions controller (#6033)
## Explanation <!-- Thanks for your contribution! Take a moment to answer these questions so that reviewers have the information they need to properly understand your changes: * What is the current state of things and why does it need to change? * What is the solution your changes offer and how does it work? * Are there any changes whose purpose might not obvious to those unfamiliar with the domain? * If your primary goal was to update one package but you found you had to update another one along the way, why did you do so? * If you had to upgrade a dependency, why did you do so? --> ### @metamask/gator-permissions-controller #### Current State and Why Change is Needed MetaMask clients currently lack a dedicated system for managing gator permissions that are stored to profile sync via the `@metamask/gator-permissions-snap`. #### Solution and How It Works This change introduces a new `@metamask/gator-permissions-controller` package that provides a comprehensive solution for managing gator permissions in MetaMask clients with gator-snap integration. #### Changes That Might Not Be Obvious - Serialization Strategy: The controller `state` uses JSON serialization for storing permission data fetched from `@metamask/gator-permissions-snap`, which allows for efficient storage and retrieval while maintaining data integrity. The deserialize permission data is represented as a list of gator permissions filtered by permission type and chainId. - Default Permission Structure: The controller initializes with an empty structure for all three permission types, ensuring consistent state even when no permissions are configured #### Package Dependencies and Integration The new package depends on `@metamask/snaps-controllers` as a peer dependency, ensuring it can leverage sending RPC requests to an installed Metamask Snap. This integration allows the `GatorPermissionsController` to forward requests to `@metamask/gator-permissions-snap` to fetch users' Gator permissions that have been stored in the MetaMask Profile Sync service. The `@metamask/gator-permissions-snap` will take on the responsibility of authenticating with MetaMask Profile Sync service using an`SRP` identifier via integration with `@metamask/message-signing-snap`. #### No Dependency Upgrades Required This is a new package that introduces new functionality without requiring changes to existing dependencies. The package uses the current stable versions of `@metamask/base-controller`, `@metamask/utils `,`@metamask/snaps-sdk`, and `@metamask/snaps-utils` following the established patterns in the MetaMask codebase. ## References <!-- Are there any issues that this pull request is tied to? Are there other links that reviewers should consult to understand these changes better? Are there client or consumer pull requests to adopt any breaking changes? For example: * Fixes #12345 * Related to #67890 --> Related to(MM snap-7715-permissions): [Persisting Granted Permissions with MM Profile Sync](MetaMask/snap-7715-permissions#84) Requires(MM snap-7715-permissions):[Add new permissionsProvider_getGrantedPermissions RPC](MetaMask/snap-7715-permissions#108) Required by(MM Extension): MetaMask/metamask-extension#33996 ### Gator Permissions Data Flow ```mermaid graph TD %% dApp flow for storing permissions A[dApp<br/>client side RPC] -->|RPC| GPS[gator-permissions-snap] C -->|WRITE| D[(permissions stored<br/>across all sites)] %% User flow for reading permissions E[user<br/>permissions page] -->|UI| F[MM client] F -->|submitRequestToBackground| G[GatorPermissionsController] G --> MSYS[messagingSystem] MSYS -->|handleRequest| SC[SnapController] SC -->|RPC| GPS C -->|READ| D %% SRP Auth GPS -->|OAuth 2.0 Auth| MS[message-signing-snap] MS -->|SRP identifier & signature| C[profile sync service] %% Styling classDef dappStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px classDef userStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px classDef serviceStyle fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px classDef dataStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px classDef authStyle fill:#ffebee,stroke:#c62828,stroke-width:2px classDef systemStyle fill:#fce4ec,stroke:#ad1457,stroke-width:2px class A dappStyle class E,F userStyle class GPS,C serviceStyle class D dataStyle class MS authStyle class G,MSYS,SC systemStyle ``` ## 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/contributing.md#updating-changelogs), highlighting breaking changes as necessary - [x] I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes
1 parent 4ce8eff commit 420b2e3

24 files changed

Lines changed: 2368 additions & 0 deletions

‎.github/CODEOWNERS‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,9 @@
2828
/packages/transaction-controller @MetaMask/confirmations
2929
/packages/user-operation-controller @MetaMask/confirmations
3030

31+
## Delegation Team
32+
/packages/gator-permissions-controller @MetaMask/delegation
33+
3134
## Earn Team
3235
/packages/earn-controller @MetaMask/earn
3336
## Notifications Team
@@ -115,6 +118,8 @@
115118
/packages/ens-controller/CHANGELOG.md @MetaMask/confirmations @MetaMask/core-platform
116119
/packages/gas-fee-controller/package.json @MetaMask/confirmations @MetaMask/core-platform
117120
/packages/gas-fee-controller/CHANGELOG.md @MetaMask/confirmations @MetaMask/core-platform
121+
/packages/gator-permissions-controller/package.json @MetaMask/delegation @MetaMask/core-platform
122+
/packages/gator-permissions-controller/CHANGELOG.md @MetaMask/delegation @MetaMask/core-platform
118123
/packages/keyring-controller/package.json @MetaMask/accounts-engineers @MetaMask/core-platform
119124
/packages/keyring-controller/CHANGELOG.md @MetaMask/accounts-engineers @MetaMask/core-platform
120125
/packages/logging-controller/package.json @MetaMask/confirmations @MetaMask/core-platform

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ Each package in this repository has its own README where you can find installati
4242
- [`@metamask/eth-json-rpc-provider`](packages/eth-json-rpc-provider)
4343
- [`@metamask/foundryup`](packages/foundryup)
4444
- [`@metamask/gas-fee-controller`](packages/gas-fee-controller)
45+
- [`@metamask/gator-permissions-controller`](packages/gator-permissions-controller)
4546
- [`@metamask/json-rpc-engine`](packages/json-rpc-engine)
4647
- [`@metamask/json-rpc-middleware-stream`](packages/json-rpc-middleware-stream)
4748
- [`@metamask/keyring-controller`](packages/keyring-controller)
@@ -103,6 +104,7 @@ linkStyle default opacity:0.5
103104
eth_json_rpc_provider(["@metamask/eth-json-rpc-provider"]);
104105
foundryup(["@metamask/foundryup"]);
105106
gas_fee_controller(["@metamask/gas-fee-controller"]);
107+
gator_permissions_controller(["@metamask/gator-permissions-controller"]);
106108
json_rpc_engine(["@metamask/json-rpc-engine"]);
107109
json_rpc_middleware_stream(["@metamask/json-rpc-middleware-stream"]);
108110
keyring_controller(["@metamask/keyring-controller"]);
@@ -201,6 +203,7 @@ linkStyle default opacity:0.5
201203
gas_fee_controller --> controller_utils;
202204
gas_fee_controller --> polling_controller;
203205
gas_fee_controller --> network_controller;
206+
gator_permissions_controller --> base_controller;
204207
json_rpc_middleware_stream --> json_rpc_engine;
205208
keyring_controller --> base_controller;
206209
logging_controller --> base_controller;

‎packages/gator-permissions-controller/CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
12+
- Initial release ([#6033](https://github.com/MetaMask/core/pull/6033))
13+
14+
[Unreleased]: https://github.com/MetaMask/core/

‎packages/gator-permissions-controller/LICENSE‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
MIT License
2+
3+
Copyright (c) 2025 MetaMask
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

‎packages/gator-permissions-controller/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# `@metamask/gator-permissions-controller`
2+
3+
A dedicated controller for reading gator permissions from profile sync storage. This controller fetches data from the encrypted user storage database and caches it locally, providing fast access to permissions across devices while maintaining privacy through client-side encryption.
4+
5+
## Installation
6+
7+
`yarn add @metamask/gator-permissions-controller`
8+
9+
or
10+
11+
`npm install @metamask/gator-permissions-controller`
12+
13+
## Usage
14+
15+
### Basic Setup
16+
17+
```typescript
18+
import { GatorPermissionsController } from '@metamask/gator-permissions-controller';
19+
20+
// Create the controller
21+
const gatorPermissionsController = new GatorPermissionsController({
22+
messenger: yourMessenger,
23+
});
24+
25+
// Enable the feature (requires authentication)
26+
gatorPermissionsController.enableGatorPermissions();
27+
```
28+
29+
### Fetch from Profile Sync
30+
31+
```typescript
32+
const permissions =
33+
await gatorPermissionsController.fetchAndUpdateGatorPermissions();
34+
```
35+
36+
## Contributing
37+
38+
This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

‎packages/gator-permissions-controller/jest.config.js‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
/*
2+
* For a detailed explanation regarding each configuration property and type check, visit:
3+
* https://jestjs.io/docs/configuration
4+
*/
5+
6+
const merge = require('deepmerge');
7+
const path = require('path');
8+
9+
const baseConfig = require('../../jest.config.packages');
10+
11+
const displayName = path.basename(__dirname);
12+
13+
module.exports = merge(baseConfig, {
14+
// The display name when running multiple projects
15+
displayName,
16+
17+
// An object that configures minimum threshold enforcement for coverage results
18+
coverageThreshold: {
19+
global: {
20+
branches: 100,
21+
functions: 100,
22+
lines: 100,
23+
statements: 100,
24+
},
25+
},
26+
});

‎packages/gator-permissions-controller/package.json‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
{
2+
"name": "@metamask/gator-permissions-controller",
3+
"version": "0.0.0",
4+
"description": "Controller for managing gator permissions with profile sync integration",
5+
"keywords": [
6+
"MetaMask",
7+
"Ethereum"
8+
],
9+
"homepage": "https://github.com/MetaMask/core/tree/main/packages/gator-permissions-controller#readme",
10+
"bugs": {
11+
"url": "https://github.com/MetaMask/core/issues"
12+
},
13+
"repository": {
14+
"type": "git",
15+
"url": "https://github.com/MetaMask/core.git"
16+
},
17+
"license": "MIT",
18+
"sideEffects": false,
19+
"exports": {
20+
".": {
21+
"import": {
22+
"types": "./dist/index.d.mts",
23+
"default": "./dist/index.mjs"
24+
},
25+
"require": {
26+
"types": "./dist/index.d.cts",
27+
"default": "./dist/index.cjs"
28+
}
29+
},
30+
"./package.json": "./package.json"
31+
},
32+
"main": "./dist/index.cjs",
33+
"types": "./dist/index.d.cts",
34+
"files": [
35+
"dist/"
36+
],
37+
"scripts": {
38+
"build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
39+
"build:docs": "typedoc",
40+
"changelog:update": "../../scripts/update-changelog.sh @metamask/gator-permissions-controller",
41+
"changelog:validate": "../../scripts/validate-changelog.sh @metamask/gator-permissions-controller",
42+
"publish:preview": "yarn npm publish --tag preview",
43+
"since-latest-release": "../../scripts/since-latest-release.sh",
44+
"test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
45+
"test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
46+
"test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
47+
"test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
48+
},
49+
"dependencies": {
50+
"@metamask/base-controller": "^8.1.0",
51+
"@metamask/snaps-sdk": "^9.0.0",
52+
"@metamask/snaps-utils": "^11.0.0",
53+
"@metamask/utils": "^11.4.2"
54+
},
55+
"devDependencies": {
56+
"@lavamoat/allow-scripts": "^3.0.4",
57+
"@lavamoat/preinstall-always-fail": "^2.1.0",
58+
"@metamask/auto-changelog": "^3.4.4",
59+
"@metamask/snaps-controllers": "^14.0.1",
60+
"@ts-bridge/cli": "^0.6.1",
61+
"@types/jest": "^27.4.1",
62+
"deepmerge": "^4.2.2",
63+
"jest": "^27.5.1",
64+
"ts-jest": "^27.1.4",
65+
"typedoc": "^0.24.8",
66+
"typedoc-plugin-missing-exports": "^2.0.0",
67+
"typescript": "~5.2.2"
68+
},
69+
"peerDependencies": {
70+
"@metamask/snaps-controllers": "^14.0.1"
71+
},
72+
"engines": {
73+
"node": "^18.18 || >=20"
74+
},
75+
"publishConfig": {
76+
"access": "public",
77+
"registry": "https://registry.npmjs.org/"
78+
}
79+
}

0 commit comments

Comments
 (0)