@@ -72,6 +72,13 @@ AUTH_DISCORD_ALLOWLIST=
 # 本地开发：为 true 时注册验证码打印到控制台而不真发信（免配 Resend）。生产保持 false。
 REGISTRATION_OTP_DEV_CONSOLE=false
 
+# IH 通行证（HoloCard 用 IH 账号登录，INV-010）。HoloCard 换码时带的 client secret，
+# 两边必须配同一个值（可用 openssl rand -hex 32 生成）。留空 = 不启用，本地开发一般留空。
+# 回跳地址默认 https://holocard.longsizhuo.com/auth/callback，要改就设 SSO_HOLOCARD_REDIRECT_URI。
+SSO_HOLOCARD_SECRET=
+# HoloCard staging 单独一个 client（回跳 https://holocard.staging.longsizhuo.com/auth/callback），同样留空 = 不启用
+SSO_HOLOCARD_STAGING_SECRET=
+
 # --- AI 模型（用 OpenAI 兼容协议调用 GLM-4.6V-Flash 作为默认 fallback） ---
 #
 # 变量名沿用 OPENAI_* 是因为 Java 代码里用的是 OpenAI /chat/completions 标准协议，
 
@@ -182,3 +182,52 @@
   INV-005a 只管 5432，这条覆盖所有端口，以后新加服务也一样。
 - **历史**：2026-10-07 在服务器上抓包，3 分钟内有 4 个外网扫描器连到 8080，从公网 IP 访问
   `/actuator/metrics` 返回 200；随本不变量改成 `127.0.0.1:8080:8080`。
+
+## INV-010 · IH 通行证：只给登记过的 client 签码，换码必须 client secret + PKCE
+
+- **保护点**：
+  - `sso/service/SsoService#issueCode`（`POST /oauth/sso/code`，需要登录）：client 必须在 `sso.clients`
+    表里且已启用；`redirectUri` 与登记值逐字相等（不做前缀、通配，不归一化大小写、尾斜杠、query）；
+    只收 `codeChallengeMethod=S256` 和 43 位 base64url 的 `codeChallenge`；disabled 账号 403。
+    码存在进程内 Caffeine，60 秒过期。
+  - `sso/service/SsoService#authenticateClient`（`POST /internal/sso/token`）：client 已启用，且
+    `clientSecret` 用 `MessageDigest.isEqual` 常量时间比较；不过就 401 `invalid_client`，**并且不碰码**。
+  - `sso/service/SsoService#redeem`：`asMap().remove` 取码即作废（只能用一次）；clientId、redirectUri、
+    `codeVerifier`（格式 + S256 常量时间比较）任一不符，或账号此时已不存在 / 被禁用，都是 400
+    `invalid_grant`，码不可重试；成功只返回 `sub/username/displayName/avatarUrl`（`sso/dto/SsoUserInfo`）。
+  - `sso/config/SsoProperties.Client#enabled`：secret 或 redirect-uri 为空即未启用，两个接口都拒绝
+    （fail closed）；`SsoService` 构造时在启动日志里逐个播报 client 启用与否，不打 secret。
+  - `common/config/SaTokenConfigure`：只放行 `/internal/sso/token` 这一条精确路径，`/oauth/sso/code` 不放行。
+- **测试**：
+  - `SsoControllerIntegrationTests#seedAccountCanSignInAndGetsOnlyTheMinimalProfile`（端到端 + 返回字段白名单）
+  - `SsoControllerIntegrationTests#profileNeverCarriesEmailRolesPermissionsOrToken`
+  - `SsoControllerIntegrationTests#issuingCodeRequiresLogin`
+  - `SsoControllerIntegrationTests#redirectUriMustMatchTheRegisteredValueExactly`
+  - `SsoControllerIntegrationTests#unknownClientCannotGetCode`
+  - `SsoControllerIntegrationTests#malformedPkceOrStateIsRejected`
+  - `SsoControllerIntegrationTests#stateLengthBoundsAreInclusive`（反向）
+  - `SsoControllerIntegrationTests#disabledAccountCannotGetCode`
+  - `SsoControllerIntegrationTests#clientWithEmptySecretIsRejectedByBothEndpoints`
+  - `SsoControllerIntegrationTests#wrongSecretIsInvalidClientAndDoesNotBurnTheCode`
+  - `SsoControllerIntegrationTests#codeCanOnlyBeRedeemedOnce`
+  - `SsoControllerIntegrationTests#wrongVerifierBurnsTheCode`
+  - `SsoControllerIntegrationTests#verifierFormatIsEnforcedEvenWhenItsHashMatches`
+  - `SsoControllerIntegrationTests#redirectUriAtRedemptionMustMatchTheCode`
+  - `SsoControllerIntegrationTests#anotherClientCannotRedeemTheCode`
+  - `SsoControllerIntegrationTests#accountDisabledAfterCodeWasIssuedCannotRedeem`
+  - `SsoServiceTests#codeExpiresAfter60Seconds`（假时钟）
+  - `SsoServiceTests#clientNeedsBothSecretAndRedirectUriToBeEnabled`
+  - `SsoControllerIntegrationTests#stagingClientFromApplicationPropertiesBindsWithItsDashedId`
+- **为什么**：签码等于 IH 替用户向别的站点担保"这是谁"，任何一环松了都是账号接管：
+  1. redirect_uri 一旦放宽成前缀或通配，攻击者构造 `/sso/authorize?redirect_uri=<自己的地址>`，
+     受害者点"继续"，码就直接送到攻击者手里——OAuth 最常见的被打穿方式。
+  2. 码会经过地址栏、浏览历史、Referer 和各种日志。PKCE 让偷到码的人换不出东西（verifier 只在
+     HoloCard 的 HttpOnly cookie 里）；60 秒过期 + 只能用一次压缩重放窗口；核对不上就作废，不给反复试。
+  3. `/internal/sso/token` 必须进 notMatch（调用方没有 IH 登录态），而 Caddy 把所有路径原样转给 8080，
+     这条路径公网可达，client secret 是唯一的门：比较要常量时间；secret 为空必须拒绝——空串对空串
+     `MessageDigest.isEqual` 判相等，漏配 env 就等于换码接口不设防。启动播报的理由同 INV-008：
+     漏配和故意停用行为上一样，只能靠日志区分。没过 client 鉴权的请求不能碰码，否则谁都能烧掉别人的码。
+  4. 交出去的资料只够对方建自己的会话。email、角色、权限不给（对方用不上，泄露面越小越好）；
+     IH 的 satoken 绝不出 IH——给出去，HoloCard 一旦被攻破就能以用户身份操作 IH。
+- **历史**：2026-10-07 随 HoloCard 接入 IH 通行证引入（授权码 + PKCE S256）。client 表：`holocard`（线上）、
+  `holocard-staging`（HoloCard 的 staging 跑着没合并的 PR，单独的 secret 和回跳地址，拿到的码换不了线上的会话）。
@@ -38,6 +38,11 @@ services:
       # GitHub REST API token：DocHistoryService 调 /repos/.../commits 需要，
       # 匿名限流 60/hour，带 token 5000/hour。未设置时 service 仍可用，只是容易被限流。
       GITHUB_TOKEN: ${GITHUB_TOKEN:-}
+      # IH 通行证（INV-010）：HoloCard 换码时带的 client secret，和 HoloCard 那边配同一个值。
+      # 留空 = holocard 这个 client 未启用，签码/换码接口都拒绝，启动日志会打 [SSO] 警告。
+      SSO_HOLOCARD_SECRET: ${SSO_HOLOCARD_SECRET:-}
+      # HoloCard staging 的 client（和线上分开的 secret、回跳地址），留空 = 未启用
+      SSO_HOLOCARD_STAGING_SECRET: ${SSO_HOLOCARD_STAGING_SECRET:-}
     # 只 bind 到 loopback（INV-009）。公网流量一律走 Cloudflare → Caddy（api.involutionhell.com），
     # Caddy（host 网络）和 ChatBot 都直连 127.0.0.1:8080，不受影响。
     # Docker 发布端口走 nat 表 DNAT，不经过主机 INPUT 链，iptables 挡不住；
 
@@ -52,6 +52,10 @@ public void addInterceptors(InterceptorRegistry registry) {
                 // 不要求 sa-token 登录态。Controller 自己校验密钥。
                 // 用 /** 覆盖子路径（/internal 提交 + /internal/summary 查询）。
                 .notMatch("/api/community/links/internal", "/api/community/links/internal/**")
+                // IH 通行证换码（INV-010）：调用方是 HoloCard 等 client 的服务端，没有 IH 登录态。
+                // SsoController 自己用 client secret 鉴权（常量时间比较，secret 未配置即拒绝）。
+                // 只放行这一条精确路径；签码的 /oauth/sso/code 需要登录，不能加进来。
+                .notMatch("/internal/sso/token")
                 .notMatch("/api/chat/sessions/save")       // AI 对话持久化（匿名 / 登录都写，登录时自动关联 userId）
                 // Posts 公开读接口：
                 //   GET /api/posts/feed                  - /feed 原创 Tab 列表（匿名可访问）
 
@@ -0,0 +1,31 @@
+package com.involutionhell.backend.sso.config;
+
+import java.util.Map;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/**
+ * IH 通行证的 client 表（INV-010）：{@code sso.clients.<clientId>.secret / .redirect-uri}。
+ * 接新站点只加配置，代码里不认任何具体的 client 名。
+ */
+@ConfigurationProperties(prefix = "sso")
+public record SsoProperties(Map<String, Client> clients) {
+
+    public SsoProperties {
+        clients = clients == null ? Map.of() : Map.copyOf(clients);
+    }
+
+    /**
+     * @param secret      换码接口认 client 用的共享密钥
+     * @param redirectUri 唯一允许的回跳地址，签码时逐字比较
+     */
+    public record Client(String secret, String redirectUri) {
+
+        /**
+         * secret 和 redirect-uri 都配了才算启用，否则两个接口都拒绝（fail closed）。
+         * redirect-uri 为空也算未启用：不然请求里传空串就能和登记值"逐字相等"。
+         */
+        public boolean enabled() {
+            return secret != null && !secret.isBlank() && redirectUri != null && !redirectUri.isBlank();
+        }
+    }
+}
@@ -0,0 +1,60 @@
+package com.involutionhell.backend.sso.controller;
+
+import cn.dev33.satoken.annotation.SaCheckLogin;
+import cn.dev33.satoken.stp.StpUtil;
+import com.involutionhell.backend.common.api.ApiResponse;
+import com.involutionhell.backend.sso.dto.SsoCodeRequest;
+import com.involutionhell.backend.sso.dto.SsoTokenRequest;
+import com.involutionhell.backend.sso.dto.SsoUserInfo;
+import com.involutionhell.backend.sso.service.SsoService;
+import java.util.Map;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * IH 通行证（INV-010）的两个接口：
+ * <ol>
+ *   <li>IH 前端 /sso/authorize 页代已登录用户调 {@code /oauth/sso/code} 签码，浏览器带着码跳回 client；</li>
+ *   <li>client 的服务端拿码调 {@code /internal/sso/token} 换用户资料，之后发它自己的会话。</li>
+ * </ol>
+ * IH 的 satoken 始终不出 IH。
+ */
+@RestController
+public class SsoController {
+
+    private final SsoService ssoService;
+
+    public SsoController(SsoService ssoService) {
+        this.ssoService = ssoService;
+    }
+
+    /**
+     * 签码，需要登录。SaTokenConfigure 的全局拦截已经要求登录，这里再挂一道注解，
+     * 防止以后有人把 /oauth/** 整个放行。
+     */
+    @SaCheckLogin
+    @PostMapping("/oauth/sso/code")
+    public ApiResponse<Map<String, String>> issueCode(@RequestBody SsoCodeRequest request) {
+        String redirect = ssoService.issueCode(StpUtil.getLoginIdAsLong(), request);
+        return ApiResponse.ok(Map.of("redirect", redirect));
+    }
+
+    /**
+     * 换码。调用方是 client 的服务端，没有 IH 登录态，所以在 SaTokenConfigure 里放行，
+     * 由这里用 client secret 鉴权。Caddy 会把这条路径转给后端，公网也能打到，secret 是唯一的门。
+     */
+    @PostMapping("/internal/sso/token")
+    public ResponseEntity<ApiResponse<SsoUserInfo>> token(@RequestBody SsoTokenRequest request) {
+        if (!ssoService.authenticateClient(request.clientId(), request.clientSecret())) {
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(new ApiResponse<>(false, "invalid_client", null));
+        }
+        return ssoService.redeem(request)
+                .map(user -> ResponseEntity.ok(ApiResponse.ok(user)))
+                .orElseGet(() -> ResponseEntity.badRequest()
+                        .body(new ApiResponse<>(false, "invalid_grant", null)));
+    }
+}
@@ -0,0 +1,14 @@
+package com.involutionhell.backend.sso.dto;
+
+/**
+ * POST /oauth/sso/code 的请求体，由 IH 前端 /sso/authorize 页代当前登录用户发起。
+ * 校验规则见 SsoService#issueCode。
+ */
+public record SsoCodeRequest(
+        String clientId,
+        String redirectUri,
+        String state,
+        String codeChallenge,
+        String codeChallengeMethod
+) {
+}
@@ -0,0 +1,13 @@
+package com.involutionhell.backend.sso.dto;
+
+/**
+ * POST /internal/sso/token 的请求体，由 client 的服务端（HoloCard）发起，不经过浏览器。
+ */
+public record SsoTokenRequest(
+        String clientId,
+        String clientSecret,
+        String code,
+        String codeVerifier,
+        String redirectUri
+) {
+}
@@ -0,0 +1,10 @@
+package com.involutionhell.backend.sso.dto;
+
+/**
+ * 换码成功后交给 client 的用户资料。故意只有这四项：不给 email、角色、权限，
+ * 也不给任何 IH 的 token（INV-010）。加字段前先改 SECURITY.md。
+ *
+ * @param sub user_accounts.id 的十进制字符串
+ */
+public record SsoUserInfo(String sub, String username, String displayName, String avatarUrl) {
+}