make-app-auth

make-app-auth

在更改任何禁止访问的页面或 403 处理程序之前，请先阅读 references/access-help.md。保留拒绝访问的负载和范围；独立的当前 App 管理员帮助不代表获得业务访问权限。React 反馈使用 makeui/references/permission-feedback.md 中经验证的包；身份验证不会渲染或设置拒绝访问页面的样式。

管理员查询是分阶段发布过程中的可选增强功能：如果缺少 SDK 方法或端点尚未部署，应保留通用授权指引，而不是将其视为登录或 App 就绪性失败。现有身份验证/IAM 要求仍然适用。

将启动拒绝访问分类器与业务拒绝访问分类器分开。auth.init() 返回 status: 'forbidden' 时，即使没有 payload.reason，也应渲染 App 入口反馈；不得将 request-adapter.md 中的业务请求分类器用作额外的启动门槛。请参阅 references/sdk-integration.md#startup-shape。

在Make App 身份验证和经过身份验证的 Make API 访问场景中使用此技能。

范围

此技能涵盖：

• @qfeius/make-app-auth SDK 集成
• 统一登录作为生成/发布的 Make App 的默认身份验证模式
• 统一登录、OAuth、SSO、ngrok、Cookie、注销和回调测试
• 直接向 Make 网关 /api/make/** 发送经过身份验证的请求
• 在已部署的 App Service 前缀下由 Service 提供服务的已发布 App 身份验证，通常为 /api/make/auth/**
• 401、403 和注销行为
• 当前上下文的身份规范化，以及账户界面所需的宿主运行时信号
• Cookie、会话、重定向和回调故障排查

此技能不涵盖：

• UI 布局、组件设计或 Make App 页面结构；请使用 makeui。
• Service 构建输出、打包、镜像入口点或发布运行时就绪性；请使用 make-app-runtime。
• 运行时架构规范化、对象字段映射、表格渲染、空白页面诊断或业务数据正确性；请使用 makeui 和宿主 App 测试。
• DSL 建模或 Make 资源定义；请使用 makedsl。
• makecli 命令执行；请使用 makecli。
• make-gateway 或 Org 服务端实现更改。
• 单 App 权限强制执行；请使用 make-app-permission。

默认行为

默认生成和发布的 Make App 使用统一登录，并设置 unifiedLogin: true、apiAuthRedirect: true，以及调用 auth.init({ redirect: true })。

此技能仅支持生成和审查 Make App 时使用统一登录。缺少统一登录前置条件属于阻塞问题，不能作为切换模式的理由。不得通过此技能生成浏览器令牌模式、模拟模式或任何免登录绕过方式。

本地预览例外：由 Service 提供服务的 App 可以使用仅限 Service 的本地预览适配器，并通过 MAKE_APP_LOCAL_PREVIEW=true 进行保护。仅可通过本地开发命令，将此标志作为临时进程环境变量启用，例如 MAKE_APP_LOCAL_PREVIEW=true corepack pnpm run dev 或项目自有的 dev:preview 脚本。新建 Make App 和明确的运行时迁移使用 make-app-runtime 基线（Node.js 22.20.0、Corepack 0.34.0，以及通过 Corepack 使用的 [email protected]）；进行身份验证工作时，现有 App 保留其声明的运行时。不得将此标志持久化到 .env、.env.local、.env.example、生成的 README 设置步骤或部署环境中。适配器应使用 makecli configure resolve --target local-preview --output=json 解析生效的公开 Make 源站，读取 make_api_origin，添加面向浏览器的 /api/make 范围，并且仅在 Service 到 Make 的请求中附加令牌。不得向 UI 暴露令牌，不得更改已发布的统一登录约定，并且必须在生产环境中默认拒绝访问。

硬性规则

• 始终使用 @qfeius/make-app-auth；不得分叉实现单独的认证方案。
• 发往 Make 后端的直连网关业务请求必须通过 /api/make/** 下的 auth.api 发出。
• 普通前端 Make 后端请求必须通过 auth.api 发出，包括 schema/meta、记录 CRUD、普通文件/查找/用户/部门请求。固定的 Make App AI v1 /client 契约是一个范围有限的例外：其 AuthenticatedTransport 需要 HTTP 状态码、响应头，以及用于 202/204、SSE 和文件字节的原始 AsyncIterable<Uint8Array>，而 auth.api 不提供这些内容。仅在共享的认证适配器内，通过同源 /api/make/app/ai/v1/** 实现该桥接，保留统一登录 Cookie 处理，并遵循 make-ai-assistant 中规定的精确范围和生命周期。这并不授权其他 /api/make/** 调用使用通用原始 fetch。
• 生成的 App 必须在共享 API 适配器或数据源层集中处理 Make 后端访问，并由其封装 auth.api。
• 每个新 Make App 的共享认证业务请求适配器都必须应用 make-app-observability 的 Trace ID 契约：发送 traceparent 和匹配的 X-Log-Id，不得暴露令牌或更改统一登录行为。认证仍由此处负责；Trace 的生成、传递和错误显示属于 make-app-observability。
• 由 Service 提供服务的 App 必须保留 UI -> Service -> make-gateway 契约；不得让 UI 绕过 Service 调用 meta/data。
• 由 Service 提供服务的 App 必须为默认权限调用保留此契约。UI 使用 auth.api("/app/principal/permission")，单应用权限行为由 make-app-permission 负责。
• 使用 Service 提供服务的已发布 App 在 UI 中使用 gatewayBaseUrl: "/api/make"。UI 调用 auth.api("/app/**")，这会转换为发往 /api/make/app/** 的浏览器请求。认证初始化和 OAuth 回调必须位于 /api/make/auth/** 和 /api/make/oauth/** 下；此模式下不得生成 /api/auth/**、/api/oauth/** 或 gatewayBaseUrl: "/api"。
• 不得在 UI 组件中或普通 Make 业务 API 调用中散布原始 window.fetch('/api/make/...')。上述 AI v1 AuthenticatedTransport 桥接是唯一的原始响应例外；拒绝任意来源/范围，并且绝不在 App 代码中读取浏览器令牌或 Cookie。
• 不得手写 Authorization。
• <img src>、<object data> 和普通 <a href> 等浏览器资源请求无法附加自定义 Authorization 请求头。如果 Make 文件下载需要 bearer 令牌，UI 必须使用同源 Service 下载代理 URL，且 Service 在使用任何由部署注入的下载令牌前必须验证当前 App 会话。
• gatewayBaseUrl 是 Make 后端 API 基址的 SDK 选项。优先复用宿主 Make 后端配置；本地预览时，优先使用 makecli configure resolve --target local-preview --output=json 及其 make_api_origin 字段，而不是为同一个 URL 创建第二种环境概念。
• gatewayBaseUrl 不是统一登录或账户中心 URL。对于同源直连网关 App 和由 Service 提供服务的已发布 App，都优先使用 /api/make；两者的区别在于 UI 业务调用使用 /data/** 等直连 Make 后端路径，还是 /app/** 等由 Service 管理的路径。
• 不得在生成的 App 代码中配置或硬编码统一登录、Org 或账户中心 URL；这些 URL 由 make-gateway 返回。
• 不得在 App 代码中读取、写入、持久化或删除 zs_session 或 make_app_session。
• 不得在生成的 App 代码中构造 Org OAuth URL、redirect_uri、state、code_challenge、令牌交换或 Org 登出 URL。
• 浏览器代码无法读取 ~/.make/credentials。
• 不得在浏览器端生成 unifiedLogin: false、accessToken、token、tokenProvider、本地凭据加载、VITE_MAKE_AUTH_MODE=token 或等效的令牌模式开关。
• 仅限 Service 的本地预览可以使用 makecli 凭据，但必须在临时的进程级 MAKE_APP_LOCAL_PREVIEW=true 后才可使用；不得在 env 文件或生成的文档中持久化此标志。本地预览必须使用 makecli configure resolve --target local-preview --output=json，调用 make_api_origin + /api/make；已发布的运行时必须使用带有 /make 的 k8s 内部网关。current-context/runtime-view 必须是明确的预览响应；路由匹配必须忽略 return_url 等查询字符串；业务请求只能在 Service 内附加令牌。
• 本地预览认证路由不得遮蔽已发布的认证代理路由。在已发布的运行时中，/api/make/auth/current-context 和 /api/make/auth/runtime-view 必须通过 auth 命名空间代理到达 make-gateway，且不得返回 localPreview、local-preview-user、authMode: "token" 或其他预览上下文。
• 使用 auth current-context 的 Service 消费方应遵循 references/service-fronted-mode.md#current-context-consumption，不得使用 Meta/Data 信封解析器。Auth 命名空间代理必须保持透明。
• 不得因缺少本地 OAuth 前置条件，就静默地将生成的 App 从统一登录降级；应报告阻碍因素。
• 在报告发布/登录已就绪前，必须通过 Agent 或平台检查验证认证路径。不得把域名访问、DevTools、k8s 日志或 Cookie 检查留作仅由用户执行的验证步骤。
• 对于由 Service 提供服务的 App，/api/make/auth/** 和 /api/make/oauth/** 是已发布 App Service 前缀下必需的命名空间级 Service 代理契约，而不是可选的便利路由或逐端点允许列表。
• 每个由 Service 提供服务的 Make App 都必须确保默认的 /api/make/app/principal/permission 路由能够接收到既有的浏览器会话上下文。
• 不得通过添加宽泛的 /api/make/** 透传来实现认证就绪。只有 auth/oauth 是默认透明的命名空间；由 Service 管理的业务请求必须位于明确的 /api/make/app/** 路由下，未知的 /api/make/** 路径必须默认拒绝。
• 对于由 Service 提供服务的 App，Service 必须为每个 make-gateway 调用保留 App 主机上下文：从入站 Host 派生 X-Forwarded-Host，不得信任客户端提供的 X-Forwarded-Host，添加 X-Forwarded-Proto，并为 auth 和业务代理请求共用同一个 helper。
• 保留经过身份验证的 current-context 响应中的展示身份信息，包括 name、avatar 和 tenantName，同时在服务器授权时将其视为不可信信息。移动账户抽屉通过 makeui 使用此规范化身份；不得仅仅因为桌面 UI 不显示 tenantName 就将其丢弃。
• 生成的认证 App 壳层必须在当前用户菜单或宿主既有账户区域中提供调用 auth.logout() 的退出操作。视觉呈面由 makeui 负责；本 Skill 负责认证 handler 与退出行为。标准例外是检测到的飞书容器：移动账户界面隐藏退出入口，但不得删除或替换认证 handler。不得通过清理 Cookie、重写 Org URL，或在无关页面操作中隐藏退出入口来实现该行为。
• 将飞书容器检测集中在一个纯函数且经过测试的宿主 helper 中。优先使用已有的宿主/运行时信号；否则检查 window.lark、window.feishu 或 window.LarkJSBridge，然后仅将不区分大小写的 Lark|Feishu 用户代理匹配用作后备方案。不得根据 tenantName、部署环境、屏幕宽度或移动端包推断容器。将结果布尔值传给 makeui 账户界面。
• 生成的 App 必须处理可恢复的统一登录过期情况：当 SDK 初始化返回 reason: "state_expired" 或 reason: "challenge_expired" 时，显示重新登录提示，并在用户操作时调用 auth.login({ redirect: true })。

预检工作流

1. 使用统一登录。如果缺少统一登录的前置条件，请报告阻塞原因，而不要切换模式。
2. 在生成或更改身份验证代码之前，阅读 references/sdk-integration.md。
3. 阅读相关模式的参考文档，除非排查问题需要阅读更多内容。
   • 默认统一登录：references/unified-login-mode.md
   • 401、403、登出：references/logout-and-401.md
   • 事件/调试：references/troubleshooting.md
4. 如果 App 在 UI 与 make-gateway 之间保留 Service 层，请阅读 references/service-fronted-mode.md。
5. 在生成或审查 Make 后端请求时，务必阅读 references/request-adapter.md。
6. 保持身份验证引导流程精简。业务功能必须使用项目的 Make API 适配器和身份验证状态，而不是直接依赖身份验证内部实现。
7. 在声称已具备发布/登录条件之前，验证身份验证路径：current-context 路由、统一登录重定向、会话回调、保留 Cookie 的业务请求，以及适用时的 Service-fronted 身份验证代理。
8. 如果有项目目录，则对生成的 App 运行 scripts/audit-auth-contract.mjs <project-root> --published；如果 App 保留 Service 层，则使用 --mode service-fronted。
9. 更改生成的代码时，为修改的身份验证路径添加或更新测试：未认证会话、过期会话、403、登出、统一登录重定向、回调代理、业务请求的 401 处理、current-context 身份规范化，或普通浏览器/飞书账号可见性。

参考文档选择

• SDK 契约和请求封装：references/sdk-integration.md
• 共享请求适配器及 401/403 处理：references/request-adapter.md
• 默认统一登录模式：references/unified-login-mode.md
• Service-fronted 统一登录模式：references/service-fronted-mode.md
• 401、403 和登出行为：references/logout-and-401.md
• 身份验证事件诊断：references/troubleshooting.md
• 最精简的 Service-fronted 路由结构示例：references/service-fronted-node-example.md；仅在阅读 references/service-fronted-mode.md 后阅读此文档。

确定性检查

对生成的 App 项目使用 scripts/audit-auth-contract.mjs，在发布前发现契约偏差：

node skills/make-app-auth/scripts/audit-auth-contract.mjs <project-root> --published
node skills/make-app-auth/scripts/audit-auth-contract.mjs <project-root> --mode service-fronted --published

此审计仅针对身份验证。它会检查统一登录就绪情况、原始 /api/make fetch 用法、Service-fronted /api/make/auth/** 和 /api/make/oauth/** 命名空间代理是否存在、本地预览中的身份验证覆盖、宽泛的 /api/make/** 透传风险，以及明显的直接路由与 Service 路由不匹配。它不会验证 schema 渲染或 UI 空白页行为。

对于已使用 current-context 的主要路由，请针对其生产处理程序运行 scripts/current-context-conformance-suite.mjs <host-adapter-module>；参见 references/service-fronted-mode.md#current-context-consumption。无需为其他路由添加身份验证请求。

审计预期：

• UI 设计系统中名为 token 的主题字段不属于身份验证 token 模式。仅标记身份验证配置中的 token 模式选项、身份验证环境开关、浏览器凭据访问，或显式的 authMode: "token" 路径。
• Service 命名空间代理可以使用直接字符串路由、常量、.startsWith(...) 或等效的正则路由挂载，只要 /api/make/auth/** 和 /api/make/oauth/** 分别映射到内部的 /make/auth/** 和 /make/oauth/**。
• Cookie 转发可以使用 req.headers.cookie、req.header("cookie")、Fetch 的 headers.get("cookie")，或等效的入站请求头适配器。
• 更改审计启发式规则时，及时更新 scripts/test-audit-auth-contract.mjs 中的测试，尤其是生成的 App 中发现误报和漏报时。

与 makeui 协作

当 makeui 生成或编辑 Make App 前端代码时，所有身份验证相关决策均由此技能负责。makeui 可以根据身份验证结果设计 UI 状态，但不得自行编写 OAuth、cookie、令牌、注销或 /api/make/** 请求逻辑。

make-app-auth 会报告用户是否已通过身份验证、未通过身份验证、被拒绝访问、身份验证已过期，或因身份验证代理／回调问题而受阻。对于身份验证通过的 Make 请求已到达后端之后出现的架构形状不匹配、缺失字段、渲染崩溃、白屏或记录表行为问题，它不应进行诊断。