Documentation
¶
Overview ¶
Package oauth implements an OAuth 2.1 authorization server for BubbleFish Nexus, enabling ChatGPT and other OAuth-only MCP clients to connect.
The implementation is additive — all existing Bearer token auth (bfn_mcp_, bfn_data_, bfn_admin_) is preserved unchanged.
Reference: Post-Build Add-On Update Technical Specification Section 3.
Index ¶
- Constants
- func GenerateCode() (string, error)
- func GenerateRSAKey() (*rsa.PrivateKey, error)
- func LoadRSAKey(path string) (*rsa.PrivateKey, error)
- func MarshalJWKS(pub *rsa.PublicKey) ([]byte, error)
- func SaveRSAKey(key *rsa.PrivateKey, path string) error
- func SignJWT(key *rsa.PrivateKey, issuer, subject, scope, bfnSource string, ...) (string, error)
- func ValidateJWT(tokenString string, pub *rsa.PublicKey, expectedIssuer string) (*nexusClaims, error)
- type CodeStore
- type JWK
- type JWKSResponse
- type OAuthClient
- type OAuthConfig
- type OAuthServer
Constants ¶
const Audience = "bubblefish-nexus"
Audience is the expected aud claim for Nexus JWT access tokens.
const KeyID = "nexus-1"
KeyID is the kid used in JWT headers and JWKS responses.
Variables ¶
This section is empty.
Functions ¶
func GenerateCode ¶
GenerateCode creates a cryptographically random 32-byte code (64 hex chars).
func GenerateRSAKey ¶
func GenerateRSAKey() (*rsa.PrivateKey, error)
GenerateRSAKey generates a new RSA-2048 private key.
func LoadRSAKey ¶
func LoadRSAKey(path string) (*rsa.PrivateKey, error)
LoadRSAKey reads a PEM-encoded private key (PKCS#8 or PKCS#1) from path.
func MarshalJWKS ¶
MarshalJWKS returns the JWKS JSON for the given public key.
func SaveRSAKey ¶
func SaveRSAKey(key *rsa.PrivateKey, path string) error
SaveRSAKey writes a PKCS#8 PEM-encoded private key to path with 0600 permissions. The private key MUST NEVER appear in logs or error messages.
func SignJWT ¶
func SignJWT(key *rsa.PrivateKey, issuer, subject, scope, bfnSource string, ttl time.Duration) (string, error)
SignJWT creates an RS256-signed JWT access token.
func ValidateJWT ¶
func ValidateJWT(tokenString string, pub *rsa.PublicKey, expectedIssuer string) (*nexusClaims, error)
ValidateJWT parses and validates an RS256-signed JWT against the given public key. It checks the signature, expiration, audience, and issuer claims. On success it returns the parsed claims.
Types ¶
type CodeStore ¶
type CodeStore struct {
// contains filtered or unexported fields
}
CodeStore is a thread-safe, in-memory store for OAuth authorization codes. It runs a background purge goroutine every 60 seconds to remove expired codes.
func NewCodeStore ¶
func NewCodeStore() *CodeStore
NewCodeStore creates and starts a CodeStore with its purge goroutine.
func (*CodeStore) Consume ¶
Consume retrieves and marks an authorization code as used. Returns nil if the code does not exist, has expired, or was already used.
type JWK ¶
type JWK struct {
Kty string `json:"kty"`
Use string `json:"use"`
Alg string `json:"alg"`
Kid string `json:"kid"`
N string `json:"n"`
E string `json:"e"`
}
JWK represents a single JSON Web Key for JWKS responses.
type JWKSResponse ¶
type JWKSResponse struct {
Keys []JWK `json:"keys"`
}
JWKSResponse wraps a set of JWKs.
type OAuthClient ¶
type OAuthClient struct {
ClientID string
ClientName string
RedirectURIs []string
OAuthSourceName string // maps to sources/*.toml
AllowedScopes []string
}
OAuthClient represents a registered OAuth client (e.g., ChatGPT).
type OAuthConfig ¶
type OAuthConfig struct {
Enabled bool
IssuerURL string
PrivateKeyFile string
AccessTokenTTL time.Duration // default 1hr
AuthCodeTTL time.Duration // default 5min
Clients []OAuthClient
}
OAuthConfig holds configuration for the OAuth 2.1 server.
type OAuthServer ¶
type OAuthServer struct {
// contains filtered or unexported fields
}
OAuthServer is the OAuth 2.1 authorization server for BubbleFish Nexus. It manages RSA key pairs, authorization codes, and JWT access tokens.
func NewOAuthServer ¶
func NewOAuthServer(cfg OAuthConfig, key *rsa.PrivateKey, logger *slog.Logger) *OAuthServer
NewOAuthServer creates an OAuthServer with the given config and RSA key pair.
func (*OAuthServer) FindClient ¶
func (s *OAuthServer) FindClient(clientID string) *OAuthClient
FindClient looks up a registered client by client_id. Returns nil if not found.
func (*OAuthServer) IssuerURL ¶
func (s *OAuthServer) IssuerURL() string
IssuerURL returns the configured issuer URL.
func (*OAuthServer) PublicKey ¶
func (s *OAuthServer) PublicKey() *rsa.PublicKey
PublicKey returns the RSA public key for JWKS and JWT validation.
func (*OAuthServer) RegisterHandlers ¶
func (s *OAuthServer) RegisterHandlers(mux *http.ServeMux)
RegisterHandlers registers OAuth HTTP endpoints on the given ServeMux.
func (*OAuthServer) ValidateAccessToken ¶
func (s *OAuthServer) ValidateAccessToken(tokenString string) bool
ValidateAccessToken checks whether tokenString is a valid RS256 JWT signed by this server. It validates the signature, exp, aud, and iss claims. Returns true only if ALL checks pass.
Source Files