使用 Spring Initializr 初始化 Gradle Native 登录服务项目

docs/bootstrap.md

@@ -0,0 +1,67 @@
+# 项目初始化
+
+2026-09-25 使用 start.spring.io API 生成，选择当时默认正式版 Spring Boot 4.1.1、
+Java 25、Gradle Groovy DSL、YAML 配置和 Jar。应用包名为 `top.ddupan.iam.login`。
+
+```sh
+curl -fsSLG https://start.spring.io/starter.zip \
+  --data-urlencode type=gradle-project \
+  --data-urlencode language=java \
+  --data-urlencode bootVersion=4.1.1 \
+  --data-urlencode javaVersion=25 \
+  --data-urlencode groupId=top.ddupan.iam \
+  --data-urlencode artifactId=iam-login \
+  --data-urlencode name=iam-login \
+  --data-urlencode packageName=top.ddupan.iam.login \
+  --data-urlencode 'description=Independent IAM login and authentication service for Hydra' \
+  --data-urlencode packaging=jar \
+  --data-urlencode configurationFileFormat=yaml \
+  --data-urlencode dependencies=native,devtools,lombok,configuration-processor,web,security,spring-security-webauthn,data-ldap,validation,actuator,prometheus,opentelemetry,distributed-tracing,unboundid-ldap,testcontainers \
+  -o iam-login-starter.zip
+```
+
+生成器提供 Gradle Wrapper、应用入口、上下文测试、依赖和 Native 构建插件。
+为生成的 `.gitignore` 补充秘密文件与日志忽略规则，以中文项目文档替代生成器的 `HELP.md`。
+Initializr 的可选版本会变化，未来可能需要调整请求；已提交源码、Gradle Wrapper 与插件版本是构建依据。
+
+LDAP 和 WebAuthn 依赖尚未配置为真实认证流程；数据库和 MFA 凭据持久化随首轮实现引入。
+Actuator 与 Prometheus 依赖存在不等于监控端点已按生产策略开放。
+
+## 骨架验证
+
+构建环境为 `ghcr.io/graalvm/native-image-community:25`，固定 digest：
+`sha256:0d936f32bb8acb5bc60c41b33e05f064d7a6aaf36b726538296c54949bd4a3c0`。
+
+2026-09-25 在上述 GraalVM 容器（Java 25.0.2）中执行 `./gradlew --no-daemon --max-workers=4 test`
+通过，包含测试 AOT 处理和 1 个 JVM 上下文测试。Grafana LGTM Testcontainer 实际启动成功。
+当前 Gradle 骨架的 `nativeCompile` 与 `nativeTest` 尚未执行，不声明 Native 已通过。
+
+生成的上下文测试通过 Testcontainers 启动 Grafana LGTM，需访问 Docker。
+它不连接真实 AD 或 Hydra，也不验证 MFA。Native 骨架测试不代替完整认证链路验收。
+
+## Docker 开发与 Gradle 缓存
+
+Linux 主机示例：将缓存保留在宿主机用户缓存目录，避免每次临时容器重新下载 Wrapper、
+插件和依赖。项目工作目录也需要挂载，以保留 `build/` 和项目级 `.gradle/`。
+
+```sh
+IAM_GRADLE_CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/iam-login/gradle"
+mkdir -p "$IAM_GRADLE_CACHE"
+docker run --rm --network host \
+  --user "$(id -u):$(id -g)" \
+  --group-add "$(stat -c %g /var/run/docker.sock)" \
+  -e LANG=C.UTF-8 \
+  -e GRADLE_USER_HOME=/gradle \
+  -e TESTCONTAINERS_HOST_OVERRIDE=127.0.0.1 \
+  -v "$IAM_GRADLE_CACHE:/gradle" \
+  -v "$PWD:/workspace" \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -w /workspace --entrypoint /bin/bash \
+  ghcr.io/graalvm/native-image-community@sha256:0d936f32bb8acb5bc60c41b33e05f064d7a6aaf36b726538296c54949bd4a3c0 \
+  -c './gradlew --no-daemon --max-workers=4 test'
+```
+
+宿主机 Docker socket 供 Testcontainers 使用，host network 让测试能访问它启动的动态端口。
+Docker Desktop 的网络方式需按平台调整。首次本地验证使用 `/tmp/iam-login-gradle` 作为
+上述缓存目录，未写入仓库；长期开发使用持久缓存目录。构建容器使用宿主 UID/GID，
+避免产物和缓存变为 root 所有。

docs/native-validation.md

@@ -0,0 +1,36 @@
+# 首轮 Native 验证范围
+
+本页定义验收要求，不表示下列功能已实现或测试通过。MFA 首先验证 Spring 官方
+WebAuthn 集成；TOTP、恢复方式与已有 Authelia MFA 的迁移方式需在实现中明确。
+
+## 认证与身份
+
+- 使用隔离 LDAP 测试夹具验证正确密码、错误密码、未知及禁用用户；随后验证 Samba AD
+  的真实 schema、LDAPS 信任和组查询，不把通用 LDAP 测试等同于 AD 验收。
+- 用户与组以 AD 为权威，直接映射；不把框架 ROLE_ 前缀或大小写转换泄露到 groups claim。
+- LDAP 与 MFA 必须绑定同一个稳定主体；仅完成密码不得接受 Hydra login challenge。
+- 验证 MFA 注册授权、challenge 过期与重放、其他用户凭据、重启后的持久化，以及恢复。
+- 新主体映射与现役 Go 适配器的 issuer/sub 哈希不同；切换前必须制定显式连续性映射，
+  不依赖可变邮箱、用户名或自动创建账号来掩盖身份变化。
+
+## Hydra
+
+- 认证事务绑定原始 challenge、浏览器会话和期限；成功后单次使用。
+- 校验允许的 client、scope、audience 和 Hydra 返回跳转的 origin/path。
+- Hydra admin 保持内部访问，业务日志不得包含密码、MFA secret、token 或 challenge。
+- 原生二进制与隔离 Hydra 完成授权码链路，再验证现有 Gitea 账号及权限。
+
+## Native 与监控
+
+- CI 构建 Native 产物并对该产物执行集成测试；测试报告区分 JVM 与 Native。
+- 最终运行镜像无需 JRE，不允许以回退 JVM 的方式令 Native 验收通过。
+- LDAP、MFA、数据库、TLS、JSON 和 Hydra HTTP 客户端全部在 Native 中执行。
+- 纳入 Actuator、Micrometer Prometheus 与 OpenTelemetry/分布式追踪；实际发起请求后
+  检查计数器、耗时分布与 trace 导出，确保 trace 属性不记录认证凭据或 challenge。
+- 记录镜像大小、启动时间、空闲与负载下内存、CPU、关键请求延迟；资源预算依据实测确认。
+- 将应用指标与 Native 运行时指标区分，不能假设 HotSpot JVM 仪表盘完整适用。
+
+## 发布条件
+
+通过上述测试后才准备生产切换；保留现役 OIDC 上游适配器作为回退路径。应用镜像以
+不可变 digest 交给 homelab-infra，部署状态与真实人类 MFA 验收分别记录。