@bsv/wallet-toolbox 1.1.62 → 1.2.1

package/src/WalletPermissionsManager.ts

@@ -0,0 +1,2424 @@
+import { WalletInterface, Utils, PushDrop, LockingScript, Transaction } from '@bsv/sdk'
+import { validateCreateActionArgs } from './sdk'
+
+////// TODO: ADD SUPPORT FOR ADMIN COUNTERPARTIES BASED ON WALLET STORAGE
+////// !!!!!!!! SECURITY-CRITICAL ADDITION — DO NOT USE UNTIL IMPLEMENTED.
+
+/**
+ * Describes a single requested permission that the user must either grant or deny.
+ *
+ * Four categories of permission are supported, each with a unique protocol:
+ *  1) protocol - "DPACP" (Domain Protocol Access Control Protocol)
+ *  2) basket   - "DBAP"  (Domain Basket Access Protocol)
+ *  3) certificate - "DCAP" (Domain Certificate Access Protocol)
+ *  4) spending - "DSAP"  (Domain Spending Authorization Protocol)
+ *
+ * This model underpins "requests" made to the user for permission, which the user can
+ * either grant or deny. The manager can then create on-chain tokens (PushDrop outputs)
+ * if permission is granted. Denying requests cause the underlying operation to throw,
+ * and no token is created. An "ephemeral" grant is also possible, denoting a one-time
+ * authorization without an associated persistent on-chain token.
+ */
+export interface PermissionRequest {
+  type: 'protocol' | 'basket' | 'certificate' | 'spending'
+  originator: string // The domain or FQDN of the requesting application
+  privileged?: boolean // For "protocol" or "certificate" usage, indicating privileged key usage
+  protocolID?: [0 | 1 | 2, string] // For type='protocol': BRC-43 style (securityLevel, protocolName)
+  counterparty?: string // For type='protocol': e.g. target public key or "self"/"anyone"
+
+  basket?: string // For type='basket': the basket name being requested
+
+  certificate?: {
+    // For type='certificate': details about the cert usage
+    verifier: string
+    certType: string
+    fields: string[]
+  }
+
+  spending?: {
+    // For type='spending': details about the requested spend
+    satoshis: number
+    lineItems?: Array<{
+      type: 'input' | 'output' | 'fee'
+      description: string
+      satoshis: number
+    }>
+  }
+
+  reason?: string // Human-readable explanation for requesting permission
+  renewal?: boolean // Whether this request is for renewing an expired token
+  previousToken?: PermissionToken // If renewing an expired permission, reference to the old token
+}
+
+/**
+ * Signature for functions that handle a permission request event, e.g. "Please ask the user to allow basket X".
+ */
+export type PermissionEventHandler = (request: PermissionRequest & { requestID: string }) => void | Promise<void>
+
+/**
+ * Data structure representing an on-chain permission token.
+ * It is typically stored as a single unspent PushDrop output in a special "internal" admin basket belonging to
+ * the user, held in their underlying wallet.
+ *
+ * It can represent any of the four permission categories by having the relevant fields:
+ *  - DPACP: originator, privileged, protocol, securityLevel, counterparty
+ *  - DBAP:  originator, basketName
+ *  - DCAP:  originator, privileged, verifier, certType, certFields
+ *  - DSAP:  originator, authorizedAmount
+ */
+export interface PermissionToken {
+  /** The transaction ID where this token resides. */
+  txid: string
+
+  /** The output index within that transaction. */
+  outputIndex: number
+
+  /** The exact script hex for the locking script. */
+  outputScript: string
+
+  /** The amount of satoshis assigned to the permission output (often 1). */
+  satoshis: number
+
+  /** The originator domain or FQDN that is allowed to use this permission. */
+  originator: string
+
+  /** The expiration time for this token in UNIX epoch seconds. (0 or omitted for spending authorizations, which are indefinite) */
+  expiry: number
+
+  /** Whether this token grants privileged usage (for protocol or certificate). */
+  privileged?: boolean
+
+  /** The protocol name, if this is a DPACP token. */
+  protocol?: string
+
+  /** The security level (0,1,2) for DPACP. */
+  securityLevel?: 0 | 1 | 2
+
+  /** The counterparty, for DPACP. */
+  counterparty?: string
+
+  /** The name of a basket, if this is a DBAP token. */
+  basketName?: string
+
+  /** The certificate type, if this is a DCAP token. */
+  certType?: string
+
+  /** The certificate fields that this token covers, if DCAP token. */
+  certFields?: string[]
+
+  /** The "verifier" public key string, if DCAP. */
+  verifier?: string
+
+  /** For DSAP, the maximum authorized spending for the month. */
+  authorizedAmount?: number
+}
+
+/**
+ * A map from each permission type to a special "admin basket" name used for storing
+ * the tokens. The tokens themselves are unspent transaction outputs (UTXOs) with a
+ * specialized PushDrop script that references the originator, expiry, etc.
+ */
+const BASKET_MAP = {
+  protocol: 'admin protocol-permission',
+  basket: 'admin basket-access',
+  certificate: 'admin certificate-access',
+  spending: 'admin spending-authorization'
+}
+
+/**
+ * The set of callbacks that external code can bind to, e.g. to display UI prompts or logs
+ * when a permission is requested.
+ */
+export interface WalletPermissionsManagerCallbacks {
+  onProtocolPermissionRequested?: PermissionEventHandler[]
+  onBasketAccessRequested?: PermissionEventHandler[]
+  onCertificateAccessRequested?: PermissionEventHandler[]
+  onSpendingAuthorizationRequested?: PermissionEventHandler[]
+}
+
+/**
+ * Configuration object for the WalletPermissionsManager. If a given option is `false`,
+ * the manager will skip or alter certain permission checks or behaviors.
+ *
+ * By default, all of these are `true` unless specified otherwise. This is the most secure configuration.
+ */
+export interface PermissionsManagerConfig {
+  /**
+   * For `createSignature` and `verifySignature`,
+   * require a "protocol usage" permission check?
+   */
+  seekProtocolPermissionsForSigning?: boolean
+
+  /**
+   * For methods that perform encryption (encrypt/decrypt), require
+   * a "protocol usage" permission check?
+   */
+  seekProtocolPermissionsForEncrypting?: boolean
+
+  /**
+   * For methods that perform HMAC creation or verification (createHmac, verifyHmac),
+   * require a "protocol usage" permission check?
+   */
+  seekProtocolPermissionsForHMAC?: boolean
+
+  /**
+   * For revealing counterparty-level or specific key linkage revelation information,
+   * should we require permission?
+   */
+  seekPermissionsForKeyLinkageRevelation?: boolean
+
+  /**
+   * For revealing any user public key (getPublicKey) **other** than the identity key,
+   * should we require permission?
+   */
+  seekPermissionsForPublicKeyRevelation?: boolean
+
+  /**
+   * If getPublicKey is requested with `identityKey=true`, do we require permission?
+   */
+  seekPermissionsForIdentityKeyRevelation?: boolean
+
+  /**
+   * If discoverByIdentityKey / discoverByAttributes are called, do we require permission
+   * for "identity resolution" usage?
+   */
+  seekPermissionsForIdentityResolution?: boolean
+
+  /**
+   * When we do internalizeAction with `basket insertion`, or include outputs in baskets
+   * with `createAction, do we ask for basket permission?
+   */
+  seekBasketInsertionPermissions?: boolean
+
+  /**
+   * When relinquishOutput is called, do we ask for basket permission?
+   */
+  seekBasketRemovalPermissions?: boolean
+
+  /**
+   * When listOutputs is called, do we ask for basket permission?
+   */
+  seekBasketListingPermissions?: boolean
+
+  /**
+   * When createAction is called with labels, do we ask for "label usage" permission?
+   */
+  seekPermissionWhenApplyingActionLabels?: boolean
+
+  /**
+   * When listActions is called with labels, do we ask for "label usage" permission?
+   */
+  seekPermissionWhenListingActionsByLabel?: boolean
+
+  /**
+   * If proving a certificate (proveCertificate) or revealing certificate fields,
+   * do we require a "certificate access" permission?
+   */
+  seekCertificateDisclosurePermissions?: boolean
+
+  /**
+   * If acquiring a certificate (acquireCertificate), do we require a permission check?
+   */
+  seekCertificateAcquisitionPermissions?: boolean
+
+  /**
+   * If relinquishing a certificate (relinquishCertificate), do we require a permission check?
+   */
+  seekCertificateRelinquishmentPermissions?: boolean
+
+  /**
+   * If listing a user's certificates (listCertificates), do we require a permission check?
+   */
+  seekCertificateListingPermissions?: boolean
+
+  /**
+   * Should transaction descriptions, input descriptions, and output descriptions be encrypted
+   * when before they are passed to the underlying wallet, and transparently decrypted when retrieved?
+   */
+  encryptWalletMetadata?: boolean
+
+  /**
+   * If the originator tries to spend wallet funds (netSpent > 0 in createAction),
+   * do we seek spending authorization?
+   */
+  seekSpendingPermissions?: boolean
+
+  /**
+   * If false, permissions are checked without regard for whether we are in
+   * privileged mode. Privileged status is ignored with respect to whether
+   * permissions are granted. Internally, they are always sought and checked
+   * with privileged=false, regardless of the actual value.
+   */
+  differentiatePrivilegedOperations?: boolean
+}
+
+/**
+ * @class WalletPermissionsManager
+ *
+ * Wraps an underlying BRC-100 `Wallet` implementation with permissions management capabilities.
+ * The manager intercepts calls from external applications (identified by originators), checks if the request is allowed,
+ * and if not, orchestrates user permission flows. It creates or renews on-chain tokens in special
+ * admin baskets to track these authorizations. Finally, it proxies the actual call to the underlying wallet.
+ *
+ * ### Key Responsibilities:
+ *  - **Permission Checking**: Before standard wallet operations (e.g. `encrypt`),
+ *    the manager checks if a valid permission token exists. If not, it attempts to request permission from the user.
+ *  - **On-Chain Tokens**: When permission is granted, the manager stores it as an unspent "PushDrop" output.
+ *    This can be spent later to revoke or renew the permission.
+ *  - **Callbacks**: The manager triggers user-defined callbacks on permission requests (to show a UI prompt),
+ *    on grants/denials, and on internal processes.
+ *
+ * ### Implementation Notes:
+ *  - The manager follows the BRC-100 `createAction` + `signAction` pattern for building or spending these tokens.
+ *  - Token revocation or renewal uses standard BRC-100 flows: we build a transaction that consumes
+ *    the old token UTXO and outputs a new one (or none, if fully revoked).
+ */
+export class WalletPermissionsManager implements WalletInterface {
+  /** A reference to the BRC-100 wallet instance. */
+  private underlying: WalletInterface
+
+  /** The "admin" domain or FQDN that is implicitly allowed to do everything. */
+  private adminOriginator: string
+
+  /**
+   * Event callbacks that external code can subscribe to, e.g. to show a UI prompt
+   * or log events. Each event can have multiple handlers.
+   */
+  private callbacks: WalletPermissionsManagerCallbacks = {
+    onProtocolPermissionRequested: [],
+    onBasketAccessRequested: [],
+    onCertificateAccessRequested: [],
+    onSpendingAuthorizationRequested: []
+  }
+
+  /**
+   * We queue parallel requests for the same resource so that only one
+   * user prompt is created for a single resource. If multiple calls come
+   * in at once for the same "protocol:domain:privileged:counterparty" etc.,
+   * they get merged.
+   *
+   * The key is a string derived from the operation; the value is an object with a reference to the
+   * associated request and an array of pending promise resolve/reject pairs, one for each active
+   * operation that's waiting on the particular resource described by the key.
+   */
+  private activeRequests: Map<
+    string,
+    {
+      request: PermissionRequest
+      pending: Array<{
+        resolve: (val: boolean) => void
+        reject: (err: any) => void
+      }>
+    }
+  > = new Map()
+
+  /**
+   * Configuration that determines whether to skip or apply various checks and encryption.
+   */
+  private config: PermissionsManagerConfig
+
+  /**
+   * Constructs a new Permissions Manager instance.
+   *
+   * @param underlyingWallet           The underlying BRC-100 wallet, where requests are forwarded after permission is granted
+   * @param adminOriginator            The domain or FQDN that is automatically allowed everything
+   * @param config                     A set of boolean flags controlling how strictly permissions are enforced
+   */
+  constructor(underlyingWallet: WalletInterface, adminOriginator: string, config: PermissionsManagerConfig = {}) {
+    this.underlying = underlyingWallet
+    this.adminOriginator = adminOriginator
+
+    // Default all config options to true unless specified
+    this.config = {
+      seekProtocolPermissionsForSigning: true,
+      seekProtocolPermissionsForEncrypting: true,
+      seekProtocolPermissionsForHMAC: true,
+      seekPermissionsForKeyLinkageRevelation: true,
+      seekPermissionsForPublicKeyRevelation: true,
+      seekPermissionsForIdentityKeyRevelation: true,
+      seekPermissionsForIdentityResolution: true,
+      seekBasketInsertionPermissions: true,
+      seekBasketRemovalPermissions: true,
+      seekBasketListingPermissions: true,
+      seekPermissionWhenApplyingActionLabels: true,
+      seekPermissionWhenListingActionsByLabel: true,
+      seekCertificateDisclosurePermissions: true,
+      seekCertificateAcquisitionPermissions: true,
+      seekCertificateRelinquishmentPermissions: true,
+      seekCertificateListingPermissions: true,
+      encryptWalletMetadata: true,
+      seekSpendingPermissions: true,
+      differentiatePrivilegedOperations: true,
+      ...config // override with user-specified config
+    }
+  }
+
+  /* ---------------------------------------------------------------------
+   *  1) PUBLIC API FOR REGISTERING CALLBACKS (UI PROMPTS, LOGGING, ETC.)
+   * --------------------------------------------------------------------- */
+
+  /**
+   * Binds a callback function to a named event, such as `onProtocolPermissionRequested`.
+   *
+   * @param eventName The name of the event to listen to
+   * @param handler   A function that handles the event
+   * @returns         A numeric ID you can use to unbind later
+   */
+  public bindCallback(eventName: keyof WalletPermissionsManagerCallbacks, handler: PermissionEventHandler): number {
+    const arr = this.callbacks[eventName]!
+    arr.push(handler)
+    return arr.length - 1
+  }
+
+  /**
+   * Unbinds a previously registered callback by either its numeric ID (returned by `bindCallback`)
+   * or by exact function reference.
+   *
+   * @param eventName  The event name, e.g. "onProtocolPermissionRequested"
+   * @param reference  Either the numeric ID or the function reference
+   * @returns          True if successfully unbound, false otherwise
+   */
+  public unbindCallback(eventName: keyof WalletPermissionsManagerCallbacks, reference: number | Function): boolean {
+    if (!this.callbacks[eventName]) return false
+    const arr = this.callbacks[eventName] as any[]
+    if (typeof reference === 'number') {
+      if (arr[reference]) {
+        arr[reference] = null
+        return true
+      }
+      return false
+    } else {
+      const index = arr.indexOf(reference)
+      if (index !== -1) {
+        arr[index] = null
+        return true
+      }
+      return false
+    }
+  }
+
+  /**
+   * Internally triggers a named event, calling all subscribed listeners.
+   * Each callback is awaited in turn (though errors are swallowed so that
+   * one failing callback doesn't prevent the others).
+   *
+   * @param eventName The event name
+   * @param param     The parameter object passed to all listeners
+   */
+  private async callEvent(eventName: keyof WalletPermissionsManagerCallbacks, param: any): Promise<void> {
+    const arr = this.callbacks[eventName] || []
+    for (const cb of arr) {
+      if (typeof cb === 'function') {
+        try {
+          await cb(param)
+        } catch (e) {
+          // Intentionally swallow errors from user-provided callbacks
+        }
+      }
+    }
+  }
+
+  /* ---------------------------------------------------------------------
+   *  2) PERMISSION (GRANT / DENY) METHODS
+   * --------------------------------------------------------------------- */
+
+  /**
+   * Grants a previously requested permission.
+   * This method:
+   *  1) Resolves all pending promise calls waiting on this request
+   *  2) Optionally creates or renews an on-chain PushDrop token (unless `ephemeral===true`)
+   *
+   * @param params      requestID to identify which request is granted, plus optional expiry
+   *                    or `ephemeral` usage, etc.
+   */
+  public async grantPermission(params: {
+    requestID: string
+    expiry?: number
+    ephemeral?: boolean
+    amount?: number
+  }): Promise<void> {
+    // 1) Identify the matching queued requests in `activeRequests`
+    const matching = this.activeRequests.get(params.requestID)
+    if (!matching) {
+      throw new Error('Request ID not found.')
+    }
+
+    // 2) Mark all matching requests as resolved, deleting the entry
+    for (const x of matching.pending) {
+      x.resolve(true)
+    }
+    this.activeRequests.delete(params.requestID)
+
+    // 3) If `ephemeral !== true`, we create or renew an on-chain token
+    if (!params.ephemeral) {
+      if (!matching.request.renewal) {
+        // brand-new permission token
+        await this.createPermissionOnChain(
+          matching.request,
+          params.expiry || Math.floor(Date.now() / 1000) + 3600 * 24 * 30, // default 30-day expiry
+          params.amount
+        )
+      } else {
+        // renewal => spend the old token, produce a new one
+        await this.renewPermissionOnChain(
+          matching.request.previousToken!,
+          matching.request,
+          params.expiry || Math.floor(Date.now() / 1000) + 3600 * 24 * 30,
+          params.amount
+        )
+      }
+    }
+  }
+
+  /**
+   * Denies a previously requested permission.
+   * This method rejects all pending promise calls waiting on that request
+   *
+   * @param requestID    requestID identifying which request to deny
+   */
+  public async denyPermission(requestID: string): Promise<void> {
+    // 1) Identify the matching requests
+    const matching = this.activeRequests.get(requestID)
+    if (!matching) {
+      throw new Error('Request ID not found.')
+    }
+
+    // 2) Reject all matching requests, deleting the entry
+    for (const x of matching.pending) {
+      x.reject(new Error('Permission denied.'))
+    }
+    this.activeRequests.delete(requestID)
+  }
+
+  /* ---------------------------------------------------------------------
+   *  3) THE "ENSURE" METHODS: CHECK IF PERMISSION EXISTS, OTHERWISE PROMPT
+   * --------------------------------------------------------------------- */
+
+  /**
+   * Ensures the originator has protocol usage permission.
+   * If no valid (unexpired) permission token is found, triggers a permission request flow.
+   */
+  public async ensureProtocolPermission({
+    originator,
+    privileged,
+    protocolID,
+    counterparty,
+    reason,
+    seekPermission = true,
+    usageType
+  }: {
+    originator: string
+    privileged: boolean
+    protocolID: [0 | 1 | 2, string]
+    counterparty: string
+    reason?: string
+    seekPermission?: boolean
+    usageType: 'signing' | 'encrypting' | 'hmac' | 'publicKey' | 'identityKey' | 'linkageRevelation' | 'generic'
+  }): Promise<boolean> {
+    // 1) adminOriginator can do anything
+    if (this.isAdminOriginator(originator)) return true
+
+    // 2) If security level=0, we consider it "open" usage
+    const [level, protoName] = protocolID
+    if (level === 0) return true
+
+    // 3) If protocol is admin-reserved, block
+    if (this.isAdminProtocol(protocolID)) {
+      throw new Error(`Protocol “${protoName}” is admin-only.`)
+    }
+
+    // Allow the configured exceptions.
+    if (usageType === 'signing' && !this.config.seekProtocolPermissionsForSigning) {
+      return true
+    }
+    if (usageType === 'encrypting' && !this.config.seekProtocolPermissionsForEncrypting) {
+      return true
+    }
+    if (usageType === 'hmac' && !this.config.seekProtocolPermissionsForHMAC) {
+      return true
+    }
+    if (usageType === 'publicKey' && !this.config.seekPermissionsForPublicKeyRevelation) {
+      return true
+    }
+    if (usageType === 'identityKey' && !this.config.seekPermissionsForIdentityKeyRevelation) {
+      return true
+    }
+    if (usageType === 'linkageRevelation' && !this.config.seekPermissionsForKeyLinkageRevelation) {
+      return true
+    }
+    if (!this.config.differentiatePrivilegedOperations) {
+      privileged = false
+    }
+
+    // 4) Attempt to find a valid token in the internal basket
+    const token = await this.findProtocolToken(
+      originator,
+      privileged,
+      protocolID,
+      counterparty,
+      /*includeExpired=*/ true
+    )
+    if (token) {
+      if (!this.isTokenExpired(token.expiry)) {
+        // valid and unexpired
+        return true
+      } else {
+        // has a token but expired => request renewal if allowed
+        if (!seekPermission) {
+          throw new Error(`Protocol permission expired and no further user consent allowed (seekPermission=false).`)
+        }
+        return await this.requestPermissionFlow({
+          type: 'protocol',
+          originator,
+          privileged,
+          protocolID,
+          counterparty,
+          reason,
+          renewal: true,
+          previousToken: token
+        })
+      }
+    } else {
+      // No token found => request a new one if allowed
+      if (!seekPermission) {
+        throw new Error(`No protocol permission token found (seekPermission=false).`)
+      }
+      return await this.requestPermissionFlow({
+        type: 'protocol',
+        originator,
+        privileged,
+        protocolID,
+        counterparty,
+        reason,
+        renewal: false
+      })
+    }
+  }
+
+  /**
+   * Ensures the originator has basket usage permission for the specified basket.
+   * If not, triggers a permission request flow.
+   */
+  public async ensureBasketAccess({
+    originator,
+    basket,
+    reason,
+    seekPermission = true,
+    usageType
+  }: {
+    originator: string
+    basket: string
+    reason?: string
+    seekPermission?: boolean
+    usageType: 'insertion' | 'removal' | 'listing'
+  }): Promise<boolean> {
+    if (this.isAdminOriginator(originator)) return true
+    if (this.isAdminBasket(basket)) {
+      throw new Error(`Basket “${basket}” is admin-only.`)
+    }
+    if (usageType === 'insertion' && !this.config.seekBasketInsertionPermissions) return true
+    if (usageType === 'removal' && !this.config.seekBasketRemovalPermissions) return true
+    if (usageType === 'listing' && !this.config.seekBasketListingPermissions) return true
+    const token = await this.findBasketToken(originator, basket, true)
+    if (token) {
+      if (!this.isTokenExpired(token.expiry)) {
+        return true
+      } else {
+        if (!seekPermission) {
+          throw new Error(`Basket permission expired (seekPermission=false).`)
+        }
+        return await this.requestPermissionFlow({
+          type: 'basket',
+          originator,
+          basket,
+          reason,
+          renewal: true,
+          previousToken: token
+        })
+      }
+    } else {
+      // none
+      if (!seekPermission) {
+        throw new Error(`No basket permission found, and no user consent allowed (seekPermission=false).`)
+      }
+      return await this.requestPermissionFlow({
+        type: 'basket',
+        originator,
+        basket,
+        reason,
+        renewal: false
+      })
+    }
+  }
+
+  /**
+   * Ensures the originator has a valid certificate permission.
+   * This is relevant when revealing certificate fields in DCAP contexts.
+   */
+  public async ensureCertificateAccess({
+    originator,
+    privileged,
+    verifier,
+    certType,
+    fields,
+    reason,
+    seekPermission = true,
+    usageType
+  }: {
+    originator: string
+    privileged: boolean
+    verifier: string
+    certType: string
+    fields: string[]
+    reason?: string
+    seekPermission?: boolean
+    usageType: 'disclosure'
+  }): Promise<boolean> {
+    if (this.isAdminOriginator(originator)) return true
+    if (usageType === 'disclosure' && !this.config.seekCertificateDisclosurePermissions) {
+      return true
+    }
+    if (!this.config.differentiatePrivilegedOperations) {
+      privileged = false
+    }
+    const token = await this.findCertificateToken(
+      originator,
+      privileged,
+      verifier,
+      certType,
+      fields,
+      /*includeExpired=*/ true
+    )
+    if (token) {
+      if (!this.isTokenExpired(token.expiry)) {
+        return true
+      } else {
+        if (!seekPermission) {
+          throw new Error(`Certificate permission expired (seekPermission=false).`)
+        }
+        return await this.requestPermissionFlow({
+          type: 'certificate',
+          originator,
+          privileged,
+          certificate: { verifier, certType, fields },
+          reason,
+          renewal: true,
+          previousToken: token
+        })
+      }
+    } else {
+      if (!seekPermission) {
+        throw new Error(`No certificate permission found (seekPermission=false).`)
+      }
+      return await this.requestPermissionFlow({
+        type: 'certificate',
+        originator,
+        privileged,
+        certificate: { verifier, certType, fields },
+        reason,
+        renewal: false
+      })
+    }
+  }
+
+  /**
+   * Ensures the originator has spending authorization (DSAP) for a certain satoshi amount.
+   * If the existing token limit is insufficient, attempts to renew. If no token, attempts to create one.
+   */
+  public async ensureSpendingAuthorization({
+    originator,
+    satoshis,
+    lineItems,
+    reason,
+    seekPermission = true
+  }: {
+    originator: string
+    satoshis: number
+    lineItems?: Array<{
+      type: 'input' | 'output' | 'fee'
+      description: string
+      satoshis: number
+    }>
+    reason?: string
+    seekPermission?: boolean
+  }): Promise<boolean> {
+    if (this.isAdminOriginator(originator)) return true
+    if (!this.config.seekSpendingPermissions) {
+      // We skip spending permission entirely
+      return true
+    }
+    const token = await this.findSpendingToken(originator)
+    if (token?.authorizedAmount) {
+      // Check how much has been spent so far
+      const spentSoFar = await this.querySpentSince(token)
+      if (spentSoFar + satoshis <= token.authorizedAmount) {
+        return true
+      } else {
+        // Renew if possible
+        if (!seekPermission) {
+          throw new Error(
+            `Spending authorization insufficient for ${satoshis}, no user consent (seekPermission=false).`
+          )
+        }
+        return await this.requestPermissionFlow({
+          type: 'spending',
+          originator,
+          spending: { satoshis, lineItems },
+          reason,
+          renewal: true,
+          previousToken: token
+        })
+      }
+    } else {
+      // no token
+      if (!seekPermission) {
+        throw new Error(`No spending authorization found, (seekPermission=false).`)
+      }
+      return await this.requestPermissionFlow({
+        type: 'spending',
+        originator,
+        spending: { satoshis, lineItems },
+        reason,
+        renewal: false
+      })
+    }
+  }
+
+  /**
+   * Ensures the originator has label usage permission.
+   * If no valid (unexpired) permission token is found, triggers a permission request flow.
+   */
+  public async ensureLabelAccess({
+    originator,
+    label,
+    reason,
+    seekPermission = true,
+    usageType
+  }: {
+    originator: string
+    label: string
+    reason?: string
+    seekPermission?: boolean
+    usageType: 'apply' | 'list'
+  }): Promise<boolean> {
+    // 1) adminOriginator can do anything
+    if (this.isAdminOriginator(originator)) return true
+
+    // 2) If label is admin-reserved, block
+    if (this.isAdminLabel(label)) {
+      throw new Error(`Label “${label}” is admin-only.`)
+    }
+
+    if (usageType === 'apply' && !this.config.seekPermissionWhenApplyingActionLabels) {
+      return true
+    }
+    if (usageType === 'list' && !this.config.seekPermissionWhenListingActionsByLabel) {
+      return true
+    }
+
+    // 3) Let ensureProtocolPermission handle the rest.
+    return await this.ensureProtocolPermission({
+      originator,
+      privileged: false,
+      protocolID: [1, `action label ${label}`],
+      counterparty: 'self',
+      reason,
+      seekPermission,
+      usageType: 'generic'
+    })
+  }
+
+  /**
+   * A central method that triggers the permission request flow.
+   * - It checks if there's already an active request for the same key
+   * - If so, we wait on that existing request rather than creating a duplicative one
+   * - Otherwise we create a new request queue, call the relevant "onXXXRequested" event,
+   *   and return a promise that resolves once permission is granted or rejects if denied.
+   */
+  private async requestPermissionFlow(r: PermissionRequest): Promise<boolean> {
+    const key = this.buildRequestKey(r)
+
+    // If there's already a queue for the same resource, we piggyback on it
+    const existingQueue = this.activeRequests.get(key)
+    if (existingQueue && existingQueue.pending.length > 0) {
+      return new Promise<boolean>((resolve, reject) => {
+        existingQueue.pending.push({ resolve, reject })
+      })
+    }
+
+    // Otherwise, create a new queue with a single entry
+    // Return a promise that resolves or rejects once the user grants/denies
+    return new Promise<boolean>(async (resolve, reject) => {
+      this.activeRequests.set(key, {
+        request: r,
+        pending: [{ resolve, reject }]
+      })
+
+      // Fire the relevant onXXXRequested event (which one depends on r.type)
+      switch (r.type) {
+        case 'protocol':
+          await this.callEvent('onProtocolPermissionRequested', {
+            ...r,
+            requestID: key
+          })
+          break
+        case 'basket':
+          await this.callEvent('onBasketAccessRequested', {
+            ...r,
+            requestID: key
+          })
+          break
+        case 'certificate':
+          await this.callEvent('onCertificateAccessRequested', {
+            ...r,
+            requestID: key
+          })
+          break
+        case 'spending':
+          await this.callEvent('onSpendingAuthorizationRequested', {
+            ...r,
+            requestID: key
+          })
+          break
+      }
+    })
+  }
+
+  /* ---------------------------------------------------------------------
+   *  4) SEARCH / DECODE / DECRYPT ON-CHAIN TOKENS (PushDrop Scripts)
+   * --------------------------------------------------------------------- */
+
+  /**
+   * We will use a administrative "permission token encryption" protocol to store fields
+   * in each permission's PushDrop script. This ensures that only the user's wallet
+   * can decrypt them. In practice, this data is not super sensitive, but we still
+   * follow the principle of least exposure.
+   */
+  private static readonly PERM_TOKEN_ENCRYPTION_PROTOCOL: [2, 'admin permission token encryption'] = [
+    2,
+    'admin permission token encryption'
+  ]
+
+  /**
+   * Similarly, we will use a "metadata encryption" protocol to preserve the confidentiality
+   * of transaction descriptions and input/output descriptions from lower storage layers.
+   */
+  private static readonly METADATA_ENCRYPTION_PROTOCOL: [2, 'admin metadata encryption'] = [
+    2,
+    'admin metadata encryption'
+  ]
+
+  /** We always use `keyID="1"` and `counterparty="self"` for these encryption ops. */
+  private async encryptPermissionTokenField(plaintext: string | number[]): Promise<number[]> {
+    const data = typeof plaintext === 'string' ? Utils.toArray(plaintext, 'utf8') : plaintext
+    const { ciphertext } = await this.underlying.encrypt(
+      {
+        plaintext: data,
+        protocolID: WalletPermissionsManager.PERM_TOKEN_ENCRYPTION_PROTOCOL,
+        keyID: '1'
+      },
+      this.adminOriginator
+    )
+    return ciphertext
+  }
+
+  private async decryptPermissionTokenField(ciphertext: number[]): Promise<number[]> {
+    const { plaintext } = await this.underlying.decrypt(
+      {
+        ciphertext,
+        protocolID: WalletPermissionsManager.PERM_TOKEN_ENCRYPTION_PROTOCOL,
+        keyID: '1'
+      },
+      this.adminOriginator
+    )
+    return plaintext
+  }
+
+  /**
+   * Encrypts wallet metadata if configured to do so, otherwise returns the original plaintext for storage.
+   * @param plaintext The metadata to encrypt if configured to do so
+   * @returns The encrypted metadata, or the original value if encryption was disabled.
+   */
+  private async maybeEncryptMetadata(plaintext: string): Promise<string> {
+    if (!this.config.encryptWalletMetadata) {
+      return plaintext
+    }
+    const { ciphertext } = await this.underlying.encrypt(
+      {
+        plaintext: Utils.toArray(plaintext, 'utf8'),
+        protocolID: WalletPermissionsManager.METADATA_ENCRYPTION_PROTOCOL,
+        keyID: '1'
+      },
+      this.adminOriginator
+    )
+    return Utils.toUTF8(ciphertext) // Still a string, but scrambled.
+  }
+
+  /**
+   * Attempts to decrypt metadata. if decryption fails, assumes the value is already plaintext and returns it.
+   * @param ciphertext The metadata to attempt decryption for.
+   * @returns The decrypted metadata. If decryption fails, returns the original value instead.
+   */
+  private async maybeDecryptMetadata(ciphertext: string): Promise<string> {
+    try {
+      const { plaintext } = await this.underlying.decrypt(
+        {
+          ciphertext: Utils.toArray(ciphertext, 'utf8'),
+          protocolID: WalletPermissionsManager.METADATA_ENCRYPTION_PROTOCOL,
+          keyID: '1'
+        },
+        this.adminOriginator
+      )
+      return Utils.toUTF8(plaintext)
+    } catch (e) {
+      return ciphertext
+    }
+  }
+
+  /** Helper to see if a token's expiry is in the past. */
+  private isTokenExpired(expiry: number): boolean {
+    const now = Math.floor(Date.now() / 1000)
+    return expiry > 0 && expiry < now
+  }
+
+  /** Looks for a DPACP permission token matching origin/domain, privileged, protocol, cpty. */
+  private async findProtocolToken(
+    originator: string,
+    privileged: boolean,
+    protocolID: [0 | 1 | 2, string],
+    counterparty: string,
+    includeExpired: boolean
+  ): Promise<PermissionToken | undefined> {
+    const [secLevel, protoName] = protocolID
+    const result = await this.underlying.listOutputs(
+      {
+        basket: BASKET_MAP.protocol,
+        tags: [
+          `originator ${originator}`,
+          `privileged ${privileged}`,
+          `protocolName ${protoName}`,
+          `protocolSecurityLevel ${secLevel}`,
+          `counterparty ${counterparty}`
+        ],
+        tagQueryMode: 'all',
+        include: 'locking scripts'
+      },
+      this.adminOriginator
+    )
+
+    for (const out of result.outputs) {
+      const script = LockingScript.fromHex(out.lockingScript!)
+      const dec = PushDrop.decode(script)
+      if (!dec || !dec.fields || dec.fields.length < 6) continue
+      const domainRaw = dec.fields[0]
+      const expiryRaw = dec.fields[1]
+      const privRaw = dec.fields[2]
+      const secLevelRaw = dec.fields[3]
+      const protoNameRaw = dec.fields[4]
+      const counterpartyRaw = dec.fields[5]
+
+      const domainDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw))
+      const expiryDecoded = parseInt(Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10)
+      const privDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(privRaw)) === 'true'
+      const secLevelDecoded = parseInt(Utils.toUTF8(await this.decryptPermissionTokenField(secLevelRaw)), 10) as
+        | 0
+        | 1
+        | 2
+      const protoNameDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(protoNameRaw))
+      const cptyDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(counterpartyRaw))
+
+      if (
+        domainDecoded !== originator ||
+        privDecoded !== privileged ||
+        secLevelDecoded !== secLevel ||
+        protoNameDecoded !== protoName ||
+        cptyDecoded !== counterparty
+      ) {
+        continue
+      }
+      if (!includeExpired && this.isTokenExpired(expiryDecoded)) {
+        continue
+      }
+      return {
+        txid: out.outpoint.split('.')[0],
+        outputIndex: parseInt(out.outpoint.split('.')[1], 10),
+        outputScript: out.lockingScript!,
+        satoshis: out.satoshis,
+        originator,
+        privileged,
+        protocol: protoName,
+        securityLevel: secLevel,
+        expiry: expiryDecoded,
+        counterparty: cptyDecoded
+      }
+    }
+    return undefined
+  }
+
+  /** Looks for a DBAP token matching (originator, basket). */
+  private async findBasketToken(
+    originator: string,
+    basket: string,
+    includeExpired: boolean
+  ): Promise<PermissionToken | undefined> {
+    const result = await this.underlying.listOutputs(
+      {
+        basket: BASKET_MAP.basket,
+        tags: [`originator ${originator}`, `basket ${basket}`],
+        tagQueryMode: 'all',
+        include: 'locking scripts'
+      },
+      this.adminOriginator
+    )
+
+    for (const out of result.outputs) {
+      const dec = PushDrop.decode(LockingScript.fromHex(out.lockingScript!))
+      if (!dec?.fields || dec.fields.length < 3) continue
+      const domainRaw = dec.fields[0]
+      const expiryRaw = dec.fields[1]
+      const basketRaw = dec.fields[2]
+
+      const domainDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw))
+      const expiryDecoded = parseInt(Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10)
+      const basketDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(basketRaw))
+      if (domainDecoded !== originator || basketDecoded !== basket) continue
+      if (!includeExpired && this.isTokenExpired(expiryDecoded)) continue
+
+      return {
+        txid: out.outpoint.split('.')[0],
+        outputIndex: parseInt(out.outpoint.split('.')[1], 10),
+        outputScript: out.lockingScript!,
+        satoshis: out.satoshis,
+        originator,
+        basketName: basketDecoded,
+        expiry: expiryDecoded
+      }
+    }
+    return undefined
+  }
+
+  /** Looks for a DCAP token matching (origin, privileged, verifier, certType, fields subset). */
+  private async findCertificateToken(
+    originator: string,
+    privileged: boolean,
+    verifier: string,
+    certType: string,
+    fields: string[],
+    includeExpired: boolean
+  ): Promise<PermissionToken | undefined> {
+    const result = await this.underlying.listOutputs(
+      {
+        basket: BASKET_MAP.certificate,
+        tags: [`originator ${originator}`, `privileged ${privileged}`, `type ${certType}`, `verifier ${verifier}`],
+        tagQueryMode: 'all',
+        include: 'locking scripts'
+      },
+      this.adminOriginator
+    )
+
+    for (const out of result.outputs) {
+      const dec = PushDrop.decode(LockingScript.fromHex(out.lockingScript!))
+      if (!dec?.fields || dec.fields.length < 6) continue
+      const [domainRaw, expiryRaw, privRaw, typeRaw, fieldsRaw, verifierRaw] = dec.fields
+
+      const domainDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw))
+      const expiryDecoded = parseInt(Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10)
+      const privDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(privRaw)) === 'true'
+      const typeDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(typeRaw))
+      const verifierDec = Utils.toUTF8(await this.decryptPermissionTokenField(verifierRaw))
+
+      const fieldsJson = await this.decryptPermissionTokenField(fieldsRaw)
+      const allFields = JSON.parse(Utils.toUTF8(fieldsJson)) as string[]
+
+      if (
+        domainDecoded !== originator ||
+        privDecoded !== privileged ||
+        typeDecoded !== certType ||
+        verifierDec !== verifier
+      ) {
+        continue
+      }
+      // Check if 'fields' is a subset of 'allFields'
+      const setAll = new Set(allFields)
+      if (fields.some(f => !setAll.has(f))) {
+        continue
+      }
+      if (!includeExpired && this.isTokenExpired(expiryDecoded)) {
+        continue
+      }
+      return {
+        txid: out.outpoint.split('.')[0],
+        outputIndex: parseInt(out.outpoint.split('.')[1], 10),
+        outputScript: out.lockingScript!,
+        satoshis: out.satoshis,
+        originator,
+        privileged,
+        verifier: verifierDec,
+        certType: typeDecoded,
+        certFields: allFields,
+        expiry: expiryDecoded
+      }
+    }
+    return undefined
+  }
+
+  /** Looks for a DSAP token matching origin, returning the first one found. */
+  private async findSpendingToken(originator: string): Promise<PermissionToken | undefined> {
+    const result = await this.underlying.listOutputs(
+      {
+        basket: BASKET_MAP.spending,
+        tags: [`originator ${originator}`],
+        tagQueryMode: 'all',
+        include: 'locking scripts'
+      },
+      this.adminOriginator
+    )
+
+    for (const out of result.outputs) {
+      const dec = PushDrop.decode(LockingScript.fromHex(out.lockingScript!))
+      if (!dec?.fields || dec.fields.length < 2) continue
+      const domainRaw = dec.fields[0]
+      const amtRaw = dec.fields[1]
+
+      const domainDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw))
+      if (domainDecoded !== originator) continue
+      const amtDecodedStr = Utils.toUTF8(await this.decryptPermissionTokenField(amtRaw))
+      const authorizedAmount = parseInt(amtDecodedStr, 10)
+
+      return {
+        txid: out.outpoint.split('.')[0],
+        outputIndex: parseInt(out.outpoint.split('.')[1], 10),
+        outputScript: out.lockingScript!,
+        satoshis: out.satoshis,
+        originator,
+        authorizedAmount,
+        expiry: 0 // Not time-limited, monthly authorization
+      }
+    }
+    return undefined
+  }
+
+  /**
+   * Returns the current month and year in UTC as a string in the format "YYYY-MM".
+   *
+   * @returns {string} The current month and year in UTC.
+   */
+  private getCurrentMonthYearUTC(): string {
+    const now = new Date()
+    const year = now.getUTCFullYear()
+    const month = (now.getUTCMonth() + 1).toString().padStart(2, '0') // Ensure 2-digit month
+    return `${year}-${month}`
+  }
+
+  /**
+   * Returns spending for an originator in the current calendar month.
+   */
+  public async querySpentSince(token: PermissionToken): Promise<number> {
+    const { actions } = await this.underlying.listActions(
+      {
+        labels: [`admin originator ${token.originator}`, `admin month ${this.getCurrentMonthYearUTC()}`],
+        labelQueryMode: 'all'
+      },
+      this.adminOriginator
+    )
+    return actions.reduce((a, e) => a + e.satoshis, 0)
+  }
+
+  /* ---------------------------------------------------------------------
+   *  5) CREATE / RENEW / REVOKE PERMISSION TOKENS ON CHAIN
+   * --------------------------------------------------------------------- */
+
+  /**
+   * Creates a brand-new permission token as a single-output PushDrop script in the relevant admin basket.
+   *
+   * The main difference between each type of token is in the "fields" we store in the PushDrop script.
+   *
+   * @param r        The permission request
+   * @param expiry   The expiry epoch time
+   * @param amount   For DSAP, the authorized spending limit
+   */
+  private async createPermissionOnChain(r: PermissionRequest, expiry: number, amount?: number): Promise<void> {
+    const basketName = BASKET_MAP[r.type]
+    if (!basketName) return
+
+    // Build the array of encrypted fields for the PushDrop script
+    const fields: number[][] = await this.buildPushdropFields(r, expiry, amount)
+
+    // Construct the script. We do a simple P2PK check. We ask `PushDrop.lock(...)`
+    // to create a script with a single OP_CHECKSIG verifying ownership to redeem.
+    const script = await new PushDrop(this.underlying).lock(
+      fields,
+      WalletPermissionsManager.PERM_TOKEN_ENCRYPTION_PROTOCOL,
+      '1',
+      'self',
+      true,
+      true
+    )
+
+    // Create tags
+    const tags = this.buildTagsForRequest(r)
+
+    // Build a transaction with exactly one output, no explicit inputs since the wallet
+    // can internally fund it from its balance.
+    await this.createAction(
+      {
+        description: `Grant ${r.type} permission`,
+        outputs: [
+          {
+            lockingScript: script.toHex(),
+            satoshis: 1,
+            outputDescription: `${r.type} permission token`,
+            basket: basketName,
+            tags
+          }
+        ]
+      },
+      this.adminOriginator
+    )
+  }
+
+  /**
+   * Renews a permission token by spending the old token as input and creating a new token output.
+   * This invalidates the old token and replaces it with a new one.
+   *
+   * @param oldToken The old token to consume
+   * @param r        The permission request being renewed
+   * @param newExpiry The new expiry epoch time
+   * @param newAmount For DSAP, the new authorized amount
+   */
+  private async renewPermissionOnChain(
+    oldToken: PermissionToken,
+    r: PermissionRequest,
+    newExpiry: number,
+    newAmount?: number
+  ): Promise<void> {
+    // 1) build new fields
+    const newFields = await this.buildPushdropFields(r, newExpiry, newAmount)
+
+    // 2) new script
+    const newScript = await new PushDrop(this.underlying).lock(
+      newFields,
+      WalletPermissionsManager.PERM_TOKEN_ENCRYPTION_PROTOCOL,
+      '1',
+      'self',
+      true,
+      true
+    )
+
+    const tags = this.buildTagsForRequest(r)
+
+    // 3) For BRC-100, we do a "createAction" with a partial input referencing oldToken
+    //    plus a single new output. We'll hydrate the template, then signAction for the wallet to finalize.
+    const oldOutpoint = `${oldToken.txid}.${oldToken.outputIndex}`
+    const { signableTransaction } = await this.createAction(
+      {
+        description: `Renew ${r.type} permission`,
+        inputs: [
+          {
+            outpoint: oldOutpoint,
+            unlockingScriptLength: 73, // length of signature
+            inputDescription: `Consume old ${r.type} token`
+          }
+        ],
+        outputs: [
+          {
+            lockingScript: newScript.toHex(),
+            satoshis: 1,
+            outputDescription: `Renewed ${r.type} permission token`,
+            basket: BASKET_MAP[r.type],
+            tags
+          }
+        ]
+      },
+      this.adminOriginator
+    )
+    const tx = Transaction.fromBEEF(signableTransaction!.tx)
+    const unlocker = new PushDrop(this.underlying).unlock(
+      WalletPermissionsManager.PERM_TOKEN_ENCRYPTION_PROTOCOL,
+      '1',
+      'self',
+      'all',
+      false,
+      1,
+      LockingScript.fromHex(oldToken.outputScript)
+    )
+    const unlockingScript = await unlocker.sign(tx, 0)
+    await this.underlying.signAction({
+      reference: signableTransaction!.reference,
+      spends: {
+        0: {
+          unlockingScript: unlockingScript.toHex()
+        }
+      }
+    })
+  }
+
+  /**
+   * Builds the encrypted array of fields for a PushDrop permission token
+   * (protocol / basket / certificate / spending).
+   */
+  private async buildPushdropFields(r: PermissionRequest, expiry: number, amount?: number): Promise<number[][]> {
+    switch (r.type) {
+      case 'protocol': {
+        const [secLevel, protoName] = r.protocolID!
+        return [
+          await this.encryptPermissionTokenField(r.originator), // domain
+          await this.encryptPermissionTokenField(String(expiry)), // expiry
+          await this.encryptPermissionTokenField(r.privileged ? 'true' : 'false'),
+          await this.encryptPermissionTokenField(String(secLevel)),
+          await this.encryptPermissionTokenField(protoName),
+          await this.encryptPermissionTokenField(r.counterparty!)
+        ]
+      }
+      case 'basket': {
+        return [
+          await this.encryptPermissionTokenField(r.originator),
+          await this.encryptPermissionTokenField(String(expiry)),
+          await this.encryptPermissionTokenField(r.basket!)
+        ]
+      }
+      case 'certificate': {
+        const { certType, fields, verifier } = r.certificate!
+        return [
+          await this.encryptPermissionTokenField(r.originator),
+          await this.encryptPermissionTokenField(String(expiry)),
+          await this.encryptPermissionTokenField(r.privileged ? 'true' : 'false'),
+          await this.encryptPermissionTokenField(certType),
+          await this.encryptPermissionTokenField(JSON.stringify(fields)),
+          await this.encryptPermissionTokenField(verifier)
+        ]
+      }
+      case 'spending': {
+        // DSAP
+        const authAmt = amount ?? (r.spending?.satoshis || 0)
+        return [
+          await this.encryptPermissionTokenField(r.originator),
+          await this.encryptPermissionTokenField(String(authAmt))
+        ]
+      }
+    }
+  }
+
+  /**
+   * Helper to build an array of tags for the new output, matching the user request's
+   * origin, basket, privileged, protocol name, etc.
+   */
+  private buildTagsForRequest(r: PermissionRequest): string[] {
+    const tags: string[] = [`originator ${r.originator}`]
+    switch (r.type) {
+      case 'protocol': {
+        tags.push(`privileged ${r.privileged}`)
+        tags.push(`protocolName ${r.protocolID![1]}`)
+        tags.push(`protocolSecurityLevel ${r.protocolID![0]}`)
+        tags.push(`counterparty ${r.counterparty}`)
+        break
+      }
+      case 'basket': {
+        tags.push(`basket ${r.basket}`)
+        break
+      }
+      case 'certificate': {
+        tags.push(`privileged ${r.privileged}`)
+        tags.push(`type ${r.certificate!.certType}`)
+        tags.push(`verifier ${r.certificate!.verifier}`)
+        break
+      }
+      case 'spending': {
+        // Only 'originator' is strictly required as a tag.
+        break
+      }
+    }
+    return tags
+  }
+
+  /* ---------------------------------------------------------------------
+   *  6) PUBLIC "LIST/HAS/REVOKE" METHODS
+   * --------------------------------------------------------------------- */
+
+  /**
+   * Lists all protocol permission tokens (DPACP) for a given originator or for all if originator is undefined.
+   * This is a convenience method for UI or debug.
+   */
+  public async listProtocolPermissions({ originator }: { originator?: string }): Promise<PermissionToken[]> {
+    const basketName = BASKET_MAP.protocol
+    const tags: string[] = originator ? [`originator ${originator}`] : []
+    const result = await this.underlying.listOutputs(
+      {
+        basket: basketName,
+        tags,
+        tagQueryMode: 'all',
+        include: 'locking scripts',
+        limit: 100
+      },
+      this.adminOriginator
+    )
+
+    const tokens: PermissionToken[] = []
+    for (const out of result.outputs) {
+      const dec = PushDrop.decode(LockingScript.fromHex(out.lockingScript!))
+      if (!dec?.fields || dec.fields.length < 6) continue
+      const [domainRaw, expiryRaw, privRaw, secRaw, protoRaw, cptyRaw] = dec.fields
+
+      const domainDec = Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw))
+      const expiryDec = parseInt(Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10)
+      const privDec = Utils.toUTF8(await this.decryptPermissionTokenField(privRaw)) === 'true'
+      const secDec = parseInt(Utils.toUTF8(await this.decryptPermissionTokenField(secRaw)), 10) as 0 | 1 | 2
+      const protoDec = Utils.toUTF8(await this.decryptPermissionTokenField(protoRaw))
+      const cptyDec = Utils.toUTF8(await this.decryptPermissionTokenField(cptyRaw))
+
+      tokens.push({
+        txid: out.outpoint.split('.')[0],
+        outputIndex: parseInt(out.outpoint.split('.')[1], 10),
+        outputScript: out.lockingScript!,
+        satoshis: out.satoshis,
+        originator: domainDec,
+        expiry: expiryDec,
+        privileged: privDec,
+        securityLevel: secDec,
+        protocol: protoDec,
+        counterparty: cptyDec
+      })
+    }
+    return tokens
+  }
+
+  /**
+   * Returns true if the originator already holds a valid unexpired protocol permission.
+   * This calls `ensureProtocolPermission` with `seekPermission=false`, so it won't prompt.
+   */
+  public async hasProtocolPermission(params: {
+    originator: string
+    privileged: boolean
+    protocolID: [0 | 1 | 2, string]
+    counterparty: string
+  }): Promise<boolean> {
+    try {
+      await this.ensureProtocolPermission({
+        ...params,
+        reason: 'hasProtocolPermission',
+        seekPermission: false,
+        usageType: 'generic'
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Lists basket permission tokens (DBAP) for a given originator (or for all if not specified).
+   */
+  public async listBasketAccess(params: { originator?: string }): Promise<PermissionToken[]> {
+    const basketName = BASKET_MAP.basket
+    const tags: string[] = []
+    if (params.originator) {
+      tags.push(`originator ${params.originator}`)
+    }
+    const result = await this.underlying.listOutputs(
+      {
+        basket: basketName,
+        tags,
+        tagQueryMode: 'all',
+        include: 'locking scripts',
+        limit: 10000
+      },
+      this.adminOriginator
+    )
+
+    const tokens: PermissionToken[] = []
+    for (const out of result.outputs) {
+      const dec = PushDrop.decode(LockingScript.fromHex(out.lockingScript!))
+      if (!dec?.fields || dec.fields.length < 3) continue
+      const [domainRaw, expiryRaw, basketRaw] = dec.fields
+      const domainDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw))
+      const expiryDecoded = parseInt(Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10)
+      const basketDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(basketRaw))
+      tokens.push({
+        txid: out.outpoint.split('.')[0],
+        outputIndex: parseInt(out.outpoint.split('.')[1], 10),
+        satoshis: out.satoshis,
+        outputScript: out.lockingScript!,
+        originator: domainDecoded,
+        basketName: basketDecoded,
+        expiry: expiryDecoded
+      })
+    }
+    return tokens
+  }
+
+  /**
+   * Returns `true` if the originator already holds a valid unexpired basket permission for `basket`.
+   */
+  public async hasBasketAccess(params: { originator: string; basket: string }): Promise<boolean> {
+    try {
+      await this.ensureBasketAccess({
+        originator: params.originator,
+        basket: params.basket,
+        seekPermission: false,
+        usageType: 'insertion' // TODO: Consider a generic case for "has"
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Lists spending authorization tokens (DSAP) for a given originator (or all).
+   */
+  public async listSpendingAuthorizations(params: { originator?: string }): Promise<PermissionToken[]> {
+    const basketName = BASKET_MAP.spending
+    const tags: string[] = []
+    if (params.originator) {
+      tags.push(`originator ${params.originator}`)
+    }
+    const result = await this.underlying.listOutputs(
+      {
+        basket: basketName,
+        tags,
+        tagQueryMode: 'all',
+        include: 'locking scripts',
+        limit: 10000
+      },
+      this.adminOriginator
+    )
+
+    const tokens: PermissionToken[] = []
+    for (const out of result.outputs) {
+      const dec = PushDrop.decode(LockingScript.fromHex(out.lockingScript!))
+      if (!dec?.fields || dec.fields.length < 2) continue
+      const [domainRaw, amtRaw] = dec.fields
+      const domainDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw))
+      const amtDecodedStr = Utils.toUTF8(await this.decryptPermissionTokenField(amtRaw))
+      const authorizedAmount = parseInt(amtDecodedStr, 10)
+      tokens.push({
+        txid: out.outpoint.split('.')[0],
+        outputIndex: parseInt(out.outpoint.split('.')[1], 10),
+        satoshis: out.satoshis,
+        outputScript: out.lockingScript!,
+        originator: domainDecoded,
+        authorizedAmount,
+        expiry: 0
+      })
+    }
+    return tokens
+  }
+
+  /**
+   * Returns `true` if the originator already holds a valid spending authorization token
+   * with enough available monthly spend. We do not prompt (seekPermission=false).
+   */
+  public async hasSpendingAuthorization(params: { originator: string; satoshis: number }): Promise<boolean> {
+    try {
+      await this.ensureSpendingAuthorization({
+        originator: params.originator,
+        satoshis: params.satoshis,
+        seekPermission: false
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Lists certificate permission tokens (DCAP) for a given originator (or all).
+   */
+  public async listCertificateAccess(params: { originator?: string }): Promise<PermissionToken[]> {
+    const basketName = BASKET_MAP.certificate
+    const tags: string[] = []
+    if (params.originator) {
+      tags.push(`originator ${params.originator}`)
+    }
+    const result = await this.underlying.listOutputs(
+      {
+        basket: basketName,
+        tags,
+        tagQueryMode: 'all',
+        include: 'locking scripts',
+        limit: 10000
+      },
+      this.adminOriginator
+    )
+
+    const tokens: PermissionToken[] = []
+    for (const out of result.outputs) {
+      const dec = PushDrop.decode(LockingScript.fromHex(out.lockingScript!))
+      if (!dec?.fields || dec.fields.length < 6) continue
+      const [domainRaw, expiryRaw, privRaw, typeRaw, fieldsRaw, verifierRaw] = dec.fields
+      const domainDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw))
+      const expiryDecoded = parseInt(Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10)
+      const privDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(privRaw)) === 'true'
+      const typeDecoded = Utils.toUTF8(await this.decryptPermissionTokenField(typeRaw))
+      const verifierDec = Utils.toUTF8(await this.decryptPermissionTokenField(verifierRaw))
+      const fieldsJson = await this.decryptPermissionTokenField(fieldsRaw)
+      const allFields = JSON.parse(Utils.toUTF8(fieldsJson)) as string[]
+      tokens.push({
+        txid: out.outpoint.split('.')[0],
+        outputIndex: parseInt(out.outpoint.split('.')[1], 10),
+        satoshis: out.satoshis,
+        outputScript: out.lockingScript!,
+        originator: domainDecoded,
+        privileged: privDecoded,
+        certType: typeDecoded,
+        certFields: allFields,
+        verifier: verifierDec,
+        expiry: expiryDecoded
+      })
+    }
+    return tokens
+  }
+
+  /**
+   * Returns `true` if the originator already holds a valid unexpired certificate access
+   * for the given certType/fields. Does not prompt the user.
+   */
+  public async hasCertificateAccess(params: {
+    originator: string
+    privileged: boolean
+    verifier: string
+    certType: string
+    fields: string[]
+  }): Promise<boolean> {
+    try {
+      await this.ensureCertificateAccess({
+        originator: params.originator,
+        privileged: params.privileged,
+        verifier: params.verifier,
+        certType: params.certType,
+        fields: params.fields,
+        seekPermission: false,
+        usageType: 'disclosure'
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Revokes a permission token by spending it with no replacement output.
+   * The manager builds a BRC-100 transaction that consumes the token, effectively invalidating it.
+   */
+  public async revokePermission(oldToken: PermissionToken): Promise<void> {
+    const oldOutpoint = `${oldToken.txid}.${oldToken.outputIndex}`
+    const { signableTransaction } = await this.createAction(
+      {
+        description: `Revoke permission`,
+        inputs: [
+          {
+            outpoint: oldOutpoint,
+            unlockingScriptLength: 73, // length of signature
+            inputDescription: `Consume old permission token`
+          }
+        ]
+      },
+      this.adminOriginator
+    )
+    const tx = Transaction.fromBEEF(signableTransaction!.tx)
+    const unlocker = new PushDrop(this.underlying).unlock(
+      WalletPermissionsManager.PERM_TOKEN_ENCRYPTION_PROTOCOL,
+      '1',
+      'self',
+      'all',
+      false,
+      1,
+      LockingScript.fromHex(oldToken.outputScript)
+    )
+    const unlockingScript = await unlocker.sign(tx, 0)
+    await this.underlying.signAction({
+      reference: signableTransaction!.reference,
+      spends: {
+        0: {
+          unlockingScript: unlockingScript.toHex()
+        }
+      }
+    })
+  }
+
+  /* ---------------------------------------------------------------------
+   *  7) BRC-100 WALLET INTERFACE FORWARDING WITH PERMISSION CHECKS
+   * --------------------------------------------------------------------- */
+
+  public async createAction(
+    args: Parameters<WalletInterface['createAction']>[0],
+    originator?: string
+  ): ReturnType<WalletInterface['createAction']> {
+    // 1) Ensure basket and label permissions
+    if (args.outputs) {
+      for (const out of args.outputs) {
+        if (out.basket) {
+          await this.ensureBasketAccess({
+            originator: originator!,
+            basket: out.basket,
+            reason: args.description,
+            usageType: 'insertion'
+          })
+        }
+      }
+    }
+    if (args.labels) {
+      for (const lbl of args.labels) {
+        await this.ensureLabelAccess({
+          originator: originator!,
+          label: lbl,
+          reason: args.description,
+          usageType: 'apply'
+        })
+      }
+    }
+
+    /**
+     * 2) Force signAndProcess=false unless the originator is admin and explicitly sets it to true.
+     *    This ensures the underlying wallet returns a signableTransaction, letting us parse the transaction
+     *    to determine net spending and request authorization if needed.
+     */
+    const modifiedOptions = { ...(args.options || {}) }
+    if (modifiedOptions.signAndProcess !== true) {
+      modifiedOptions.signAndProcess = false
+    } else if (!this.isAdminOriginator(originator!)) {
+      throw new Error('Only the admin originator can set signAndProcess=true explicitly.')
+    }
+
+    // 3) Encrypt transaction metadata, saving originals for use in permissions and line items.
+    const originalDescription = args.description
+    const originalInputDescriptions = {}
+    const originalOutputDescriptions = {}
+    args.description = await this.maybeEncryptMetadata(args.description)
+    for (let i = 0; i < (args.inputs || []).length; i++) {
+      if (args.inputs![i].inputDescription) {
+        originalInputDescriptions[i] = args.inputs![i].inputDescription
+        args.inputs![i].inputDescription = await this.maybeEncryptMetadata(args.inputs![i].inputDescription)
+      }
+    }
+    for (let i = 0; i < (args.outputs || []).length; i++) {
+      if (args.outputs![i].outputDescription) {
+        originalOutputDescriptions[i] = args.outputs![i].outputDescription
+        args.outputs![i].outputDescription = await this.maybeEncryptMetadata(args.outputs![i].outputDescription)
+      }
+      if (args.outputs![i].customInstructions) {
+        args.outputs![i].customInstructions = await this.maybeEncryptMetadata(args.outputs![i].customInstructions!)
+      }
+    }
+
+    /**
+     * 4) Call the underlying wallet’s createAction. We add two “admin” labels:
+     *    - "admin originator <domain>"
+     *    - "admin month YYYY-MM"
+     *    These labels help track the originator’s monthly spending.
+     */
+    const createResult = await this.underlying.createAction(
+      {
+        ...args,
+        options: modifiedOptions,
+        labels: [
+          ...(args.labels || []),
+          `admin originator ${originator}`,
+          `admin month ${this.getCurrentMonthYearUTC()}`
+        ]
+      },
+      originator
+    )
+
+    // If there's no signableTransaction, the underlying wallet must have fully finalized it. Return as is.
+    if (!createResult.signableTransaction) {
+      return createResult
+    }
+
+    /**
+     * 5) We have a signable transaction. Parse it to determine how much the originator is actually spending.
+     *    We only consider inputs the originator explicitly listed in args.inputs.
+     *    netSpent = (sum of originator-requested outputs) - (sum of matching originator inputs).
+     *    If netSpent > 0, we need spending authorization.
+     */
+    const tx = Transaction.fromAtomicBEEF(createResult.signableTransaction.tx)
+    const reference = createResult.signableTransaction.reference
+
+    let netSpent = 0
+    const lineItems: Array<{
+      type: 'input' | 'output' | 'fee'
+      description: string
+      satoshis: number
+    }> = []
+
+    // Sum originator-provided inputs:
+    let totalInputSatoshis = 0
+    for (const input of tx.inputs) {
+      const outpoint = `${input.sourceTXID}.${input.sourceOutputIndex}`
+      const matchingIndex = (args.inputs || []).findIndex(i => i.outpoint === outpoint)
+      if (matchingIndex !== -1) {
+        const satoshis = input.sourceTransaction!.outputs[input.sourceOutputIndex].satoshis
+        totalInputSatoshis += satoshis!
+        lineItems.push({
+          type: 'input',
+          description: originalInputDescriptions[matchingIndex] || 'No input description provided',
+          satoshis: satoshis!
+        })
+      }
+    }
+
+    // Sum originator-requested outputs:
+    const totalOutputSatoshis = (args.outputs || []).reduce((acc, out) => acc + out.satoshis, 0)
+    for (const outIndex in args.outputs || []) {
+      const out = args.outputs![outIndex]
+      lineItems.push({
+        type: 'output',
+        satoshis: out.satoshis,
+        description: originalOutputDescriptions[outIndex] || 'No output description provided'
+      })
+    }
+
+    // Add an entry for the transaction fee:
+    lineItems.push({
+      type: 'fee',
+      satoshis: tx.getFee(),
+      description: 'Network fee'
+    })
+
+    /**
+     * When it comes to spending authorizations, and the computation of net spend, there are
+     * two types of inputs and two types of outputs:
+     *
+     * There are foreign (originator-requested) ones, and domestic (internally-provided) ones.
+     * The net spend is always calculated from the domestic, internal perspective. Therefore, the
+     * cost of funding the foreign outputs is the base cost to the domestic user, unless this is
+     * somehow offset.
+     *
+     * The only way to offset this cost is when the foreign inputs help carry some of the burden.
+     * This is why we can subtract the sum of the foreign inputs from the sum of foreign outputs,
+     * to gague how much of that cost needs to be born domestically by the user.
+     *
+     * The logic does not need to account for whatever domestic inputs are provided, or whatever
+     * domestic outputs are re-captured by the wallet back as change. The wallet could conceivably
+     * provide 21e8 satoshis as input and re-capture the same amount as change, but the net effect
+     * on actual spending would be zero. Therefore, we base net spend on total foreign outflows
+     * minus total foreign inflows. Fees are also considered.
+     */
+    netSpent = totalOutputSatoshis + tx.getFee() - totalInputSatoshis
+
+    // 6) If netSpent > 0, require spending authorization. Abort if denied.
+    if (netSpent > 0) {
+      try {
+        await this.ensureSpendingAuthorization({
+          originator: originator!,
+          satoshis: netSpent,
+          lineItems,
+          reason: originalDescription
+        })
+      } catch (err) {
+        await this.underlying.abortAction({ reference })
+        throw err
+      }
+    }
+
+    /**
+     * 7) Decide whether to finalize the transaction automatically or return the signableTransaction:
+     *    - If the user originally wanted signAndProcess (the default when undefined), we forcibly set it to false earlier, so check if we should now finalize it.
+     *    - If the transaction still needs more signatures, we must return the signableTransaction.
+     */
+    const vargs = validateCreateActionArgs(args)
+    if (vargs.isSignAction) {
+      return createResult
+    }
+
+    const signResult = await this.underlying.signAction({ reference, spends: {}, options: args.options }, originator)
+    // Merge signResult into createResult and remove signableTransaction:
+    return {
+      ...createResult,
+      ...signResult,
+      signableTransaction: undefined
+    }
+
+    // const userWantedImmediate = args.options?.signAndProcess !== false
+    // const weOverrode =
+    //   modifiedOptions.signAndProcess === false &&
+    //   args.options?.signAndProcess !== false
+
+    // // Check if all inputs already have valid unlockingScripts (no partial signatures needed)
+    const allInputsHaveScripts = tx.inputs.every(i => i.unlockingScript)
+
+    // // If user wanted immediate broadcast and we forcibly suppressed it, we can finalize now by calling signAction with no additional scripts:
+    // if (allInputsHaveScripts && userWantedImmediate && weOverrode) {
+
+    // }
+
+    // // Otherwise, return the partial transaction so the caller can do signAction.
+    // return createResult
+  }
+
+  public async signAction(
+    ...args: Parameters<WalletInterface['signAction']>
+  ): ReturnType<WalletInterface['signAction']> {
+    return this.underlying.signAction(...args)
+  }
+
+  public async abortAction(
+    ...args: Parameters<WalletInterface['abortAction']>
+  ): ReturnType<WalletInterface['abortAction']> {
+    return this.underlying.abortAction(...args)
+  }
+
+  public async listActions(
+    ...args: Parameters<WalletInterface['listActions']>
+  ): ReturnType<WalletInterface['listActions']> {
+    const [requestArgs, originator] = args
+    // for each label, ensure label access
+    if (requestArgs.labels) {
+      for (const lbl of requestArgs.labels) {
+        await this.ensureLabelAccess({
+          originator: originator!,
+          label: lbl,
+          reason: 'listActions',
+          usageType: 'list'
+        })
+      }
+    }
+    const results = await this.underlying.listActions(...args)
+    // Transparently decrypt transaction metadata, if configured to do so.
+    if (results.actions) {
+      for (let i = 0; i < results.actions.length; i++) {
+        if (results.actions[i].description) {
+          results.actions[i].description = await this.maybeDecryptMetadata(results.actions[i].description)
+        }
+        if (results.actions[i].inputs) {
+          for (let j = 0; j < results.actions[i].inputs!.length; j++) {
+            if (results.actions[i].inputs![j].inputDescription) {
+              results.actions[i].inputs![j].inputDescription = await this.maybeDecryptMetadata(
+                results.actions[i].inputs![j].inputDescription
+              )
+            }
+          }
+        }
+        if (results.actions[i].outputs) {
+          for (let j = 0; j < results.actions[i].outputs!.length; j++) {
+            if (results.actions[i].outputs![j].outputDescription) {
+              results.actions[i].outputs![j].outputDescription = await this.maybeDecryptMetadata(
+                results.actions[i].outputs![j].outputDescription
+              )
+            }
+            if (results.actions[i].outputs![j].customInstructions) {
+              results.actions[i].outputs![j].customInstructions = await this.maybeDecryptMetadata(
+                results.actions[i].outputs![j].customInstructions!
+              )
+            }
+          }
+        }
+      }
+    }
+    return results
+  }
+
+  public async internalizeAction(
+    ...args: Parameters<WalletInterface['internalizeAction']>
+  ): ReturnType<WalletInterface['internalizeAction']> {
+    const [requestArgs, originator] = args
+    // If the transaction is inserting outputs into baskets, we also ensure basket permission
+    for (const outIndex in requestArgs.outputs) {
+      const out = requestArgs.outputs[outIndex]
+      if (out.protocol === 'basket insertion') {
+        await this.ensureBasketAccess({
+          originator: originator!,
+          basket: out.insertionRemittance!.basket,
+          reason: requestArgs.description,
+          usageType: 'insertion'
+        })
+        if (out.insertionRemittance!.customInstructions) {
+          requestArgs.outputs[outIndex].insertionRemittance!.customInstructions = await this.maybeEncryptMetadata(
+            out.insertionRemittance!.customInstructions
+          )
+        }
+      }
+    }
+    return this.underlying.internalizeAction(...args)
+  }
+
+  public async listOutputs(
+    ...args: Parameters<WalletInterface['listOutputs']>
+  ): ReturnType<WalletInterface['listOutputs']> {
+    const [requestArgs, originator] = args
+    // Ensure the originator has permission for the basket.
+    await this.ensureBasketAccess({
+      originator: originator!,
+      basket: requestArgs.basket,
+      reason: 'listOutputs',
+      usageType: 'listing'
+    })
+    const results = await this.underlying.listOutputs(...args)
+    // Transparently decrypt transaction metadata, if configured to do so.
+    if (results.outputs) {
+      for (let i = 0; i < results.outputs.length; i++) {
+        if (results.outputs[i].customInstructions) {
+          results.outputs[i].customInstructions = await this.maybeDecryptMetadata(
+            results.outputs[i].customInstructions!
+          )
+        }
+      }
+    }
+    return results
+  }
+
+  public async relinquishOutput(
+    ...args: Parameters<WalletInterface['relinquishOutput']>
+  ): ReturnType<WalletInterface['relinquishOutput']> {
+    const [requestArgs, originator] = args
+    await this.ensureBasketAccess({
+      originator: originator!,
+      basket: requestArgs.basket,
+      reason: 'relinquishOutput',
+      usageType: 'removal'
+    })
+    return this.underlying.relinquishOutput(...args)
+  }
+
+  public async getPublicKey(
+    ...args: Parameters<WalletInterface['getPublicKey']>
+  ): ReturnType<WalletInterface['getPublicKey']> {
+    const [requestArgs, originator] = args
+    if (requestArgs.protocolID) {
+      await this.ensureProtocolPermission({
+        originator: originator!,
+        privileged: requestArgs.privileged!,
+        protocolID: requestArgs.protocolID,
+        counterparty: requestArgs.counterparty || 'self',
+        reason: requestArgs.privilegedReason,
+        usageType: 'publicKey'
+      })
+    }
+    if (requestArgs.identityKey) {
+      // We also require a minimal protocol permission to retrieve the user's identity key
+      await this.ensureProtocolPermission({
+        originator: originator!,
+        privileged: requestArgs.privileged!,
+        protocolID: [1, 'identity key retrieval'],
+        counterparty: 'self',
+        reason: requestArgs.privilegedReason,
+        usageType: 'identityKey'
+      })
+    }
+    return this.underlying.getPublicKey(...args)
+  }
+
+  public async revealCounterpartyKeyLinkage(
+    ...args: Parameters<WalletInterface['revealCounterpartyKeyLinkage']>
+  ): ReturnType<WalletInterface['revealCounterpartyKeyLinkage']> {
+    const [requestArgs, originator] = args
+    await this.ensureProtocolPermission({
+      originator: originator!,
+      privileged: requestArgs.privileged!,
+      protocolID: [2, `counterparty key linkage revelation ${requestArgs.counterparty}`],
+      counterparty: requestArgs.verifier,
+      reason: requestArgs.privilegedReason,
+      usageType: 'linkageRevelation'
+    })
+    return this.underlying.revealCounterpartyKeyLinkage(...args)
+  }
+
+  public async revealSpecificKeyLinkage(
+    ...args: Parameters<WalletInterface['revealSpecificKeyLinkage']>
+  ): ReturnType<WalletInterface['revealSpecificKeyLinkage']> {
+    const [requestArgs, originator] = args
+    await this.ensureProtocolPermission({
+      originator: originator!,
+      privileged: requestArgs.privileged!,
+      protocolID: [
+        2,
+        `specific key linkage revelation ${requestArgs.protocolID[1]} ${requestArgs.protocolID[0] === 2 ? requestArgs.keyID : 'all'}`
+      ],
+      counterparty: requestArgs.verifier,
+      reason: requestArgs.privilegedReason,
+      usageType: 'linkageRevelation'
+    })
+    return this.underlying.revealSpecificKeyLinkage(...args)
+  }
+
+  public async encrypt(...args: Parameters<WalletInterface['encrypt']>): ReturnType<WalletInterface['encrypt']> {
+    const [requestArgs, originator] = args
+    await this.ensureProtocolPermission({
+      originator: originator!,
+      protocolID: requestArgs.protocolID,
+      privileged: requestArgs.privileged!,
+      counterparty: requestArgs.counterparty || 'self',
+      reason: requestArgs.privilegedReason,
+      usageType: 'encrypting'
+    })
+    return this.underlying.encrypt(...args)
+  }
+
+  public async decrypt(...args: Parameters<WalletInterface['decrypt']>): ReturnType<WalletInterface['decrypt']> {
+    const [requestArgs, originator] = args
+    await this.ensureProtocolPermission({
+      originator: originator!,
+      privileged: requestArgs.privileged!,
+      protocolID: requestArgs.protocolID,
+      counterparty: requestArgs.counterparty || 'self',
+      reason: requestArgs.privilegedReason,
+      usageType: 'encrypting'
+    })
+    return this.underlying.decrypt(...args)
+  }
+
+  public async createHmac(
+    ...args: Parameters<WalletInterface['createHmac']>
+  ): ReturnType<WalletInterface['createHmac']> {
+    const [requestArgs, originator] = args
+    await this.ensureProtocolPermission({
+      originator: originator!,
+      privileged: requestArgs.privileged!,
+      protocolID: requestArgs.protocolID,
+      counterparty: requestArgs.counterparty || 'self',
+      reason: requestArgs.privilegedReason,
+      usageType: 'hmac'
+    })
+    return this.underlying.createHmac(...args)
+  }
+
+  public async verifyHmac(
+    ...args: Parameters<WalletInterface['verifyHmac']>
+  ): ReturnType<WalletInterface['verifyHmac']> {
+    const [requestArgs, originator] = args
+    await this.ensureProtocolPermission({
+      originator: originator!,
+      privileged: requestArgs.privileged!,
+      protocolID: requestArgs.protocolID,
+      counterparty: requestArgs.counterparty || 'self',
+      reason: requestArgs.privilegedReason,
+      usageType: 'hmac'
+    })
+    return this.underlying.verifyHmac(...args)
+  }
+
+  public async createSignature(
+    ...args: Parameters<WalletInterface['createSignature']>
+  ): ReturnType<WalletInterface['createSignature']> {
+    const [requestArgs, originator] = args
+    await this.ensureProtocolPermission({
+      originator: originator!,
+      privileged: requestArgs.privileged!,
+      protocolID: requestArgs.protocolID,
+      counterparty: requestArgs.counterparty || 'self',
+      reason: requestArgs.privilegedReason,
+      usageType: 'signing'
+    })
+    return this.underlying.createSignature(...args)
+  }
+
+  public async verifySignature(
+    ...args: Parameters<WalletInterface['verifySignature']>
+  ): ReturnType<WalletInterface['verifySignature']> {
+    const [requestArgs, originator] = args
+    await this.ensureProtocolPermission({
+      originator: originator!,
+      privileged: requestArgs.privileged!,
+      protocolID: requestArgs.protocolID,
+      counterparty: requestArgs.counterparty || 'self',
+      reason: requestArgs.privilegedReason,
+      usageType: 'signing'
+    })
+    return this.underlying.verifySignature(...args)
+  }
+
+  public async acquireCertificate(
+    ...args: Parameters<WalletInterface['acquireCertificate']>
+  ): ReturnType<WalletInterface['acquireCertificate']> {
+    const [requestArgs, originator] = args
+    if (this.config.seekCertificateAcquisitionPermissions) {
+      await this.ensureProtocolPermission({
+        originator: originator!,
+        privileged: requestArgs.privileged!,
+        protocolID: [1, `certificate acquisition ${requestArgs.type}`],
+        counterparty: 'self',
+        reason: requestArgs.privilegedReason,
+        usageType: 'generic'
+      })
+    }
+    return this.underlying.acquireCertificate(...args)
+  }
+
+  public async listCertificates(
+    ...args: Parameters<WalletInterface['listCertificates']>
+  ): ReturnType<WalletInterface['listCertificates']> {
+    const [requestArgs, originator] = args
+    if (this.config.seekCertificateListingPermissions) {
+      await this.ensureProtocolPermission({
+        originator: originator!,
+        privileged: requestArgs.privileged!,
+        protocolID: [1, `certificate list`],
+        counterparty: 'self',
+        reason: requestArgs.privilegedReason,
+        usageType: 'generic'
+      })
+    }
+    return this.underlying.listCertificates(...args)
+  }
+
+  public async proveCertificate(
+    ...args: Parameters<WalletInterface['proveCertificate']>
+  ): ReturnType<WalletInterface['proveCertificate']> {
+    const [requestArgs, originator] = args
+    await this.ensureCertificateAccess({
+      originator: originator!,
+      privileged: requestArgs.privileged!,
+      verifier: requestArgs.verifier,
+      certType: requestArgs.certificate.type!,
+      fields: requestArgs.fieldsToReveal,
+      reason: 'proveCertificate',
+      usageType: 'disclosure'
+    })
+    return this.underlying.proveCertificate(...args)
+  }
+
+  public async relinquishCertificate(
+    ...args: Parameters<WalletInterface['relinquishCertificate']>
+  ): ReturnType<WalletInterface['relinquishCertificate']> {
+    const [requestArgs, originator] = args
+    if (this.config.seekCertificateRelinquishmentPermissions) {
+      await this.ensureProtocolPermission({
+        originator: originator!,
+        privileged: (requestArgs as any).privileged ? true : false,
+        protocolID: [1, `certificate relinquishment ${requestArgs.type}`],
+        counterparty: 'self',
+        reason: (requestArgs as any).privilegedReason || 'relinquishCertificate',
+        usageType: 'generic'
+      })
+    }
+    return this.underlying.relinquishCertificate(...args)
+  }
+
+  public async discoverByIdentityKey(
+    ...args: Parameters<WalletInterface['discoverByIdentityKey']>
+  ): ReturnType<WalletInterface['discoverByIdentityKey']> {
+    const [_, originator] = args
+    if (this.config.seekPermissionsForIdentityResolution) {
+      await this.ensureProtocolPermission({
+        originator: originator!,
+        privileged: false,
+        protocolID: [1, `identity resolution`],
+        counterparty: 'self',
+        reason: 'discoverByIdentityKey',
+        usageType: 'generic'
+      })
+    }
+    return this.underlying.discoverByIdentityKey(...args)
+  }
+
+  public async discoverByAttributes(
+    ...args: Parameters<WalletInterface['discoverByAttributes']>
+  ): ReturnType<WalletInterface['discoverByAttributes']> {
+    const [_, originator] = args
+    if (this.config.seekPermissionsForIdentityResolution) {
+      await this.ensureProtocolPermission({
+        originator: originator!,
+        privileged: false,
+        protocolID: [1, `identity resolution`],
+        counterparty: 'self',
+        reason: 'discoverByAttributes',
+        usageType: 'generic'
+      })
+    }
+    return this.underlying.discoverByAttributes(...args)
+  }
+
+  public async isAuthenticated(
+    ...args: Parameters<WalletInterface['isAuthenticated']>
+  ): ReturnType<WalletInterface['isAuthenticated']> {
+    return this.underlying.isAuthenticated(...args)
+  }
+
+  public async waitForAuthentication(
+    ...args: Parameters<WalletInterface['waitForAuthentication']>
+  ): ReturnType<WalletInterface['waitForAuthentication']> {
+    return this.underlying.waitForAuthentication(...args)
+  }
+
+  public async getHeight(...args: Parameters<WalletInterface['getHeight']>): ReturnType<WalletInterface['getHeight']> {
+    return this.underlying.getHeight(...args)
+  }
+
+  public async getHeaderForHeight(
+    ...args: Parameters<WalletInterface['getHeaderForHeight']>
+  ): ReturnType<WalletInterface['getHeaderForHeight']> {
+    return this.underlying.getHeaderForHeight(...args)
+  }
+
+  public async getNetwork(
+    ...args: Parameters<WalletInterface['getNetwork']>
+  ): ReturnType<WalletInterface['getNetwork']> {
+    return this.underlying.getNetwork(...args)
+  }
+
+  public async getVersion(
+    ...args: Parameters<WalletInterface['getVersion']>
+  ): ReturnType<WalletInterface['getVersion']> {
+    return this.underlying.getVersion(...args)
+  }
+
+  /* ---------------------------------------------------------------------
+   *  8) INTERNAL HELPER UTILITIES
+   * --------------------------------------------------------------------- */
+
+  /** Returns true if the specified origin is the admin originator. */
+  private isAdminOriginator(originator: string): boolean {
+    return originator === this.adminOriginator
+  }
+
+  /**
+   * Checks if the given protocol is admin-reserved per BRC-100 rules:
+   *
+   *  - Must not start with `admin` (admin-reserved)
+   *  - Must not start with `p ` (allows for future specially permissioned protocols)
+   *
+   * If it violates these rules and the caller is not admin, we consider it "admin-only."
+   */
+  private isAdminProtocol(proto: [0 | 1 | 2, string]): boolean {
+    const protocolName = proto[1]
+    if (protocolName.startsWith('admin') || protocolName.startsWith('p ')) {
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Checks if the given label is admin-reserved per BRC-100 rules:
+   *
+   *  - Must not start with `admin` (admin-reserved)
+   *
+   * If it violates these rules and the caller is not admin, we consider it "admin-only."
+   */
+  private isAdminLabel(label: string): boolean {
+    if (label.startsWith('admin')) {
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Checks if the given basket is admin-reserved per BRC-100 rules:
+   *
+   *  - Must not start with `admin`
+   *  - Must not be `default` (some wallets use this for internal operations)
+   *  - Must not start with `p ` (future specially permissioned baskets)
+   */
+  private isAdminBasket(basket: string): boolean {
+    if (basket === 'default') return true
+    if (basket.startsWith('admin')) return true
+    if (basket.startsWith('p ')) return true
+    return false
+  }
+
+  /**
+   * Builds a "map key" string so that identical requests (e.g. "protocol:domain:true:protoName:counterparty")
+   * do not produce multiple user prompts.
+   */
+  private buildRequestKey(r: PermissionRequest): string {
+    switch (r.type) {
+      case 'protocol':
+        return `proto:${r.originator}:${r.privileged}:${r.protocolID?.join(',')}:${r.counterparty}`
+      case 'basket':
+        return `basket:${r.originator}:${r.basket}`
+      case 'certificate':
+        return `cert:${r.originator}:${r.privileged}:${r.certificate?.verifier}:${r.certificate?.certType}:${r.certificate?.fields.join('|')}`
+      case 'spending':
+        return `spend:${r.originator}`
+    }
+  }
+}