用户(Resource Owner) ──点击登录──> Client
Client ──重定向──> Authorization Server ──"是否授权？"──> 用户
用户 ──同意──> Authorization Server
Authorization Server ──authorization_code──> Client（通过用户浏览器重定向）
Client ──authorization_code──> Authorization Server（后端直连）
Authorization Server ──access_token──> Client（后端直连）
Client ──access_token──> Resource Server（后端直连）
Resource Server ──受保护资源──> Client

1. Client 重定向用户到授权服务器
   GET /authorize?response_type=code&client_id=xxx&redirect_uri=xxx&scope=xxx&state=xxx

2. 用户登录并授权（在授权服务器域名下完成）

3. 授权服务器重定向回 Client，携带 code
   302 Location: https://client.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xxx

4. Client 后端用 code 向授权服务器换 token
   POST /token
   Host: authorization-server.com
   Body: grant_type=authorization_code&code=xxx&redirect_uri=xxx&client_id=xxx&client_secret=xxx

5. 授权服务器返回 access_token（和可选的 refresh_token）
   {
     "access_token": "2YotnFZFEjr1zCsicMWpAA",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
   }

POST /token
Body: grant_type=client_credentials&client_id=xxx&client_secret=xxx&scope=xxx

Response:
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

GET /authorize?response_type=token&client_id=xxx&redirect_uri=xxx&scope=xxx&state=xxx

// 授权服务器直接在 URL fragment 中返回 access_token
302 Location: https://client.example.com/callback#access_token=xxx&expires_in=3600

POST /token
Body: grant_type=password&username=xxx&password=xxx&client_id=xxx

Response:
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

https://client.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA

Step 1: Client 生成 code_verifier
         code_verifier = 43-128 个字符的随机字符串
         （字符集：[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"）

Step 2: Client 计算 code_challenge
         code_challenge = BASE64URL(SHA256(code_verifier))

Step 3: 授权请求携带 code_challenge
         GET /authorize?response_type=code&code_challenge=xxx&code_challenge_method=S256...

Step 4: 授权服务器存储 code_challenge（与 code 关联）

Step 5: 用 code 换 token 时，同时发送 code_verifier
         POST /token
         Body: grant_type=authorization_code&code=xxx&code_verifier=yyy...

Step 6: 授权服务器验证
         BASE64URL(SHA256(code_verifier)) == 之前存储的 code_challenge ?

func generateCodeVerifier() (string, error) {
    // 43-128 字符的未保留字符随机串
    // 推荐使用 32 字节随机数 base64url 编码后约 43 字符
    b := make([]byte, 32)
    if _, err := rand.Read(b); err != nil {
        return "", err
    }
    return base64.RawURLEncoding.EncodeToString(b), nil
}

func computeCodeChallenge(verifier string) string {
    h := sha256.Sum256([]byte(verifier))
    return base64.RawURLEncoding.EncodeToString(h[:])
}

POST /token
Body: grant_type=refresh_token&refresh_token=old_refresh_token

Response:
{
  "access_token": "new_access_token",
  "refresh_token": "new_refresh_token",  // 旧 token 失效
  "expires_in": 3600
}

{
  "access_token": "xxx",
  "expires_in": 3600,    // 秒，而非 "2026-06-15T14:00:00Z"
  "token_type": "Bearer"
}

// Step 1: 发起授权请求前生成 state
func initiateOAuth(w http.ResponseWriter, r *http.Request) {
    state := generateRandomState() // 32 字节随机数，base64url 编码

    // 将 state 存入 session（服务端）
    session.Values["oauth_state"] = state
    session.Save(r, w)

    // 将 state 放入授权 URL
    authURL := fmt.Sprintf(
        "https://auth.example.com/authorize?response_type=code&client_id=%s&state=%s&...",
        clientID, state,
    )
    http.Redirect(w, r, authURL, http.StatusFound)
}

// Step 2: 回调时验证 state
func oauthCallback(w http.ResponseWriter, r *http.Request) {
    returnedState := r.URL.Query().Get("state")
    expectedState := session.Values["oauth_state"].(string)

    if returnedState != expectedState {
        // state 不匹配：这是 CSRF 攻击或重放
        http.Error(w, "Invalid state", http.StatusBadRequest)
        return
    }

    // state 匹配：继续换 token
    delete(session.Values, "oauth_state") // 用完即弃
    session.Save(r, w)

    // ... 用 code 换 token
}

func generateRandomState() string {
    b := make([]byte, 32)
    rand.Read(b)
    return base64.RawURLEncoding.EncodeToString(b)
}

<!-- 在 https://client.example.com/callback?code=xxx 页面上 -->
<img src="https://external-site.com/pixel.gif">
<!-- 浏览器发送 Referer: https://client.example.com/callback?code=xxx -->

// 攻击者构造的恶意授权请求
GET /authorize?response_type=code&client_id=xxx&redirect_uri=https://evil.com/callback

// 如果授权服务器不验证 redirect_uri 与注册值匹配：
// → 用户授权后，浏览器跳转到 evil.com，code 暴露给攻击者

func validateRedirectURI(registered, requested string) error {
    // OAuth 2.1: 精确字符串匹配，不允许通配符
    if registered != requested {
        return fmt.Errorf("redirect_uri mismatch: expected %q, got %q", registered, requested)
    }

    u, err := url.Parse(requested)
    if err != nil {
        return fmt.Errorf("invalid redirect_uri: %w", err)
    }

    // 仅允许 HTTPS（本地开发例外）
    if u.Scheme != "https" && !isLocalDevelopment(u) {
        return fmt.Errorf("redirect_uri must use HTTPS")
    }

    // 禁止 fragment（fragment 不会被发送到服务器）
    if u.Fragment != "" {
        return fmt.Errorf("redirect_uri must not contain fragment")
    }

    // 禁止 userinfo 部分
    if u.User != nil {
        return fmt.Errorf("redirect_uri must not contain userinfo")
    }

    return nil
}

func validateAccessToken(tokenString string, requiredAudience string) (*Claims, error) {
    claims := &Claims{}
    token, err := jwt.ParseWithClaims(tokenString, claims, func(token *jwt.Token) (interface{}, error) {
        return publicKey, nil
    })
    if err != nil {
        return nil, err
    }

    // 核心：验证 aud（audience）——这个 token 是颁给哪个 Client 的
    audOK := false
    for _, aud := range claims.Audience {
        if aud == requiredAudience {
            audOK = true
            break
        }
    }
    if !audOK {
        return nil, fmt.Errorf("token audience %v does not include %s", claims.Audience, requiredAudience)
    }

    return claims, nil
}

func generateToken() (string, error) {
    b := make([]byte, 32)
    if _, err := rand.Read(b); err != nil {
        return "", err
    }
    return hex.EncodeToString(b), nil
}

type AuthUser struct {
    UserID      int64
    Role        string   // user / admin / superadmin
    Status      string   // active / restricted / banned / deleted
    AccessToken string   // 飞书 user_access_token，后端调飞书 API 使用
}

// 创建会话时存储 refresh_token 的 SHA256 摘要
func CreateAuthSession(ctx context.Context, userID int64, refreshToken string, expiresAt time.Time) error {
    hash := sha256.Sum256([]byte(refreshToken))
    session := &AuthSession{
        UserID:           userID,
        RefreshTokenHash: hex.EncodeToString(hash[:]), // 存哈希，不存明文
        Status:           "active",
        ExpiresAt:        expiresAt,
    }
    return db.Insert(ctx, session)
}

// 正确的做法：留出 60 秒缓冲
ttl := time.Duration(expireInSec-60) * time.Second
if ttl < 60*time.Second {
    ttl = 60 * time.Second  // 兜底最小 60 秒
}

const (
    FeishuAppTokenKey    = "feishu:app_token"
    FeishuTenantTokenKey = "feishu:tenant_token"
    FeishuJSAPITicketKey = "feishu:jsapi_ticket"
)

// larkcore.Cache 接口
type Cache interface {
    Set(ctx context.Context, key, value string, expireTime time.Duration) error
    Get(ctx context.Context, key string) (string, error)
}

type RedisCache struct{}

// 编译期接口断言：SDK 升级变更 Cache 接口时编译直接报错
var _ larkcore.Cache = RedisCache{}

func (RedisCache) Set(ctx context.Context, key, value string, expireTime time.Duration) error {
    ctx = pkgredis.WithProjectPrefixOnly(ctx)
    return pkgredis.Client.Set(ctx, key, value, expireTime).Err()
}

func (RedisCache) Get(ctx context.Context, key string) (string, error) {
    ctx = pkgredis.WithProjectPrefixOnly(ctx)
    value, err := pkgredis.Client.Get(ctx, key).Result()
    if err == goredis.Nil {
        return "", nil  // 关键：未命中返回空串，不是 error
    }
    return value, err
}

func Init() {
    cfg := config.AppConfig
    if cfg.Feishu_AppID == "" || cfg.Feishu_AppSecret == "" {
        panic("feishu: FEISHU_APP_ID / FEISHU_APP_SECRET must be configured")
    }
    Client = lark.NewClient(
        cfg.Feishu_AppID,
        cfg.Feishu_AppSecret,
        lark.WithTokenCache(RedisCache{}),
        lark.WithEnableTokenCache(true),
        lark.WithReqTimeout(10*time.Second),
    )
}

func Login(ctx context.Context, req *userv1.LoginRequest) (*userv1.LoginResponse, error) {
    // 1. 用飞书授权码换 token（含 PKCE code_verifier）
    feishuToken, err := feishu.ExchangeCode(ctx, req.Code, codeVerifier, req.GetRedirectUri())
    if err != nil {
        return nil, fmt.Errorf("feishu exchange code: %w", err)
    }

    // 2. 用飞书 token 获取当前用户信息
    userInfo, err := feishu.GetCurrentUser(ctx, feishuToken.AccessToken)
    if err != nil {
        return nil, fmt.Errorf("feishu get current user: %w", err)
    }

    // 3. 创建或更新本地用户记录（Upsert）
    user, err := repository.UpsertUser(ctx, userInfo.OpenID, userInfo.Name, userInfo.AvatarURL)
    if err != nil {
        return nil, fmt.Errorf("upsert user: %w", err)
    }

    // 4. 状态门禁——不在 SQL 层过滤，应用层明确判断
    if err := checkUserCanLogin(user); err != nil {
        return nil, err
    }

    // 5. 生成后端自签 token
    sessionToken, err := generateToken()
    if err != nil {
        return nil, fmt.Errorf("generate token: %w", err)
    }

    // 6. 写 session 和 user cache 到 Redis
    store.SaveSession(ctx, sessionToken, authUser)
    store.SaveUserCache(ctx, authUser)

    // 7. 返回
    return &userv1.LoginResponse{
        AccessToken: sessionToken,
        ExpiresIn:   int32(sessionTTL.Seconds()),
        Member:      toLoginMember(user),
    }, nil
}

package oauth

import (
    "context"
    "crypto/rand"
    "crypto/sha256"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "strings"
    "sync"
    "time"
)

// OAuth2Config holds client registration details.
type OAuth2Config struct {
    ClientID     string
    ClientSecret string
    RedirectURI  string
    AuthURL      string // e.g. https://auth.example.com/authorize
    TokenURL     string // e.g. https://auth.example.com/token
    Scopes       []string
}

// TokenSet represents the OAuth 2.0 token response.
type TokenSet struct {
    AccessToken  string `json:"access_token"`
    TokenType    string `json:"token_type"`
    RefreshToken string `json:"refresh_token,omitempty"`
    ExpiresIn    int    `json:"expires_in"`
}

// Client handles the OAuth 2.0 authorization code flow with PKCE.
type Client struct {
    config OAuth2Config
    http   *http.Client
    mu     sync.Mutex
}

// NewClient creates a new OAuth 2.0 client.
func NewClient(config OAuth2Config) *Client {
    return &Client{
        config: config,
        http:   &http.Client{Timeout: 10 * time.Second},
    }
}

// generateRandomString generates a cryptographically random URL-safe string.
func generateRandomString(length int) (string, error) {
    b := make([]byte, length)
    if _, err := rand.Read(b); err != nil {
        return "", err
    }
    return base64.RawURLEncoding.EncodeToString(b), nil
}

// computeCodeChallenge computes the S256 code challenge from a verifier.
// RFC 7636 Section 4.2: code_challenge = BASE64URL(SHA256(code_verifier))
func computeCodeChallenge(verifier string) string {
    h := sha256.Sum256([]byte(verifier))
    return base64.RawURLEncoding.EncodeToString(h[:])
}

// BuildAuthURL constructs the authorization URL for initiating the OAuth flow.
// It generates a new PKCE code_verifier + code_challenge pair and a CSRF state.
func (c *Client) BuildAuthURL() (authURL, state, codeVerifier string, err error) {
    state, err = generateRandomString(32) // 256 bits of entropy
    if err != nil {
        return "", "", "", fmt.Errorf("generate state: %w", err)
    }

    codeVerifier, err = generateRandomString(32) // 256 bits
    if err != nil {
        return "", "", "", fmt.Errorf("generate code_verifier: %w", err)
    }

    codeChallenge := computeCodeChallenge(codeVerifier)

    u, err := url.Parse(c.config.AuthURL)
    if err != nil {
        return "", "", "", fmt.Errorf("parse auth URL: %w", err)
    }

    q := u.Query()
    q.Set("response_type", "code")
    q.Set("client_id", c.config.ClientID)
    q.Set("redirect_uri", c.config.RedirectURI)
    q.Set("scope", strings.Join(c.config.Scopes, " "))
    q.Set("state", state)
    q.Set("code_challenge", codeChallenge)
    q.Set("code_challenge_method", "S256")
    u.RawQuery = q.Encode()

    return u.String(), state, codeVerifier, nil
}

// ExchangeCode exchanges an authorization code for tokens.
// The code_verifier must match the one generated during BuildAuthURL.
func (c *Client) ExchangeCode(ctx context.Context, code, codeVerifier string) (*TokenSet, error) {
    data := url.Values{
        "grant_type":    {"authorization_code"},
        "code":          {code},
        "redirect_uri":  {c.config.RedirectURI},
        "client_id":     {c.config.ClientID},
        "client_secret": {c.config.ClientSecret},
        "code_verifier": {codeVerifier}, // PKCE: prove possession of the verifier
    }

    return c.doTokenRequest(ctx, data)
}

// RefreshAccessToken uses a refresh token to obtain a new access token.
// Implements refresh token rotation: the old refresh token is invalidated.
func (c *Client) RefreshAccessToken(ctx context.Context, refreshToken string) (*TokenSet, error) {
    data := url.Values{
        "grant_type":    {"refresh_token"},
        "refresh_token": {refreshToken},
        "client_id":     {c.config.ClientID},
        "client_secret": {c.config.ClientSecret},
    }

    return c.doTokenRequest(ctx, data)
}

// doTokenRequest sends a POST request to the token endpoint.
func (c *Client) doTokenRequest(ctx context.Context, data url.Values) (*TokenSet, error) {
    req, err := http.NewRequestWithContext(ctx, "POST", c.config.TokenURL,
        strings.NewReader(data.Encode()))
    if err != nil {
        return nil, fmt.Errorf("build token request: %w", err)
    }
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    resp, err := c.http.Do(req)
    if err != nil {
        return nil, fmt.Errorf("token request: %w", err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20)) // 1 MB limit
    if err != nil {
        return nil, fmt.Errorf("read token response: %w", err)
    }

    if resp.StatusCode >= 400 {
        return nil, fmt.Errorf("token endpoint returned %d: %s", resp.StatusCode, string(body))
    }

    var token TokenSet
    if err := json.Unmarshal(body, &token); err != nil {
        return nil, fmt.Errorf("parse token response: %w", err)
    }

    return &token, nil
}

// CallbackHandler is an HTTP handler for the OAuth redirect endpoint.
// It validates the state parameter (CSRF protection) and exchanges the code.
func (c *Client) CallbackHandler(expectedState, expectedCodeVerifier string, onSuccess func(*TokenSet)) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // Validate state parameter to prevent CSRF (RFC 6819 Section 4.4.1)
        returnedState := r.URL.Query().Get("state")
        if returnedState == "" || returnedState != expectedState {
            http.Error(w, "Invalid state parameter", http.StatusBadRequest)
            return
        }

        // Check for authorization errors
        if errDesc := r.URL.Query().Get("error_description"); errDesc != "" {
            http.Error(w, fmt.Sprintf("Authorization error: %s", errDesc), http.StatusBadRequest)
            return
        }

        code := r.URL.Query().Get("code")
        if code == "" {
            http.Error(w, "Missing authorization code", http.StatusBadRequest)
            return
        }

        // Exchange code for token (PKCE verifier proves possession)
        token, err := c.ExchangeCode(r.Context(), code, expectedCodeVerifier)
        if err != nil {
            http.Error(w, fmt.Sprintf("Token exchange failed: %v", err), http.StatusInternalServerError)
            return
        }

        onSuccess(token)
        w.Write([]byte("Authorization successful"))
    }
}

前端获取 JSAPI 签名 → 飞书授权页 → 回调 → 换 token → 获取用户 → Upsert
→ 状态门禁 → 自签 token → 写 session/cache → 返回