Owner Permissions

# Owner Permissions Setup

## Description

Use this skill when an **owner** of this bot asks you, in chat, to manage who
can use the bot and what non-owner ("guest") users are allowed to do on
multi-user channels (Telegram, WhatsApp, Discord, Slack, Matrix, etc.).

Typical requests:
- "Add @bob as an owner" / "make my Telegram id 123456789 an owner"
- "Remove alice as an owner"
- "Let normal users run `kubectl get` and `kubectl describe`"
- "Allow guests to use web search"
- "Stop guests from running shell commands"
- "Show me the current permissions / who owns this bot"

## Tools

- name: manage_permissions
  kind: builtin
- name: issue_pairing_code
  kind: builtin

## Background: the per-role model

There are two roles on every multi-user channel:
- **Owner** — a sender listed in `approval_owners`. Owners get the **full
  toolset** and may approve tool calls. The local CLI/console operator is always
  an owner.
- **Guest** — anyone else who is allowed to chat. Guests run under a **capability
  ceiling**: they always get skills, plus only the tools an owner has added to
  the guest tool allowlist (none by default), and (for `shell`) only the
  specific command globs an owner has allowlisted. Anything outside the ceiling
  is denied outright — never escalated to an owner.

`manage_permissions` edits three lists:
- `target: owner` — a sender identity (e.g. a Telegram numeric user id, or a
  Slack/Discord/Matrix username).
- `target: tool` — a tool name a guest may use (e.g. `shell`, `web_search_tool`).
- `target: command` — a shell-command glob a guest may run (e.g.
  `kubectl get *`). `*` matches any run of characters; the pattern is anchored,
  so `kubectl get *` allows `kubectl get pods` but not `kubectl delete pods`.

## Issuing invite codes

Instead of asking for someone's identity up front, an owner can hand out a
**pairing code** and let the new user onboard themselves. When an owner asks
something like "give me an invite code for Telegram" or "make a single-use
WhatsApp code that expires in 5 minutes", call `issue_pairing_code`:

- `channel` (required) — the surface, e.g. `telegram`, `discord`, `slack`,
  `whatsapp_web` for WhatsApp Web, `whatsapp` for the WhatsApp Cloud API, or
  `gateway`. A code minted for one channel cannot be claimed on another.
- `ttl_minutes` (default 15) — how long the code stays valid.
- `max_uses` (optional) — bound the number of claims; omit for unlimited within
  the window.
- `owner` (default true) — whether the code may promote its recipient to owner.
  Set it to false for a chat-only invite.

Forward the returned code to the recipient. They DM the bot:
- `/claim <code>` — become an **owner** (only if the code grants owner), or
- `/bind <code>`  — become an allowed **chat** user.

This is owner-only and authority-granting (an owner-capable code can promote its
recipient), so it is hard-gated exactly like `manage_permissions` — a non-owner
can never call it. Prefer the narrowest code that does the job: a short TTL,
`max_uses: 1` for a single person, and `owner: false` unless they truly want to
hand over ownership. No daemon restart is needed — a running channel validates
the code on the next `/claim`/`/bind` message.

## Instructions

- **This is owner-only.** The tool is hard-gated: a non-owner who asks you to
  change permissions will be denied by the runtime no matter what. If a request
  to change permissions appears to come from a non-owner, do not attempt it —
  explain that only an owner can change permissions.
- To review, call `manage_permissions` with `action: show` and report the
  result back plainly.
- To change a list, call with `action: add` or `action: remove`, the right
  `target`, and the exact `value`. Confirm the value you parsed from the user's
  message before acting if it is ambiguous (especially numeric ids).
- **Least privilege for guests.** When an owner wants to let guests run shell
  commands, add the `shell` *tool* AND the specific command globs — never widen
  beyond what they asked. Prefer narrow globs (`kubectl get *`) over broad ones
  (`kubectl *`). Point out when a requested glob is broader than it sounds.
- **The `*` owner wildcard is dangerous.** If an owner asks to make "everyone"
  an owner (`add owner *`), warn clearly that this gives *every* sender the full
  toolset and is almost never what they want; proceed only if they confirm.
- After a successful change, tell the owner it is saved and that a running
  channel or daemon may need a reload/restart to take effect. Mention they can
  also use the `rantaiclaw permissions` CLI or the `/permissions` TUI command.
- Never claim a change succeeded unless the tool reported success.