feat(forgejo): upstream OAuth client (forgejo-mcp-broker-b9i)
Adds internal/forgejo: a stateless OAuth 2.1 client for upstream Forgejo.
Covers what the broker AS needs:
- AuthorizeURL: builds the user-agent redirect to /login/oauth/authorize
- ExchangeCode: code → access+refresh tokens (PKCE verifier included)
- Refresh: refresh_token grant (Forgejo rotates the refresh token)
- FetchUserInfo: OIDC userinfo claims (sub, preferred_username, etc.)
OAuth errors come back as a structured *forgejo.Error so the AS can
distinguish "user must re-authenticate" (invalid_grant) from "transient
network problem" via errors.As. Forgejo doesn't currently expose a token
revocation endpoint, so revocation lives in the broker's own store —
upstream tokens expire naturally.
Defaults:
- 30s HTTP timeout (Forgejo OAuth is sub-second when healthy)
- User-Agent "fjmcp-broker" if not overridden
- 64 KiB cap on response bodies (these endpoints return ~kilobytes)
Tests: 95.1% coverage. httptest.Server fake Forgejo exercises every
public method, every error shape (OAuth-formatted, plain {"message":...},
malformed JSON, missing required fields, network failure), and verifies
form params hit the wire as expected.
Closes forgejo-mcp-broker-b9i.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
e4a7baa0bc
commit
006d5c1448
3 changed files with 669 additions and 2 deletions
277
internal/forgejo/forgejo.go
Normal file
277
internal/forgejo/forgejo.go
Normal file
|
|
@ -0,0 +1,277 @@
|
|||
// Package forgejo is the broker's OAuth 2.1 client for upstream Forgejo.
|
||||
//
|
||||
// Scope is narrow on purpose: build the authorize URL, exchange a code for
|
||||
// access+refresh tokens, refresh, and fetch user info. The package is
|
||||
// stateless — callers own persistence (the OAuth AS in internal/oauth holds
|
||||
// the token store, not us).
|
||||
//
|
||||
// Forgejo speaks OIDC at /login/oauth/* and exposes a userinfo endpoint
|
||||
// returning standard OIDC claims. Token revocation is not yet supported by
|
||||
// upstream Forgejo (as of this writing), so the broker handles "revoke" by
|
||||
// dropping its own copy and letting the upstream token expire naturally.
|
||||
package forgejo
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Default HTTP timeout. Conservative — Forgejo OAuth is a sub-second
|
||||
// operation in healthy conditions; 30s leaves room for slow networks
|
||||
// without letting a misbehaving upstream stall a request indefinitely.
|
||||
const defaultHTTPTimeout = 30 * time.Second
|
||||
|
||||
// Client talks to a Forgejo instance's OAuth 2.1 endpoints.
|
||||
type Client struct {
|
||||
baseURL *url.URL
|
||||
clientID string
|
||||
clientSecret string
|
||||
userAgent string
|
||||
httpClient *http.Client
|
||||
}
|
||||
|
||||
// ClientConfig collects the fields required to construct a Client. BaseURL,
|
||||
// ClientID, and ClientSecret are required; the rest have sensible defaults.
|
||||
type ClientConfig struct {
|
||||
BaseURL string
|
||||
ClientID string
|
||||
ClientSecret string
|
||||
UserAgent string // default "fjmcp-broker"
|
||||
HTTPClient *http.Client // default with a 30s timeout
|
||||
}
|
||||
|
||||
// NewClient validates the config and returns a ready-to-use Client.
|
||||
func NewClient(cfg ClientConfig) (*Client, error) {
|
||||
if cfg.BaseURL == "" {
|
||||
return nil, errors.New("forgejo: BaseURL is required")
|
||||
}
|
||||
if cfg.ClientID == "" {
|
||||
return nil, errors.New("forgejo: ClientID is required")
|
||||
}
|
||||
if cfg.ClientSecret == "" {
|
||||
return nil, errors.New("forgejo: ClientSecret is required")
|
||||
}
|
||||
u, err := url.Parse(cfg.BaseURL)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("forgejo: parse BaseURL %q: %w", cfg.BaseURL, err)
|
||||
}
|
||||
if u.Scheme != "http" && u.Scheme != "https" {
|
||||
return nil, fmt.Errorf("forgejo: BaseURL must use http(s), got %q", u.Scheme)
|
||||
}
|
||||
if u.Host == "" {
|
||||
return nil, fmt.Errorf("forgejo: BaseURL missing host: %q", cfg.BaseURL)
|
||||
}
|
||||
httpClient := cfg.HTTPClient
|
||||
if httpClient == nil {
|
||||
httpClient = &http.Client{Timeout: defaultHTTPTimeout}
|
||||
}
|
||||
ua := cfg.UserAgent
|
||||
if ua == "" {
|
||||
ua = "fjmcp-broker"
|
||||
}
|
||||
return &Client{
|
||||
baseURL: u,
|
||||
clientID: cfg.ClientID,
|
||||
clientSecret: cfg.ClientSecret,
|
||||
userAgent: ua,
|
||||
httpClient: httpClient,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// AuthorizeURLOptions controls the redirect to Forgejo's authorize endpoint.
|
||||
type AuthorizeURLOptions struct {
|
||||
RedirectURI string // where Forgejo will send the user back (broker /oauth/callback)
|
||||
State string // opaque CSRF token; broker stores and re-checks it
|
||||
Scopes string // space-separated; mapped to Forgejo's coarse scope set
|
||||
CodeChallenge string // PKCE challenge (S256)
|
||||
CodeChallengeMethod string // must be "S256"
|
||||
}
|
||||
|
||||
// AuthorizeURL builds the URL to redirect the user-agent to so Forgejo can
|
||||
// authenticate them and ask for consent. Required: RedirectURI, State,
|
||||
// CodeChallenge, CodeChallengeMethod. Scopes is optional (Forgejo will use
|
||||
// its app-default if empty).
|
||||
func (c *Client) AuthorizeURL(opts AuthorizeURLOptions) string {
|
||||
q := url.Values{}
|
||||
q.Set("response_type", "code")
|
||||
q.Set("client_id", c.clientID)
|
||||
q.Set("redirect_uri", opts.RedirectURI)
|
||||
q.Set("state", opts.State)
|
||||
q.Set("code_challenge", opts.CodeChallenge)
|
||||
q.Set("code_challenge_method", opts.CodeChallengeMethod)
|
||||
if opts.Scopes != "" {
|
||||
q.Set("scope", opts.Scopes)
|
||||
}
|
||||
u := *c.baseURL
|
||||
u.Path = strings.TrimRight(u.Path, "/") + "/login/oauth/authorize"
|
||||
u.RawQuery = q.Encode()
|
||||
return u.String()
|
||||
}
|
||||
|
||||
// TokenResponse is the parsed body of a successful token endpoint response.
|
||||
type TokenResponse struct {
|
||||
AccessToken string `json:"access_token"`
|
||||
TokenType string `json:"token_type"`
|
||||
RefreshToken string `json:"refresh_token,omitempty"`
|
||||
ExpiresIn int `json:"expires_in"`
|
||||
Scope string `json:"scope,omitempty"`
|
||||
}
|
||||
|
||||
// Error is the structured form of an OAuth error response from the token
|
||||
// or userinfo endpoint. Callers can `errors.As(err, &forgejo.Error{})` to
|
||||
// decide how to react (e.g. invalid_grant → user must re-authenticate).
|
||||
type Error struct {
|
||||
Code string // OAuth error code, e.g. "invalid_grant"
|
||||
Description string // optional human-readable description
|
||||
HTTPStatus int // upstream HTTP status code
|
||||
}
|
||||
|
||||
func (e *Error) Error() string {
|
||||
if e.Description != "" {
|
||||
return fmt.Sprintf("forgejo oauth: %s (http %d): %s", e.Code, e.HTTPStatus, e.Description)
|
||||
}
|
||||
return fmt.Sprintf("forgejo oauth: %s (http %d)", e.Code, e.HTTPStatus)
|
||||
}
|
||||
|
||||
// ExchangeCode swaps an authorization code for access+refresh tokens.
|
||||
// codeVerifier is the PKCE verifier matching the challenge sent on /authorize.
|
||||
func (c *Client) ExchangeCode(ctx context.Context, code, codeVerifier, redirectURI string) (*TokenResponse, error) {
|
||||
form := url.Values{}
|
||||
form.Set("grant_type", "authorization_code")
|
||||
form.Set("code", code)
|
||||
form.Set("redirect_uri", redirectURI)
|
||||
form.Set("client_id", c.clientID)
|
||||
form.Set("client_secret", c.clientSecret)
|
||||
form.Set("code_verifier", codeVerifier)
|
||||
return c.postToken(ctx, form)
|
||||
}
|
||||
|
||||
// Refresh exchanges a refresh token for a new access token. Forgejo returns
|
||||
// a new refresh token alongside (token rotation).
|
||||
func (c *Client) Refresh(ctx context.Context, refreshToken string) (*TokenResponse, error) {
|
||||
form := url.Values{}
|
||||
form.Set("grant_type", "refresh_token")
|
||||
form.Set("refresh_token", refreshToken)
|
||||
form.Set("client_id", c.clientID)
|
||||
form.Set("client_secret", c.clientSecret)
|
||||
return c.postToken(ctx, form)
|
||||
}
|
||||
|
||||
func (c *Client) postToken(ctx context.Context, form url.Values) (*TokenResponse, error) {
|
||||
endpoint := c.endpoint("/login/oauth/access_token")
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader(form.Encode()))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("forgejo: build token request: %w", err)
|
||||
}
|
||||
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
|
||||
req.Header.Set("Accept", "application/json")
|
||||
req.Header.Set("User-Agent", c.userAgent)
|
||||
|
||||
resp, err := c.httpClient.Do(req)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("forgejo: token request: %w", err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
|
||||
body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<16))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("forgejo: read token response: %w", err)
|
||||
}
|
||||
|
||||
if resp.StatusCode/100 != 2 {
|
||||
return nil, parseOAuthError(body, resp.StatusCode)
|
||||
}
|
||||
|
||||
var tok TokenResponse
|
||||
if err := json.Unmarshal(body, &tok); err != nil {
|
||||
return nil, fmt.Errorf("forgejo: decode token response: %w", err)
|
||||
}
|
||||
if tok.AccessToken == "" {
|
||||
return nil, fmt.Errorf("forgejo: token response missing access_token")
|
||||
}
|
||||
return &tok, nil
|
||||
}
|
||||
|
||||
// UserInfo is the subset of OIDC userinfo claims the broker cares about.
|
||||
// Forgejo populates `sub` with the numeric user ID (as a string).
|
||||
type UserInfo struct {
|
||||
Sub string `json:"sub"`
|
||||
PreferredUsername string `json:"preferred_username"`
|
||||
Name string `json:"name,omitempty"`
|
||||
Email string `json:"email,omitempty"`
|
||||
}
|
||||
|
||||
// FetchUserInfo calls the OIDC /login/oauth/userinfo endpoint with the given
|
||||
// access token and returns the parsed claims.
|
||||
func (c *Client) FetchUserInfo(ctx context.Context, accessToken string) (*UserInfo, error) {
|
||||
endpoint := c.endpoint("/login/oauth/userinfo")
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("forgejo: build userinfo request: %w", err)
|
||||
}
|
||||
req.Header.Set("Authorization", "Bearer "+accessToken)
|
||||
req.Header.Set("Accept", "application/json")
|
||||
req.Header.Set("User-Agent", c.userAgent)
|
||||
|
||||
resp, err := c.httpClient.Do(req)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("forgejo: userinfo request: %w", err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
|
||||
body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<16))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("forgejo: read userinfo response: %w", err)
|
||||
}
|
||||
if resp.StatusCode/100 != 2 {
|
||||
// userinfo errors aren't always shaped as RFC 6749 OAuth errors —
|
||||
// some Forgejo versions return plain JSON like {"message": "..."}
|
||||
// for 401. Try the OAuth shape first, fall back to a generic.
|
||||
if oerr := parseOAuthError(body, resp.StatusCode); oerr.Code != "" {
|
||||
return nil, oerr
|
||||
}
|
||||
return nil, &Error{
|
||||
Code: "userinfo_failed",
|
||||
Description: strings.TrimSpace(string(body)),
|
||||
HTTPStatus: resp.StatusCode,
|
||||
}
|
||||
}
|
||||
var ui UserInfo
|
||||
if err := json.Unmarshal(body, &ui); err != nil {
|
||||
return nil, fmt.Errorf("forgejo: decode userinfo response: %w", err)
|
||||
}
|
||||
if ui.Sub == "" {
|
||||
return nil, fmt.Errorf("forgejo: userinfo response missing sub")
|
||||
}
|
||||
return &ui, nil
|
||||
}
|
||||
|
||||
func (c *Client) endpoint(path string) string {
|
||||
u := *c.baseURL
|
||||
u.Path = strings.TrimRight(u.Path, "/") + path
|
||||
u.RawQuery = ""
|
||||
return u.String()
|
||||
}
|
||||
|
||||
// parseOAuthError extracts a structured Error from a 4xx/5xx body. If the
|
||||
// body isn't valid JSON or doesn't carry an "error" field, returns an Error
|
||||
// with Code="" so callers can fall back to a generic message.
|
||||
func parseOAuthError(body []byte, status int) *Error {
|
||||
var raw struct {
|
||||
Code string `json:"error"`
|
||||
Description string `json:"error_description"`
|
||||
}
|
||||
_ = json.Unmarshal(body, &raw) // best-effort
|
||||
return &Error{
|
||||
Code: raw.Code,
|
||||
Description: raw.Description,
|
||||
HTTPStatus: status,
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue