Metadata-Version: 2.4
Name: multi-user-rbac
Version: 0.1.1
Summary: Hermes plugin implementing multi-user RBAC, preferences, and owner controls.
Author: Ahsan Athallah
License: MIT
Project-URL: Homepage, https://github.com/
Project-URL: Repository, https://github.com/
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"

# Multi-user RBAC for Hermes

This plugin keeps per-platform, per-channel roles and preferences so Hermes can enforce owner/user/guest permissions and personalize responses. It stores all state in `~/.hermes/plugins/multi-user-rbac/data/users.db` and wires hooks/tools/commands following the Hermes plugin guide.

## Installation
1. Copy this directory to `~/.hermes/plugins/multi-user-rbac/`.
2. Optional: install the Python dependencies (Hermes already bundles `sqlite3`, but you need PyYAML for owner configuration):
   ```bash
   pip install pyyaml
   ```
3. Restart Hermes. You should see `multi-user-rbac` in `/plugins` and a new set of tools/commands.

## Configuration
Create `~/.hermes/plugins/multi-user-rbac/config.yaml` to tell the plugin who the owners are:

```yaml
owner:
  telegram:
    - 123456789  # replace with your Telegram ID
  discord:
    - 987654321  # replace with your Discord ID
```

Owner IDs are promoted automatically on first interaction. No config file means everyone starts as `guest`.

## Tools
| Tool | Description | Role access |
| --- | --- | --- |
| `identify_user` | Returns the current session user identity (platform, display name, role). | Everyone |
| `get_user_preference` | Reads a preference (global or channel-scoped) for the caller. | Owner/User |
| `set_user_preference` | Stores a preference for the caller (optional `channel_id`). | Owner/User |
| `set_channel_preference` | Owners set channel-wide defaults. | Owner only |
| `list_channel_users` | Lists channel members and their roles; auto-refreshes membership when users join. | Owner/User |
| `promote_user` / `demote_user` | Owner-only tools to change another member’s role. | Owner only |

## Hooks
- `on_session_start`: identifies who is speaking, auto-promotes owners, records channel membership.
- `pre_llm_call`: injects a short summary of the current user + recent preferences into every turn.
- `post_tool_call`: logs all tool usage, records denied access attempts for auditing.
- `on_session_finalize`: clears per-session context so new sessions start clean.

## Commands
- `/users`: owner-only list of channel members (mirrors `list_channel_users`).
- `/promote <platform_user_id>`: owner-only; promotes the chosen member to `user`.
- `/demote <platform_user_id>`: owner-only; demotes the chosen member to `guest`.
- `/set-for <platform_user_id> <key> <value>`: owner-only; set preferences on behalf of someone else.

## Testing
Run the bundled tests with `pytest tests`. The suite covers storage, permission checks, and the tool handlers so you can safely refactor the RBAC rules.

## Packaging & release
1. Run `./build_release.sh` (or `python3 -m build --outdir dist`) from the plugin root; a wheel and sdist land in `dist/`.
2. Install the release locally with `pip install dist/multi_user_rbac-0.1.0-py3-none-any.whl` or publish `dist/` to PyPI/Nexus.
3. Hermes auto-discovers the plugin when `multi-user-rbac` is installed via an entry point (`[project.entry-points."hermes_agent.plugins"]` in `pyproject.toml`). Restart Hermes after installation.

## Next steps
1. Wire the plugin into your agent by placing it under `~/.hermes/plugins/` and restarting Hermes.
2. Keep `config.yaml` in sync with the owners you trust; the plugin auto-promotes them on first use.
3. Extend tools/commands if you need more automation (e.g., CLI commands or skills).
