[enhance] phát triển UX grant quyền thực thi CLI/MCP theo user/group/channel

[mrgoonie]

Context

GoClaw already has basic role-style permissions and channel allowlists, but the UX is still too coarse for real team/company usage.

A common need is not just “is this user allowed to talk to the bot?”, but:

• Which CLI/runtime commands can this user or group execute in this channel?
• Which MCP tools can this user or group call in this channel?
• Is the permission permanent, or only valid for a fixed duration?
• How do admins review and revoke these grants later without digging through config or logs?

This becomes more important as GoClaw exposes powerful runtime/package commands, MCP tools, file operations, connector actions, and delegated agents across Telegram, Discord, Slack, Zalo, Feishu/Lark, WhatsApp, and other channels.

Problem

Today, granting execution rights is hard to model and hard to review when the permission depends on:

• subject: a user, group, role, team, channel member, or external channel identity;
• channel context: DM vs group, Discord guild/channel/member, Telegram group/thread/user, Slack workspace/channel/user, etc.;
• command/tool surface: CLI commands, runtime package commands, MCP tools, built-in tools;
• policy shape: full access, allowlist, denylist, inherited permission, temporary grant;
• governance: who granted it, why, when it expires, and how to audit/revoke it.

For team/company deployments, admins need a safer and more discoverable way to say things like:

• “This Discord guild member can run only these GoClaw CLI commands in this channel for 7 days.”
• “This Telegram group can use MCP tools except shell/file-write tools.”
• “This support team can call read-only connector tools, but not destructive DB execute.”
• “This user has full CLI execution in this private ops channel, but nowhere else.”
• “Show me every active grant for this channel/user/tool before I approve a risky action.”

Proposed direction

Build an advanced execution permission system for CLI and MCP grants, with a central management UX.

1. Permission grant model

Support grants for:

• CLI/runtime command execution:
  • full access;
  • allowlisted commands;
  • denied commands;
  • command groups/templates.
• MCP/tool execution:
  • full access;
  • allowlisted tools;
  • denied tools;
  • tool groups/templates, e.g. read-only, media, connector read, destructive/admin.
• Scope:
  • user;
  • group/team;
  • channel;
  • channel + user/group combination;
  • org/tenant where appropriate.
• Duration:
  • permanent grant;
  • temporary grant with expires_at;
  • optional one-time or session-bound grants if useful later.

The default should remain safe: no implicit escalation, and risky/destructive tools should be deny-by-default unless explicitly granted by a privileged admin/operator.

2. Channel-aware identity and search

Normalize channel-specific identity metadata so admins can search and grant permissions without manually copying opaque IDs.

Examples:

• Discord:
  • guild ID/name;
  • channel ID/name;
  • member/user ID, username, display name, roles.
• Telegram:
  • chat ID/title;
  • thread/topic where available;
  • user ID, username, display name.
• Slack/Feishu/Zalo/WhatsApp:
  • workspace/org/chat/channel identifiers where available;
  • user/member display metadata.

Needed UX:

• Search users by channel.
• Search groups/channels by platform.
• View recent participants known to GoClaw.
• Grant permission from a search result without manually entering raw IDs.
• Show enough channel metadata to avoid granting access to the wrong person/channel.

3. Centralized management UI

Add a centralized permission management interface for review and maintenance.

Suggested screens:

• Active grants list:
  • subject;
  • channel/scope;
  • CLI/MCP access summary;
  • allowlist/denylist details;
  • expiration;
  • granted by;
  • created/updated timestamps.
• Grant editor:
  • choose subject/channel;
  • choose CLI permission mode: full / allowlist / denylist;
  • choose MCP permission mode: full / allowlist / denylist;
  • choose duration: forever / fixed time;
  • optional reason/note.
• Review/revoke view:
  • revoke immediately;
  • extend/shorten duration;
  • convert full access to allowlist;
  • inspect audit history.
• Risk indicators:
  • destructive commands/tools highlighted;
  • expired grants clearly marked;
  • inherited grants explained.

4. API endpoints and CLI commands

Expose first-class API and CLI surfaces so permissions can be automated and reviewed outside the web UI.

Potential API shape:

• GET /v1/permission-grants
• POST /v1/permission-grants
• GET /v1/permission-grants/{id}
• PATCH /v1/permission-grants/{id}
• DELETE /v1/permission-grants/{id} or POST /v1/permission-grants/{id}/revoke
• GET /v1/permission-subjects/search?channel=...&q=...
• POST /v1/permission-checks for dry-run/explain: “would this subject be allowed to run this command/tool here?”

Potential CLI shape:

goclaw permissions grant cli \
  --subject user:<id> \
  --channel telegram:<chat_id> \
  --allow "sessions:list,cron:list,skills:search" \
  --duration 7d \
  --reason "temporary ops support"

goclaw permissions grant mcp \
  --subject group:<id> \
  --channel discord:<guild_id>:<channel_id> \
  --deny "db_execute,shell,write_file" \
  --forever

goclaw permissions list --channel discord:<guild_id>:<channel_id>
goclaw permissions explain --subject user:<id> --tool mcp:db_query --channel telegram:<chat_id>
goclaw permissions revoke <grant_id>

Naming can change, but the feature should support automation and explainability from day one.

Acceptance criteria

• Permission model supports CLI command grants and MCP/tool grants.
• Each grant can be full access, allowlist, or denylist.
• Grants can target user/group/channel combinations, not only global users.
• Grants can be permanent or expire after a fixed duration.
• Channel-specific identity metadata is captured enough to distinguish Discord guild/channel/member and similar platform-specific concepts.
• Admins can search users/members/channels from known channel metadata when creating a grant.
• Centralized web UI lists, filters, reviews, edits, and revokes active/expired grants.
• API endpoints exist for CRUD, search, revoke, and permission-check/explain workflows.
• CLI commands exist for grant/list/explain/revoke workflows.
• Permission checks are enforced before CLI/runtime command execution and before MCP/tool execution.
• Risky/destructive tools and commands can be denied by default or clearly highlighted in templates/UX.
• Audit log records who granted/revoked/updated a permission, target subject/scope, reason, timestamps, and expiration.
• Backward compatibility/migration path is documented for existing operator/writer/reader/channel allowlist behavior.
• Tests cover tenant isolation, scope matching, expiry, allowlist vs denylist precedence, channel-specific subject matching, and revoke behavior.

Security and privacy notes

• Default-deny is safer than broad implicit access, especially for shell, file-write, connector write, DB execute, credential, and admin tools.
• Denylist mode is convenient but dangerous if new commands/tools appear later; consider versioned command/tool identifiers or templates that make new destructive capabilities opt-in.
• Temporary grants must expire reliably across scheduler restarts and should not rely only on UI state.
• Permission explanation should be available for debugging: why allowed/denied, which grant matched, and what boundary applied.
• Audit log must avoid leaking secrets or raw command arguments containing sensitive values.
• Tenant isolation is critical: no cross-tenant subject search, grant listing, or permission matching.

Open questions

• Should CLI command IDs and MCP tool IDs be versioned to avoid accidental broad grants when packages/tools evolve?
• What is the precedence rule when multiple grants match: explicit deny over allow, most-specific scope wins, or both?
• Should temporary grants support approval flows, e.g. “ask admin to approve this command once”?
• Should permission templates be system-defined only, or org-customizable?
• Should channel roles, e.g. Discord roles or Slack user groups, become first-class grant subjects?