docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]

This commit is contained in:
2026-11-16 17:52:11 +08:00
parent 30829eeb86
commit 1090591503
123 changed files with 1279 additions and 3 deletions
+22
View File
@@ -1,3 +1,4 @@
// Package auth 管理项目隔离的登录:提供方回调产生 grant,前端凭 verifier 换取 bearer 会话。
package auth
import (
@@ -19,9 +20,11 @@ import (
"time"
)
// 项目名限制为可用于路由的短标识;令牌格式对应 32 随机字节的无填充 base64url。
var projectName = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
var tokenPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{43}$`)
// service 共享数据库、回调白名单和外部 HTTP 客户端;passwordSlots 限制 bcrypt 并发。
type service struct {
db *sql.DB
projects map[string]*url.URL
@@ -33,13 +36,16 @@ type service struct {
slack *SlackConfig
}
// New 由进程入口调用,验证项目回调并返回独立认证路由;db 的关闭由调用方负责。
func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string, email *EmailConfig, slack *SlackConfig) (http.Handler, error) {
// 未注册邮箱也执行同成本密码比对,减少通过响应耗时区分账号存在性的差异。
dummy, err := bcrypt.GenerateFromPassword([]byte("foundry-invalid-login-placeholder"), bcrypt.DefaultCost)
if err != nil {
return nil, err
}
s := &service{db: db, email: email, slack: slack, passwordSlots: make(chan struct{}, 4), dummyPassword: dummy, projects: make(map[string]*url.URL), redirectURI: redirectURI, clientID: id, secret: secret,
google: &http.Client{Timeout: 10 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}}
// 回调固定在配置白名单,生产要求 HTTPS,开发仅允许回环主机使用 HTTP。
for name, raw := range callbacks {
u, err := url.Parse(raw)
if err != nil {
@@ -52,6 +58,7 @@ func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string
}
s.projects[name] = u
}
// healthz 仅说明进程可响应;readyz 查询账户表,覆盖连接与基础 schema 就绪性。
mux := http.NewServeMux()
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) { reply(w, 200, payload{"status": "ok"}) })
mux.HandleFunc("GET /readyz", s.wrap(func(w http.ResponseWriter, r *http.Request) error {
@@ -73,8 +80,10 @@ func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string
}), nil
}
// payload 是小型 JSON 响应对象,nil 响应体用于 204 等无内容结果。
type payload map[string]any
// reply 必须在尚未写响应时调用;编码/网络错误当前由调用链忽略。
func reply(w http.ResponseWriter, status int, body payload) {
if body != nil {
w.Header().Set("Content-Type", "application/json")
@@ -85,11 +94,13 @@ func reply(w http.ResponseWriter, status int, body payload) {
}
}
// reject 已写出预期业务错误并返回 nil,避免 wrap 再次将它改写为 503。
func reject(w http.ResponseWriter, status int, code string) error {
reply(w, status, payload{"error": code})
return nil
}
// wrap 将未处理依赖错误统一返回 503,日志仅记录类型,避免泄露凭据和提供方响应。
func (s *service) wrap(handle func(http.ResponseWriter, *http.Request) error) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
if err := handle(w, r); err != nil {
@@ -99,17 +110,20 @@ func (s *service) wrap(handle func(http.ResponseWriter, *http.Request) error) ht
}
}
// token 生成可放入 Cookie、URL fragment 或请求头的随机凭据。
func token() string {
var value [32]byte
rand.Read(value[:])
return base64.RawURLEncoding.EncodeToString(value[:])
}
// digest 用于凭据落库摘要和 S256 challenge;不用于密码存储,密码使用 bcrypt。
func digest(value string) string {
sum := sha256.Sum256([]byte(value))
return base64.RawURLEncoding.EncodeToString(sum[:])
}
// project 先校验项目,再分派登录与会话动作;Origin 缺省的服务端请求仍可进入认证。
func (s *service) project(w http.ResponseWriter, r *http.Request) error {
project, action := r.PathValue("project"), r.PathValue("action")
frontend := s.projects[project]
@@ -150,11 +164,14 @@ func (s *service) project(w http.ResponseWriter, r *http.Request) error {
return nil
}
// oauthCookie 以随机 state 区分并行登录,__Host- 前缀配合 Secure、根路径和无 Domain。
func oauthCookie(state, value string, maxAge int) *http.Cookie {
return &http.Cookie{Name: "__Host-foundry-oauth-" + state, Value: value, Path: "/", MaxAge: maxAge,
Secure: true, HttpOnly: true, SameSite: http.SameSiteLaxMode}
}
// start 保存十分钟 OAuth 尝试;browser 绑定浏览器,verifier 用于 Google 端 PKCE。
// 前端 challenge 是另一层兑换证明,最终与 login_grants 绑定。
func (s *service) start(w http.ResponseWriter, r *http.Request, project string) error {
challenge := r.URL.Query().Get("challenge")
if !tokenPattern.MatchString(challenge) {
@@ -177,6 +194,7 @@ func (s *service) start(w http.ResponseWriter, r *http.Request, project string)
return nil
}
// googleJSON 同时用于 Google 和 Slack;客户端拒绝重定向,响应解码最多读取 1 MiB。
func (s *service) googleJSON(ctx context.Context, method, endpoint string, form url.Values, bearer string, result any) error {
var body io.Reader
if form != nil {
@@ -203,6 +221,7 @@ func (s *service) googleJSON(ctx context.Context, method, endpoint string, form
return json.NewDecoder(io.LimitReader(res.Body, 1<<20)).Decode(result)
}
// callback 原子删除 OAuth 尝试后换取 Google 身份;后续网络失败也不能重放该 state。
func (s *service) callback(w http.ResponseWriter, r *http.Request) error {
ctx := r.Context()
query := r.URL.Query()
@@ -232,6 +251,7 @@ func (s *service) callback(w http.ResponseWriter, r *http.Request) error {
}
http.SetCookie(w, oauthCookie(state, "", -1))
// 复制共享 URL 后再写 fragment,避免并发请求改动项目白名单;交换码不放查询参数。
destination := *frontend
code := query.Get("code")
if code == "" || query.Has("error") {
@@ -278,6 +298,7 @@ func (s *service) callback(w http.ResponseWriter, r *http.Request) error {
return nil
}
// exchange 在同一 SQL 中消费一次性 grant 并建会话;项目、challenge、期限必须全部匹配。
func (s *service) exchange(w http.ResponseWriter, r *http.Request, project string) error {
code, verifier := r.Header.Get("X-Foundry-Code"), r.Header.Get("X-Foundry-Verifier")
if !tokenPattern.MatchString(code) || !tokenPattern.MatchString(verifier) {
@@ -307,6 +328,7 @@ func (s *service) exchange(w http.ResponseWriter, r *http.Request, project strin
return nil
}
// account 的 me 分支校验并续期,logout 按项目删除摘要且允许重复注销返回 204。
func (s *service) account(w http.ResponseWriter, r *http.Request, project string, logout bool) error {
token, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
if !ok || !tokenPattern.MatchString(token) {
+12
View File
@@ -1,3 +1,4 @@
// 邮箱登录链路:注册写待验证记录和 outbox,确认链接才创建账户;登录直接校验 bcrypt。
package auth
import (
@@ -13,11 +14,14 @@ import (
"golang.org/x/crypto/bcrypt"
)
// emailAddress 统一大小写并拒绝显示名形式,只接受最多 254 字节的纯邮箱地址。
func emailAddress(value string) (string, bool) {
value = strings.ToLower(strings.TrimSpace(value))
address, err := mail.ParseAddress(value)
return value, err == nil && address.Address == value && len(value) <= 254
}
// emailBody 限制 16 KiB、拒绝未知字段及尾随 JSON;失败时已经写出 400。
func emailBody(w http.ResponseWriter, r *http.Request, input any) bool {
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 16384))
decoder.DisallowUnknownFields()
@@ -28,6 +32,7 @@ func emailBody(w http.ResponseWriter, r *http.Request, input any) bool {
return true
}
// rateLimit 将键摘要计入数据库十五分钟固定窗口,过期后第一次访问重新计数。
func (s *service) rateLimit(ctx context.Context, key string, limit int) (bool, error) {
var count int
err := s.db.QueryRowContext(ctx, `
@@ -40,6 +45,7 @@ RETURNING attempts
return count <= limit, err
}
// emailAction 由 project 路由调用;先限频,再以非阻塞信号量限制密码哈希占用。
func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, action string) error {
if action == "verify-email" {
return s.verifyEmail(w, r, project)
@@ -70,6 +76,7 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
w.Header().Set("Retry-After", "900")
return reject(w, 429, "rate_limited")
}
// 四个槽位都忙时立即返回 429,不让昂贵 bcrypt 请求无限排队。
select {
case s.passwordSlots <- struct{}{}:
defer func() { <-s.passwordSlots }()
@@ -87,6 +94,7 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
return err
}
passwordHash := []byte(hash)
// 不存在的账户使用启动时生成的 dummy 哈希,但无论密码比对结果如何均拒绝登录。
if missing {
passwordHash = s.dummyPassword
}
@@ -102,6 +110,8 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
return nil
}
// registerEmail 在邮箱级事务锁下更新三十分钟验证记录,邮件与记录共同提交。
// 已注册邮箱不写新邮件,仍返回相同 202,避免从此响应枚举账号。
func (s *service) registerEmail(w http.ResponseWriter, r *http.Request, project, email, password string) error {
hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
if err != nil {
@@ -147,6 +157,8 @@ INSERT INTO email_outbox(project,recipient,subject,body,expires_at) VALUES($1,$2
return nil
}
// verifyEmail 先定位邮箱再加同一事务锁,随后删除并返回有效记录以保证验证码一次性消费。
// 账户、邮箱凭据、会话都成功后才提交,任何失败交由 defer 回滚。
func (s *service) verifyEmail(w http.ResponseWriter, r *http.Request, project string) error {
var input struct {
Token string `json:"token"`
+3
View File
@@ -1,3 +1,4 @@
// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。
package auth
import (
@@ -12,6 +13,7 @@ import (
"testing"
)
// TestConcurrentRegistrationAndVerification 并发重发注册与消费原验证链接,允许任一先取得邮箱锁;最终只能留下一个凭据或一个待验证记录。
func TestConcurrentRegistrationAndVerification(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -45,6 +47,7 @@ func TestConcurrentRegistrationAndVerification(t *testing.T) {
if len(match) != 2 {
t.Fatal("missing verification link")
}
// 缓冲通道收集两条 goroutine 的结果;这里断言最终数据库一致性,不规定抢锁顺序。
done := make(chan error, 2)
go func() {
r := httptest.NewRequest("POST", "https://api.example.com/register", nil)
+9 -1
View File
@@ -1,3 +1,4 @@
// 本文件把 Google、Slack、邮箱等提供方身份归一为项目账户,并签发一次性交换码。
package auth
import (
@@ -8,7 +9,10 @@ import (
"strings"
)
// identityGrant 由已完成提供方验证的登录流程调用;subject 必须是该提供方的稳定身份。
// challenge 来自前端登录起点,后续 exchange 必须提交对应 verifier 才能换取会话。
func (s *service) identityGrant(ctx context.Context, project, provider, subject string, email *string, name, picture, challenge string) (string, error) {
// 外部资料仅作为初始显示信息:限制姓名长度,头像只接受无用户信息的 HTTPS URL。
name = strings.TrimSpace(name)
if len(name) > 160 {
name = ""
@@ -20,13 +24,15 @@ func (s *service) identityGrant(ctx context.Context, project, provider, subject
if err != nil {
return "", err
}
// 账户、身份关联和短期 grant 同事务提交;任一步失败都不遗留半注册账户。
defer tx.Rollback()
// Serialize first registration for the same provider identity.
// 事务级 advisory lock 串行化同项目、同提供方、同 subject 的首次注册;事务结束即释放。
if _, err = tx.ExecContext(ctx, "SELECT pg_advisory_xact_lock(hashtextextended($1,0))", project+":"+provider+":"+subject); err != nil {
return "", err
}
var account string
err = tx.QueryRowContext(ctx, "SELECT account_id::text FROM account_identities WHERE project=$1 AND provider=$2 AND subject=$3", project, provider, subject).Scan(&account)
// 身份不存在才建账户;不会仅凭相同邮箱自动合并不同提供方的身份。
if errors.Is(err, sql.ErrNoRows) {
var googleSubject *string
if provider == "google" {
@@ -44,6 +50,7 @@ SELECT $1,id,$2,$3,
}
_, err = tx.ExecContext(ctx, "INSERT INTO account_identities(project,provider,subject,account_id) VALUES($1,$2,$3,$4)", project, provider, subject, account)
} else if err == nil {
// 老账户保留已有显示名/头像,只补空值;非空提供方邮箱会更新账户邮箱。
_, err = tx.ExecContext(ctx, `
UPDATE project_accounts SET email=COALESCE($3,email),
display_name=CASE WHEN display_name='' THEN $4 ELSE display_name END,
@@ -55,6 +62,7 @@ UPDATE project_accounts SET email=COALESCE($3,email),
if err != nil {
return "", err
}
// 只落库交换码摘要,明文仅返回给回调方;一分钟期限和前端 challenge 限制兑换。
grant := token()
_, err = tx.ExecContext(ctx, "INSERT INTO login_grants VALUES($1,$2,$3,$4,now()+interval '1 minute')", digest(grant), project, account, challenge)
if err != nil {
+12
View File
@@ -1,3 +1,4 @@
// 邮件发送采用数据库 outbox:登录请求写队列,Run 后台轮询租约并通过 SMTP 投递。
package auth
import (
@@ -15,10 +16,12 @@ import (
"time"
)
// EmailConfig 是可选 SMTP 能力配置;Password 仅用于内存中的 SMTP 认证。
type EmailConfig struct {
Host, Port, Username, Password, From string
}
// EmailConfigFromEnv 允许整组缺省以关闭邮件登录;部分配置或非 465 TLS 配置会启动失败。
func EmailConfigFromEnv() (*EmailConfig, error) {
c := &EmailConfig{Host: os.Getenv("SMTP_HOST"), Port: os.Getenv("SMTP_PORT"), Username: os.Getenv("SMTP_USERNAME"), Password: os.Getenv("SMTP_PASSWORD"), From: os.Getenv("SMTP_FROM")}
if c.Host == "" && c.Port == "" && c.Username == "" && c.Password == "" && c.From == "" {
@@ -31,6 +34,8 @@ func EmailConfigFromEnv() (*EmailConfig, error) {
return c, nil
}
// send 同步发送一封纯文本邮件;拒绝头部换行,并用 TLS 主机名验证和连接期限约束网络操作。
// SMTP 调用不接收 context,Run 的取消要等当前发送结束或网络期限到达。
func (c *EmailConfig) send(recipient, subject, body string) error {
if strings.ContainsAny(recipient+subject, "\r\n") {
return errors.New("invalid mail headers")
@@ -69,6 +74,7 @@ func (c *EmailConfig) send(recipient, subject, body string) error {
return client.Quit()
}
// Run 由进程入口启动;每三秒最多认领一封,nil 配置直接返回,取消上下文停止后续轮询。
func (c *EmailConfig) Run(ctx context.Context, db *sql.DB) {
if c == nil {
return
@@ -86,6 +92,9 @@ func (c *EmailConfig) Run(ctx context.Context, db *sql.DB) {
}
}
}
// deliver 用 SKIP LOCKED 避开其他 worker 正在认领的行,两分钟租约允许进程失败后重试。
// SMTP 成功与数据库标记并非同一事务;标记失败时后续可能再次投递。
func (c *EmailConfig) deliver(ctx context.Context, db *sql.DB) error {
var id, lease, recipient, subject, body string
var attempts int
@@ -99,11 +108,14 @@ RETURNING id::text,lease_id::text,recipient,subject,body,attempts
if err != nil {
return err
}
// lease 是本轮所有权标记;回写时匹配它,避免旧 worker 覆盖租约到期后的新认领结果。
sendErr := c.send(recipient, subject, body)
if sendErr == nil {
// 成功后清空邮件正文,减少验证码在队列中的保留;收件人和投递记录仍保留。
_, err = db.ExecContext(ctx, "UPDATE email_outbox SET sent_at=now(),body='',lease_until=NULL,lease_id=NULL WHERE id=$1 AND lease_id=$2", id, lease)
return err
}
// attempts 在认领时递增:第一次失败延迟 60 秒,指数退避最多 3840 秒,最多尝试十次。
delay := 30 * (1 << min(attempts, 7))
_, err = db.ExecContext(ctx, "UPDATE email_outbox SET available_at=now()+$3*interval '1 second',lease_until=NULL,lease_id=NULL WHERE id=$1 AND lease_id=$2", id, lease, delay)
if err != nil {
+11
View File
@@ -1,3 +1,4 @@
// 本文件是认证与 platform/research 路由共享的会话入口:数据库同时检查项目、闲置期限和绝对期限。
package auth
import (
@@ -9,11 +10,16 @@ import (
"strings"
)
// SessionIdleSeconds 是每次有效访问可续期的闲置窗口,绝对期限仍由数据库列限制。
const SessionIdleSeconds = 30 * 24 * 60 * 60
// SessionExpiryHeader 向客户端返回本次续期后的剩余秒数,供其更新本地会话提示。
const SessionExpiryHeader = "X-Foundry-Session-Expires-In"
// ErrInvalidSession 区分凭据无效与数据库故障,调用方可据此选择 401 或服务错误。
var ErrInvalidSession = errors.New("invalid session")
// Session 只携带项目内账户和剩余有效期;原始 bearer token 不进入返回结构。
type Session struct {
AccountID string
ExpiresIn int64
@@ -21,11 +27,13 @@ type Session struct {
// AuthenticateSession atomically validates and renews a live session, bounded by
// its absolute deadline. Expired, revoked and wrong-project tokens never renew.
// AuthenticateSession 在单条 UPDATE 中检查项目、闲置和绝对期限,仅续期仍有效会话并返回剩余秒数。
func AuthenticateSession(ctx context.Context, db *sql.DB, project, authorization string) (Session, error) {
value, ok := strings.CutPrefix(authorization, "Bearer ")
if !ok || !tokenPattern.MatchString(value) {
return Session{}, ErrInvalidSession
}
// 单条 UPDATE 完成校验和续期,避免先查后写把已经撤销或过期的会话重新激活。
var session Session
err := db.QueryRowContext(ctx, `
UPDATE project_sessions
@@ -33,17 +41,20 @@ SET expires_at=LEAST(now()+interval '30 days',absolute_expires_at)
WHERE project=$1 AND token_hash=$2 AND expires_at>now() AND absolute_expires_at>now()
RETURNING account_id::text,GREATEST(0,FLOOR(EXTRACT(EPOCH FROM (expires_at-now()))))::bigint
`, project, digest(value)).Scan(&session.AccountID, &session.ExpiresIn)
// 无匹配行包含错误项目、已注销、闲置过期和绝对过期,统一隐藏具体原因。
if errors.Is(err, sql.ErrNoRows) {
return Session{}, ErrInvalidSession
}
return session, err
}
// WriteSessionHeaders 由 HTTP 调用方在写出响应体前执行;它本身不校验或续期。
func WriteSessionHeaders(w http.ResponseWriter, session Session) {
w.Header().Set(SessionExpiryHeader, strconv.FormatInt(session.ExpiresIn, 10))
}
// Authenticate preserves the existing API for clients that only need an account ID.
// Authenticate 供只需账户 ID 的旧调用方使用,同样会触发 AuthenticateSession 的续期。
func Authenticate(ctx context.Context, db *sql.DB, project, authorization string) (string, error) {
session, err := AuthenticateSession(ctx, db, project, authorization)
return session.AccountID, err
+5
View File
@@ -1,3 +1,4 @@
// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。
package auth
import (
@@ -14,6 +15,7 @@ import (
_ "github.com/jackc/pgx/v5/stdlib"
)
// sessionFixture 建随机项目账户,通过 t.Cleanup 级联删除相关数据并关闭连接池。
func sessionFixture(t *testing.T) (*sql.DB, string, string) {
t.Helper()
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
@@ -33,6 +35,7 @@ func sessionFixture(t *testing.T) (*sql.DB, string, string) {
return db, project, account
}
// TestSessionIdleAndAbsoluteExpiry 覆盖闲置/绝对过期与续期上限;过期记录的时间戳不得被认证请求更新。
func TestSessionIdleAndAbsoluteExpiry(t *testing.T) {
db, project, account := sessionFixture(t)
for _, test := range []struct {
@@ -85,6 +88,7 @@ func TestSessionIdleAndAbsoluteExpiry(t *testing.T) {
}
}
// TestSessionIsolationRevocationAndConcurrentRenewal 检查错误项目与坏凭据拒绝、四个并发续期受绝对期限限制、删除后不能重新续期。
func TestSessionIsolationRevocationAndConcurrentRenewal(t *testing.T) {
db, project, account := sessionFixture(t)
value := token()
@@ -116,6 +120,7 @@ func TestSessionIsolationRevocationAndConcurrentRenewal(t *testing.T) {
}
}
// TestOAuthExchangeIssuesLongLivedSessionAndMeReturnsRemainingLifetime 从真实 grant 兑换会话,检查三十天闲置/九十天绝对期限,以及 me 响应的续期头。
func TestOAuthExchangeIssuesLongLivedSessionAndMeReturnsRemainingLifetime(t *testing.T) {
db, project, account := sessionFixture(t)
code, verifier := token(), token()
+13
View File
@@ -1,3 +1,4 @@
// Slack OIDC 登录验证独立 ID token,再复用 identityGrant 和前端 grant 兑换协议。
package auth
import (
@@ -18,6 +19,7 @@ import (
"time"
)
// SlackConfig 保存可选客户端凭据以及由 mu 保护的签名公钥缓存。
type SlackConfig struct {
ClientID, Secret, RedirectURI string
mu sync.Mutex
@@ -25,6 +27,7 @@ type SlackConfig struct {
fetchedAt time.Time
}
// SlackConfigFromEnv 允许整组缺省以关闭 Slack;只配置一半会阻止服务启动。
func SlackConfigFromEnv(redirect string) (*SlackConfig, error) {
id, secret := os.Getenv("SLACK_CLIENT_ID"), os.Getenv("SLACK_CLIENT_SECRET")
if id == "" && secret == "" {
@@ -36,6 +39,7 @@ func SlackConfigFromEnv(redirect string) (*SlackConfig, error) {
return &SlackConfig{ClientID: id, Secret: secret, RedirectURI: redirect}, nil
}
// slackClaims 仅在验签、发行方/受众/时间和 nonce 校验后用于账户身份。
type slackClaims struct {
Issuer string `json:"iss"`
Subject string `json:"sub"`
@@ -50,6 +54,7 @@ type slackClaims struct {
Picture string `json:"picture"`
}
// slackKey 在互斥锁内加载并缓存 JWKS 一分钟;缓存期遇到未知 kid 直接拒绝,避免重复拉取。
func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, error) {
c := s.slack
c.mu.Lock()
@@ -73,6 +78,7 @@ func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, err
if err := s.googleJSON(ctx, "GET", "https://slack.com/openid/connect/keys", nil, "", &document); err != nil {
return nil, err
}
// 只接收可用于 RS256 签名的 RSA 公钥,并约束模数和指数大小。
keys := map[string]*rsa.PublicKey{}
for _, key := range document.Keys {
n, nErr := base64.RawURLEncoding.DecodeString(key.N)
@@ -93,6 +99,8 @@ func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, err
}
return nil, errors.New("unknown Slack signing key")
}
// verifySlack 限制 token 长度与算法,先验签再信任 payload;nonce 将身份绑定到本次登录。
func (s *service) verifySlack(ctx context.Context, value, nonce string) (slackClaims, error) {
var claims slackClaims
invalid := errors.New("invalid Slack identity token")
@@ -136,6 +144,8 @@ func (s *service) verifySlack(ctx context.Context, value, nonce string) (slackCl
}
return claims, nil
}
// startSlack 写十分钟尝试和 OIDC nonce,Cookie 采用 SameSite=None 以接收跨站 POST 回调。
func (s *service) startSlack(w http.ResponseWriter, r *http.Request, project string) error {
if s.slack == nil {
return reject(w, 503, "slack_not_configured")
@@ -159,6 +169,8 @@ VALUES($1,$2,$3,$4,'',now()+interval '10 minutes','slack',$5)
http.Redirect(w, r, "https://slack.com/openid/connect/authorize?"+query.Encode(), 302)
return nil
}
// slackCallback 接受 GET/POST,先一次性消费浏览器绑定的尝试,再向 Slack 兑换 ID token。
func (s *service) slackCallback(w http.ResponseWriter, r *http.Request) error {
if s.slack == nil {
return reject(w, 503, "slack_not_configured")
@@ -216,6 +228,7 @@ RETURNING project,frontend_challenge,oidc_nonce
if err != nil {
return err
}
// 团队和用户共同构成 subject;verifySlack 已拒绝冒号,避免拼接身份产生歧义。
grant, err := s.identityGrant(r.Context(), project, "slack", claims.Team+":"+claims.Subject, claims.Email, claims.Name, claims.Picture, challenge)
if err != nil {
return err
+9
View File
@@ -1,3 +1,4 @@
// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。
package auth
import (
@@ -21,6 +22,7 @@ import (
_ "github.com/jackc/pgx/v5/stdlib"
)
// signIdentity 为 fixture kid 生成 RS256 JWT;测试公钥缓存在内存,不访问 Slack JWKS。
func signIdentity(t *testing.T, key *rsa.PrivateKey, claims slackClaims) string {
t.Helper()
header := base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"RS256","kid":"fixture"}`))
@@ -36,6 +38,8 @@ func signIdentity(t *testing.T, key *rsa.PrivateKey, claims slackClaims) string
}
return value + "." + base64.RawURLEncoding.EncodeToString(sig)
}
// TestSlackIdentityVerification 使用本地 RSA 私钥签发样本,分别破坏发行方、受众、时间、nonce、签名及算法,仅有效样本可通过。
func TestSlackIdentityVerification(t *testing.T) {
key, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
@@ -76,6 +80,8 @@ func TestSlackIdentityVerification(t *testing.T) {
})
}
}
// TestSlackCallbackAndExchange 使用临时 HTTP 上游和真实测试库走 Slack 起点、POST 回调、grant 兑换;拒绝回调重放并保留用户已选资料。
func TestSlackCallbackAndExchange(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -184,8 +190,10 @@ func TestSlackCallbackAndExchange(t *testing.T) {
}
}
// rewriteTransport 只把测试外部调用改写到本地上游,保留路径和请求上下文。
type rewriteTransport struct{ destination string }
// RoundTrip 克隆请求后改目标,避免修改被测函数持有的原请求对象。
func (t rewriteTransport) RoundTrip(r *http.Request) (*http.Response, error) {
cloned := r.Clone(r.Context())
target, _ := url.Parse(t.destination)
@@ -193,6 +201,7 @@ func (t rewriteTransport) RoundTrip(r *http.Request) (*http.Response, error) {
return http.DefaultTransport.RoundTrip(cloned)
}
// TestGoogleIdentityKeepsLegacyAccount 依赖迁移 fixture 的旧 Google 身份与会话,验证新身份归一流程仍使用原账户且不删除旧会话。
func TestGoogleIdentityKeepsLegacyAccount(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {