Skip to content

Latest commit

 

History

History
181 lines (134 loc) · 10 KB

0073.md

File metadata and controls

181 lines (134 loc) · 10 KB
Raw

BRC-73: Group Permissions for App Access

Ty Everett (ty@projectbabbage.com)

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 a new requestGroupPermission function, which is added to the BRC-56 suite.
  • Wallets determine the group permissions from the application's manifest.json file. Alternatively, the groupPermissions object can be provided by the application to the requestGroupPermission function.
  • 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).

  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:

    {
  "protocolID": [2, "Convo"],
  "counterparty": "...",
  "description": "For encrypted messaging."
}

  2. spendingAuthorization Example:

    {
  "amount": 10000,
  "duration": 3600,
  "description": "For in-app purchases."
}

  3. basketAccess Example:

    {
  "basket": "BRC-46 Gold",
  "description": "For in-game items."
}

  4. certificateAccess Example:

    {
  "type": "...",
  "fields": ["Name", "DOB"],
  "verifierPublicKey": "...",
  "description": "For age verification."
}

  5. Full manifest.json Example:

    {
  "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.