authhttp

package
v0.45.0 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ActionUpdateUsername           = "update_username"
	ActionRequestPasswordReset     = "request_password_reset"
	ActionRequestEmailVerification = "request_email_verification"
	ActionRequestPhoneVerification = "request_phone_verification"
)
View Source 
const (
	// 2FA-specific rate limit buckets
	RL2FAStartPhone      = "auth_2fa_start_phone"
	RL2FAEnable          = "auth_2fa_enable"
	RL2FADisable         = "auth_2fa_disable"
	RL2FARegenerateCodes = "auth_2fa_regenerate_codes"
	RL2FAVerify          = "auth_2fa_verify"

	RLAuthToken                = "auth_token"
	RLAuthRegister             = "auth_register"
	RLAuthRegisterAvailability = "auth_register_availability"
	RLAuthRegisterResendEmail  = "auth_register_resend_email"
	RLAuthRegisterResendPhone  = "auth_register_resend_phone"
	RLAuthRegisterAbandon      = "auth_register_abandon"
	RLPasswordLogin            = "auth_password_login"
	RLAuthLogout               = "auth_logout"
	RLAuthSessionsCurrent      = "auth_sessions_current"
	RLAuthSessionsList         = "auth_sessions_list"
	RLAuthSessionsRevoke       = "auth_sessions_revoke"
	RLAuthSessionsRevokeAll    = "auth_sessions_revoke_all"

	RLPasswordResetRequest = "auth_pwd_reset_request"
	RLPasswordResetConfirm = "auth_pwd_reset_confirm"
	RLEmailVerifyRequest   = "auth_email_verify_request"
	RLEmailVerifyConfirm   = "auth_email_verify_confirm"
	RLPhoneVerifyRequest   = "auth_phone_verify_request"
	RLPhoneVerifyConfirm   = "auth_phone_verify_confirm"

	RLOIDCStart    = "auth_oidc_start"
	RLOIDCCallback = "auth_oidc_callback"

	RLUserPasswordChange  = "auth_user_password_change"
	RLUserMe              = "auth_user_me"
	RLUserUpdateUsername  = "auth_user_update_username"
	RLUserPreferredLocale = "auth_user_preferred_locale"
	RLUserUpdateEmail     = "auth_user_update_email"

	RLUserEmailChangeRequest = "auth_user_email_change_request"
	RLUserEmailChangeConfirm = "auth_user_email_change_confirm"
	RLUserEmailChangeResend  = "auth_user_email_change_resend"
	RLUserEmailChangeCancel  = "auth_user_email_change_cancel"

	RLUserPhoneChangeRequest = "auth_user_phone_change_request"
	RLUserPhoneChangeConfirm = "auth_user_phone_change_confirm"
	RLUserPhoneChangeResend  = "auth_user_phone_change_resend"
	RLUserPhoneChangeCancel  = "auth_user_phone_change_cancel"

	RLUserDelete         = "auth_user_delete"
	RLUserUnlinkProvider = "auth_user_unlink_provider"

	RLAdminRolesGrant            = "auth_admin_roles_grant"
	RLAdminRolesRevoke           = "auth_admin_roles_revoke"
	RLAdminUserSessionsList      = "auth_admin_user_sessions_list"
	RLAdminUserSessionsRevoke    = "auth_admin_user_sessions_revoke"
	RLAdminUserSessionsRevokeAll = "auth_admin_user_sessions_revoke_all"
	RLAdminPasswordReset         = "auth_admin_password_reset"

	// Solana SIWS authentication
	RLSolanaChallenge = "auth_solana_challenge"
	RLSolanaLogin     = "auth_solana_login"
	RLSolanaLink      = "auth_solana_link"
)

Bucket names used by authkit endpoints.

View Source 
const (
	ServicePrincipalType       = verify.ServicePrincipalType
	RemoteApplicationTokenType = verify.RemoteApplicationTokenType
)
View Source 
const AccessTokenType = jwtkit.AccessTokenType

AccessTokenType is the canonical JOSE `typ` header value for an AuthKit user access token.

View Source 
const DefaultOutboundTimeout = 30 * time.Second

DefaultOutboundTimeout bounds AuthKit's first-party outbound HTTP calls that reach networked dependencies under partial attacker control — most notably the Verifier's JWKS fetches (the issuer/JWKS URL can come from org-issuer federation data) and the org-issuer registration POST. Without a timeout a slow or hostile endpoint can wedge a request goroutine indefinitely; when the caller also single-flights (as the Verifier does on first use of an issuer or after an unknown-kid refetch), one hung fetch stalls every concurrent waiter — a cheap denial-of-service amplifier.

View Source 
const DelegatedAccessTokenType = jwtkit.DelegatedAccessTokenType

DelegatedAccessTokenType is the canonical JOSE `typ` header value for a delegated access token.

View Source 
const RemoteApplicationAccessTokenType = jwtkit.RemoteApplicationAccessTokenType

RemoteApplicationAccessTokenType is the JOSE `typ` for a remote application access token. AuthKit resolves authority from the stored remote_application assignment, never from role claims in the token.

Variables

View Source 
var (
	NewVerifier            = verify.NewVerifier
	Required               = verify.Required
	Optional               = verify.Optional
	RequireEntitlement     = verify.RequireEntitlement
	RequireAnyEntitlement  = verify.RequireAnyEntitlement
	ClaimsFromContext      = verify.ClaimsFromContext
	WithSkew               = verify.WithSkew
	WithAlgorithms         = verify.WithAlgorithms
	WithHTTPClient         = verify.WithHTTPClient
	WithSSRFGuard          = verify.WithSSRFGuard
	WithOrgMode            = verify.WithOrgMode
	WithAPIKeyPrefix       = verify.WithAPIKeyPrefix
	WithPermissions        = verify.WithPermissions
	WithAttributesPolicy   = verify.WithAttributesPolicy
	WithAttributeHydration = verify.WithAttributeHydration

	RequiredServiceJWT             = verify.RequiredServiceJWT
	ServiceJWTPrincipalFromContext = verify.ServiceJWTPrincipalFromContext
	WithServiceJWTMaxLifetime      = verify.WithServiceJWTMaxLifetime
	WithServiceJWTReplayChecker    = verify.WithServiceJWTReplayChecker
	RemoteApplicationCORS          = verify.RemoteApplicationCORS
	RequireDelegatedOrigin         = verify.RequireDelegatedOrigin
	NewSSRFGuardedClient           = verify.NewSSRFGuardedClient
)

Functions

func AllowNamed 

func AllowNamed(r *http.Request, rl RateLimiter, bucket string) bool

AllowNamed applies a per-IP limit using the provided bucket name. It fails open on limiter error.

func CheckOrgAccess 

func CheckOrgAccess(ctx context.Context, svc *core.Service, userID, orgSlug string) (canonicalOrg string, memberRoles []string, isMember bool, err error)

CheckOrgAccess resolves orgSlug (slug or alias) to its canonical slug, verifies membership, and returns the member's org-scoped roles.

func DefaultRateLimits 

func DefaultRateLimits() map[string]Limit

DefaultRateLimits returns AuthKit's built-in per-endpoint rate limits.

These limits are enforced per client IP (as determined by the Service's ClientIPFunc). Hosts can override by supplying their own limiter via WithRateLimiter(...).

func HasAnyOrgRole 

func HasAnyOrgRole(roles []string, want ...string) bool

HasAnyOrgRole returns true if roles contains any of want (case-insensitive).

func JWKSHandler 

func JWKSHandler(jwks jwtkit.JWKS) http.Handler

JWKSHandler serves the public JWKS document for the given key set.

func LanguageMiddleware 

func LanguageMiddleware(cfg *LanguageConfig) func(http.Handler) http.Handler

LanguageMiddleware infers request language and attaches it to the request context.

func MintDelegatedAccessToken added in v0.12.0 

func MintDelegatedAccessToken(ctx context.Context, signer jwtkit.Signer, p DelegatedAccessParams) (string, error)

MintDelegatedAccessToken signs a canonical delegated access token with an explicit signer. It is a thin re-export of core.MintDelegatedAccessToken; embedders holding a *core.Service should prefer (*core.Service).MintDelegatedAccessToken so they never construct a signer.

func ToMemoryLimits 

func ToMemoryLimits(in map[string]Limit) map[string]memorylimiter.Limit

func ToRedisLimits 

func ToRedisLimits(in map[string]Limit) map[string]redislimiter.Limit

Types

type ActionAvailability added in v0.9.4 

type ActionAvailability struct {
	Action            string     `json:"action"`
	Allowed           bool       `json:"allowed"`
	Reason            string     `json:"reason,omitempty"`
	RetryAfterSeconds int64      `json:"retry_after_seconds,omitempty"`
	NextAllowedAt     *time.Time `json:"next_allowed_at,omitempty"`
	Limit             *int       `json:"limit,omitempty"`
	Remaining         *int       `json:"remaining,omitempty"`
	WindowSeconds     *int64     `json:"window_seconds,omitempty"`
	CooldownSeconds   *int64     `json:"cooldown_seconds,omitempty"`
}

type AttributeDefResolver added in v0.27.0 

type AttributeDefResolver = verify.AttributeDefResolver

type AttributesValidator added in v0.12.0 

type AttributesValidator = verify.AttributesValidator

type Claims 

type Claims = verify.Claims

type ClientIPFunc 

type ClientIPFunc func(r *http.Request) string

ClientIPFunc determines the client IP used for rate limiting and auditing.

Returning an empty string means "unknown" and causes rate limiting to fail open.

func ClientIPFromForwardedHeaders 

func ClientIPFromForwardedHeaders(trustedProxies []netip.Prefix) ClientIPFunc

ClientIPFromForwardedHeaders trusts CF-Connecting-IP and X-Forwarded-For only when the immediate peer (RemoteAddr) is in trustedProxies. Otherwise it falls back to DefaultClientIP behavior.

func DefaultClientIP 

func DefaultClientIP() ClientIPFunc

DefaultClientIP returns the immediate peer IP from RemoteAddr.

This intentionally includes private and loopback peers so embedded/local deployments still get default rate-limit protection. Hosts behind reverse proxies should use ClientIPFromForwardedHeaders with trusted proxy CIDRs when they need the original public client IP instead of the proxy peer.

func PublicRemoteAddrClientIP added in v0.9.1 

func PublicRemoteAddrClientIP() ClientIPFunc

PublicRemoteAddrClientIP returns the older conservative client IP strategy:

  • If RemoteAddr is a public IP, use it.
  • If RemoteAddr is private/loopback/etc, return "" (fail open) so we don't accidentally rate-limit a reverse proxy/ingress as a single client.

type DelegatedAccessParams added in v0.12.0 

type DelegatedAccessParams = core.DelegatedAccessParams

DelegatedAccessParams describes a delegated access token to mint. It is an alias for core.DelegatedAccessParams; the canonical definition (and the (*core.Service).MintDelegatedAccessToken mint method) live in package core so hosts can mint through the Service's internal signer without touching keys.

type DelegatedPrincipal added in v0.9.6 

type DelegatedPrincipal = verify.DelegatedPrincipal

type Enricher added in v0.45.0 

type Enricher = verify.Enricher

type InternalErrorEvent added in v0.8.7 

type InternalErrorEvent struct {
	Route  string
	Stage  string
	Code   string
	Method string
	Path   string
	Err    error
}

InternalErrorEvent captures a swallowed internal handler error so host apps can log it without exposing implementation details to clients.

func (InternalErrorEvent) Error added in v0.8.7 

func (e InternalErrorEvent) Error() string

type IssuerKey 

type IssuerKey = verify.IssuerKey

type IssuerOptions 

type IssuerOptions = verify.IssuerOptions

type LanguageConfig 

type LanguageConfig struct {
	Supported  []string
	Default    string
	QueryParam string
	CookieName string
}

type Limit 

type Limit struct {
	Limit    int
	Window   time.Duration
	Cooldown time.Duration
}

Limit configures a named rate limit bucket.

type OrgIssuersClient added in v0.30.0 

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

OrgIssuersClient publishes THIS org's issuer registration to a resource server's inbound accept endpoint. It is the OUTBOUND (send-side) half of the AuthKit-owned federation handshake — the platform/IdP side (e.g. cozy-art) uses it to tell a resource server (e.g. tensorhub) "trust delegated tokens I mint with this issuer + JWKS URL". The resource server's handleOrgIssuerRegisterPOST stores the registration.

func NewOrgIssuersClient added in v0.30.0 

func NewOrgIssuersClient(opts ...OrgIssuersClientOption) *OrgIssuersClient

NewOrgIssuersClient creates a OrgIssuersClient.

func (*OrgIssuersClient) RegisterIssuer added in v0.30.0 

func (fc *OrgIssuersClient) RegisterIssuer(ctx context.Context, acceptURL string, reg OrgIssuersRegistration) error

RegisterIssuer POSTs this remote_application's registration to the resource server's accept endpoint (acceptURL is the fully-qualified URL of the inbound handler, e.g. "https://tensorhub.example/api/v1/remote-applications"). It returns an error for non-2xx responses.

type OrgIssuersClientOption added in v0.30.0 

type OrgIssuersClientOption func(*OrgIssuersClient)

OrgIssuersClientOption configures a OrgIssuersClient.

func WithOrgIssuersAuthToken added in v0.30.0 

func WithOrgIssuersAuthToken(token string) OrgIssuersClientOption

WithOrgIssuersAuthToken sets the Bearer token used to authenticate to the resource server's accept endpoint (owner/admin of the org being registered).

func WithOrgIssuersHTTPClient added in v0.30.0 

func WithOrgIssuersHTTPClient(c *http.Client) OrgIssuersClientOption

WithOrgIssuersHTTPClient sets the HTTP client used for registration calls.

type OrgIssuersRegistration added in v0.30.0 

type OrgIssuersRegistration struct {
	// Slug is this remote_application's slug on the receiving service.
	Slug string
	// Issuer is THIS platform's issuer URL (the `iss` of delegated tokens).
	Issuer string
	// JWKSURI is where the resource server fetches THIS platform's public keys
	// (jwks mode — preferred). Mutually exclusive with PublicKeys.
	JWKSURI string
	// PublicKeys is the static-mode key list for platforms without a JWKS
	// endpoint (#74). Mutually exclusive with JWKSURI.
	PublicKeys []core.RemoteAppKey
	// AllowedOrigins is the exact browser Origin allow-list the resource server
	// should accept for delegated browser requests signed by this issuer.
	AllowedOrigins []string
}

OrgIssuersRegistration is the payload published to a resource server.

type PermissionValidator added in v0.12.0 

type PermissionValidator = verify.PermissionValidator

type RateLimitResult added in v0.9.1 

type RateLimitResult struct {
	Allowed      bool
	RetryAfter   time.Duration
	Availability *ActionAvailability
}

type RateLimiter 

type RateLimiter interface {
	AllowNamed(bucket string, key string) (bool, error)
}

RateLimiter is a minimal interface used by adapters.

type RateLimiterWithResult added in v0.9.4 

type RateLimiterWithResult interface {
	AllowNamedResult(bucket string, key string) (ratelimit.Result, error)
}

type RateLimiterWithRetryAfter added in v0.9.1 

type RateLimiterWithRetryAfter interface {
	AllowNamedWithRetryAfter(bucket string, key string) (bool, time.Duration, error)
}

type RemoteApplicationAuthoritySource added in v0.28.0 

type RemoteApplicationAuthoritySource = verify.RemoteApplicationAuthoritySource

type RemoteApplicationSource added in v0.27.0 

type RemoteApplicationSource = verify.RemoteApplicationSource

type RouteGroup added in v0.8.5 

type RouteGroup string

RouteGroup identifies a prefix-neutral AuthKit route capability. Host applications can mount all default groups or select only the capabilities they want to expose. 

const (
	RouteCore               RouteGroup = "core"
	RoutePassword           RouteGroup = "password"
	RouteRegister           RouteGroup = "register"
	RouteOwners             RouteGroup = "owners"
	RouteEmailVerification  RouteGroup = "email_verification"
	RoutePhoneVerification  RouteGroup = "phone_verification"
	RouteOrgs               RouteGroup = "orgs"
	RouteUser               RouteGroup = "user"
	RouteAccountOIDCLinking RouteGroup = "account_oidc_linking"
	RouteTwoFactor          RouteGroup = "two_factor"
	RouteSolana             RouteGroup = "solana"
	RouteAdmin              RouteGroup = "admin"
	RouteOIDCBrowser        RouteGroup = "oidc_browser"
	// RouteOrgIssuers exposes the inbound accept-side org-issuer registry
	// routes (the home for what tensorhub previously exposed as
	// `/api/v1/platform/issuers`).
	RouteOrgIssuers RouteGroup = "federation"
)

type RouteSpec added in v0.8.5 

type RouteSpec struct {
	Method  string
	Path    string
	Group   RouteGroup
	Handler http.Handler
}

RouteSpec is a concrete, prefix-neutral route with its AuthKit handler attached. Path parameters use net/http ServeMux syntax, e.g. "/namespaces/{slug}".

type Routes added in v0.8.5 

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

Routes provides access to AuthKit's canonical route groups.

func (Routes) DefaultAPI added in v0.8.5 

func (r Routes) DefaultAPI() []RouteSpec

DefaultAPI returns every AuthKit JSON API route enabled by this service.

func (Routes) Groups added in v0.8.5 

func (r Routes) Groups(groups ...RouteGroup) []RouteSpec

Groups returns every enabled AuthKit JSON API route in the requested groups.

func (Routes) OIDCBrowser added in v0.8.5 

func (r Routes) OIDCBrowser() []RouteSpec

OIDCBrowser returns browser redirect OIDC routes without a mount prefix. Host applications choose where to mount them, commonly "/oidc".

type Service 

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

Service wraps core.Service with net/http mounting helpers.

func NewService 

func NewService(cfg core.Config) (*Service, error)

NewService constructs a core.Service and wraps it for net/http mounting. Returns an error if the core service fails to initialize (e.g., missing keys in production).

func (*Service) APIHandler 

func (s *Service) APIHandler() http.Handler

APIHandler returns a handler that serves prefix-neutral JSON API routes. It is intended to be mounted under the host's mux/router at the host's chosen API prefix.

func (*Service) APIRoutes added in v0.8.5 

func (s *Service) APIRoutes(groups ...RouteGroup) []RouteSpec

APIRoutes returns AuthKit's enabled JSON API routes. With no groups it returns the default API surface. With groups, it returns only matching routes.

func (*Service) CheckSMSHealth added in v0.15.4 

func (s *Service) CheckSMSHealth(ctx context.Context) error

CheckSMSHealth probes (without sending an SMS) whether the configured sender can actually deliver, caching the result to gate phone-based flows. Returns the probe error (nil = healthy) so the host app can log it at startup.

func (*Service) Core 

func (s *Service) Core() *core.Service

func (*Service) DisableRateLimiter 

func (s *Service) DisableRateLimiter() *Service

func (*Service) JWKSHandler 

func (s *Service) JWKSHandler() http.Handler

JWKSHandler returns a handler for GET /.well-known/jwks.json.

func (*Service) OIDCBrowserRoutes added in v0.8.5 

func (s *Service) OIDCBrowserRoutes(groups ...RouteGroup) []RouteSpec

OIDCBrowserRoutes returns browser redirect routes with no mount prefix.

func (*Service) OIDCHandler 

func (s *Service) OIDCHandler() http.Handler

OIDCHandler returns a handler that serves browser redirect flows: - GET /oidc/{provider}/login - GET /oidc/{provider}/callback - GET /oidc/{provider}/reauth/callback

func (*Service) Routes added in v0.8.5 

func (s *Service) Routes() Routes

Routes returns AuthKit's canonical route registry for this service.

func (*Service) SMSAvailable added in v0.15.4 

func (s *Service) SMSAvailable() bool

SMSAvailable reports whether phone-based flows should be offered (a sender is configured and, if checked, found able to deliver).

func (*Service) SMSHealthReason added in v0.15.4 

func (s *Service) SMSHealthReason() string

SMSHealthReason returns why SMS was last found unhealthy, if any.

func (*Service) SMSHealthy added in v0.15.4 

func (s *Service) SMSHealthy() bool

SMSHealthy reports the last CheckSMSHealth result (true until a check runs).

func (*Service) Verifier 

func (s *Service) Verifier() *Verifier

func (*Service) WithAuthLogReader 

func (s *Service) WithAuthLogReader(r core.AuthEventLogReader) *Service

func (*Service) WithAuthLogger 

func (s *Service) WithAuthLogger(l core.AuthEventLogger) *Service

func (*Service) WithClientIPFunc 

func (s *Service) WithClientIPFunc(fn ClientIPFunc) *Service

func (*Service) WithEmailSender 

func (s *Service) WithEmailSender(es core.EmailSender) *Service

func (*Service) WithEntitlements 

func (s *Service) WithEntitlements(p core.EntitlementsProvider) *Service

func (*Service) WithEphemeralStore 

func (s *Service) WithEphemeralStore(store core.EphemeralStore, mode core.EphemeralMode) *Service

func (*Service) WithErrorLogger added in v0.8.7 

func (s *Service) WithErrorLogger(fn func(context.Context, InternalErrorEvent)) *Service

func (*Service) WithLanguageConfig 

func (s *Service) WithLanguageConfig(cfg LanguageConfig) *Service

func (*Service) WithPostgres 

func (s *Service) WithPostgres(pg *pgxpool.Pool) *Service

func (*Service) WithRateLimiter 

func (s *Service) WithRateLimiter(rl RateLimiter) *Service

func (*Service) WithRedis 

func (s *Service) WithRedis(rd *redis.Client) *Service

func (*Service) WithSMSSender 

func (s *Service) WithSMSSender(sender core.SMSSender) *Service

func (*Service) WithSolanaDomain 

func (s *Service) WithSolanaDomain(domain string) *Service

WithSolanaDomain sets the domain used in SIWS sign-in messages. If not set, the domain is derived from the request Origin or Host header.

type ServiceJWTPrincipal added in v0.13.1 

type ServiceJWTPrincipal = verify.ServiceJWTPrincipal

type ServiceJWTReplayChecker added in v0.13.1 

type ServiceJWTReplayChecker = verify.ServiceJWTReplayChecker

type ServiceJWTVerifyOption added in v0.13.1 

type ServiceJWTVerifyOption = verify.ServiceJWTVerifyOption

type Verifier 

type Verifier = verify.Verifier

type VerifierOption 

type VerifierOption = verify.VerifierOption

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.