Documentation
¶
Overview ¶
Package auth provides HTTP handlers for wallet-based authentication, JWT token management, and API key operations. It supports challenge/response flows using cryptographic signatures for Ethereum and other blockchain wallets.
Index ¶
- Constants
- type APIKeyRequest
- type ChallengeRequest
- type DatabaseClient
- type Handlers
- func (h *Handlers) APIKeyToJWTHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) ChallengeHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) IssueAPIKeyHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) LoginPageHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) LogoutHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) RefreshHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) RegisterHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) SimpleAPIKeyHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) VerifyHandler(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) WhoamiHandler(w http.ResponseWriter, r *http.Request)
- type LogoutRequest
- type NetworkClient
- type QueryResult
- type RefreshRequest
- type RegisterRequest
- type SimpleAPIKeyRequest
- type VerifyRequest
Constants ¶
const ( CtxKeyAPIKey = ctxkeys.APIKey CtxKeyJWT = ctxkeys.JWT CtxKeyNamespaceOverride = ctxkeys.NamespaceOverride )
Use shared context keys from ctxkeys package to ensure consistency with middleware
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIKeyRequest ¶
type APIKeyRequest struct {
Wallet string `json:"wallet"`
Nonce string `json:"nonce"`
Signature string `json:"signature"`
Namespace string `json:"namespace"`
ChainType string `json:"chain_type"`
Plan string `json:"plan"`
}
APIKeyRequest is the request body for API key generation
type ChallengeRequest ¶
type ChallengeRequest struct {
Wallet string `json:"wallet"`
Purpose string `json:"purpose"`
Namespace string `json:"namespace"`
}
ChallengeRequest is the request body for challenge generation
type DatabaseClient ¶
type DatabaseClient interface {
Query(ctx context.Context, sql string, args ...interface{}) (*QueryResult, error)
}
DatabaseClient defines the database query interface
type Handlers ¶
type Handlers struct {
// contains filtered or unexported fields
}
Handlers holds dependencies for authentication HTTP handlers
func NewHandlers ¶
func NewHandlers( logger *logging.ColoredLogger, authService *authsvc.Service, netClient NetworkClient, defaultNamespace string, internalAuthFn func(context.Context) context.Context, ) *Handlers
NewHandlers creates a new authentication handlers instance
func (*Handlers) APIKeyToJWTHandler ¶
func (h *Handlers) APIKeyToJWTHandler(w http.ResponseWriter, r *http.Request)
APIKeyToJWTHandler issues a short-lived JWT from a valid API key. This allows API key holders to obtain JWT tokens for use with the gateway.
POST /v1/auth/token Requires: Authorization header with API key (Bearer, ApiKey, or X-API-Key header) Response: { "access_token", "token_type", "expires_in", "namespace" }
func (*Handlers) ChallengeHandler ¶
func (h *Handlers) ChallengeHandler(w http.ResponseWriter, r *http.Request)
ChallengeHandler generates a cryptographic nonce for wallet signature challenges. This is the first step in the authentication flow where clients request a nonce to sign with their wallet.
POST /v1/auth/challenge Request body: ChallengeRequest Response: { "wallet", "namespace", "nonce", "purpose", "expires_at" }
func (*Handlers) IssueAPIKeyHandler ¶
func (h *Handlers) IssueAPIKeyHandler(w http.ResponseWriter, r *http.Request)
IssueAPIKeyHandler issues an API key after signature verification. Similar to VerifyHandler but only returns the API key without JWT tokens.
POST /v1/auth/api-key Request body: APIKeyRequest Response: { "api_key", "namespace", "plan", "wallet" }
func (*Handlers) LoginPageHandler ¶
func (h *Handlers) LoginPageHandler(w http.ResponseWriter, r *http.Request)
LoginPageHandler serves the wallet authentication login page. This provides an interactive HTML page for wallet-based authentication using MetaMask or other Web3 wallet providers.
GET /v1/auth/login?callback=<url> Query params: callback (required) - URL to redirect after successful auth Response: HTML page with wallet connection UI
func (*Handlers) LogoutHandler ¶
func (h *Handlers) LogoutHandler(w http.ResponseWriter, r *http.Request)
LogoutHandler revokes refresh tokens. If a refresh_token is provided, it will be revoked. If all=true is provided (and the request is authenticated via JWT), all tokens for the JWT subject within the namespace are revoked.
POST /v1/auth/logout Request body: LogoutRequest Response: { "status": "ok" }
func (*Handlers) RefreshHandler ¶
func (h *Handlers) RefreshHandler(w http.ResponseWriter, r *http.Request)
RefreshHandler refreshes an access token using a refresh token.
POST /v1/auth/refresh Request body: RefreshRequest Response: { "access_token", "token_type", "expires_in", "refresh_token", "subject", "namespace" }
func (*Handlers) RegisterHandler ¶
func (h *Handlers) RegisterHandler(w http.ResponseWriter, r *http.Request)
RegisterHandler registers a new application/client after wallet signature verification. This allows wallets to register applications and obtain client credentials.
POST /v1/auth/register Request body: RegisterRequest Response: { "client_id", "app": { ... }, "signature_verified" }
func (*Handlers) SimpleAPIKeyHandler ¶
func (h *Handlers) SimpleAPIKeyHandler(w http.ResponseWriter, r *http.Request)
SimpleAPIKeyHandler generates an API key without signature verification. This is a simplified flow for development/testing purposes.
POST /v1/auth/simple-key Request body: SimpleAPIKeyRequest Response: { "api_key", "namespace", "wallet", "created" }
func (*Handlers) VerifyHandler ¶
func (h *Handlers) VerifyHandler(w http.ResponseWriter, r *http.Request)
VerifyHandler verifies a wallet signature and issues JWT tokens and an API key. This completes the authentication flow by validating the signed nonce and returning access credentials.
POST /v1/auth/verify Request body: VerifyRequest Response: { "access_token", "token_type", "expires_in", "refresh_token", "subject", "namespace", "api_key", "nonce", "signature_verified" }
func (*Handlers) WhoamiHandler ¶
func (h *Handlers) WhoamiHandler(w http.ResponseWriter, r *http.Request)
WhoamiHandler returns the authenticated user's identity and method. This endpoint shows whether the request is authenticated via JWT or API key, and provides details about the authenticated principal.
GET /v1/auth/whoami Response: { "authenticated", "method", "subject", "namespace", ... }
type LogoutRequest ¶
type LogoutRequest struct {
RefreshToken string `json:"refresh_token"`
Namespace string `json:"namespace"`
All bool `json:"all"`
}
LogoutRequest is the request body for logout/token revocation
type NetworkClient ¶
type NetworkClient interface {
Database() DatabaseClient
}
NetworkClient defines the minimal network client interface needed by auth handlers
type QueryResult ¶
type QueryResult struct {
Count int `json:"count"`
Rows []interface{} `json:"rows"`
}
QueryResult represents a database query result
type RefreshRequest ¶
type RefreshRequest struct {
RefreshToken string `json:"refresh_token"`
Namespace string `json:"namespace"`
}
RefreshRequest is the request body for token refresh
type RegisterRequest ¶
type RegisterRequest struct {
Wallet string `json:"wallet"`
Nonce string `json:"nonce"`
Signature string `json:"signature"`
Namespace string `json:"namespace"`
ChainType string `json:"chain_type"`
Name string `json:"name"`
}
RegisterRequest is the request body for app registration
type SimpleAPIKeyRequest ¶
type SimpleAPIKeyRequest struct {
Wallet string `json:"wallet"`
Namespace string `json:"namespace"`
}
SimpleAPIKeyRequest is the request body for simple API key generation (no signature)
Source Files