IWish Auth开发者文档
V1 Alpha GitHub
Manifest 与权限/Manifest 规范

Manifest 规范

声明 App、权限和角色的稳定契约

auth.manifest.json 是 App 权限和角色的唯一声明契约。它属于业务 App 代码仓库，必须和功能代码一起评审、测试和版本化。

1. 完整示例

{
  "$schema": "https://auth-docs-staging.iwishapp.cn/auth-manifest.schema.json",
  "schemaVersion": "1.0",
  "appKey": "crm",
  "name": "CRM 系统",
  "description": "销售客户与联系人管理",
  "environment": "dev",
  "manifestVersion": "2026.07.20-1",
  "permissions": [
    { "key": "crm.access", "name": "访问 CRM" },
    { "key": "crm.contact.read", "name": "查看联系人" },
    { "key": "crm.contact.write", "name": "编辑联系人" }
  ],
  "roles": [
    {
      "key": "crm.viewer",
      "name": "CRM 查看者",
      "permissions": ["crm.access", "crm.contact.read"]
    },
    {
      "key": "crm.admin",
      "name": "CRM 管理员",
      "permissions": ["crm.access", "crm.contact.read", "crm.contact.write"]
    }
  ]
}

2. 顶层字段

字段规则
$schema指向 IWish Auth 发布的 Manifest JSON Schema
schemaVersionManifest 契约版本，当前为 1.0
appKey全局唯一、全小写，发布后不可随意变更
name中文产品名称，用于 Admin、Portal 和审计
description说明 App 业务边界，不写营销文案
environmentdev、staging 或 prod
manifestVersion每次同步唯一，推荐日期加递增序号
permissions当前版本声明的权限点
rolesApp 提供的角色模板

3. 权限字段

权限 key 使用 {app}.{resource_path}.{action}，每个 App 必须包含 {app}.access。resource_path 至少包含一个稳定资源段，必要时可以使用多段层级资源，例如 auth.apps.sso.manage；Auth 将最后一段解析为 action，中间所有段合并为 resource。这些派生值不在权限对象中重复声明；name 是管理后台展示的中文名称。

不要把部门、客户 ID、用户 ID 或环境写入 permission key。

4. 角色字段

角色 key 必须位于当前 App 命名空间，例如 crm.viewer。角色只引用同一 Manifest 中存在的 permission key，不能引用其他 App 权限，也不能重复引用。

角色是权限集合模板，不是业务数据范围。不要创建 client_acme_viewer、east_china_sales 等带数据范围的角色。

5. 本地校验

npx iwish-auth manifest validate ./auth.manifest.json
npx iwish-auth manifest validate ./auth.manifest.json --environment staging --json

校验会检查 JSON、Schema、重复权限/角色、命名空间、角色引用和环境。

6. 远程预检和同步

先执行不带 --yes 的远程预检：

npx iwish-auth manifest sync ./auth.manifest.json

确认 diff 和风险后同步：

npx iwish-auth manifest sync ./auth.manifest.json --yes

CLI 只从 IWISH_AUTH_ADMIN_TOKEN 或 --token-env 指定的环境变量读取 token，不支持命令行明文 token 参数。

Manifest 写入必须走 Admin API。CLI 的远程预检调用 POST /v1/admin/apps/{appKey}/manifest/validate，确认同步调用 POST /v1/admin/apps/{appKey}/manifest/sync；调用者必须具有 auth.manifest.write。旧公开写入端点只返回迁移错误，不允许业务 App 绕过治理流程直接写入。

7. 删除和废弃

从 Manifest 移除权限或角色是高风险变更。同步只会给出风险提示，不会自动删除或停用数据库中的既有权限和授权关系。

正确流程：

  1. 新权限与旧权限并行发布。
  2. 更新业务代码和角色模板。
  3. 迁移已有授权。
  4. 观察一个完整迁移周期。
  5. 标记旧权限 deprecated。
  6. 确认无引用后由平台管理员处理停用。

8. 生产变更要求

  • Manifest diff 必须进入代码审查。
  • manifestVersion 不得覆盖已同步版本。
  • prod 同步需要平台管理员或 App owner 审核。
  • 破坏性变更必须提供影响清单和回滚 Manifest。
  • 同步操作会写入审计日志。