make-app-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

make-app-auth

Use this skill for Make App authentication and authenticated Make API access.

本技能用于 Make App 认证及带认证的 Make API 访问。

Scope

范围

This skill covers:

```
@qfeius/make-app-auth
```
SDK integration
unified login as the default generated/published Make App auth mode
unified login, OAuth, SSO, ngrok, cookie, logout, and callback testing
direct Make gateway
```
/api/make/**
```
authenticated requests
Service-fronted published App auth under the deployed App Service prefix, normally
```
/api/make/auth/**
```
401, 403, and logout behavior
current-context identity normalization and host runtime signals needed by account surfaces
cookie, session, redirect, and callback troubleshooting

This skill does not cover:

UI layout, component design, or Make App page structure; use
```
makeui
```
.
Service build output, packaging, image entrypoints, or publish runtime readiness; use
```
make-app-runtime
```
.
runtime schema normalization, object-field mapping, table rendering, blank-page diagnosis, or business data correctness; use
```
makeui
```
and the host app tests.
DSL modeling or Make resource definitions; use
```
makedsl
```
.
makecli command execution; use
```
makecli
```
.
make-gateway or Org server implementation changes.
single-app permission enforcement; use
```
make-app-permission
```
.

本技能涵盖：

```
@qfeius/make-app-auth
```
SDK 集成
统一登录作为生成/发布的 Make App 默认认证模式
统一登录、OAuth、SSO、ngrok、cookie、登出及回调测试
Make 网关
```
/api/make/**
```
的直接认证请求
已部署 App Service 前缀下的 Service 前置发布应用认证，通常为
```
/api/make/auth/**
```
401、403 及登出行为
账户界面所需的当前上下文身份标准化及宿主运行时信号
cookie、会话、重定向及回调问题排查

本技能不涵盖：

UI 布局、组件设计或 Make App 页面结构；请使用
```
makeui
```
。
Service 构建产物、打包、镜像入口或发布运行时就绪检查；请使用
```
make-app-runtime
```
。
运行时 schema 标准化、对象字段映射、表格渲染、白屏诊断或业务数据正确性；请使用
```
makeui
```
及宿主应用测试。
DSL 建模或 Make 资源定义；请使用
```
makedsl
```
。
makecli 命令执行；请使用
```
makecli
```
。
make-gateway 或 Org 服务端的实现变更。
单应用权限管控；请使用
```
make-app-permission
```
。

Default Behavior

默认行为

Default generated and published Make Apps use unified login with

unifiedLogin: true

apiAuthRedirect: true

, and

auth.init({ redirect: true })

This skill only supports unified login for generated and reviewed Make Apps. Missing unified-login prerequisites are blockers, not reasons to switch modes. Do not generate browser token mode, mock mode, or any no-login bypass from this skill.

Local preview exception: a Service-fronted App may provide a Service-only local preview adapter guarded by

MAKE_APP_LOCAL_PREVIEW=true

. Enable that flag only as a temporary process environment variable from the local dev command, for example

MAKE_APP_LOCAL_PREVIEW=true corepack pnpm run dev

or a project-owned

dev:preview

script. New Make Apps and explicit runtime migrations use the

make-app-runtime

baseline (Node.js

22.20.0

, Corepack

0.34.0

, and

pnpm@10.20.0

through Corepack); existing Apps retain their declared runtime during auth work. Do not persist the flag in

.env

.env.local

.env.example

, generated README setup steps, or deployment environment. The adapter should resolve the effective public Make origin with

makecli configure resolve --target local-preview --output=json

, consume

make_api_origin

, add the browser-facing

/api/make

scope, and attach the token only on Service-to-Make requests. It must not expose the token to UI, must not change the published unified-login contract, and must fail closed in production.

默认生成和发布的 Make App 使用统一登录，配置为

unifiedLogin: true

、

apiAuthRedirect: true

及

auth.init({ redirect: true })

。

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

本地预览例外：Service 前置应用可提供一个仅 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 使用

pnpm@10.20.0

）；现有应用在认证开发期间保留其声明的运行时版本。不得将该标志持久化到

.env

、

.env.local

、

.env.example

、生成的 README 配置步骤或部署环境中。适配器应通过

makecli configure resolve --target local-preview --output=json

解析有效的公开 Make 源站，读取

make_api_origin

，添加面向浏览器的

/api/make

作用域，且仅在 Service 向 Make 发起请求时附加 token。严禁将 token 暴露给 UI，不得修改已发布的统一登录契约，生产环境必须默认失败关闭。

Hard Rules

硬性规则

Always use
```
@qfeius/make-app-auth
```
; do not fork a separate auth implementation.
Direct-gateway business requests to Make backend must go through
```
auth.api
```
under
```
/api/make/**
```
.
Ordinary frontend Make backend requests go through
```
auth.api
```
, including schema/meta, record CRUD, ordinary file/lookup/user/department requests. The fixed Make App AI v1
```
/client
```
contract is a narrow exception: its
```
AuthenticatedTransport
```
needs HTTP status, headers and raw
```
AsyncIterable<Uint8Array>
```
for 202/204, SSE and file bytes, which
```
auth.api
```
does not expose. Implement that bridge only under same-origin
```
/api/make/app/ai/v1/**
```
inside the shared authenticated adapter, preserve unified-login cookie handling, and follow
```
make-ai-assistant
```
for its exact scope and lifecycle. This does not authorize generic raw fetch for other
```
/api/make/**
```
calls.
Generated Apps must centralize Make backend access in a shared API adapter or data-source layer that wraps
```
auth.api
```
.
Every new Make App's shared authenticated business-request adapter must apply the
```
make-app-observability
```
Trace ID contract: send
```
traceparent
```
and matching
```
X-Log-Id
```
without exposing tokens or changing unified-login behavior. Authentication remains owned here; Trace generation, propagation, and error display belong to
```
make-app-observability
```
.
Service-fronted Apps must preserve the
```
UI -> Service -> make-gateway
```
contract; do not let UI bypass Service for meta/data calls.
Service-fronted Apps must preserve this contract for the default permission call. UI uses
```
auth.api("/app/principal/permission")
```
, and the single-app permission behavior belongs to
```
make-app-permission
```
.
Service-fronted published Apps use
```
gatewayBaseUrl: "/api/make"
```
in UI. UI calls
```
auth.api("/app/**")
```
, which becomes browser requests to
```
/api/make/app/**
```
. Auth bootstrap and OAuth callbacks must stay under
```
/api/make/auth/**
```
and
```
/api/make/oauth/**
```
; do not generate
```
/api/auth/**
```
,
```
/api/oauth/**
```
, or
```
gatewayBaseUrl: "/api"
```
for this mode.
Do not scatter raw
```
window.fetch('/api/make/...')
```
in UI components or for ordinary Make business APIs. The AI v1
```
AuthenticatedTransport
```
bridge above is the sole raw-response exception; reject arbitrary origins/scopes and never read browser tokens or cookies in App code.
Do not hand-write
```
Authorization
```
.
Browser resource requests such as
```
<img src>
```
,
```
<object data>
```
, and plain
```
<a href>
```
cannot attach custom
```
Authorization
```
headers. If a Make file download requires a bearer token, UI must use a same-origin Service download proxy URL, and the Service must validate the current App session before using any deployment-injected download token.
```
gatewayBaseUrl
```
is the SDK option for the Make backend API base. Reuse the host Make backend config first; for local preview, prefer
```
makecli configure resolve --target local-preview --output=json
```
and its
```
make_api_origin
```
field instead of creating a second environment concept for the same URL.
```
gatewayBaseUrl
```
is not the unified login or account-center URL. Prefer
```
/api/make
```
for both same-origin direct-gateway Apps and Service-fronted published Apps; the difference is whether UI business calls use direct Make backend paths such as
```
/data/**
```
or Service-owned paths such as
```
/app/**
```
.
Do not configure or hard-code unified login, Org, or account-center URLs in generated App code; make-gateway returns those URLs.
Do not read, write, persist, or delete
```
zs_session
```
or
```
make_app_session
```
in App code.
Do not construct Org OAuth URLs,
```
redirect_uri
```
,
```
state
```
,
```
code_challenge
```
, token exchange, or Org logout URLs in generated App code.
Browser code cannot read
```
~/.make/credentials
```
.
Do not generate browser-side
```
unifiedLogin: false
```
,
```
accessToken
```
,
```
token
```
,
```
tokenProvider
```
, local credential loading,
```
VITE_MAKE_AUTH_MODE=token
```
, or equivalent token-mode switches.
Service-only local preview may use makecli credentials only behind a temporary process-level
```
MAKE_APP_LOCAL_PREVIEW=true
```
; do not persist this flag in env files or generated docs. Local preview must use
```
makecli configure resolve --target local-preview --output=json
```
, call
```
make_api_origin + /api/make
```
, and published runtime must call the k8s-internal gateway with
```
/make
```
. current-context/runtime-view must be explicit preview responses, route matching must ignore query strings such as
```
return_url
```
, and business requests must attach the token only inside Service.
Local preview auth routes must not shadow published auth proxy routes. In published runtime,
```
/api/make/auth/current-context
```
and
```
/api/make/auth/runtime-view
```
must reach make-gateway through the auth namespace proxy and must not return
```
localPreview
```
,
```
local-preview-user
```
,
```
authMode: "token"
```
, or other preview context.
Do not silently downgrade generated Apps from unified login because local OAuth prerequisites are missing; report the blocker.
Before reporting publish/login readiness, verify the auth path with the agent or platform checks. Do not leave domain access, DevTools, k8s logs, or cookie inspection as user-only validation steps.
For Service-fronted Apps,
```
/api/make/auth/**
```
and
```
/api/make/oauth/**
```
are required namespace-level Service proxy contracts under the published App Service prefix, not optional convenience routes or endpoint-by-endpoint allowlists.
Every Service-fronted Make App must ensure the default
```
/api/make/app/principal/permission
```
route receives the established browser session context.
Do not implement auth readiness by adding a broad
```
/api/make/**
```
passthrough. Only auth/oauth are default transparent namespaces; Service-owned business requests stay under explicit
```
/api/make/app/**
```
routes, and unknown
```
/api/make/**
```
paths fail closed.
For Service-fronted Apps, Service must preserve the App host context for every make-gateway call: derive
```
X-Forwarded-Host
```
from inbound
```
Host
```
, do not trust client-supplied
```
X-Forwarded-Host
```
, add
```
X-Forwarded-Proto
```
, and share the same helper for auth and business proxy requests.
Preserve display identity from authenticated current-context responses, including
```
name
```
,
```
avatar
```
, and
```
tenantName
```
, while keeping it untrusted for server authorization. The mobile account drawer consumes this normalized identity through
```
makeui
```
; do not discard
```
tenantName
```
merely because desktop UI does not render it.
生成的认证 App 壳层必须在当前用户菜单或宿主既有账户区域提供调用
```
auth.logout()
```
的退出操作。视觉表面归
```
makeui
```
，本 Skill 负责认证 handler 与退出行为。标准例外是检测到的飞书容器：移动账户表面隐藏退出入口，但不得删除或替换认证 handler。不得通过清理 cookie、重写 Org URL，或在无关页面操作中隐藏退出实现该行为。
Keep Feishu-container detection in one pure, tested host helper. Prefer an established host/runtime signal; otherwise check
```
window.lark
```
,
```
window.feishu
```
, or
```
window.LarkJSBridge
```
, then use a case-insensitive
```
Lark|Feishu
```
user-agent match only as fallback. Do not infer the container from
```
tenantName
```
, deployment environment, screen width, or the mobile package. Pass the resulting boolean to the
```
makeui
```
account surface.
Generated Apps must handle recoverable unified-login expiry: when SDK init returns
```
reason: "state_expired"
```
or
```
reason: "challenge_expired"
```
, show a relogin prompt and call
```
auth.login({ redirect: true })
```
from user action.

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

Pre-flight Workflow

前置检查工作流

Use unified login. If unified-login prerequisites are missing, report the blocker instead of switching modes.
Read
```
references/sdk-integration.md
```
before generating or changing auth code.
Read the relevant mode reference unless troubleshooting requires more.
- Default unified login:
```
references/unified-login-mode.md
```
- 401, 403, logout:
```
references/logout-and-401.md
```
- Incident/debugging:
```
references/troubleshooting.md
```
Read
```
references/service-fronted-mode.md
```
when the App keeps a Service layer between UI and make-gateway.
Read
```
references/request-adapter.md
```
whenever generating or reviewing Make backend requests.
Keep auth bootstrap thin. Business features must consume the project Make API adapter and auth state, not auth internals.
Before claiming publish/login readiness, verify the auth path: current-context route, unified redirect, session callback, cookie-preserving business requests, and Service-fronted auth proxy when applicable.
Run
```
scripts/audit-auth-contract.mjs <project-root> --published
```
for generated Apps when a project tree is available; use
```
--mode service-fronted
```
when the App keeps a Service layer.
When changing generated code, add or update tests for the touched auth path: unauthenticated session, expired session, 403, logout, unified-login redirect, callback proxy, business-request 401 handling, current-context identity normalization, or normal-browser/Feishu account visibility.

使用统一登录。如果缺少统一登录前置条件，上报阻塞问题而非切换模式。
在生成或修改认证代码前，阅读
```
references/sdk-integration.md
```
。
阅读相关模式的参考文档，除非问题排查需要更多内容。
- 默认统一登录：
```
references/unified-login-mode.md
```
- 401、403、登出：
```
references/logout-and-401.md
```
- 事件/调试：
```
references/troubleshooting.md
```
当应用在 UI 和 make-gateway 之间保留 Service 层时，阅读
```
references/service-fronted-mode.md
```
。
每当生成或审查 Make 后端请求时，阅读
```
references/request-adapter.md
```
。
保持认证引导逻辑轻量。业务功能必须使用项目的 Make API 适配器和认证状态，而非直接依赖认证内部实现。
在声明发布/登录就绪前，验证认证路径：current-context 路由、统一重定向、会话回调、保留 cookie 的业务请求，以及（如适用）Service 前置认证代理。
当项目目录可用时，对生成的应用运行
```
scripts/audit-auth-contract.mjs <project-root> --published
```
；如果应用保留 Service 层，使用
```
--mode service-fronted
```
。
修改生成的代码时，为涉及的认证路径添加或更新测试：未认证会话、过期会话、403、登出、统一登录重定向、回调代理、业务请求 401 处理、current-context 身份标准化，或普通浏览器/飞书账户可见性。

Reference Selection

参考文档选择

SDK contract and request wrapper:
```
references/sdk-integration.md
```
Shared request adapter and 401/403 handling:
```
references/request-adapter.md
```
Default unified login mode:
```
references/unified-login-mode.md
```
Service-fronted unified-login mode:
```
references/service-fronted-mode.md
```
401, 403, and logout behavior:
```
references/logout-and-401.md
```
Auth incident diagnosis:
```
references/troubleshooting.md
```

Minimal Service-fronted route-shape example:

references/service-fronted-node-example.md

; read it only after

references/service-fronted-mode.md

SDK 契约与请求封装：
```
references/sdk-integration.md
```
共享请求适配器与 401/403 处理：
```
references/request-adapter.md
```
默认统一登录模式：
```
references/unified-login-mode.md
```
Service 前置统一登录模式：
```
references/service-fronted-mode.md
```
401、403 及登出行为：
```
references/logout-and-401.md
```
认证事件诊断：
```
references/troubleshooting.md
```

最简 Service 前置路由形态示例：

references/service-fronted-node-example.md

；仅在阅读

references/service-fronted-mode.md

后阅读。

Deterministic Checks

确定性检查

Use

scripts/audit-auth-contract.mjs

on generated App projects to catch contract drift before publish:

bash

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

The audit is auth-scoped. It checks unified-login readiness, raw

/api/make

fetch usage, Service-fronted

/api/make/auth/**

and

/api/make/oauth/**

namespace proxy presence, local-preview auth shadowing, broad

/api/make/**

passthrough risk, and obvious direct-vs-Service route mismatches. It does not verify schema rendering or UI blank-page behavior.

Audit expectations:

UI design-system theme fields named
```
token
```
are not auth token mode. Only flag token-mode options inside auth configuration, auth environment switches, browser credential access, or explicit
```
authMode: "token"
```
paths.
Service namespace proxies may be expressed as direct string routes, constants,
```
.startsWith(...)
```
, or equivalent regex route mounts, as long as
```
/api/make/auth/**
```
and
```
/api/make/oauth/**
```
map to internal
```
/make/auth/**
```
and
```
/make/oauth/**
```
.
Cookie forwarding may use
```
req.headers.cookie
```
,
```
req.header("cookie")
```
, Fetch
```
headers.get("cookie")
```
, or an equivalent inbound-header adapter.
Keep tests in
```
scripts/test-audit-auth-contract.mjs
```
updated when changing audit heuristics, especially for false-positive and false-negative cases discovered in generated Apps.

对生成的应用项目使用

scripts/audit-auth-contract.mjs

，可在发布前发现契约偏移：

bash

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 前置

/api/make/auth/**

和

/api/make/oauth/**

命名空间代理是否存在、本地预览认证路由遮蔽、宽泛

/api/make/**

透传风险，以及明显的直连与 Service 路由不匹配问题。它不会验证 schema 渲染或 UI 白屏行为。

审计预期：

UI 设计系统主题中名为
```
token
```
的字段不属于认证 token 模式。仅标记认证配置、认证环境开关、浏览器凭证访问或明确的
```
authMode: "token"
```
路径中的 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
```
中的测试更新，尤其是针对生成应用中发现的误报和漏报情况。

Collaboration With makeui

与 makeui 的协作

When

makeui

is generating or editing Make App frontend code, this skill owns all authentication decisions.

makeui

may design UI states around auth results, but it must not invent OAuth, cookie, token, logout, or

/api/make/**

request logic.

make-app-auth

reports whether the user is authenticated, unauthenticated, forbidden, expired, or blocked by an auth proxy/callback problem. It should not diagnose schema shape mismatches, missing fields, render crashes, white screens, or record-table behavior after authenticated Make requests are already reaching the backend.

当

makeui

生成或编辑 Make App 前端代码时，本技能拥有所有认证相关的决策权。

makeui

可以围绕认证结果设计 UI 状态，但不得自行实现 OAuth、cookie、token、登出或

/api/make/**

请求逻辑。

make-app-auth

负责报告用户是否已认证、未认证、被禁止、已过期，或因认证代理/回调问题被阻塞。它不应诊断 schema 形态不匹配、字段缺失、渲染崩溃、白屏，或已认证的 Make 请求到达后端后的记录表格行为问题。