# Group Permissions for App Access Ty Everett () ## Abstract This specification outlines the architecture and structure of permissions granted to apps. It focuses on the grouping of permissions to provide a concise overview for users. The key permissions include Protocol Permissions, Spending Authorizations, Basket Access, and Certificate Field Access Grants. ## Motivation As applications become more integrated with user data and cryptographic operations, the need for a clear and concise permission system has never been greater. This specification seeks to simplify user decisions by grouping permissions, ensuring transparency and user autonomy over their identities, their data and their digital assets. ## Specification ### Overview of Permission Types There are four primary permission types that apps can be granted by users, each with its significance, function, and associated specifications: 1. **Protocol Permissions (BRC-43)**: This permission grants an application the ability to utilize a user's keys to execute cryptographic operations (such as BRC-2 encryption or BRC-3 digital signatures). 2. **Spending Authorizations (BRC-1)**: As the name suggests, this allows apps to transact or spend a predefined number of satoshis over a specified time frame, within BRC-1 transactions. 3. **Basket Access (BRC-46)**: This pertains to the app's capability to insert into and spend UTXO-based tokens from specific BRC-46 Output Baskets. The significance of this permission is to manage token operations within the app ecosystem. Each "basket" can be thought of as a container or grouping for tokens, and BRC-46 provides the framework for how apps can interact with these baskets, ensuring a structured approach to token management. 4. **Certificate Field Access Grants (BRC-52)**: This is about identity verification. The permission allows an app to reveal specific fields from a BRC-52 identity certificate to designated verifiers. It's a crucial step in processes that require identity verification or authentication. ### Group Permission Trigger Methodology * Applications initiate the permission request process via the `waitForAuthentication` function, which is part of the BRC-100 suite. * Wallets determine the group permissions from the application's `manifest.json` file. * The user receives a prompt detailing the permissions. They can choose to accept or deny each or all permissions. The wallet then applies their choices. ### Manifest File - `manifest.json` * The file is to be served over HTTPS and requested from the application by the wallet. HTTP is only accepted when running on `localhost` for development purposes. * The existing `babbage` key is expanded to include the `groupPermissions` key. * The `groupPermissions` key holds four subsequent keys representing the categories of permissions: `protocolPermissions`, `spendingAuthorization`, `basketAccess`, and `certificateAccess`. ### Definition for `groupPermissions` key in `manifest.json` The `groupPermissions` key is an object that encompasses various types of permissions, which the app might request from a user. This key contains four sub-keys: `protocolPermissions`, `spendingAuthorization`, `basketAccess`, and `certificateAccess`. 1. `protocolPermissions` is an array of objects, where each object defines a specific Protocol Permission. Each object contains three fields: `protocolID` (a protocol ID array with two elements, the first a security level and the second a protocol string), `counterparty` (a string in hexadecimal format representing a public key, required only if the security level of the `protocolID` is `2`), and `description` (a short text explaining the purpose of this request). > NOTE: We do not support privileged key use in group permissions for security reasons. For the purpose of grouped permission requests, `privileged` is always `false`. By nature, every use of a privileged key must be requested on a one-off basis. Thus privileged operations can never be covered by a grouped permission scheme. 2. `spendingAuthorization` is an object that provides details about the satoshis an app is requesting authorization to spend. It has three fields: `amount` (a number indicating the amount in satoshis), `duration` (a number representing the time in seconds for the authorization's validity), and `description`. 3. `basketAccess` is an array of objects, where each object denotes the access to a specific BRC-46 basket. The objects here have two fields: `basket` (the name of the BRC-46 basket) and `description`. 4. `certificateAccess` is an array of objects that represent the different certificate types an app wants access to. Each object here consists of `type` (indicating the certificate type), `fields` (an array of strings naming the fields the app wants to reveal), `verifierPublicKey` (a string in hex format, representing the public key of the verifier), and `description`. With this structured approach, app developers can seamlessly integrate their permission requests within their `manifest.json`, and users can be assured of a clear understanding of the permissions they're granting. For the avoidance of doubt, the following sections provide tables that define each specific field, and example data structures. ### Table 1: General Structure | Key Name | Value Type | Description | | ----------------------- | ---------------- | ------------------------------------------------- | | `protocolPermissions` | Array of Objects | Contains Protocol Permissions requests. | | `spendingAuthorization` | Object | Contains Spending Authorization details. | | `basketAccess` | Array of Objects | Contains Basket Access requests. | | `certificateAccess` | Array of Objects | Contains Certificate Field Access Grant requests. | ### Table 2: Protocol Permissions Object Structure | Field Name | Value Type | Description | | -------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `protocolID` | Array | BRC-43 protocol ID array with two elements. First the security level between `0` and `2`, followed by the protocol string. | | `counterparty` | String (Hexadecimal) | Public key, 33-byte in hex format. Only required if `protocolID` security level is `2`. | | `description` | String | Justification for the request, less than 50 characters. | ### Table 3: Spending Authorization Object Structure | Field Name | Value Type | Description | | ------------- | --------------- | ------------------------------------------------------- | | `amount` | Positive Number | Satoshis being authorized for the app to spend. | | `duration` | Positive Number | Time in seconds for the authorization's validity. | | `description` | String | Justification for the request, less than 50 characters. | ### Table 4: Basket Access Object Structure | Field Name | Value Type | Description | | ------------- | ---------- | ------------------------------------------------------- | | `basket` | String | Name of the BRC-46 basket. | | `description` | String | Justification for the request, less than 50 characters. | ### Table 5: Certificate Access Object Structure | Field Name | Value Type | Description | | ------------------- | -------------------- | -------------------------------------------------------- | | `type` | String (base64) | Certificate type field of a BRC-52 identity certificate. | | `fields` | Array of Strings | Array of field names being requested for revelation. | | `verifierPublicKey` | String (Hexadecimal) | Public key of the verifier in 33-byte hex format. | | `description` | String | Justification for the request, less than 50 characters. | ## Examples 1. **protocolPermissions Example**: ```json { "protocolID": [2, "Convo"], "counterparty": "...", "description": "For encrypted messaging." } ``` 2. **spendingAuthorization Example**: ```json { "amount": 10000, "duration": 3600, "description": "For in-app purchases." } ``` 3. **basketAccess Example**: ```json { "basket": "BRC-46 Gold", "description": "For in-game items." } ``` 4. **certificateAccess Example**: ```json { "type": "...", "fields": ["Name", "DOB"], "verifierPublicKey": "...", "description": "For age verification." } ``` 5. **Full manifest.json Example**: ```json { "babbage": { "groupPermissions": { "protocolPermissions": [ { "protocolID": [2, "Convo"], "counterparty": "...", "description": "For encrypted messaging." } ], "spendingAuthorization": { "amount": 10000, "duration": 3600, "description": "For in-app purchases." }, "basketAccess": [ { "basket": "BRC-46 Gold", "description": "For in-game items." } ], "certificateAccess": [ { "type": "...", "fields": ["Name", "DOB"], "verifierPublicKey": "...", "description": "For age verification." } ] } } } ``` App developers should prioritize user understanding and transparency when requesting permissions. The description field must be utilized effectively to convey the reason for the request, allowing users to make informed decisions. This approach ensures a streamlined and transparent process for apps to request and for users to grant permissions. It promotes a higher level of trust and clarity between applications and their users.