---
url: /docs/adr/001-auth-hint-cookie.md
---
# 决策 001：认证提示 Cookie

**状态：** 原路由决策已被当前公开首页策略替代；设置和清除钩子仍保留。

**原决策日期：** 2025-12-28。**当前说明核对日期：** 2026-10-09。

## 原问题与方案

上游项目希望边缘入口快速根据登录提示选择首页，不读取完整会话，也不向认证服务发额外查询。原方案在新会话时写入值为 `1` 的提示 cookie，退出或会话无效时清除。

HTTPS 使用 `__Host-auth`，本地 HTTP 使用 `auth`，因为浏览器不接受缺少安全连接的 `__Host-` cookie。

## 当前行为

AgentBuff Stack 的 `/` 始终返回公开 Astro 页面，工作台位于 `/dashboard`。`apps/web/worker.ts` 不再根据提示 cookie 切换首页。设置和清除逻辑仍在 `apps/api/lib/auth.ts`，但不能依据它决定用户权限。

## 安全边界

提示 cookie 只表示可能存在会话，不能证明有效登录。工作台从统一会话查询读取真实身份，私有接口由服务端验证会话、成员和数据归属。

## 取舍

公开入口不承担认证逻辑，静态页面稳定返回，有利于搜索访问与分享。保留旧钩子需要维护，但不应将历史行为误写成现行路由说明。

相关教程：[边缘路由与绑定](../architecture/edge.md)、[会话与访问控制](../auth/sessions.md)。

## 独立产品预览中的命名

2026-10-09：登录提示 Cookie 改为 `<site.id>.auth`，HTTPS 环境使用 `__Host-<site.id>.auth`。Better Auth 会话 Cookie 已按站点 ID 设置前缀。提示本身仍不是权限判断依据；公开边缘路由不读取提示决定访问权限。

多个 localhost 端口共用 Cookie 范围，因此每个独立产品必须具有唯一站点 ID。端口、数据库、认证 secret 和邮件记录也分别配置。