docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]
This commit is contained in:
@@ -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) {
|
||||
|
||||
Reference in New Issue
Block a user