Management API tokens + /api guard: foundation for a management CLI

Đang mở
  • Có gì không ổn?
#1,507 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
20/100
Loại issue
Tính năng
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Sôi nổi
Công nghệ
openapi, postgresql, typescript
Lĩnh vực
api, authentication, authorization, database, security

Hướng nghiên cứu

Start by reading AGENTS.md and the existing MCP auth guards, RolesGuard, rate-limit guard and middleware, plus the /api/mcp-keys controller and Prisma schema. The issue requires agreement on credential shape and scope semantics before implementation, then calls for auth and rate-limit tests, a Prisma migration, minting UI changes, and OpenAPI annotations in the File Search and file-share controllers. Done means those decisions are agreed and the listed tasks are implemented.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Summary

Add a management-scoped API credential and a guard that lets it authorize the
/api/* management endpoints, as the foundation for a full management CLI
(configure connectors, MCP servers, roles, users, SSO, code mode, settings,
memory/skills/knowledge-graph from the terminal — and by a connected agent).

This is a discussion-first issue per AGENTS.md (it changes authentication
and the Prisma schema). No code until the approach here is agreed.

Problem (verified in source)

There are two auth realms:

  • MCP realm — the MCP API key is authenticated by McpAuthMiddleware /
    McpCombinedAuthGuard, bound only to .forRoutes('mcp'), and resolves to a
    user pinned to one mcpServerId + mcpRoleId (a tool allow-list). It exists
    to call tools.
  • Management realm — every /api/* controller is guarded by
    AuthGuard('jwt') (browser session cookie) + @Roles('ADMIN') on sensitive
    routes. The MCP key cannot reach it, and cookie+CSRF is unusable from a CLI/CI.
    Cloud SSO users have no username/password login at all.

So a CLI cannot manage an instance today with the existing credential.

Proposal

Extend the existing API-key machinery rather than build a parallel system:

  1. Scope on the credential — add a scope to McpApiKey
    (mcp | management-read | management-admin). The key carries the user's
    identity and role; the scope is a downward cap, never an elevation.
    Effective power = min(user role, key scope). A non-admin's key still gets the
    same @Roles('ADMIN') 403s as in the dashboard.
  2. Guard — a guard that accepts a valid session JWT or a management
    key on /api/*, composing with the existing RolesGuard.
  3. Rate limiting — apply the existing per-principal rate-limit
    (mcp-principal-rate-limit.guard / mcp-rate-limit.middleware) to /api/*
    keyed to the management key, plus a per-key daily op cap. Protects against a
    looping tool/agent hammering the backend.
  4. Self-service minting — /api/mcp-keys is already JWT-only and
    user-scoped, so any user mints their own key; add the scope selector (offer
    only scopes <= the user's role). Agent-issued keys default to read-only.

Deployment behavior

Same feature on Cloud and self-hosted. Self-hosted gets it for free; on Cloud it
is the only non-interactive path for SSO users. No Cloud operator procedures are
part of this change.

Security

Least privilege (read vs admin scope), revocation, per-principal rate limit +
per-key quota, every management mutation already lands in the audit log, and
registration / forgot-password stay off the CLI (launcher-only to the web page,
no API call, no email).

Schema change + migration

New scope column (enum) on McpApiKey; migration included with the
implementation PR. Open to a separate ManagementApiKey table instead if we
prefer to keep MCP and management credentials fully distinct — a design question
for this thread.

Pre-work found

OpenAPI coverage audit: 179 / 207 management routes already carry
@ApiOperation. The gap is almost entirely File Search (file-search 3/23,
file-share 0/8, ~29 routes). Those two controllers need annotation before we
generate a typed CLI client from /api/docs.

Out of scope (follow-ups)

  • Browser OAuth login for human ergonomics / SSO (fast-follow; reuses the
    OAuth2 server already in the repo).
  • The CLI command surface itself (225 management commands mapped; one command
    per controller route) and public npm distribution.
  • Declarative apply / export ("instance as code").

Tasks

  • Agree credential shape (scope on McpApiKey vs separate table)
  • Define scope semantics (read = GET only; admin = all, role-capped)
  • Guard design (JWT-or-management-key) + tests
  • Apply per-principal rate limit + per-key quota to /api/*
  • Prisma migration
  • Mint UI + /api/mcp-keys scope selector (cap to role; agent default read-only)
  • Annotate File Search / file-share controllers for OpenAPI
Ngôn ngữ chính
TypeScript
Star
856
Fork
82
Merge trung bình
6 giờ 23 phút
Pull request đã merge (30 ngày)
430

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của HelpCode-ai/anythingmcp

Tất cả issue của HelpCode-ai/anythingmcp

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.