bff-entry-points

用途

bff-entry-points 用于设计和保护面向浏览器的 BFF（Backend for Frontend）与后端 HTTP 入口点。BFF 是一个驱动型宿主：它拥有面向浏览器的 HTTP 边界，并代表某个用户体验调用应用操作。本技能负责该边界的行为安全模型——谁可以调用每个入口点、如何通过构造方式强制执行，以及当调用方不是浏览器时应用如何保持安全。它遵循 IETF 针对基于浏览器的应用的 BCP 轨道指南：令牌保留在服务端，浏览器只持有会话 Cookie。

主要能力

显式访问分类：每个生产入口点都必须声明其访问分类，没有隐式默认值。未分类的路由是构建失败，而不是“由碰巧先运行的中间件保护”。面向浏览器的 HTTP 端点最低分类包括 public、protected-read、protected-browser-mutation，以及用于原始 WebSocket 升级的 protected-upgrade。
预置注册器（深层模块）：组合层一次性准备注册器，提供端点绝不能自行选择的内容：会话解析、浏览器请求策略、安全错误转换（RFC 9457 问题详情，不含内部信息）和遥测。端点所有者只提供契约和轻量处理器。
派生目录：不手工维护中央路由安全映射，而是从特性本地的端点契约和显式生产组合中派生中央入口目录。注册器记录每次挂载，目录是其输出而非输入。
请求排序：为受保护读取和受保护浏览器变更定义了明确的检查顺序，包括会话解析、401 返回、应用内授权、Origin/Fetch Metadata/内容类型检查、CSRF 校验、正文验证和效果执行。
六边形职责划分：BFF 作为驱动适配器，拥有 Cookie、请求头、会话解析、策略和协议响应；应用操作独立授权主体，不依赖 Hono、Cookie、Keycloak、OAuth 令牌等。
受保护的实时入口点：支持受保护的 SSE 流和受保护的 WebSocket 升级注册。
浏览器会话协调：提供单一的浏览器端认证协调器。
自动化强制门禁：通过测试将目录与框架路由表和生成的 OpenAPI 文档进行核对，实现自动化中央可见性。

使用方式

在实现前阅读相关参考文档：references/endpoint-protection.md（端点契约形状、会话 Cookie 配置、Origin/Fetch Metadata/CSRF/内容类型策略、派生入口目录）、references/hexagonal-auth-boundaries.md（AuthenticatedPrincipal、应用内授权、参与者映射、行级安全）、references/realtime-entry-points.md（受保护 SSE 流和受保护 WebSocket 升级注册器）、references/browser-session-coordination.md（单一浏览器端认证协调器）、references/enforcement-and-testing.md（自动化门禁、正向控制和敌对测试矩阵）、references/hono-example.md（具体 Hono 注册器；模型与框架无关，可映射到 Fastify、Express 和基于 Fetch 的路由器）。

组合层创建注册器：

const endpoints = createEndpointRegistrar({
  app,            // framework instance (Hono, Fastify, Fetch router...)
  sessions,       // cookie → validated session → AuthenticatedPrincipal
  browserPolicy,  // exact-origin allowlist, Fetch Metadata, CSRF, content types
  abuse,          // rate limits and payload caps, keyed by endpoint contract
  errors,         // safe problem-details translation
  telemetry,
});

端点所有者只提供契约和轻量处理器：

endpoints.register(getOrderContract, async ({ principal, params }) => {
  const result = await orders.viewOrder({ principal, orderId: params.orderId });
  return toHttpResponse(result);
});

适用场景

新增或审查 HTTP 端点时。
当租户或客户可能通过某条路由看到他人数据，或端点报告任何授权缺陷时。
处理认证中间件、会话 Cookie、CSRF 或 Origin 策略、实时流、登录/登出流程时。
审计哪些路由为公开路由时。

相关技能：是否采用 BFF、粒度、聚合和上游身份中介使用 bff-design；物理 BFF 路由布局使用 structure-codebase；REST 语义、分页和版本控制使用 api-design；OAuth/OIDC 协议流程使用 secure-oauth-oidc；端口与适配器实现使用 hexagonal-architecture。

限制

注册器是前期机制，其自身必须经过测试。
随着新认证模式出现，分类模型必须保持穷尽（扩展联合类型，绝不添加布尔标志）。
目录派生需要契约和生产组合两者，因此组合必须保持显式。
非常小的服务可以合理地从设计 1 加枚举所有路由的审计测试开始，但应在第二种认证模式或第二个 BFF 之前采用注册器。
本技能假设模式级决策已由 bff-design 确定。
具体框架示例仅提供 Hono，但模型与框架无关。

技能介绍

用途

主要能力

使用方式

适用场景

限制