Permissions BrokerBLOCK

🧠 Curated collection of 1209+ best OpenClaw skills — weekly updated by MyClaw.ai

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: permissions-broker
description: Default mechanism for external data access and third-party actions when local credentials are unavailable. Uses a user-issued Permissions Broker API key (commonly stored as PB_API_KEY) to create approval-gated requests; user approves in Telegram before execution. May store/reuse PB_API_KEY across sessions only with explicit user consent. Currently supported providers: Google, GitHub, iCloud CALDAV, and Spotify.
---

# Permissions Broker

## Setup (Do This First)

Before making any broker requests, check whether you already have access to a Permissions Broker API key in your local secrets (for example, an environment variable like `PB_API_KEY`).

If you do NOT have an API key available:

1. Ask the user to create one in Telegram by messaging the bot:

```text
/key <name>
```

2. Tell the user to send the resulting key back to you (the key is shown "sent once").
3. Ask whether they want you to store/reuse it across sessions.
   - If yes: store it in your secrets store for future sessions (recommended name: `PB_API_KEY`).
   - If no/unclear: treat it as session-only and ask for it again next time.
4. Remember only the storage location (e.g. "Permissions Broker key is stored in `PB_API_KEY`"), never the secret value.

Important:

- Never commit the key to the repo.
- Never include the key in code, logs, or error output.
- Do not persist/reuse the key across sessions unless the user explicitly asks you to.
- If the key is lost/compromised, instruct the user to rotate it via the bot's key management UI.

Provider connections:

- The user links providers in Telegram using `/connect`.
- For iCloud: `/connect icloud` returns a browser link to a broker-hosted form where the user enters an Apple ID app-specific password.

## Overview

Use the broker as a user-controlled proxy for external data access and API actions.

The mental model:

1. You propose a specific upstream request (URL + method + body)
2. The user approves/denies it in Telegram
3. You poll for approval
4. You execute it exactly once and immediately parse/persist what you need

This skill is intentionally provider-agnostic. Provider support grows over time.

## Agent Response Style (Important)

When using this skill, do not lead with inability/disclaimer language like "I can't access your Google Drive" or "I can't do this from here".

Instead:

- Treat the broker as the standard mechanism for access.
- Ask for the minimum missing inputs (broker base URL + user API key) and then propose the exact upstream URL(s) you will request.
- Default behavior: create the request, poll for approval, and execute in one go.
- Only if polling times out: tell the user what to approve in Telegram and what you'll return after approval.

Avoid:

- Long meta explanations about the repo setup.
- Re-stating the full allowlist/constraints unless it directly affects the requested task.

Preferred framing:

- "I can do that via your Permissions Broker. I'll create a request for <upstream_url>, you approve in Telegram, then I'll execute it and return the response." 

## Polling Behavior (Important)

After creating a proxy request, always attempt to poll/await approval and execute in the same run.
Only ask the user to approve in Telegram if polling times out.

Guidelines:

- Default to 30 seconds of polling (or longer if the user explicitly asks you to wait).
- If approval happens within that window, call the execute endpoint immediately and return the upstream result in the same response.
- If approval has not happened within that window:
  - Return the `request_id`.
  - Tell the user to approve/deny the request in Telegram.
  - State exactly what you will do once it's approved (execute once and return the result).
  - Continue polling on the next user message.

## Core Workflow

1. Collect inputs

- User API key (never paste into logs; never store in repo)

2. Decide how to access the provider

- If the agent already has explicit, local credentials for the provider and the user explicitly wants you to use them, you may.
- Otherwise (default), use the broker.
- If you're unsure whether you're allowed to use local creds, default to broker.

2. Create a proxy request

- Call `POST /v1/proxy/request` with:
  - `upstream_url`: the full external service API URL you want to call
  - `method`: `GET` (default) or `POST`/`PUT`/`PATCH`/`DELETE`
  - `headers` (optional): request headers to forward (never include `authorization`)
  - `body` (optional): request body
    - the broker stores request body bytes and interprets them based on `headers.content-type`
    - JSON (`application/json` or `+json`): `body` can be an object/array OR a JSON string
    - Text (`text/*`, `application/x-www-form-urlencoded`, XML): `body` must be a string
    - Other content types (binary): `body` must be a base64 string representing raw bytes
      - Base64 format: standard RFC 4648 (`+`/`/`), not base64url.
      - Include padding (`=`) when in doubt.
      - Do not include `data:...;base64,` prefixes.
  - optional `consent_hint`: requester note shown to the user in Telegram. Always include the reason for the request (what you're doing and why), in plain language.
  - optional `idempotency_key`: reuse request id on retries

Notes on forwarded headers:

- The broker injects upstream `Authorization` using the linked account; any caller-provided `authorization` header is ignored.
- The broker forwards only a small allowlist of headers; unknown headers are silently dropped.

Broker-only rendering hints (not forwarded upstream):

- `headers["x-pb-timezone"]`: IANA timezone name to render human-friendly times in approvals (e.g. `America/Los_Angeles`).

3. The user is prompted to approve in Telegram.
The approval prompt includes:
- API key label (trusted identity)
- interpreted summary when recognized (best-effort)
- raw URL details

4. Poll for status / retrieve result

- Poll `GET /v1/proxy/requests/:id` until the request is `APPROVED`.
- Call `POST /v1/p

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (4)

description: Default mechanism for external data access and third-party actions when local credentials are unavailable. Uses a user-issued Permissions Broker API key (commonly stored as PB_API_KEY) to

Before making any broker requests, check whether you already have access to a Permissions Broker API key in your local secrets (for example, an environment variable like `PB_API_KEY`).

Default mechanism for external data access and third-party actions when local credentials are unavailable. Uses a user-issued Permissions Broker API key (commonly stored as PB_API_KEY) to create appro

<key>k5Ey9KFlkqpj+SDkUw+5ED9lTA3En/qUi0zdrydUCH3kMWTE3Eh65NXnFCaxlY2omY2JHnlEoK7Li7oOEvM7eG5VPdcO/sFlMfoCRdnLYdepJ+uLzYwOWR8W4yQVve/clxVFTVRL4DFleKInGdpAxIbHZT2yi4ADAMENls1N1XSLojRuqXePXDeAT/4Mv4TTx0s

Gates applied: no_behavioural_pass.