auth

package
v0.26.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package auth provides authentication and authorization for the Memos server.

This package is used by: - server/router/api/v1: gRPC and Connect API interceptors - server/router/fileserver: HTTP file server authentication

Authentication methods supported: - JWT access tokens: Short-lived tokens (15 minutes) for API access - JWT refresh tokens: Long-lived tokens (30 days) for obtaining new access tokens - Personal Access Tokens (PAT): Long-lived tokens for programmatic access

Index

Constants

View Source 
const (
	// Issuer is the issuer claim in JWT tokens.
	// This identifies tokens as issued by Memos.
	Issuer = "memos"

	// KeyID is the key identifier used in JWT header.
	// Version "v1" allows for future key rotation while maintaining backward compatibility.
	// If signing mechanism changes, add "v2", "v3", etc. and verify both versions.
	KeyID = "v1"

	// AccessTokenAudienceName is the audience claim for JWT access tokens.
	// This ensures tokens are only used for API access, not other purposes.
	AccessTokenAudienceName = "user.access-token"

	// AccessTokenDuration is the lifetime of access tokens (15 minutes).
	AccessTokenDuration = 15 * time.Minute

	// RefreshTokenDuration is the lifetime of refresh tokens (30 days).
	RefreshTokenDuration = 30 * 24 * time.Hour

	// RefreshTokenAudienceName is the audience claim for refresh tokens.
	RefreshTokenAudienceName = "user.refresh-token"

	// RefreshTokenCookieName is the cookie name for refresh tokens.
	RefreshTokenCookieName = "memos_refresh"

	// PersonalAccessTokenPrefix is the prefix for PAT tokens.
	PersonalAccessTokenPrefix = "memos_pat_"
)

Variables

This section is empty.

Functions

func ExtractBearerToken added in v0.26.0 

func ExtractBearerToken(authHeader string) string

ExtractBearerToken extracts the JWT token from an Authorization header value. Expected format: "Bearer {token}" Returns empty string if no valid bearer token is found.

func ExtractRefreshTokenFromCookie added in v0.26.0 

func ExtractRefreshTokenFromCookie(cookieHeader string) string

ExtractRefreshTokenFromCookie extracts the refresh token from cookie header.

func GenerateAccessToken 

func GenerateAccessToken(username string, userID int32, expirationTime time.Time, secret []byte) (string, error)

GenerateAccessToken generates a JWT access token for a user.

Parameters: - username: The user's username (stored in "name" claim) - userID: The user's ID (stored in "sub" claim) - expirationTime: When the token expires (pass zero time for no expiration) - secret: Server secret used to sign the token

Returns a signed JWT string or an error.

func GenerateAccessTokenV2 added in v0.26.0 

func GenerateAccessTokenV2(userID int32, username, role, status string, secret []byte) (string, time.Time, error)

GenerateAccessTokenV2 generates a short-lived access token with user claims.

func GeneratePersonalAccessToken added in v0.26.0 

func GeneratePersonalAccessToken() string

GeneratePersonalAccessToken generates a random PAT string.

func GenerateRefreshToken 

func GenerateRefreshToken(userID int32, tokenID string, secret []byte) (string, time.Time, error)

GenerateRefreshToken generates a long-lived refresh token.

func GetAccessToken added in v0.26.0 

func GetAccessToken(ctx context.Context) string

GetAccessToken retrieves the JWT access token from the context. Returns empty string if not authenticated via bearer token.

func GetUserID added in v0.26.0 

func GetUserID(ctx context.Context) int32

GetUserID retrieves the authenticated user's ID from the context. Returns 0 if no user ID is set (unauthenticated request).

func HashPersonalAccessToken added in v0.26.0 

func HashPersonalAccessToken(token string) string

HashPersonalAccessToken returns SHA-256 hash of a PAT.

func SetUserClaimsInContext added in v0.26.0 

func SetUserClaimsInContext(ctx context.Context, claims *UserClaims) context.Context

SetUserClaimsInContext sets the user claims in context.

func SetUserInContext added in v0.26.0 

func SetUserInContext(ctx context.Context, user *store.User, accessToken string) context.Context

SetUserInContext sets the authenticated user's information in the context. This is a simpler alternative to AuthorizeAndSetContext for cases where authorization is handled separately (e.g., HTTP middleware).

Parameters:

  • user: The authenticated user
  • accessToken: Set if authenticated via JWT token (empty string otherwise)

Types

type AccessTokenClaims added in v0.26.0 

type AccessTokenClaims struct {
	Type     string `json:"type"`     // "access"
	Role     string `json:"role"`     // User role
	Status   string `json:"status"`   // User status
	Username string `json:"username"` // Username for display
	jwt.RegisteredClaims
}

AccessTokenClaims contains claims for short-lived access tokens. These tokens are validated by signature only (stateless).

func ParseAccessTokenV2 added in v0.26.0 

func ParseAccessTokenV2(tokenString string, secret []byte) (*AccessTokenClaims, error)

ParseAccessTokenV2 parses and validates a short-lived access token.

type AuthResult added in v0.26.0 

type AuthResult struct {
	User        *store.User // Set for PAT authentication
	Claims      *UserClaims // Set for Access Token V2 (stateless)
	AccessToken string      // Non-empty if authenticated via JWT
}

AuthResult contains the result of an authentication attempt.

type Authenticator added in v0.26.0 

type Authenticator struct {
	// contains filtered or unexported fields
}

Authenticator provides shared authentication and authorization logic. Used by gRPC interceptor, Connect interceptor, and file server to ensure consistent authentication behavior across all API endpoints.

Authentication methods: - JWT access tokens: Short-lived tokens (15 minutes) for API access - Personal Access Tokens (PAT): Long-lived tokens for programmatic access

This struct is safe for concurrent use.

func NewAuthenticator added in v0.26.0 

func NewAuthenticator(store *store.Store, secret string) *Authenticator

NewAuthenticator creates a new Authenticator instance.

func (*Authenticator) Authenticate added in v0.26.0 

func (a *Authenticator) Authenticate(ctx context.Context, authHeader string) *AuthResult

Authenticate tries to authenticate using the provided credentials. Priority: 1. Access Token V2, 2. PAT Returns nil if no valid credentials are provided.

func (*Authenticator) AuthenticateByAccessTokenV2 added in v0.26.0 

func (a *Authenticator) AuthenticateByAccessTokenV2(accessToken string) (*UserClaims, error)

AuthenticateByAccessTokenV2 validates a short-lived access token. Returns claims without database query (stateless validation).

func (*Authenticator) AuthenticateByPAT added in v0.26.0 

func (a *Authenticator) AuthenticateByPAT(ctx context.Context, token string) (*store.User, *storepb.PersonalAccessTokensUserSetting_PersonalAccessToken, error)

AuthenticateByPAT validates a Personal Access Token.

func (*Authenticator) AuthenticateByRefreshToken added in v0.26.0 

func (a *Authenticator) AuthenticateByRefreshToken(ctx context.Context, refreshToken string) (*store.User, string, error)

AuthenticateByRefreshToken validates a refresh token against the database.

type ClaimsMessage added in v0.26.0 

type ClaimsMessage struct {
	Name string `json:"name"` // Username
	jwt.RegisteredClaims
}

ClaimsMessage represents the claims structure in a JWT token.

JWT Claims include: - name: Username (custom claim) - iss: Issuer = "memos" - aud: Audience = "user.access-token" - sub: Subject = user ID - iat: Issued at time - exp: Expiration time (optional, may be empty for never-expiring tokens).

type ContextKey added in v0.26.0 

type ContextKey int

ContextKey is the key type for context values. Using a custom type prevents collisions with other packages. 

const (
	// UserIDContextKey stores the authenticated user's ID.
	// Set for all authenticated requests.
	// Use GetUserID(ctx) to retrieve this value.
	UserIDContextKey ContextKey = iota

	// AccessTokenContextKey stores the JWT token for token-based auth.
	// Only set when authenticated via Bearer token.
	AccessTokenContextKey

	// UserClaimsContextKey stores the claims from access token.
	UserClaimsContextKey

	// RefreshTokenIDContextKey stores the refresh token ID.
	RefreshTokenIDContextKey
)

type RefreshTokenClaims added in v0.26.0 

type RefreshTokenClaims struct {
	Type    string `json:"type"` // "refresh"
	TokenID string `json:"tid"`  // Token ID for revocation lookup
	jwt.RegisteredClaims
}

RefreshTokenClaims contains claims for long-lived refresh tokens. These tokens are validated against the database for revocation.

func ParseRefreshToken added in v0.26.0 

func ParseRefreshToken(tokenString string, secret []byte) (*RefreshTokenClaims, error)

ParseRefreshToken parses and validates a refresh token.

type UserClaims added in v0.26.0 

type UserClaims struct {
	UserID   int32
	Username string
	Role     string
	Status   string
}

UserClaims represents authenticated user info from access token.

func GetUserClaims added in v0.26.0 

func GetUserClaims(ctx context.Context) *UserClaims

GetUserClaims retrieves the user claims from context. Returns nil if not authenticated via access token.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.