README
¶
gas/auth
Part of the Gas monorepo · Documentation · All modules
Authentication, authorization, and credential management for the Gas framework: JWT, server-side sessions, API keys, and single-use tokens.
Implements gas.Authenticator, gas.Authorizer, gas.PrincipalRevoker.
go get github.com/gasmod/gas/auth
gas.WithSingletonService[*jwt.Service](jwt.New()),
gas.WithSingletonService[*session.Service](session.New()),
jwt.New() needs gas.ConfigProvider and gas.Logger. session.New(), apikey.New() and
token.New() also need gas.DatabaseProvider and gas.MigrationManager, since they persist
credentials and own migrations.
| Package | Provides |
|---|---|
auth |
BasePrincipal, Chain, middleware, scheme constants, sentinel errors |
auth/jwt |
Stateless JWT, HS256 or RS256 |
auth/session |
Server-side sessions with cookie management |
auth/apikey |
Hashed API keys with scopes |
auth/token |
Single-use tokens: magic links, verification, password reset |
auth/authtest |
Mocks for the three auth interfaces |
Documentation
The full guide, with configuration, testing, and worked examples, is on the docs site. This README is deliberately a signpost: keeping a second copy here is how the docs drifted before.
- Guide: Authenticate requests
- API reference: pkg.go.dev/github.com/gasmod/gas/auth
- Contributing: CONTRIBUTING.md
License
Documentation
¶
Overview ¶
Package auth provides authentication, authorization, and credential management for the Gas ecosystem.
Package auth provides authentication and authorization for the Gas ecosystem: JWT, server-side sessions, API keys, and single-use tokens. Sub-packages live under jwt, session, apikey, and token.
See the module README for usage examples and design rationale.
SPDX-License-Identifier: MIT
Index ¶
Constants ¶
const ( // SchemeJWT is the scheme for JWT-authenticated principals. SchemeJWT = "jwt" // SchemeSession is the scheme for session-authenticated principals. SchemeSession = "session" // SchemeAPIKey is the scheme for API-key-authenticated principals. SchemeAPIKey = "apikey" )
Scheme constants identify the authentication method used by a principal.
Variables ¶
var ( // ErrUnauthenticated indicates that no valid credentials were provided. ErrUnauthenticated = errors.New("unauthenticated") // ErrForbidden indicates that the principal lacks permission for the action. ErrForbidden = errors.New("forbidden") // ErrCredentialsExpired indicates that the presented credentials have expired. ErrCredentialsExpired = errors.New("credentials expired") // ErrCredentialRevoked indicates that the presented credentials have been revoked. ErrCredentialRevoked = errors.New("credential revoked") )
Sentinel errors returned by authenticators and middleware.
Functions ¶
func Middleware ¶
func Middleware(provider gas.Authenticator, opts ...MiddlewareOption) func(http.Handler) http.Handler
Middleware extracts and validates credentials from the request using the given authenticator. On success it sets the principal in the request context via gas.WithPrincipal and calls the next handler. On failure it invokes the OnError handler or writes a 401 Unauthorized response.
func RequireScheme ¶
RequireScheme enforces that the authenticated principal uses a specific authentication scheme (e.g. "jwt", "session", "apikey"). It reads the principal from context. If absent or the scheme doesn't match, it writes a 403 Forbidden response.
Types ¶
type BasePrincipal ¶
type BasePrincipal struct {
// contains filtered or unexported fields
}
BasePrincipal is a concrete implementation of gas.Principal.
func NewPrincipal ¶
func NewPrincipal(subject, scheme, credentialID string, meta gas.PrincipalMetadata) *BasePrincipal
NewPrincipal creates a new BasePrincipal. If meta is nil, an empty gas.BasePrincipalMetadata is used to avoid nil dereferences on Metadata().Value().
func (*BasePrincipal) CredentialID ¶
func (p *BasePrincipal) CredentialID() string
CredentialID returns the identifier for the specific credential used.
func (*BasePrincipal) Metadata ¶
func (p *BasePrincipal) Metadata() gas.PrincipalMetadata
Metadata returns the principal's metadata.
func (*BasePrincipal) Scheme ¶
func (p *BasePrincipal) Scheme() string
Scheme returns the authentication method (e.g. "jwt", "session", "apikey").
func (*BasePrincipal) Subject ¶
func (p *BasePrincipal) Subject() string
Subject returns the stable user identifier.
type Chain ¶
type Chain []gas.Authenticator
Chain is a composite authenticator that tries each authenticator in order. It satisfies gas.Authenticator.
func (Chain) Authenticate ¶
Authenticate tries each authenticator in order. It returns the first successful principal. If all fail, it returns the last error. If the chain is empty, it returns ErrUnauthenticated.
type MiddlewareOption ¶
type MiddlewareOption func(*middlewareOptions)
MiddlewareOption configures the behavior of Middleware.
func WithOnError ¶
func WithOnError(fn func(w http.ResponseWriter, r *http.Request, err error)) MiddlewareOption
WithOnError sets a custom error handler that is called when authentication fails. The handler receives the original error and is responsible for writing the HTTP response. When not set, the middleware writes a plain 401 Unauthorized response.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apikey provides API key authentication for the Gas ecosystem.
|
Package apikey provides API key authentication for the Gas ecosystem. |
|
Package authtest provides mock implementations of the gas authentication and authorization interfaces for use in tests.
|
Package authtest provides mock implementations of the gas authentication and authorization interfaces for use in tests. |
|
internal
|
|
|
cryptoutil
Package cryptoutil provides shared cryptographic helpers used across gas/auth sub-packages.
|
Package cryptoutil provides shared cryptographic helpers used across gas/auth sub-packages. |
|
testutil
Package testutil provides shared test helpers and mock implementations for gas/auth integration and unit tests.
|
Package testutil provides shared test helpers and mock implementations for gas/auth integration and unit tests. |
|
Package jwt provides a stateless JWT authenticator for the Gas ecosystem.
|
Package jwt provides a stateless JWT authenticator for the Gas ecosystem. |
|
Package session provides server-side session authentication for the Gas ecosystem.
|
Package session provides server-side session authentication for the Gas ecosystem. |
|
Package token provides single-use, time-limited tokens for the Gas ecosystem.
|
Package token provides single-use, time-limited tokens for the Gas ecosystem. |