iam

IAM

IAM 是方寸山项目的身份与访问管理服务，当前运行单元是 iam-apiserver。它提供认证、Token/JWKS、授权判定、角色与策略管理、用户档案、ProfileLink 档案关系、IDP 集成和 SDK 接入能力。

当前事实源

冲突时优先级是：源码与运行时行为、机器契约与配置、当前维护文档、历史文档与归档材料。

核心能力

• AuthN：v2 显式登录、Refresh Token、Access Token 撤销、会话校验、Service Token、JWKS 发布与管理端保护。
• AuthZ：REST 与 gRPC 判定、授权快照、角色/资源/策略/assignment wire term，内部实现以 rolebinding 为准。
• Identity：用户资料、儿童档案、ProfileLink 档案关系查询与写入。
• IDP：微信应用配置与登录所需 IDP 能力。
• Suggest：GET /api/v2/suggest/profile 儿童档案联想搜索。
• CacheGovernance：只读缓存目录、family 状态和 debug 治理面。
• Transactional Outbox：授权版本变更等领域事件通过 outbox relay 持久发布。

快速开始

make deps
make build
make test

开发配置默认入口：

make run APISERVER_CONFIG=configs/apiserver.dev.yaml
curl http://localhost:8080/health
curl http://localhost:8080/.well-known/jwks.json

常用验证：

make docs-hygiene
make api-validate
go test ./...

make api-validate 会运行 Spectral Docker 镜像和本仓库的 OpenAPI/路由契约检查；本机需要 Docker daemon 可用。

API 入口

REST 契约以 OpenAPI 文件为准：

• api/rest/authn.v2.yaml
• api/rest/authz.v2.yaml
• api/rest/identity.v2.yaml
• api/rest/idp.v2.yaml
• api/rest/suggest.v2.yaml

gRPC 契约以 proto 文件为准：

• api/grpc/iam/authn/v2/authn.proto
• api/grpc/iam/authz/v2/authz.proto
• api/grpc/iam/identity/v2/identity.proto
• api/grpc/iam/idp/v2/idp.proto

说明性 API 文档见 api/README.md、api/rest/README.md 和 api/grpc/README.md。

文档导航

• docs/README.md：文档中心与阅读路径。
• docs/00-概览：系统地图、术语、代码组织和事实来源。
• docs/01-运行时：启动链、REST/gRPC、HTTP 认证、健康检查和 debug 面。
• docs/02-业务域：AuthN、AuthZ、ProfileLink、Suggest。
• docs/03-接口与集成：REST、gRPC、授权、身份关系和 QS 接入。
• docs/04-基础设施与运维：架构实践、CQRS、契约校验、迁移、Outbox。
• docs/05-专题分析：认证链路、授权链路、缓存治理、SDK 等深潜材料。
• docs/_archive：历史文档，非权威事实层。

开发约定

• 代码变更触及路由、proto、OpenAPI、配置、迁移或架构边界时，同步更新文档。
• 活跃文档不得依赖 docs/_archive 中的历史事实。
• 提交前至少运行 make docs-hygiene；涉及 API 契约时运行 make api-validate。
• 文档写作规范见 docs/CONTRIBUTING-DOCS.md。