Permissions Broker

---

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:

/key 

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 , 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/proxy/requests/:id/execute to execute and retrieve the upstream response bytes.

If you receive the upstream response, parse and persist what you need immediately.

Do not assume you can execute the same request again.

Important:

Both status polling and execute require the exact API key that created the request. Using a different API key (even for the same user) returns 403.

Sample Code (Create + Await)

Use these snippets to create a broker request, poll status, then execute to retrieve upstream bytes.

JavaScript/TypeScript (Bun/Node)

type CreateRequestResponse = {
  request_id: string;
  status: string;
  approval_expires_at: string;
};
type StatusResponse = {
  request_id: string;
  status: string;
  approval_expires_at?: string;
  error?: string;
  error_code?: string | null;
  error_message?: string | null;
  upstream_http_status?: number | null;
  upstream_content_type?: string | null;
  upstream_bytes?: number | null;
};
async function createBrokerRequest(params: {
  baseUrl: string;
  apiKey: string;
  upstreamUrl: string;
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  headers?: Record;
  body?: unknown;
  consentHint?: string;
  idempotencyKey?: string;
}): Promise {
  const res = await fetch(${params.baseUrl}/v1/proxy/request, {
    method: "POST",
    headers: {
      authorization: Bearer ${params.apiKey},
      "content-type": "application/json",
    },
    body: JSON.stringify({
      upstream_url: params.upstreamUrl,
      method: params.method ?? "GET",
      headers: params.headers,
      body: params.body,
      consent_hint: params.consentHint,
      idempotency_key: params.idempotencyKey,
    }),
  });
  if (!res.ok) {
    throw new Error(broker create failed: ${res.status} ${await res.text()});
  }
  return (await res.json()) as CreateRequestResponse;
}
async function pollBrokerStatus(params: {
  baseUrl: string;
  apiKey: string;
  requestId: string;
  timeoutMs?: number;
}): Promise {
  // Recommended default: wait at least 30s before returning a request_id to the user.
  const deadline = Date.now() + (params.timeoutMs ?? 30_000);
  while (Date.now() < deadline) {
    const res = await fetch(
      ${params.baseUrl}/v1/proxy/requests/${params.requestId},
      {
        headers: { authorization: Bearer ${params.apiKey} },
      },
    );
    // Status endpoint always returns JSON for both 202 and 200.
    const data = (await res.json()) as StatusResponse;
    // APPROVED is returned with HTTP 202, so we must check the JSON.
    if (data.status === "APPROVED") return data;
    if (res.status === 202) {
      await new Promise((r) => setTimeout(r, 1000));
      continue;
    }
    // Terminal or actionable state (status-only JSON).
    if (!res.ok && res.status !== 403 && res.status !== 408) {
      throw new Error(broker status failed: ${res.status} ${JSON.stringify(data)});
    }
    return data;
  }
  throw new Error("timed out waiting for approval");
}
async function awaitApprovalThenExecute(params: {
  baseUrl: string;
  apiKey: string;
  requestId: string;
  timeoutMs?: number;
}): Promise {
  const status = await pollBrokerStatus({
    baseUrl: params.baseUrl,
    apiKey: params.apiKey,
    requestId: params.requestId,
    timeoutMs: params.timeoutMs,
  });
  if (status.status !== "APPROVED") {
    throw new Error(request not approved yet (status=${status.status}));
  }
  return executeBrokerRequest({
    baseUrl: params.baseUrl,
    apiKey: params.apiKey,
    requestId: params.requestId,
  });
}
async function getBrokerStatusOnce(params: {
  baseUrl: string;
  apiKey: string;
  requestId: string;
}): Promise {
  const res = await fetch(${params.baseUrl}/v1/proxy/requests/${params.requestId}, {
    headers: { authorization: Bearer ${params.apiKey} },
  });
  // Always JSON (even for 202).
  return (await res.json()) as StatusResponse;
}
async function executeBrokerRequest(params: {
  baseUrl: string;
  apiKey: string;
  requestId: string;
}): Promise {
  const res = await fetch(
    ${params.baseUrl}/v1/proxy/requests/${params.requestId}/execute,
    {
      method: "POST",
      headers: { authorization: Bearer ${params.apiKey} },
    },
  );
  // Terminal: upstream bytes (2xx/4xx/5xx) or broker error JSON (403/408/409/410/etc).
  // IMPORTANT:
  // - execution is one-time; subsequent calls return 410.
  // - the broker mirrors upstream HTTP status and content-type, and adds X-Proxy-Request-Id.
  // - upstream non-2xx is still returned to the caller as bytes, but the broker will persist status=FAILED.
  return res;
}
// Suggested control flow:
// - Start polling for ~30 seconds.
// - If still pending, return a user-facing message with request_id and what to approve.
// - On the next user message, poll again (or recreate if expired/consumed).
// Example usage
// const baseUrl = "https://permissions-broker.steer.fun"
// const apiKey = process.env.PB_API_KEY!
// const upstreamUrl = "https://www.googleapis.com/drive/v3/files?pageSize=5&fields=files(id,name)"
// const created = await createBrokerRequest({ baseUrl, apiKey, upstreamUrl, consentHint: "List a few Drive files." })
// Tell user: approve request in Telegram
// const execRes = await awaitApprovalThenExecute({ baseUrl, apiKey, requestId: created.request_id, timeoutMs: 30_000 })
// const bodyText = await execRes.text()
// GitHub example (create PR)
// const created = await createBrokerRequest({
//   baseUrl,
//   apiKey,
//   upstreamUrl: "https://api.github.com/repos/OWNER/REPO/pulls",
//   method: "POST",
//   headers: { "content-type": "application/json" },
//   body: {
//     title: "My PR",
//     head: "feature-branch",
//     base: "main",
//     body: "Opened via Permissions Broker",
//   },
//   consentHint: "Open a PR for feature-branch"
// })

Supported Providers (Today)

The broker enforces an allowlist and chooses which linked account (OAuth token) to use based on the upstream hostname.

Currently supported:

Google

- Hosts: docs.googleapis.com, www.googleapis.com, sheets.googleapis.com - Typical uses: Drive listing/search, Docs reads, Sheets range reads

GitHub

- Host: api.github.com - Typical uses: PRs/issues/comments/labels and other GitHub actions

iCloud (CalDAV)

- Hosts: discovered on connect (starts at caldav.icloud.com) - Typical uses: Calendar events (VEVENT) and Reminders/tasks (VTODO)

Spotify

- Host: api.spotify.com - Typical uses: read profile, list playlists/tracks, control playback

If you need a provider that isn't supported yet:

Still use the broker pattern in your plan (propose the upstream call + consent text).

Then tell the user which host(s) need to be enabled/implemented.

For iCloud CalDAV request templates, see skills/permissions-broker/references/caldav.md.

Git Operations (Smart HTTP Proxy)

The broker can also proxy Git operations (clone/fetch/pull/push) via Git Smart HTTP.

This is separate from /v1/proxy.

High-level flow:

1. Create a git session (POST /v1/git/sessions). 2. The user approves/denies the session in Telegram. 3. Poll session status (GET /v1/git/sessions/:id) until approved. 4. Fetch a session-scoped remote URL (GET /v1/git/sessions/:id/remote). 5. Run git clone / git push against that remote URL.

Important behavior:

Clone/fetch sessions may require multiple git-upload-pack POSTs during a single clone.

Push sessions are single-use and may become unusable after the first git-receive-pack.

Push protections are enforced by the broker:

- tag pushes are rejected - ref deletes are rejected - default-branch pushes may be blocked unless explicitly allowed in the approval

Endpoints

Auth for all git session endpoints:

Authorization: Bearer

Create session

POST /v1/git/sessions

JSON body:

- operation: "clone", "fetch", "pull", or "push" - repo: "owner/repo" (GitHub) - optional consent_hint: requester note shown to the user in Telegram. Always include the reason for the session (what you're doing and why).

Response: { "session_id": "...", "status": "PENDING_APPROVAL", "approval_expires_at": "..." }

Poll status

GET /v1/git/sessions/:id (status JSON)

Get remote URL

GET /v1/git/sessions/:id/remote

Response: { "remote_url": "https://..." }

Example: Clone

1. Create session:

{
  "operation": "clone",
  "repo": "OWNER/REPO",
  "consent_hint": "Clone repo to inspect code"
}

Example: Fetch

Use fetch when you already have a repo locally and just need to update refs.

1. Create session:

{
  "operation": "fetch",
  "repo": "OWNER/REPO",
  "consent_hint": "Fetch latest refs to update local checkout"
}

2. Poll until approved.

3. Get remote_url, then:

git fetch "" --prune

Example: Pull

git pull is a fetch plus a local merge/rebase. The broker only proxies the network portion.

git pull "" main

2. Poll until status == "APPROVED".

3. Get remote_url, then:

git clone "" ./repo

Example: Push New Branch (Recommended)

1. Create session:

{
  "operation": "push",
  "repo": "OWNER/REPO",
  "consent_hint": "Push branch feature-x for a PR"
}

2. Poll until approved.

3. Get remote_url, add as a remote, then push to a non-default branch:

git remote add broker ""
git push broker "HEAD:refs/heads/feature-x"

Notes:

Prefer creating a new branch name (e.g. pb//) rather than pushing to main.

If the broker session becomes USED, create a new push session.

Python (requests)

import time
import requests
def create_request(base_url, api_key, upstream_url, consent_hint=None, idempotency_key=None):
  # Optional: method/headers/body for non-GET requests.
  r = requests.post(
    f"{base_url}/v1/proxy/request",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
      "upstream_url": upstream_url,
      # "method": "POST",
      # "headers": {"accept": "application/vnd.github+json"},
      # "headers": {"content-type": "application/json"},
      # "body": {"title": "...", "head": "...", "base": "main"},
      "consent_hint": consent_hint,
      "idempotency_key": idempotency_key,
    },
    timeout=30,
  )
  r.raise_for_status()
  return r.json()
def await_result(base_url, api_key, request_id, timeout_s=120):
  deadline = time.time() + timeout_s
  while time.time() < deadline:
    r = requests.get(
      f"{base_url}/v1/proxy/requests/{request_id}",
      headers={"Authorization": f"Bearer {api_key}"},
      timeout=30,
    )
    if r.status_code == 202:
      time.sleep(1)
      continue
    # Terminal response (status-only JSON).
    return r.json()
  raise TimeoutError("timed out waiting for approval")
def execute_request(base_url, api_key, request_id):
  # IMPORTANT: execution is one-time; read and store now.
  return requests.post(
    f"{base_url}/v1/proxy/requests/{request_id}/execute",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=60,
  )
def await_approval_then_execute(base_url, api_key, request_id, timeout_s=30):
  status = await_result(base_url, api_key, request_id, timeout_s=timeout_s)
  if status.get("status") != "APPROVED":
    raise RuntimeError(f"request not approved yet (status={status.get('status')})")
  return execute_request(base_url, api_key, request_id)

Constraints You Must Respect

Upstream scheme: HTTPS only.

Upstream host allowlist: provider-defined (the request must target a supported host).

Upstream methods: GET/POST/PUT/PATCH/DELETE.

Upstream response size cap: 1 MiB.

Upstream request body cap: 256 KiB.

One-time execution: after executing a request, you cannot execute it again.

Sheets Note (Without Drama)

The broker supports the Google Sheets API host (sheets.googleapis.com).

Preferred approach for reading spreadsheet data:

1. Use Drive search/list to find the spreadsheet file. 2. Use Sheets values read to fetch only the range you need.

Fallback:

Use Drive export to fetch contents as CSV when that is sufficient.

Note: large exports can exceed the broker's 1 MiB upstream response cap. If an export fails due to size, narrow the scope (smaller range, fewer tabs, or fewer rows/columns).

Handling Common Terminal States

202: request is still actionable; JSON includes status (often PENDING_APPROVAL, APPROVED, or EXECUTING).

- If status == APPROVED, execute immediately. - Otherwise keep polling.

403: denied by user.

403: forbidden (wrong API key or request not accessible) is also possible; inspect {error: ...}.

408: approval expired (user did not decide in time).

409: already executing; retry shortly.

410: already executed; recreate the request if you still need it.

How To Build Upstream URLs (Google example)

Prefer narrow reads so approvals are understandable and responses are small.

Drive search/list files: https://www.googleapis.com/drive/v3/files?...

- Use q, pageSize, and fields to minimize payload.

Drive export file contents: https://www.googleapis.com/drive/v3/files/{fileId}/export?mimeType=...

- Useful for Google Docs/Sheets export to text/plain or text/csv.

Docs structured doc read: https://docs.googleapis.com/v1/documents/{documentId}?fields=...

See references/api_reference.md for endpoint details and a Google URL cheat sheet.

How To Build Upstream URLs (GitHub examples)

Create PR: POST https://api.github.com/repos///pulls

- JSON body: { "title": "...", "head": "branch", "base": "main", "body": "..." }

Create issue: POST https://api.github.com/repos///issues

- JSON body: { "title": "...", "body": "..." }

Data Handling Rules

Treat the user's API key as secret.

Resources

Reference: references/api_reference.md