Documentation
¶
Overview ¶
Package auth provides signed access and rotating refresh-token primitives.
Index ¶
- Constants
- func Can(c *gin.Context, a string) bool
- func HashAPIToken(token string) string
- func HashRefreshToken(token string) string
- func Issue(userID string, secret []byte, ttl time.Duration) (string, error)
- func LoginSession(c *gin.Context, userID string) error
- func LogoutSession(c *gin.Context) error
- func NewRefreshToken() (plain, hash string, err error)
- func RequireAuth(manager *Manager) gin.HandlerFunc
- func RequireLogin(manager *Manager) gin.HandlerFunc
- func RequireToken(store TokenStore, abilities ...string) gin.HandlerFunc
- func SessionMiddleware() gin.HandlerFunc
- func UserID(c *gin.Context) string
- func ValidateSecret(secret []byte) error
- type APIToken
- type Claims
- type Manager
- type TokenStore
Constants ¶
const APITokenPrefix = "gk_"
APITokenPrefix define package-level implementation state.
const MinimumSecretLength = 32
MinimumSecretLength is the smallest accepted signing secret in bytes.
Variables ¶
This section is empty.
Functions ¶
func HashAPIToken ¶
HashAPIToken performs this package operation.
func HashRefreshToken ¶
HashRefreshToken performs this package operation.
func LoginSession ¶
LoginSession records the authenticated user in the encrypted session.
func LogoutSession ¶
LogoutSession removes the authenticated user from the encrypted session.
func NewRefreshToken ¶
NewRefreshToken returns a random plaintext refresh token and its SHA-256 hash.
func RequireAuth ¶
func RequireAuth(manager *Manager) gin.HandlerFunc
RequireAuth authenticates requests with a Bearer token, stores the verified claims in the request context, and rejects unauthenticated requests with a canonical 401 envelope. It panics when manager is nil so a wiring mistake fails at route registration, not per request.
func RequireLogin ¶
func RequireLogin(manager *Manager) gin.HandlerFunc
RequireLogin authenticates requests with an OAuth browser session when one is present, otherwise it requires the same Bearer token accepted by RequireAuth. Install SessionMiddleware after the session middleware.
func RequireToken ¶
func RequireToken(store TokenStore, abilities ...string) gin.HandlerFunc
RequireToken performs this package operation.
func SessionMiddleware ¶
func SessionMiddleware() gin.HandlerFunc
SessionMiddleware restores an OAuth-authenticated user ID from the encrypted session cookie. It must run after session.Middleware and before RequireLogin.
func ValidateSecret ¶
ValidateSecret rejects secrets shorter than MinimumSecretLength.
Types ¶
type APIToken ¶
type APIToken struct {
// ID store data used by this type.
ID string
// UserID store data used by this type.
UserID string
// Name store data used by this type.
Name string
// TokenHash store data used by this type.
TokenHash string
// Abilities store data used by this type.
Abilities []string
// ExpiresAt store data used by this type.
ExpiresAt *time.Time
// LastUsedAt store data used by this type.
LastUsedAt *time.Time
// RevokedAt store data used by this type.
RevokedAt *time.Time
}
APIToken defines an implementation type used by this package.
type Claims ¶
type Claims struct {
// UserID is the authenticated account identifier.
UserID string `json:"sub"`
jwt.RegisteredClaims
}
Claims is the verified subject carried by a signed access token.
func ClaimsFromContext ¶
ClaimsFromContext returns the claims stored by RequireAuth.
type Manager ¶
type Manager struct {
// Issuer is embedded in every token when non-empty.
Issuer string
// AccessTTL is the default lifetime used by Issue.
AccessTTL time.Duration
// contains filtered or unexported fields
}
Manager signs and verifies access tokens with one immutable secret.
type TokenStore ¶
type TokenStore interface {
// FindByTokenHash define an operation required by this interface.
FindByTokenHash(context.Context, string) (*APIToken, error)
// TouchLastUsed define an operation required by this interface.
TouchLastUsed(context.Context, string, time.Time) error
}
TokenStore defines an implementation type used by this package.
Source Files