multi-user-rbac 0.1.1__tar.gz

multi_user_rbac-0.1.1/PKG-INFO

@@ -0,0 +1,74 @@
+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).

multi_user_rbac-0.1.1/README.md

@@ -0,0 +1,59 @@
+# 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).

multi_user_rbac-0.1.1/multi_user_rbac/__init__.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import logging
+
+from . import schemas, tools
+
+logger = logging.getLogger(__name__)
+
+
+def register(ctx) -> None:
+    logger.info("Registering multi-user RBAC plugin with Hermes")
+    toolset = "multi-user-rbac"
+    ctx.register_tool(
+        name=schemas.IDENTIFY_USER["name"],
+        toolset=toolset,
+        schema=schemas.IDENTIFY_USER,
+        handler=tools.identify_user,
+    )
+    ctx.register_tool(
+        name=schemas.GET_USER_PREFERENCE["name"],
+        toolset=toolset,
+        schema=schemas.GET_USER_PREFERENCE,
+        handler=tools.get_user_preference,
+    )
+    ctx.register_tool(
+        name=schemas.SET_USER_PREFERENCE["name"],
+        toolset=toolset,
+        schema=schemas.SET_USER_PREFERENCE,
+        handler=tools.set_user_preference,
+    )
+    ctx.register_tool(
+        name=schemas.SET_CHANNEL_PREFERENCE["name"],
+        toolset=toolset,
+        schema=schemas.SET_CHANNEL_PREFERENCE,
+        handler=tools.set_channel_preference,
+    )
+    ctx.register_tool(
+        name=schemas.LIST_CHANNEL_USERS["name"],
+        toolset=toolset,
+        schema=schemas.LIST_CHANNEL_USERS,
+        handler=tools.list_channel_users,
+    )
+    ctx.register_tool(
+        name=schemas.PROMOTE_USER["name"],
+        toolset=toolset,
+        schema=schemas.PROMOTE_USER,
+        handler=tools.promote_user,
+    )
+    ctx.register_tool(
+        name=schemas.DEMOTE_USER["name"],
+        toolset=toolset,
+        schema=schemas.DEMOTE_USER,
+        handler=tools.demote_user,
+    )
+    ctx.register_hook("on_session_start", tools.on_session_start)
+    ctx.register_hook("pre_llm_call", tools.on_pre_llm_call)
+    ctx.register_hook("post_tool_call", tools.on_post_tool_call)
+    ctx.register_hook("on_session_finalize", tools.on_session_finalize)
+    ctx.register_command(
+        "users", handler=tools.cmd_users, description="List channel members and roles"
+    )
+    ctx.register_command("promote", handler=tools.cmd_promote, description="Promote a user")
+    ctx.register_command("demote", handler=tools.cmd_demote, description="Demote a user")
+    ctx.register_command(
+        "set-for", handler=tools.cmd_set_preference_for, description="Owner: set preference for another"
+    )

multi_user_rbac-0.1.1/multi_user_rbac/config.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - optional dependency
+    yaml = None
+
+logger = logging.getLogger(__name__)
+
+CONFIG_DIR = Path.home() / ".hermes" / "plugins" / "multi-user-rbac"
+CONFIG_PATH = CONFIG_DIR / "config.yaml"
+
+
+def load_owner_config() -> dict[str, set[str]]:
+    if not CONFIG_PATH.exists():
+        return {}
+    if yaml is None:
+        logger.warning("PyYAML not installed; owner config disabled")
+        return {}
+    try:
+        data = yaml.safe_load(CONFIG_PATH.read_text()) or {}
+    except Exception as exc:
+        logger.warning("Unable to parse %s: %s", CONFIG_PATH, exc)
+        return {}
+
+    raw_owners = data.get("owner") or {}
+    normalized: dict[str, set[str]] = {}
+    for platform, ids in raw_owners.items():
+        if isinstance(ids, (list, tuple)):
+            normalized[platform.lower()] = {str(i) for i in ids if i is not None}
+        elif isinstance(ids, str):
+            normalized.setdefault(platform.lower(), set()).add(ids)
+    return normalized
+
+
+def is_owner(platform: str | None, platform_user_id: str | int, owners: dict[str, set[str]] | None = None) -> bool:
+    if not platform or not platform_user_id:
+        return False
+    owners = owners or load_owner_config()
+    bucket = owners.get(platform.lower(), set())
+    return str(platform_user_id) in bucket
+
+
+def ensure_config_dir() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)

multi_user_rbac-0.1.1/multi_user_rbac/permissions.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+ROLE_PERMISSIONS: dict[str, frozenset[str]] = {
+    "owner": frozenset(),  # owner gets implicit access to everything
+    "user": frozenset(
+        {
+            "identify_user",
+            "get_user_preference",
+            "set_user_preference",
+            "list_channel_users",
+        }
+    ),
+    "guest": frozenset({"identify_user"}),
+}
+
+
+def check_permission(role: str | None, tool_name: str) -> bool:
+    if not role:
+        return False
+    normalized = role.lower()
+    if normalized == "owner":
+        return True
+    allowed = ROLE_PERMISSIONS.get(normalized, frozenset())
+    return tool_name in allowed
+
+
+def is_owner(role: str | None) -> bool:
+    return (role or "").lower() == "owner"

multi_user_rbac-0.1.1/multi_user_rbac/schemas.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+ToolSchema = dict
+
+IDENTIFY_USER: ToolSchema = {
+    "name": "identify_user",
+    "description": (
+        "Return the current user identity, their platform, display name, and role. "
+        "Use this when you need to make decisions that depend on who is talking."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    },
+}
+
+GET_USER_PREFERENCE: ToolSchema = {
+    "name": "get_user_preference",
+    "description": (
+        "Retrieve a stored preference for the current user. "
+        "Preference keys can be global or scoped to a channel (pass channel_id)."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "key": {
+                "type": "string",
+                "description": "Preference key, e.g. 'theme' or 'tone'.",
+            },
+            "channel_id": {
+                "type": "string",
+                "description": "Optional channel scope to lookup a channel-specific preference.",
+            },
+        },
+        "required": ["key"],
+    },
+}
+
+SET_USER_PREFERENCE: ToolSchema = {
+    "name": "set_user_preference",
+    "description": (
+        "Store a preference for the current user. "
+        "Use channel_id to make it channel-specific."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "key": {"type": "string"},
+            "value": {"type": "string"},
+            "channel_id": {"type": "string"},
+        },
+        "required": ["key", "value"],
+    },
+}
+
+SET_CHANNEL_PREFERENCE: ToolSchema = {
+    "name": "set_channel_preference",
+    "description": (
+        "Owner-only: store a preference that applies to the entire channel and is visible to everyone."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "channel_id": {"type": "string"},
+            "key": {"type": "string"},
+            "value": {"type": "string"},
+        },
+        "required": ["channel_id", "key", "value"],
+    },
+}
+
+LIST_CHANNEL_USERS: ToolSchema = {
+    "name": "list_channel_users",
+    "description": (
+        "Return every known member of the current channel (or the channel_id parameter). "
+        "Results include display_name, platform, and role."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "channel_id": {"type": "string"},
+        },
+        "required": [],
+    },
+}
+
+PROMOTE_USER: ToolSchema = {
+    "name": "promote_user",
+    "description": (
+        "Owner-only: promote a channel member to the 'user' role. "
+        "Provide platform and platform_user_id so we can find the right record."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "platform": {"type": "string"},
+            "platform_user_id": {"type": "string"},
+        },
+        "required": ["platform", "platform_user_id"],
+    },
+}
+
+DEMOTE_USER: ToolSchema = {
+    "name": "demote_user",
+    "description": (
+        "Owner-only: demote a channel member to 'guest'. "
+        "Use the same arguments as promote_user."
+    ),
+    "parameters": PROMOTE_USER["parameters"],
+}

multi_user_rbac-0.1.1/multi_user_rbac/storage.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from threading import Lock
+from typing import Iterable
+
+
+def _ensure_path(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+class Storage:
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        if db_path is None:
+            db_path = Path.home() / ".hermes" / "plugins" / "multi-user-rbac" / "data" / "users.db"
+        self._db_path = Path(db_path)
+        _ensure_path(self._db_path)
+        self._lock = Lock()
+        self._conn = sqlite3.connect(
+            str(self._db_path),
+            check_same_thread=False,
+            isolation_level=None,
+        )
+        self._conn.row_factory = sqlite3.Row
+        with self._lock:
+            self._conn.execute("PRAGMA journal_mode = WAL;")
+            self._conn.execute("PRAGMA foreign_keys = ON;")
+        self._ensure_tables()
+
+    def _ensure_tables(self) -> None:
+        with self._lock:
+            self._conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS users (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    platform TEXT NOT NULL,
+                    platform_user_id TEXT NOT NULL,
+                    display_name TEXT NOT NULL,
+                    role TEXT NOT NULL DEFAULT 'guest',
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    UNIQUE(platform, platform_user_id)
+                );
+                CREATE TABLE IF NOT EXISTS channel_members (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    channel_id TEXT NOT NULL,
+                    platform TEXT NOT NULL,
+                    platform_user_id TEXT NOT NULL,
+                    UNIQUE(channel_id, platform, platform_user_id)
+                );
+                CREATE TABLE IF NOT EXISTS preferences (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    user_id INTEGER NOT NULL,
+                    channel_id TEXT,
+                    key TEXT NOT NULL,
+                    value TEXT NOT NULL,
+                    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE,
+                    UNIQUE(user_id, channel_id, key)
+                );
+                CREATE TABLE IF NOT EXISTS channel_preferences (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    channel_id TEXT NOT NULL,
+                    key TEXT NOT NULL,
+                    value TEXT NOT NULL,
+                    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    UNIQUE(channel_id, key)
+                );
+                CREATE INDEX IF NOT EXISTS idx_users_platform_user ON users(platform, platform_user_id);
+                CREATE INDEX IF NOT EXISTS idx_preferences_user ON preferences(user_id);
+                CREATE INDEX IF NOT EXISTS idx_channel_members_channel ON channel_members(channel_id);
+                CREATE INDEX IF NOT EXISTS idx_channel_preferences_channel ON channel_preferences(channel_id);
+                """
+            )
+
+    def _fetchone(self, query: str, params: Iterable | None = None) -> sqlite3.Row | None:
+        with self._lock:
+            cur = self._conn.execute(query, tuple(params) if params else ())
+            return cur.fetchone()
+
+    def _fetchall(self, query: str, params: Iterable | None = None) -> list[sqlite3.Row]:
+        with self._lock:
+            cur = self._conn.execute(query, tuple(params) if params else ())
+            return cur.fetchall()
+
+    def _execute(self, query: str, params: Iterable | None = None) -> None:
+        with self._lock:
+            self._conn.execute(query, tuple(params) if params else ())
+
+    def get_or_create_user(
+        self,
+        platform: str,
+        platform_user_id: str,
+        display_name: str,
+        default_role: str = "guest",
+    ) -> dict:
+        user = self.get_user_by_platform(platform, platform_user_id)
+        if user:
+            if user["display_name"] != display_name:
+                self.update_display_name(user["id"], display_name)
+                user = self.get_user_by_id(user["id"])
+            return user
+        self._execute(
+            "INSERT INTO users (platform, platform_user_id, display_name, role) VALUES (?, ?, ?, ?)" ,
+            (platform, platform_user_id, display_name, default_role),
+        )
+        return self.get_user_by_platform(platform, platform_user_id)
+
+    def get_user_by_id(self, user_id: int) -> dict | None:
+        row = self._fetchone("SELECT * FROM users WHERE id = ?", (user_id,))
+        return dict(row) if row else None
+
+    def get_user_by_platform(self, platform: str, platform_user_id: str) -> dict | None:
+        row = self._fetchone(
+            "SELECT * FROM users WHERE platform = ? AND platform_user_id = ?",
+            (platform, platform_user_id),
+        )
+        return dict(row) if row else None
+
+    def update_display_name(self, user_id: int, display_name: str) -> None:
+        self._execute(
+            "UPDATE users SET display_name = ? WHERE id = ?", (display_name, user_id)
+        )
+
+    def set_role(self, user_id: int, role: str) -> None:
+        self._execute("UPDATE users SET role = ? WHERE id = ?", (role, user_id))
+
+    def record_channel_membership(
+        self, channel_id: str, platform: str, platform_user_id: str
+    ) -> None:
+        self._execute(
+            "INSERT OR IGNORE INTO channel_members (channel_id, platform, platform_user_id) VALUES (?, ?, ?)",
+            (channel_id, platform, platform_user_id),
+        )
+
+    def list_channel_users(self, channel_id: str, platform: str | None = None) -> list[dict]:
+        if platform:
+            rows = self._fetchall(
+                "SELECT u.* FROM channel_members cm JOIN users u ON cm.platform = u.platform AND cm.platform_user_id = u.platform_user_id WHERE cm.channel_id = ? AND cm.platform = ?",
+                (channel_id, platform),
+            )
+        else:
+            rows = self._fetchall(
+                "SELECT u.* FROM channel_members cm JOIN users u ON cm.platform = u.platform AND cm.platform_user_id = u.platform_user_id WHERE cm.channel_id = ?",
+                (channel_id,),
+            )
+        return [dict(row) for row in rows]
+
+    def set_preference(
+        self,
+        user_id: int,
+        key: str,
+        value: str,
+        channel_id: str | None = None,
+    ) -> None:
+        self._execute(
+            "INSERT INTO preferences (user_id, channel_id, key, value) VALUES (?, ?, ?, ?)"
+            " ON CONFLICT(user_id, channel_id, key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP",
+            (user_id, channel_id, key, value),
+        )
+
+    def get_preference(
+        self,
+        user_id: int,
+        key: str,
+        channel_id: str | None = None,
+    ) -> dict | None:
+        row = self._fetchone(
+            "SELECT * FROM preferences WHERE user_id = ? AND key = ? AND channel_id IS ?",
+            (user_id, key, channel_id),
+        )
+        return dict(row) if row else None
+
+    def get_recent_preferences(self, user_id: int, limit: int = 3) -> list[str]:
+        rows = self._fetchall(
+            "SELECT key FROM preferences WHERE user_id = ? ORDER BY updated_at DESC, id DESC LIMIT ?",
+            (user_id, limit),
+        )
+        return [row["key"] for row in rows]
+
+    def set_channel_preference(self, channel_id: str, key: str, value: str) -> None:
+        self._execute(
+            "INSERT INTO channel_preferences (channel_id, key, value) VALUES (?, ?, ?)"
+            " ON CONFLICT(channel_id, key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP",
+            (channel_id, key, value),
+        )
+
+    def get_channel_preferences(self, channel_id: str) -> dict[str, str]:
+        rows = self._fetchall(
+            "SELECT key, value FROM channel_preferences WHERE channel_id = ?",
+            (channel_id,),
+        )
+        return {row["key"]: row["value"] for row in rows}

multi_user_rbac-0.1.1/multi_user_rbac/tools.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from .config import ensure_config_dir, is_owner as config_is_owner, load_owner_config
+from .permissions import check_permission, is_owner as role_is_owner
+from .storage import Storage
+
+logger = logging.getLogger(__name__)
+
+ensure_config_dir()
+_storage = Storage()
+
+
+@dataclass
+class PluginContext:
+    session_id: str | None = None
+    platform: str | None = None
+    channel_id: str | None = None
+    current_user: dict | None = None
+
+
+_plugin_ctx = PluginContext()
+
+
+def _error(message: str) -> str:
+    return json.dumps({"error": message})
+
+
+def _require_current_user() -> dict | str:
+    user = _plugin_ctx.current_user
+    if not user:
+        return _error("No user identified in this session")
+    return user
+
+
+def identify_user(args: dict, **kwargs: Any) -> str:
+    user = _require_current_user()
+    if isinstance(user, str):
+        return user
+    return json.dumps(
+        {
+            "platform": user.get("platform"),
+            "platform_user_id": user.get("platform_user_id"),
+            "display_name": user.get("display_name"),
+            "role": user.get("role"),
+        }
+    )
+
+
+def get_user_preference(args: dict, **kwargs: Any) -> str:
+    user = _require_current_user()
+    if isinstance(user, str):
+        return user
+    key = (args or {}).get("key")
+    if not key:
+        return _error("key required")
+    channel_id = args.get("channel_id") if args else None
+    pref = _storage.get_preference(user["id"], key, channel_id)
+    if not pref and channel_id:
+        pref = _storage.get_preference(user["id"], key, None)
+    if not pref:
+        return _error(f"{key} not set")
+    return json.dumps(
+        {
+            "status": "ok",
+            "key": pref["key"],
+            "value": pref["value"],
+            "channel_id": pref["channel_id"],
+        }
+    )
+
+
+def set_user_preference(args: dict, **kwargs: Any) -> str:
+    user = _require_current_user()
+    if isinstance(user, str):
+        return user
+    key = (args or {}).get("key")
+    value = (args or {}).get("value")
+    if not key or value is None:
+        return _error("key and value required")
+    channel_id = args.get("channel_id") if args else None
+    _storage.set_preference(user["id"], key, str(value), channel_id)
+    return json.dumps({"status": "ok", "key": key, "value": value, "channel_id": channel_id})
+
+
+def set_channel_preference(args: dict, **kwargs: Any) -> str:
+    user = _require_current_user()
+    if isinstance(user, str):
+        return user
+    if not role_is_owner(user.get("role")):
+        return _error("Only owner can set channel preferences")
+    channel_id = args.get("channel_id")
+    key = args.get("key")
+    value = args.get("value")
+    if not channel_id or not key or value is None:
+        return _error("channel_id, key, value required")
+    _storage.set_channel_preference(channel_id, key, str(value))
+    return json.dumps({"status": "ok", "channel_id": channel_id, "key": key, "value": value})
+
+
+def list_channel_users(args: dict, **kwargs: Any) -> str:
+    user = _require_current_user()
+    if isinstance(user, str):
+        return user
+    channel_id = (args or {}).get("channel_id") or _plugin_ctx.channel_id
+    if not channel_id:
+        return _error("No channel ID known; specify channel_id")
+    users = _storage.list_channel_users(channel_id, _plugin_ctx.platform)
+    serialized = [
+        {
+            "display_name": u["display_name"],
+            "role": u["role"],
+            "platform": u["platform"],
+            "platform_user_id": u["platform_user_id"],
+        }
+        for u in users
+    ]
+    return json.dumps({"users": serialized, "count": len(serialized)})
+
+
+def _change_role(
+    target_platform: str | None,
+    target_user_id: str | None,
+    new_role: str,
+) -> dict | str:
+    resolved_platform = target_platform or _plugin_ctx.platform
+    if not resolved_platform or not target_user_id:
+        return _error("platform and platform_user_id required")
+    target = _storage.get_user_by_platform(resolved_platform, target_user_id)
+    if not target:
+        return _error("User not found. They need to interact first.")
+    _storage.set_role(target["id"], new_role)
+    return {"status": new_role, "user": target["display_name"], "role": new_role}
+
+
+def promote_user(args: dict, **kwargs: Any) -> str:
+    user = _require_current_user()
+    if isinstance(user, str):
+        return user
+    if not role_is_owner(user.get("role")):
+        return _error("Only owner can promote users")
+    result = _change_role(args.get("platform"), args.get("platform_user_id"), "user")
+    if isinstance(result, str):
+        return result
+    return json.dumps(result)
+
+
+def demote_user(args: dict, **kwargs: Any) -> str:
+    user = _require_current_user()
+    if isinstance(user, str):
+        return user
+    if not role_is_owner(user.get("role")):
+        return _error("Only owner can demote users")
+    result = _change_role(args.get("platform"), args.get("platform_user_id"), "guest")
+    if isinstance(result, str):
+        return result
+    return json.dumps(result)
+
+
+def _extract_metadata(kwargs: dict[str, Any]) -> dict[str, Any]:
+    for key in ("metadata", "session_metadata", "gateway_metadata", "context", "env"):
+        candidate = kwargs.get(key)
+        if isinstance(candidate, dict):
+            return candidate
+    return {}
+
+
+def _identify_sender(platform: str | None, kwargs: dict[str, Any]) -> tuple[str | None, str | None, str | None]:
+    meta = _extract_metadata(kwargs)
+    platform_user_id = (
+        kwargs.get("platform_user_id")
+        or kwargs.get("sender_id")
+        or meta.get("platform_user_id")
+        or meta.get("user_id")
+        or meta.get("sender_id")
+        or meta.get("user")
+    )
+    display_name = (
+        meta.get("display_name")
+        or meta.get("sender_display_name")
+        or meta.get("username")
+        or meta.get("name")
+    )
+    channel_id = (
+        kwargs.get("channel_id")
+        or meta.get("channel_id")
+        or meta.get("chat_id")
+        or meta.get("room_id")
+        or meta.get("conversation_id")
+    )
+    return platform_user_id, display_name, channel_id
+
+
+def on_session_start(session_id: str, model: str, platform: str, **kwargs: Any) -> None:
+    platform_user_id, display_name, channel_id = _identify_sender(platform, kwargs)
+    if not platform or not platform_user_id:
+        _plugin_ctx.current_user = None
+        return
+    display_name = display_name or f"{platform_user_id}"
+    user = _storage.get_or_create_user(
+        platform=platform,
+        platform_user_id=str(platform_user_id),
+        display_name=display_name,
+        default_role="guest",
+    )
+    owners = load_owner_config()
+    if config_is_owner(platform, platform_user_id, owners):
+        _storage.set_role(user["id"], "owner")
+        user = _storage.get_user_by_id(user["id"])
+    if channel_id:
+        _storage.record_channel_membership(channel_id, platform, str(platform_user_id))
+    _plugin_ctx.session_id = session_id
+    _plugin_ctx.platform = platform
+    _plugin_ctx.channel_id = channel_id
+    _plugin_ctx.current_user = user
+    logger.debug(
+        "[%s] session user identified: %s (role=%s)",
+        session_id,
+        user.get("display_name"),
+        user.get("role"),
+    )
+
+
+def on_pre_llm_call(
+    session_id: str,
+    user_message: str,
+    conversation_history: list[Any],
+    is_first_turn: bool,
+    model: str,
+    platform: str,
+    **kwargs: Any,
+) -> dict[str, str] | str | None:
+    user = _plugin_ctx.current_user
+    if not user:
+        return None
+    pref_keys = _storage.get_recent_preferences(user["id"], limit=3)
+    channel_prefs = (
+        _storage.get_channel_preferences(_plugin_ctx.channel_id)
+        if _plugin_ctx.channel_id
+        else {}
+    )
+    pref_str = ", ".join(pref_keys) if pref_keys else "(none)"
+    channel_pref_text = (
+        ", ".join(f"{k}={v}" for k, v in channel_prefs.items())
+        if channel_prefs
+        else ""
+    )
+    context_parts = [
+        f"[MultiUserRBAC] User: {user['display_name']} (role={user['role']})",
+        f"Active prefs: {pref_str}",
+    ]
+    if channel_pref_text:
+        context_parts.append(f"Channel prefs: {channel_pref_text}")
+    return {"context": " | ".join(context_parts)}
+
+
+def on_post_tool_call(
+    tool_name: str, args: dict[str, Any], result: str, task_id: str, **kwargs: Any
+) -> None:
+    user = _plugin_ctx.current_user
+    if not user:
+        return
+    if not check_permission(user.get("role"), tool_name):
+        logger.warning(
+            "Role %s tried to call %s; denying in post hook (session %s)",
+            user.get("role"),
+            tool_name,
+            task_id,
+        )
+    logger.debug(
+        "Post tool call: %s args=%s user=%s", tool_name, args, user.get("display_name")
+    )
+
+
+def on_session_finalize(session_id: str | None, platform: str, **kwargs: Any) -> None:
+    _plugin_ctx.current_user = None
+    _plugin_ctx.channel_id = None
+    _plugin_ctx.platform = None
+    _plugin_ctx.session_id = None
+
+
+# Slash command helpers
+def _require_owner_or_error() -> str | None:
+    user = _plugin_ctx.current_user
+    if not user:
+        return "No current user"
+    if not role_is_owner(user.get("role")):
+        return "Only owner can run this command"
+    return None
+
+
+def _resolve_platform_and_id(raw_args: str) -> tuple[str | None, str | None, str]:
+    parts = raw_args.strip().split()
+    if len(parts) == 1:
+        platform = _plugin_ctx.platform
+        if not platform:
+            return None, None, "Specify platform and platform_user_id"
+        return platform, parts[0], ""
+    if len(parts) == 2:
+        return parts[0], parts[1], ""
+    return None, None, "Usage: <platform_user_id> or <platform> <platform_user_id>"
+
+
+def _extract_error(payload: str) -> str:
+    try:
+        data = json.loads(payload)
+        return data.get("error", payload)
+    except Exception:
+        return payload
+
+
+def cmd_users(raw_args: str) -> str:
+    if err := _require_owner_or_error():
+        return err
+    channel_id = _plugin_ctx.channel_id
+    if not channel_id:
+        return "No channel ID known; provide a channel_id"
+    users = _storage.list_channel_users(channel_id, _plugin_ctx.platform)
+    lines = [f"{u['display_name']} ({u['role']})" for u in users]
+    return f"Channel members ({len(lines)}):\n" + "\n".join(lines)
+
+
+def cmd_promote(raw_args: str) -> str:
+    if err := _require_owner_or_error():
+        return err
+    platform, target_id, usage = _resolve_platform_and_id(raw_args)
+    if usage:
+        return usage
+    result = _change_role(platform, target_id, "user")
+    if isinstance(result, str):
+        return _extract_error(result)
+    return f"Promoted {result['user']} to {result['role']}"
+
+
+def cmd_demote(raw_args: str) -> str:
+    if err := _require_owner_or_error():
+        return err
+    platform, target_id, usage = _resolve_platform_and_id(raw_args)
+    if usage:
+        return usage
+    result = _change_role(platform, target_id, "guest")
+    if isinstance(result, str):
+        return _extract_error(result)
+    return f"Demoted {result['user']} to {result['role']}"
+
+
+def cmd_set_preference_for(raw_args: str) -> str:
+    if err := _require_owner_or_error():
+        return err
+    parts = raw_args.strip().split(maxsplit=2)
+    if len(parts) < 3:
+        return "Usage: /set-for <platform_user_id> <key> <value>"
+    target_id, key, value = parts
+    platform = _plugin_ctx.platform
+    if not platform:
+        return "Cannot determine platform"
+    target = _storage.get_user_by_platform(platform, target_id)
+    if not target:
+        return f"Unknown user {target_id}"
+    _storage.set_preference(target["id"], key, value)
+    return f"Set {target['display_name']} {key}={value}"

multi_user_rbac-0.1.1/multi_user_rbac.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+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).

multi_user_rbac-0.1.1/multi_user_rbac.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+multi_user_rbac/__init__.py
+multi_user_rbac/config.py
+multi_user_rbac/permissions.py
+multi_user_rbac/schemas.py
+multi_user_rbac/storage.py
+multi_user_rbac/tools.py
+multi_user_rbac.egg-info/PKG-INFO
+multi_user_rbac.egg-info/SOURCES.txt
+multi_user_rbac.egg-info/dependency_links.txt
+multi_user_rbac.egg-info/entry_points.txt
+multi_user_rbac.egg-info/requires.txt
+multi_user_rbac.egg-info/top_level.txt
+tests/test_permissions.py
+tests/test_storage.py
+tests/test_tools.py

multi_user_rbac-0.1.1/multi_user_rbac.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

multi_user_rbac-0.1.1/multi_user_rbac.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+multi-user-rbac = multi_user_rbac

multi_user_rbac-0.1.1/multi_user_rbac.egg-info/requires.txt

@@ -0,0 +1,5 @@
+pyyaml>=6.0
+
+[dev]
+pytest
+build

multi_user_rbac-0.1.1/multi_user_rbac.egg-info/top_level.txt

@@ -0,0 +1 @@
+multi_user_rbac

multi_user_rbac-0.1.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=70.0", "wheel", "build"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "multi-user-rbac"
+version = "0.1.1"
+description = "Hermes plugin implementing multi-user RBAC, preferences, and owner controls."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [ { name = "Ahsan Athallah" } ]
+license = { text = "MIT" }
+dependencies = ["pyyaml>=6.0"]
+
+[project.urls]
+Homepage = "https://github.com/"
+Repository = "https://github.com/"
+
+[project.optional-dependencies]
+dev = ["pytest", "build"]
+
+[project.entry-points."hermes_agent.plugins"]
+multi-user-rbac = "multi_user_rbac"

multi_user_rbac-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

multi_user_rbac-0.1.1/tests/test_permissions.py

@@ -0,0 +1,16 @@
+from multi_user_rbac.permissions import check_permission, is_owner
+
+
+def test_owner_has_full_access() -> None:
+    assert check_permission("owner", "anything")
+    assert is_owner("owner")
+
+
+def test_user_only_safe_tools() -> None:
+    assert check_permission("user", "identify_user")
+    assert not check_permission("user", "promote_user")
+
+
+def test_guest_limited_access() -> None:
+    assert check_permission("guest", "identify_user")
+    assert not check_permission("guest", "set_user_preference")

multi_user_rbac-0.1.1/tests/test_storage.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from multi_user_rbac.storage import Storage
+
+
+def test_preferences_and_channel_membership(tmp_path: Path) -> None:
+    db_path = tmp_path / "data.db"
+    storage = Storage(db_path)
+    user = storage.get_or_create_user("test", "user1", "User One")
+    storage.set_preference(user["id"], "theme", "dark")
+    assert storage.get_preference(user["id"], "theme")["value"] == "dark"
+    storage.set_preference(user["id"], "tone", "friendly", channel_id="chanA")
+    assert storage.get_recent_preferences(user["id"], limit=2) == ["tone", "theme"]
+    storage.set_channel_preference("chanA", "mode", "quiet")
+    assert storage.get_channel_preferences("chanA")["mode"] == "quiet"
+    storage.record_channel_membership("chanA", "test", "user1")
+    members = storage.list_channel_users("chanA", "test")
+    assert members and members[0]["platform_user_id"] == "user1"
+
+
+def test_channel_preferences_are_isolated(tmp_path: Path) -> None:
+    storage = Storage(tmp_path / "second.db")
+    storage.set_channel_preference("chanB", "tone", "calm")
+    assert storage.get_channel_preferences("chanB") == {"tone": "calm"}
+    assert storage.get_channel_preferences("chanC") == {}

multi_user_rbac-0.1.1/tests/test_tools.py

@@ -0,0 +1,65 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from multi_user_rbac import tools
+from multi_user_rbac.storage import Storage
+
+
+@pytest.fixture(autouse=True)
+def reset_context() -> None:
+    tools._plugin_ctx.current_user = None
+    tools._plugin_ctx.platform = None
+    tools._plugin_ctx.channel_id = None
+    tools._plugin_ctx.session_id = None
+    yield
+    tools._plugin_ctx.current_user = None
+    tools._plugin_ctx.platform = None
+    tools._plugin_ctx.channel_id = None
+    tools._plugin_ctx.session_id = None
+
+
+@pytest.fixture
+def patched_storage(tmp_path: Path) -> Storage:
+    original = tools._storage
+    replacement = Storage(tmp_path / "tools.db")
+    tools._storage = replacement
+    yield replacement
+    tools._storage = original
+
+
+def test_set_and_get_preference(patched_storage: Storage) -> None:
+    storage = patched_storage
+    user = storage.get_or_create_user("test", "userA", "Tester")
+    tools._plugin_ctx.current_user = user
+    tools._plugin_ctx.platform = "test"
+    response = tools.set_user_preference({"key": "theme", "value": "dark"})
+    assert json.loads(response)["status"] == "ok"
+    lookup = json.loads(tools.get_user_preference({"key": "theme"}))
+    assert lookup["value"] == "dark"
+
+
+def test_owner_channel_preferences(patched_storage: Storage) -> None:
+    storage = patched_storage
+    owner = storage.get_or_create_user("platform", "owner1", "Owner")
+    storage.set_role(owner["id"], "owner")
+    tools._plugin_ctx.current_user = storage.get_user_by_id(owner["id"])
+    response = tools.set_channel_preference(
+        {"channel_id": "chan", "key": "mood", "value": "focused"}
+    )
+    assert json.loads(response)["status"] == "ok"
+    assert storage.get_channel_preferences("chan")["mood"] == "focused"
+
+
+def test_cmd_promote_demote(patched_storage: Storage) -> None:
+    storage = patched_storage
+    owner = storage.get_or_create_user("test", "owner1", "Owner")
+    target = storage.get_or_create_user("test", "target1", "Target")
+    storage.set_role(owner["id"], "owner")
+    tools._plugin_ctx.current_user = storage.get_user_by_id(owner["id"])
+    tools._plugin_ctx.platform = "test"
+    assert "Promoted" in tools.cmd_promote("target1")
+    assert storage.get_user_by_platform("test", "target1")["role"] == "user"
+    assert "Demoted" in tools.cmd_demote("target1")
+    assert storage.get_user_by_platform("test", "target1")["role"] == "guest"