diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java b/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java
index 9de13d8b5..8ab9314b0 100644
--- a/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java
+++ b/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java
@@ -50,8 +50,31 @@ public class ApiGuardCoverageAuditor {
"/api/version", // 客户端启动时拉最新版本号,必须先于登录
"/api/tutorial", // 后台可维护的使用教程,公开内容
"/api/kd-flow/verify", // 开店流程访问密码校验:它自己就是那道门
+ // 下面四条都是 AdminConsoleController 的 302 兜底(response.sendRedirect 完事,
+ // 不读库、不回数据),旧书签打进这些地址只会被送到 /admin-vue/。
+ // 前缀匹配语义是 equals || startsWith(prefix + "/"),所以 "/" 只盖住根路径本身。
+ "/",
+ "/admin", // → /admin-vue/
+ "/admin.html", // 旧入口兜底
+ "/login.html", // 旧入口兜底
"/error");
+ /**
+ * 第二道门已到位、只欠进第一道门(前缀名单)的路径。
+ *
+ *
鉴权有两道:过滤器的前缀名单,和控制器方法体里的 {@code require*}。自检只看前者,
+ * 所以后者设防、前缀没进名单的端点会被报成"匿名可达"。2026-10-08 现网首跑报出的 5 条里
+ * 就有这一条:{@code ClientCredentialController.credentials:39} 第一行就是
+ * {@code adminAuthSupport.requireUser(request)},拿到紫鸟口令的前提是登录态。
+ *
+ *
这一格**不是许可**:登记它等于承认"该前缀该进 USER_TOOL_PREFIXES 却还没进"。
+ * 每条都由测试回到源码逐方法体核对确实带 {@code require*}(见
+ * {@code ApiGuardCoverageAuditorTest#methodGuardedEntriesAreActuallyGatedInSource}),
+ * 往里塞一条没设防的路径会红。
+ */
+ static final Set METHOD_GUARDED_PATHS = Set.of(
+ "/api/client/credentials");
+
/**
* 待收欠账:数据按 user_id 归属、却既不进守卫名单也没有 require* 的前缀。
* 划掉它们的条件是"进 USER_TOOL_PREFIXES、并在 user-tool-guard-enabled 打开后回归 covered",
@@ -90,8 +113,9 @@ public class ApiGuardCoverageAuditor {
public void auditOnBoot() {
Report report = audit(mappedPaths());
if (report.uncovered().isEmpty()) {
- log.info("[api-guard-coverage] mapped={} covered={} public={} pending={} uncovered=0",
- report.mapped(), report.covered(), report.publicPaths().size(), report.pending().size());
+ log.info("[api-guard-coverage] mapped={} covered={} public={} methodGuarded={} pending={} uncovered=0",
+ report.mapped(), report.covered(), report.publicPaths().size(),
+ report.methodGuarded().size(), report.pending().size());
return;
}
log.warn("[api-guard-coverage] {} count={} endpoints={} —— 这些端点不在守卫前缀里、也不在公开/待收清单里,"
@@ -104,12 +128,15 @@ public class ApiGuardCoverageAuditor {
List uncovered = new ArrayList<>();
Set publicPaths = new LinkedHashSet<>();
Set pending = new LinkedHashSet<>();
+ Set methodGuarded = new LinkedHashSet<>();
int covered = 0;
for (String path : paths) {
if (matchesAny(path, AdminApiGuardFilter.guardedPrefixes())) {
covered++;
} else if (matchesAny(path, PUBLIC_BY_DESIGN)) {
publicPaths.add(path);
+ } else if (matchesAny(path, METHOD_GUARDED_PATHS)) {
+ methodGuarded.add(path);
} else if (matchesAny(path, PENDING_CONVERGENCE)) {
pending.add(path);
} else {
@@ -117,7 +144,7 @@ public class ApiGuardCoverageAuditor {
}
}
return new Report(paths.size(), covered, List.copyOf(publicPaths), List.copyOf(pending),
- List.copyOf(new LinkedHashSet<>(uncovered)));
+ List.copyOf(methodGuarded), List.copyOf(new LinkedHashSet<>(uncovered)));
}
private static boolean matchesAny(String path, Collection prefixes) {
@@ -137,6 +164,7 @@ public class ApiGuardCoverageAuditor {
return paths;
}
- record Report(int mapped, int covered, List publicPaths, List pending, List uncovered) {
+ record Report(int mapped, int covered, List publicPaths, List pending,
+ List methodGuarded, List uncovered) {
}
}
diff --git a/backend-java/src/test/java/com/nanri/aiimage/config/ApiGuardCoverageAuditorTest.java b/backend-java/src/test/java/com/nanri/aiimage/config/ApiGuardCoverageAuditorTest.java
index f43c35d26..1893bd45d 100644
--- a/backend-java/src/test/java/com/nanri/aiimage/config/ApiGuardCoverageAuditorTest.java
+++ b/backend-java/src/test/java/com/nanri/aiimage/config/ApiGuardCoverageAuditorTest.java
@@ -32,17 +32,20 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
class ApiGuardCoverageAuditorTest {
@Test
- void classifiesEachOfTheFourBuckets() {
+ void classifiesEachOfTheFiveBuckets() {
ApiGuardCoverageAuditor.Report report = ApiGuardCoverageAuditor.audit(List.of(
"/api/admin/users", // 名单内,无条件
"/api/notifications/summary", // 自助前缀,无条件
"/api/collect-data/pull", // 用户态前缀(在开关后面,但仍算"在名单里")
"/login", // 设计公开
+ "/api/client/credentials", // 前缀没进名单,但方法体里有 require 门
"/api/dedupe/runs", // 待收欠账
"/api/brand-check-tasks/1")); // 谁都不沾
assertEquals(3, report.covered(), "守卫名单内应有 3 条:admin / 自助 / 用户态");
assertEquals(List.of("/login"), report.publicPaths());
+ assertEquals(List.of("/api/client/credentials"), report.methodGuarded(),
+ "方法级已设防的那格没接上,现网每次重启都会把它报成匿名可达");
assertEquals(List.of("/api/dedupe/runs"), report.pending());
assertEquals(List.of("/api/brand-check-tasks/1"), report.uncovered(),
"新端点必须落进 uncovered,否则这条护栏就是装饰");
@@ -107,6 +110,68 @@ class ApiGuardCoverageAuditorTest {
assertTrue(overlap.isEmpty(), () -> "这些前缀已被守卫看守,登记成『设计公开』会让欠账看起来已收口:" + overlap);
}
+ /**
+ * 『方法级已设防』这一格最容易变成自我豁免:往清单里加一条就等于宣布它不匿名,而没人核对过。
+ * 所以判据回到源码——逐处理器方法体(不是整份文件)里必须有 require* 身份门。
+ */
+ @Test
+ void methodGuardedEntriesAreActuallyGatedInSource() throws IOException {
+ assertFalse(ApiGuardCoverageAuditor.METHOD_GUARDED_PATHS.isEmpty(),
+ "现网首跑报出的 5 条里有一条是这一格(/api/client/credentials),清单空了说明整格被删了");
+ for (String path : ApiGuardCoverageAuditor.METHOD_GUARDED_PATHS) {
+ String body = handlerMethodBody(path);
+ assertTrue(body.contains("require"),
+ () -> "登记成『方法级已设防』但处理器方法体里没有 require*,它就是匿名可达:" + path);
+ ApiGuardCoverageAuditor.Report report = ApiGuardCoverageAuditor.audit(List.of(path));
+ assertEquals(1, report.methodGuarded().size(), () -> path + " 没落进方法级那一格:" + report);
+ assertTrue(report.uncovered().isEmpty(), () -> path + " 仍被报成 uncovered:" + report.uncovered());
+ }
+ }
+
+ /** 上一条的反向自证:抽取范围必须精确到方法体,否则整类里一处 adminAuthSupport 就能喂饱它。 */
+ @Test
+ void theRequireCheckIsScopedToTheMethodNotTheFile() throws IOException {
+ String redirect = handlerMethodBody("/admin.html");
+ assertTrue(redirect.contains("sendRedirect"), () -> "抽取到的不是那段重定向方法体:" + redirect);
+ assertFalse(redirect.contains("require"),
+ "AdminConsoleController 类里另有 adminAuthSupport 的用法,方法体抽取若越界就会把重定向也判成已设防");
+ }
+
+ /**
+ * 取某个已映射路径对应的处理器方法体:从路径字面量起,到该方法收尾的 4 空格缩进 `}` 为止。
+ *
+ * URI 是"类级前缀 + 方法级路径"拼出来的,源码里往往只有后半截({@code @RequestMapping("/api/client")}
+ * + {@code @GetMapping("/credentials")}),所以整段 URI 命中 0 处时要用末段再找一次。
+ */
+ private static String handlerMethodBody(String path) throws IOException {
+ List needles = new ArrayList<>();
+ needles.add("\"" + path + "\"");
+ int cut = path.lastIndexOf('/');
+ if (cut > 0) {
+ needles.add("\"" + path.substring(cut) + "\"");
+ }
+ List tried = new ArrayList<>();
+ for (String needle : needles) {
+ List hits = new ArrayList<>();
+ for (Path file : controllers()) {
+ String text = stripComments(read(file));
+ int at = text.indexOf(needle);
+ if (at < 0) {
+ continue;
+ }
+ int end = text.indexOf("\n }", at);
+ assertTrue(end > at, () -> "定位不到 " + path + " 所属方法的结尾(缩进形状变了?):" + file);
+ hits.add(text.substring(at, end));
+ }
+ if (hits.size() == 1) {
+ return hits.get(0);
+ }
+ tried.add(needle + " 命中 " + hits.size() + " 处");
+ }
+ throw new AssertionError("定位不到 " + path + " 的处理器方法(" + tried
+ + ")—— 0 处是字面量找错,>1 处是不唯一,两种都不能放行 require 判据");
+ }
+
/** 从控制器源码取映射基路径:类级 @RequestMapping 优先,没有类级的才看方法级绝对路径。 */
private static Set controllerBasePaths() throws IOException {
Set out = new java.util.LinkedHashSet<>();
@@ -118,18 +183,24 @@ class ApiGuardCoverageAuditorTest {
bases.add(klass.group(1));
}
if (bases.isEmpty()) {
+ // 括号内可能是一次性列出多条(@GetMapping({"/admin", "/admin.html"})),
+ // 只抓第一条的话剩下的兜底路径就被判成"没人映射"(10-08 实测 [/admin, /admin.html, /login.html])。
Matcher method = Pattern.compile(
- "@(?:Get|Post|Put|Delete|Request)Mapping\\(\\s*(?:value\\s*=\\s*)?\"([/][^\"]+)").matcher(text);
+ "@(?:Get|Post|Put|Delete|Request)Mapping\\s*\\(([^)]*)\\)").matcher(text);
while (method.find()) {
- String absolute = method.group(1);
- while (absolute.endsWith("/")) {
- absolute = absolute.substring(0, absolute.length() - 1);
+ Matcher literal = Pattern.compile("\"([/][^\"]*)\"").matcher(method.group(1));
+ while (literal.find()) {
+ String absolute = literal.group(1);
+ // 只裁尾斜杠,别把根路径 "/" 裁成空串(10-08 现网首报就有 "/",裁空会让它永远不算"活着")
+ while (absolute.length() > 1 && absolute.endsWith("/")) {
+ absolute = absolute.substring(0, absolute.length() - 1);
+ }
+ String[] parts = absolute.split("/"); // "/login" -> ["", "login"]
+ for (int depth = 1; depth <= parts.length - 1 && depth <= 3; depth++) {
+ bases.add("/" + String.join("/", java.util.Arrays.copyOfRange(parts, 1, 1 + depth)));
+ }
+ bases.add(absolute);
}
- String[] parts = absolute.split("/"); // "/login" -> ["", "login"]
- for (int depth = 1; depth <= parts.length - 1 && depth <= 3; depth++) {
- bases.add("/" + String.join("/", java.util.Arrays.copyOfRange(parts, 1, 1 + depth)));
- }
- bases.add(absolute);
}
}
out.addAll(bases);