# Group Permissions for App Access

Ty Everett (<ty@projectbabbage.com>)

## Abstract

This specification defines the manifest declaration format for grouped wallet permissions. It allows an application to declare, in one place, the protocol access, spending authorization, basket access, and certificate disclosure capabilities it expects to request from the user.

The current interoperable manifest namespace is `metanet.groupPermissions`. Wallets may continue to read the legacy `babbage.groupPermissions` namespace for backwards compatibility, but it is deprecated.

## Motivation

As applications become more integrated with user data and cryptographic operations, permission prompts can become fragmented and repetitive. Grouped permission declarations let wallets present a single, coherent prompt instead of a series of unrelated one-off requests, improving both transparency and user comprehension.

## Status Note

This document defines the **grouped-permission declaration shape**.

The full runtime permission lifecycle, including manifest fetching, prompt routing, persistence, renewal, revocation, and interaction with counterparty trust (PACT), is authoritatively specified by [BRC-116](/wallet/0116.md). This document should therefore be read as the grouped-permission schema used by current BRC-100 wallet implementations, not as a complete permission-system specification by itself.

## Specification

### Canonical Manifest Location

Applications SHOULD serve a W3C web-app manifest at:

`https://{originator}/manifest.json`

For local development, wallets MAY use:

`http://localhost/.../manifest.json`

Wallets MAY fetch this manifest proactively, or lazily when the first protected operation is attempted. Current wallet-toolbox behavior supports both patterns.

### Namespace

The canonical grouped-permission declaration lives under:

`metanet.groupPermissions`

Wallets SHOULD continue to recognize:

`babbage.groupPermissions`

for backwards compatibility, but applications SHOULD migrate to `metanet`.

### `groupPermissions` Structure

The `groupPermissions` object may contain the following keys:

* `description`
* `protocolPermissions`
* `spendingAuthorization`
* `basketAccess`
* `certificateAccess`

Grouped permissions do **not** cover privileged-key usage. Privileged operations remain one-off permission decisions in current interoperable wallet behavior.

### Permission Types

There are four grouped permission categories:

1. **Protocol permissions** for BRC-43 scoped cryptographic operations.
2. **Spending authorization** for wallet spending on behalf of the originator.
3. **Basket access** for BRC-46 basket usage.
4. **Certificate access** for BRC-52 field revelation to a designated verifier.

### Protocol Permissions

Each element of `protocolPermissions` is an object with:

* `protocolID`: a BRC-43 protocol tuple `[securityLevel, protocolName]`
* `counterparty`: required when the declaration is for a specific Level 2 counterparty
* `description`: human-readable explanation for the user

Level 1 protocol declarations MAY omit `counterparty`.

Level 2 declarations used in grouped permission requests SHOULD name the specific counterparty they are about.

### Spending Authorization

`spendingAuthorization` is an object with:

* `amount`: the authorized monthly spend limit in satoshis
* `description`: human-readable explanation for the user

The older `duration` field is no longer part of current interoperable grouped-permission behavior and SHOULD be considered deprecated for new manifests.

### Basket Access

Each element of `basketAccess` is an object with:

* `basket`: the BRC-46 basket name
* `description`: human-readable explanation for the user

### Certificate Access

Each element of `certificateAccess` is an object with:

* `type`: the BRC-52 certificate type
* `fields`: the certificate fields requested for revelation
* `verifierPublicKey`: the verifier's compressed public key
* `description`: human-readable explanation for the user

## Current Interoperability Notes

* Wallets commonly fetch grouped permissions from `manifest.json` when the first protected operation is attempted, not only during `waitForAuthentication`.
* `metanet.groupPermissions` is canonical.
* `babbage.groupPermissions` is a deprecated backwards-compatibility fallback.
* Grouped permissions and PACT are distinct; PACT is defined in [BRC-116](/wallet/0116.md).

## Examples

1. **`protocolPermissions`**

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

   ```json
   {
     "amount": 10000,
     "description": "For in-app purchases."
   }
   ```
3. **`basketAccess`**

   ```json
   {
     "basket": "BRC-46 Gold",
     "description": "For in-game items."
   }
   ```
4. **`certificateAccess`**

   ```json
   {
     "type": "...",
     "fields": ["Name", "DOB"],
     "verifierPublicKey": "...",
     "description": "For age verification."
   }
   ```
5. **Full `manifest.json`**

   ```json
   {
     "name": "My App",
     "short_name": "MyApp",
     "display": "standalone",
     "metanet": {
       "schemaVersion": 1,
       "groupPermissions": {
         "protocolPermissions": [
           {
             "protocolID": [2, "Convo"],
             "counterparty": "...",
             "description": "For encrypted messaging."
           }
         ],
         "spendingAuthorization": {
           "amount": 10000,
           "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."
           }
         ]
       }
     },
     "icons": []
   }
   ```

Applications SHOULD provide clear descriptions that help the user understand why each grouped permission is being requested. Wallets SHOULD interpret these declarations using the lifecycle and enforcement rules in [BRC-116](/wallet/0116.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bsv.brc.dev/wallet/0073.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.