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

未关闭
  • 哪里不对？
#1,507 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
20/100
Issue 类型
功能
描述清晰度
需要澄清
活跃度
活跃
技术栈
openapi, postgresql, typescript
领域
api, authentication, authorization, database, security

调研方向

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.

由索引模型根据 Issue 内容生成。

描述

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
主要语言
TypeScript
星标
856
派生
82
平均合并
6 小时 23 分钟
30 天内合并 PR
430

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

HelpCode-ai/anythingmcp 的其他 Issue

查看 HelpCode-ai/anythingmcp 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。