@nihplod/sso-sdk 1.4.1 → 1.6.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";
@@ -32,13 +36,25 @@ interface SsoMiddlewareConfig {
     redirectUri: string;
     /** 请求的 scope（空格分隔），默认 "openid profile" */
     scopes?: string;
-    /** 公开路由前缀（不需要认证） */
+    /**
+     * 公开路由前缀（不需要认证）。
+     *
+     * 注意：/api/ 下的路径永不按静态资源扩展名（.js/.css/...）放行；
+     * 如需公开某个 API 路径，必须在此显式列出。
+     */
     publicPaths?: string[];
     /** 回调路径（不触发重定向），默认 "/api/auth/callback" */
     callbackPath?: string;
     /**
      * 主站用户会话 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 +67,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 +172,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 +191,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>>;
 
@@ -248,6 +303,28 @@ interface LogoutTokenPayload {
     sub?: string;
     sid?: string;
 }
+/**
+ * jti 防重放存储接口（可注入）。
+ *
+ * 默认实现是进程内 Map（per-instance）：多实例 / Serverless 部署下各实例
+ * 互不可见，重放检查形同虚设，必须注入共享存储（如 Redis）。
+ * key 为 `${issuer}:${jti}`，ttlSeconds 为建议过期时间（logout_token exp + 60s 宽限）。
+ */
+interface LogoutJtiStore {
+    has(key: string): Promise<boolean> | boolean;
+    add(key: string, ttlSeconds: number): Promise<void> | void;
+    /**
+     * 原子 check-and-set（如 Redis `SET key 1 NX EX ttl`）：返回 false 表示
+     * key 已存在（判重放）。提供时优先使用；缺失时回退 has+add
+     * （非原子，仅单实例部署可接受：并发窗口内同一 jti 可能双双通过）。
+     */
+    addIfAbsent?(key: string, ttlSeconds: number): Promise<boolean> | boolean;
+    /**
+     * 释放已记录的 key。onLogout 钩子失败后需要允许 IdP 用同一 logout_token
+     * 重投，SDK 会调用此方法；未实现时 IdP 重投将被重放检查以 400 拒绝。
+     */
+    remove?(key: string): Promise<void> | void;
+}
 
 /**
  * App Router Backchannel Logout 接收端 Route Handler
@@ -290,6 +367,15 @@ interface BackchannelLogoutRouteConfig {
     refreshTokenCookieName?: string;
     /** ID Token Cookie 名称，默认 __Host-nihplod_sso_id */
     idTokenCookieName?: string;
+    /**
+     * jti 防重放存储（可选）。
+     *
+     * 默认实现是进程内 Map（per-instance）：多实例 / Serverless 部署下各实例
+     * 互不可见，重放保护形同虚设（IdP 重投/攻击者重放到另一实例会被当作首次）。
+     * 这类部署 MUST 注入共享存储（如 Redis：addIfAbsent = `SET key 1 NX EX ttl`，
+     * remove = `DEL key`——onLogout 失败时用于释放 jti 允许 IdP 重投）。
+     */
+    jtiStore?: LogoutJtiStore;
     /**
      * 本地 HTTP 开发模式（默认 false）。关闭 Cookie 的 Secure 属性并去除
      * __Host-/__Secure- 前缀；必须与 middleware / callback / logout 的配置保持一致。
@@ -341,4 +427,4 @@ declare function getSecureCookieOptions(maxAge?: number, path?: string, secure?:
     maxAge?: number;
 };
 
-export { type BackchannelLogoutRouteConfig, type CallbackRouteConfig, DEFAULT_ACCESS_TOKEN_COOKIE_NAME, DEFAULT_ID_TOKEN_COOKIE_NAME, DEFAULT_LOGOUT_STATE_COOKIE_NAME, DEFAULT_NONCE_COOKIE_NAME, DEFAULT_REFRESH_TOKEN_COOKIE_NAME, DEFAULT_RETURN_COOKIE_NAME, DEFAULT_STATE_COOKIE_NAME, DEFAULT_VERIFIER_COOKIE_NAME, type LogoutRouteConfig, type SsoMiddlewareConfig, createBackchannelLogoutRouteHandler, createCallbackRouteHandler, createLogoutRouteHandler, createSsoMiddleware, getHostCookieOptions, getSecureCookieOptions, toInsecureCookieName };
+export { type BackchannelLogoutRouteConfig, type CallbackRouteConfig, DEFAULT_ACCESS_TOKEN_COOKIE_NAME, DEFAULT_ID_TOKEN_COOKIE_NAME, DEFAULT_LOGOUT_STATE_COOKIE_NAME, DEFAULT_NONCE_COOKIE_NAME, DEFAULT_REFRESH_TOKEN_COOKIE_NAME, DEFAULT_RETURN_COOKIE_NAME, DEFAULT_STATE_COOKIE_NAME, DEFAULT_VERIFIER_COOKIE_NAME, type LogoutJtiStore, type LogoutRouteConfig, type SsoMiddlewareConfig, createBackchannelLogoutRouteHandler, createCallbackRouteHandler, createLogoutRouteHandler, createSsoMiddleware, getHostCookieOptions, getSecureCookieOptions, toInsecureCookieName };

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";
@@ -32,13 +36,25 @@ interface SsoMiddlewareConfig {
     redirectUri: string;
     /** 请求的 scope（空格分隔），默认 "openid profile" */
     scopes?: string;
-    /** 公开路由前缀（不需要认证） */
+    /**
+     * 公开路由前缀（不需要认证）。
+     *
+     * 注意：/api/ 下的路径永不按静态资源扩展名（.js/.css/...）放行；
+     * 如需公开某个 API 路径，必须在此显式列出。
+     */
     publicPaths?: string[];
     /** 回调路径（不触发重定向），默认 "/api/auth/callback" */
     callbackPath?: string;
     /**
      * 主站用户会话 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 +67,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 +172,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 +191,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>>;
 
@@ -248,6 +303,28 @@ interface LogoutTokenPayload {
     sub?: string;
     sid?: string;
 }
+/**
+ * jti 防重放存储接口（可注入）。
+ *
+ * 默认实现是进程内 Map（per-instance）：多实例 / Serverless 部署下各实例
+ * 互不可见，重放检查形同虚设，必须注入共享存储（如 Redis）。
+ * key 为 `${issuer}:${jti}`，ttlSeconds 为建议过期时间（logout_token exp + 60s 宽限）。
+ */
+interface LogoutJtiStore {
+    has(key: string): Promise<boolean> | boolean;
+    add(key: string, ttlSeconds: number): Promise<void> | void;
+    /**
+     * 原子 check-and-set（如 Redis `SET key 1 NX EX ttl`）：返回 false 表示
+     * key 已存在（判重放）。提供时优先使用；缺失时回退 has+add
+     * （非原子，仅单实例部署可接受：并发窗口内同一 jti 可能双双通过）。
+     */
+    addIfAbsent?(key: string, ttlSeconds: number): Promise<boolean> | boolean;
+    /**
+     * 释放已记录的 key。onLogout 钩子失败后需要允许 IdP 用同一 logout_token
+     * 重投，SDK 会调用此方法；未实现时 IdP 重投将被重放检查以 400 拒绝。
+     */
+    remove?(key: string): Promise<void> | void;
+}
 
 /**
  * App Router Backchannel Logout 接收端 Route Handler
@@ -290,6 +367,15 @@ interface BackchannelLogoutRouteConfig {
     refreshTokenCookieName?: string;
     /** ID Token Cookie 名称，默认 __Host-nihplod_sso_id */
     idTokenCookieName?: string;
+    /**
+     * jti 防重放存储（可选）。
+     *
+     * 默认实现是进程内 Map（per-instance）：多实例 / Serverless 部署下各实例
+     * 互不可见，重放保护形同虚设（IdP 重投/攻击者重放到另一实例会被当作首次）。
+     * 这类部署 MUST 注入共享存储（如 Redis：addIfAbsent = `SET key 1 NX EX ttl`，
+     * remove = `DEL key`——onLogout 失败时用于释放 jti 允许 IdP 重投）。
+     */
+    jtiStore?: LogoutJtiStore;
     /**
      * 本地 HTTP 开发模式（默认 false）。关闭 Cookie 的 Secure 属性并去除
      * __Host-/__Secure- 前缀；必须与 middleware / callback / logout 的配置保持一致。
@@ -341,4 +427,4 @@ declare function getSecureCookieOptions(maxAge?: number, path?: string, secure?:
     maxAge?: number;
 };
 
-export { type BackchannelLogoutRouteConfig, type CallbackRouteConfig, DEFAULT_ACCESS_TOKEN_COOKIE_NAME, DEFAULT_ID_TOKEN_COOKIE_NAME, DEFAULT_LOGOUT_STATE_COOKIE_NAME, DEFAULT_NONCE_COOKIE_NAME, DEFAULT_REFRESH_TOKEN_COOKIE_NAME, DEFAULT_RETURN_COOKIE_NAME, DEFAULT_STATE_COOKIE_NAME, DEFAULT_VERIFIER_COOKIE_NAME, type LogoutRouteConfig, type SsoMiddlewareConfig, createBackchannelLogoutRouteHandler, createCallbackRouteHandler, createLogoutRouteHandler, createSsoMiddleware, getHostCookieOptions, getSecureCookieOptions, toInsecureCookieName };
+export { type BackchannelLogoutRouteConfig, type CallbackRouteConfig, DEFAULT_ACCESS_TOKEN_COOKIE_NAME, DEFAULT_ID_TOKEN_COOKIE_NAME, DEFAULT_LOGOUT_STATE_COOKIE_NAME, DEFAULT_NONCE_COOKIE_NAME, DEFAULT_REFRESH_TOKEN_COOKIE_NAME, DEFAULT_RETURN_COOKIE_NAME, DEFAULT_STATE_COOKIE_NAME, DEFAULT_VERIFIER_COOKIE_NAME, type LogoutJtiStore, type LogoutRouteConfig, type SsoMiddlewareConfig, createBackchannelLogoutRouteHandler, createCallbackRouteHandler, createLogoutRouteHandler, createSsoMiddleware, getHostCookieOptions, getSecureCookieOptions, toInsecureCookieName };