@innerfire/auth-cli
v0.1.0
Published
Lightweight per-project session authorization and API request CLI for Payload CMS administrators.
Readme
@innerfire/auth-cli
Payload CMS Admin OAuth & API CLI for Autonomous Agents & Operations
@innerfire/auth-cli 为运维人员与自治 AI Agent(如 Claude Code / Antigravity)提供轻量、免安装(支持 npx)且基于 Payload 3 管理员身份(payload-token Cookie)的鉴权与 API 代发工具。
🌟 核心特性
- 🔒 一项目一存储(物理隔离):项目间凭据相互独立,按项目分目录存放于
~/.config/innerfire-auth-cli/projects/<projectKey>/。 - ⚡ 按需临时回环授权:零常驻后台进程,仅在需要时于
127.0.0.1:0动态端口启动临时 HTTP 接收服务,校验 32 字节高熵随机state防伪造,接收完成后立即销毁 Server 释放端口。 - 🛡️ 严格安全权限:在 POSIX 系统上强制使用
0600(仅属主读写)权限保存session.json。 - 🌐 天然穿透 Payload 3 CSRF:API 代发请求自动注入
Cookie: <cookieName>=<token>、Origin: <cmsUrl>与Referer: <cmsUrl>/admin,在各集合(Collections)与钩子中完整识别为管理员(req.user)。 - 🔄 401 自动重登重试:当服务端管理员会话失效或 Secret 轮换导致 401 时,自动清除本地会话、重新唤起授权流程并重发请求。
- 📦 零运行时依赖:100% 依赖 Node.js 内置核心模块(
node:http,node:fs,node:crypto,node:child_process),极致精简安全。 - 🚀 开箱即用支持
npx:支持npx @innerfire/auth-cli无缝免装运行。
🚀 快速开始
方式 1:使用 npx 免安装直接调用
# 登录目标 CMS 管理员
npx @innerfire/auth-cli login -p xai -u http://localhost:3000
# 读取当前会话 Token
npx @innerfire/auth-cli token -p xai --raw
# 发送 GET 请求
npx @innerfire/auth-cli req -p xai GET "/api/courses?limit=5"
# 发送 POST 创建数据
npx @innerfire/auth-cli req -p xai POST /api/courses -d '{"name":"AI Agent 研发实践"}'方式 2:作为依赖安装并使用全局 / 本地命令
# 全局安装
pnpm add -g @innerfire/auth-cli
# 或在项目依赖中安装
vp add -D @innerfire/auth-cli📖 CLI 命令行命令手册
auth-cli <command> [options]1. login - 唤起浏览器登录并获取会话
# 初次登录需指定 --url / -u
auth-cli login -p xai -u https://cms.example.com
# 自定义授权端点或 Cookie 名称(默认 /api/cli-auth 与 payload-token)
auth-cli login -p xai -u https://cms.example.com --auth-endpoint /api/cli-auth --cookie-name payload-token2. token - 打印管理员会话 Token
如果本地没有有效会话或已过期(离过期不到 60 秒),会自动唤起浏览器重新登录。
# 打印 JSON 详情
auth-cli token -p xai
# 仅输出裸 Token(便于 Shell 脚本赋值)
export ADMIN_TOKEN=$(auth-cli token -p xai --raw)3. req - 以管理员身份向 Payload CMS 发送请求
# GET 请求
auth-cli req -p xai GET "/api/courses?limit=10"
auth-cli req -p xai "/api/courses"
# POST 请求(自动追加 Content-Type: application/json)
auth-cli req -p xai POST /api/courses -d '{"title":"Node.js 架构","status":"draft"}'
# PATCH / PUT 请求,附带自定义请求头
auth-cli req -p xai PATCH /api/courses/item-123 -d '{"status":"published"}' -H "X-Client: cli"
# DELETE 请求
auth-cli req -p xai DELETE /api/courses/item-1234. data - 管理各项目的私有键值存储
为各个项目保存 Agent 上下文或运营状态(如上次处理到的 ID、环境标识等):
# 设置键值
auth-cli data -p xai set defaultSeriesId "series-001"
auth-cli data -p xai set agentContext '{"step":2,"status":"done"}' --json
# 读取键值
auth-cli data -p xai get defaultSeriesId
# 删除键值
auth-cli data -p xai delete defaultSeriesId5. list - 列出所有已配置项目
# 人类友好格式展示
auth-cli list
# JSON 格式输出
auth-cli list --json6. logout - 清除本地会话凭据
auth-cli logout -p xai🛠️ CMS 服务端接入配合
在你的 Payload CMS 项目中,引入 @innerfire/auth-center-server 提供的 createCliAdminEndpoints 并在 payload.config.ts 的 endpoints 中挂载:
import { createCliAdminEndpoints } from "@innerfire/auth-center-server";
import { buildConfig } from "payload";
export default buildConfig({
// ...
endpoints: [
...createCliAdminEndpoints({
path: "/api/cli-auth", // 默认授权端点
loginPath: "/admin/login", // 未登录时 302 重定向登录页
allowOrigins: ["127.0.0.1", "localhost"], // 回环防御白名单
}),
],
});💻 编程式 SDK (Node.js API)
除了命令行以外,自治 Agent 或脚本可以在 Node.js 中直接导入 SDK 函数:
import { loginProject, executeRequest, getSession, listProjects } from "@innerfire/auth-cli";
// 1. 发起 API 请求(无有效会话时自动唤起登录)
const res = await executeRequest({
projectKey: "xai",
method: "POST",
path: "/api/products",
body: JSON.stringify({ name: "Pro Plan", price: 99 }),
});
console.log(res.status, res.body);
// 2. 读取项目会话
const session = await getSession("xai");
console.log("Current user:", session?.userEmail);📂 存储结构规范
默认配置目录位于 ~/.config/innerfire-auth-cli/(可通过 $INNERFIRE_AUTH_CONFIG_DIR 环境变量覆盖):
~/.config/innerfire-auth-cli/
└── projects/
├── xai/
│ ├── project.json # 项目元数据与私有数据 (0644)
│ └── session.json # 管理员凭证 (强制 0600 权限)
└── session-cms/
├── project.json
└── session.json🧪 研发与测试
# 运行单元测试
vp -C packages/auth-cli test
# 检查代码风格与类型
vp -C packages/auth-cli check
# 构建打包
vp -C packages/auth-cli pack