@nihplod/sso-sdk 1.4.0 → 1.5.0

package/dist/next/index.d.mts

@@ -10,6 +10,10 @@ import { NextRequest, NextResponse } from 'next/server';
  * - PKCE code_challenge 使用 Web Crypto API 的 crypto.subtle.digest(SHA-256)
  *   （Edge Runtime 18+ 完全支持此 API）
  *
+ * ⚠️ 安全须知：middleware 只是 UX 层（未认证重定向的入口优化），
+ * 不能作为安全边界。敏感接口必须在 Route Handler / Server Component 中
+ * 用 @nihplod/sso-verify 对 access_token 做二次校验。
+ *
  * 用法 (src/middleware.ts):
  * ```ts
  * import { createSsoMiddleware } from "@nihplod/sso-sdk/next";
@@ -39,6 +43,13 @@ interface SsoMiddlewareConfig {
     /**
      * 主站用户会话 Cookie 名称，用于检测是否已有 SSO 会话。
      * 默认 "__Host-user_token"（与主站 C 端登录 Cookie 一致）。
+     *
+     * @deprecated 该「主站会话 Cookie 快速通道」已移除，此选项不再生效：
+     * 1. `__Host-user_token` 存的是主站内部 token（type="user", aud="user"），
+     *    introspect 端点只接受 type="access_token"，校验必然返回 inactive；
+     * 2. `__Host-` Cookie 不会下发到子域/其他域名，跨域子项目根本收不到。
+     * 该分支永不命中，却让每个请求白付一次 introspection 往返并被负缓存 30s。
+     * 保留字段仅为兼容旧配置，请勿使用；会话检测以本站 access_token Cookie 为准。
      */
     ssoCookieName?: string;
     /**
@@ -51,8 +62,27 @@ interface SsoMiddlewareConfig {
      * 默认 true（推荐）。设为 false 时仅检查 Cookie 存在性，延迟最低但可能放行
      * 已失效/被撤销的会话 —— 中间件本质上只是 UX 层，敏感数据必须在
      * Route Handler / Server Component 中二次校验。
+     *
+     * @deprecated 随「主站会话 Cookie 快速通道」一并移除（见 ssoCookieName），
+     * 此选项不再生效。保留字段仅为兼容旧配置，请勿使用。
      */
     validateSsoCookie?: boolean;
+    /**
+     * Introspection 不可达（网络异常/超时/5xx，token 有效性未确证）时的策略。
+     *
+     * 默认 false（fail-open）：对已持有 access_token Cookie 的请求放行——
+     * middleware 只是 UX 层，敏感接口的鉴权由 Route Handler / Server Component
+     * 兜底，此时重定向到一个同样不可达的 SSO 中心没有意义。
+     *
+     * 设为 true（fail-closed）时：对持有 access_token Cookie 的请求返回
+     * 502 错误页而不是放行。适用于对可用性敏感、宁可拒绝也不放行的场景。
+     * 注意 fail-closed 只影响「不可达」这一种结果；token 确证无效（inactive）
+     * 无论该选项如何都会清除 Cookie 并重定向到 SSO 登录。
+     *
+     * ⚠️ 无论取何值，middleware 都只是 UX 层：敏感接口必须在
+     * Route Handler / Server Component 中用 @nihplod/sso-verify 二次校验。
+     */
+    failClosedOnIntrospectionError?: boolean;
     /** Access Token Cookie 名称，默认 __Host-nihplod_sso_at */
     accessTokenCookieName?: string;
     /** State Cookie 名称，默认 __Host-nihplod_sso_state */
@@ -137,6 +167,12 @@ interface CallbackRouteConfig {
     returnUrlCookieName?: string;
     /** PKCE Verifier Cookie 名称，默认 __Secure-nihplod_sso_verifier */
     verifierCookieName?: string;
+    /**
+     * 请求的 OAuth scope（空格分隔），建议与 createSsoMiddleware 的 scopes 保持一致。
+     * 仅当**显式配置**且包含 openid 时回调才强制要求 token 响应携带 id_token（fail-closed）；
+     * 未配置时保持兼容行为（id_token 存在则校验，缺失不拒绝），避免升级后旧接入方登录失败。
+     */
+    scopes?: string;
     /**
      * 本地 HTTP 开发模式（默认 false）。关闭 Cookie 的 Secure 属性并去除
      * __Host-/__Secure- 前缀；必须与 createSsoMiddleware 的配置保持一致，
@@ -150,6 +186,20 @@ interface CallbackRouteConfig {
      * 仅用于 token 交换等服务器间请求；浏览器跳转仍使用 ssoBaseUrl 公网地址。
      */
     serverBaseUrl?: string;
+    /**
+     * 自定义回调错误响应（可选）。
+     * 传入后优先生效；返回 undefined 时回退默认行为。
+     * 默认行为：浏览器导航（Accept 含 text/html 且未带 ?format=json）渲染内置中文错误页
+     * （含"重新登录"入口）；其他请求（fetch/自动化）返回 JSON，保持 API 兼容。
+     */
+    renderErrorPage?: (ctx: {
+        error: string;
+        errorDescription: string;
+        status: number;
+        request: NextRequest;
+    }) => Response | undefined | Promise<Response | undefined>;
+    /** 调试日志开关（默认 false）：回调失败时输出服务端告警日志，便于定位配置/流程问题 */
+    debug?: boolean;
 }
 declare function createCallbackRouteHandler(config: CallbackRouteConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;
 

package/dist/next/index.d.ts

@@ -10,6 +10,10 @@ import { NextRequest, NextResponse } from 'next/server';
  * - PKCE code_challenge 使用 Web Crypto API 的 crypto.subtle.digest(SHA-256)
  *   （Edge Runtime 18+ 完全支持此 API）
  *
+ * ⚠️ 安全须知：middleware 只是 UX 层（未认证重定向的入口优化），
+ * 不能作为安全边界。敏感接口必须在 Route Handler / Server Component 中
+ * 用 @nihplod/sso-verify 对 access_token 做二次校验。
+ *
  * 用法 (src/middleware.ts):
  * ```ts
  * import { createSsoMiddleware } from "@nihplod/sso-sdk/next";
@@ -39,6 +43,13 @@ interface SsoMiddlewareConfig {
     /**
      * 主站用户会话 Cookie 名称，用于检测是否已有 SSO 会话。
      * 默认 "__Host-user_token"（与主站 C 端登录 Cookie 一致）。
+     *
+     * @deprecated 该「主站会话 Cookie 快速通道」已移除，此选项不再生效：
+     * 1. `__Host-user_token` 存的是主站内部 token（type="user", aud="user"），
+     *    introspect 端点只接受 type="access_token"，校验必然返回 inactive；
+     * 2. `__Host-` Cookie 不会下发到子域/其他域名，跨域子项目根本收不到。
+     * 该分支永不命中，却让每个请求白付一次 introspection 往返并被负缓存 30s。
+     * 保留字段仅为兼容旧配置，请勿使用；会话检测以本站 access_token Cookie 为准。
      */
     ssoCookieName?: string;
     /**
@@ -51,8 +62,27 @@ interface SsoMiddlewareConfig {
      * 默认 true（推荐）。设为 false 时仅检查 Cookie 存在性，延迟最低但可能放行
      * 已失效/被撤销的会话 —— 中间件本质上只是 UX 层，敏感数据必须在
      * Route Handler / Server Component 中二次校验。
+     *
+     * @deprecated 随「主站会话 Cookie 快速通道」一并移除（见 ssoCookieName），
+     * 此选项不再生效。保留字段仅为兼容旧配置，请勿使用。
      */
     validateSsoCookie?: boolean;
+    /**
+     * Introspection 不可达（网络异常/超时/5xx，token 有效性未确证）时的策略。
+     *
+     * 默认 false（fail-open）：对已持有 access_token Cookie 的请求放行——
+     * middleware 只是 UX 层，敏感接口的鉴权由 Route Handler / Server Component
+     * 兜底，此时重定向到一个同样不可达的 SSO 中心没有意义。
+     *
+     * 设为 true（fail-closed）时：对持有 access_token Cookie 的请求返回
+     * 502 错误页而不是放行。适用于对可用性敏感、宁可拒绝也不放行的场景。
+     * 注意 fail-closed 只影响「不可达」这一种结果；token 确证无效（inactive）
+     * 无论该选项如何都会清除 Cookie 并重定向到 SSO 登录。
+     *
+     * ⚠️ 无论取何值，middleware 都只是 UX 层：敏感接口必须在
+     * Route Handler / Server Component 中用 @nihplod/sso-verify 二次校验。
+     */
+    failClosedOnIntrospectionError?: boolean;
     /** Access Token Cookie 名称，默认 __Host-nihplod_sso_at */
     accessTokenCookieName?: string;
     /** State Cookie 名称，默认 __Host-nihplod_sso_state */
@@ -137,6 +167,12 @@ interface CallbackRouteConfig {
     returnUrlCookieName?: string;
     /** PKCE Verifier Cookie 名称，默认 __Secure-nihplod_sso_verifier */
     verifierCookieName?: string;
+    /**
+     * 请求的 OAuth scope（空格分隔），建议与 createSsoMiddleware 的 scopes 保持一致。
+     * 仅当**显式配置**且包含 openid 时回调才强制要求 token 响应携带 id_token（fail-closed）；
+     * 未配置时保持兼容行为（id_token 存在则校验，缺失不拒绝），避免升级后旧接入方登录失败。
+     */
+    scopes?: string;
     /**
      * 本地 HTTP 开发模式（默认 false）。关闭 Cookie 的 Secure 属性并去除
      * __Host-/__Secure- 前缀；必须与 createSsoMiddleware 的配置保持一致，
@@ -150,6 +186,20 @@ interface CallbackRouteConfig {
      * 仅用于 token 交换等服务器间请求；浏览器跳转仍使用 ssoBaseUrl 公网地址。
      */
     serverBaseUrl?: string;
+    /**
+     * 自定义回调错误响应（可选）。
+     * 传入后优先生效；返回 undefined 时回退默认行为。
+     * 默认行为：浏览器导航（Accept 含 text/html 且未带 ?format=json）渲染内置中文错误页
+     * （含"重新登录"入口）；其他请求（fetch/自动化）返回 JSON，保持 API 兼容。
+     */
+    renderErrorPage?: (ctx: {
+        error: string;
+        errorDescription: string;
+        status: number;
+        request: NextRequest;
+    }) => Response | undefined | Promise<Response | undefined>;
+    /** 调试日志开关（默认 false）：回调失败时输出服务端告警日志，便于定位配置/流程问题 */
+    debug?: boolean;
 }
 declare function createCallbackRouteHandler(config: CallbackRouteConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;