authn

package
v0.0.18 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package authn is the authentication scenario: every Authorization scheme and the ?token=/?auth= query form, resolved to a principal.

Index

Constants

This section is empty.

Variables

View Source
var ErrNotFound = domain.ErrNotFound // one sentinel across the scenario ports

ErrNotFound is the storage port's not-found sentinel.

Functions

This section is empty.

Types

type CredentialKind

type CredentialKind int

CredentialKind discriminates the raw credential carried by the request.

const (
	CredentialNone CredentialKind = iota
	CredentialToken
	CredentialLicense
	CredentialBasic
)

The raw kinds: how the credential arrived, before the mode resolves what a Basic username means.

type Credentials

type Credentials struct {
	Kind CredentialKind
	// Scheme is the Authorization scheme as sent ("Bearer", "Token",
	// "License", "Basic"); empty when the credential came from the query.
	Scheme string
	// Value is the bearer/token value (Bearer, Token, License) or the
	// Basic payload's username (legacy Basic token auth).
	Value string
	// Secret is the Basic payload's password (the license key or token
	// value for the "license:"/"token:" prefixed forms, or the user's
	// password for the email form).
	Secret string
	// PasswordPresent distinguishes a Basic username from username: (empty password).
	PasswordPresent bool
}

Credentials is the raw authentication material of one request.

func Parse

func Parse(authorization, queryValue string) Credentials

Parse extracts the raw credentials: the Authorization header first, then the ?token=/?auth= query value. Basic values are base64-decoded here; what the username means is resolved per-mode in Resolve.

func (Credentials) Resolve

func (c Credentials) Resolve(mode Mode) Resolved

Resolve interprets the credentials for the endpoint's mode: the license:/token: Basic prefixes always map to their flows, an email:password Basic pair is a password flow only where the endpoint honors passwords, and anything else is (legacy) token auth with the username as the value.

type Flow

type Flow int

Flow is an authentication flow.

const (
	FlowNone Flow = iota
	FlowToken
	FlowLicense
	FlowPassword
)

The flows.

type Mode

type Mode int

Mode selects the endpoint's authentication entry point.

const (
	ModeToken Mode = iota
	ModePasswordOrToken
)

The entry points: authenticate_with_token! (everything) and authenticate_with_password_or_token! (POST /tokens).

type Resolved

type Resolved struct {
	// Flow is the authentication flow to execute.
	Flow Flow
	// TokenValue is the token secret (FlowToken).
	TokenValue string
	// LicenseKey is the license key (FlowLicense).
	LicenseKey string
	// Email and Password carry the Basic email:password pair
	// (FlowPassword).
	Email    string
	Password string
}

Resolved is the mode-resolved credential: exactly one flow to run.

func (Resolved) ChallengeScheme

func (r Resolved) ChallengeScheme() string

ChallengeScheme answers the WWW-Authenticate scheme for a failure: the Basic realm for the password flow, Bearer otherwise.

type Result

type Result struct {
	Token   *domain.Token
	User    *domain.User
	License *domain.LicenseAuth
	// ChallengeScheme feeds WWW-Authenticate on a later 401: Basic for
	// the password flow, Bearer otherwise.
	ChallengeScheme string
}

Result is what the request learned about its caller, beyond the principal: the token row (token authn) and the bearer's user or license.

type Scenario

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

Scenario authenticates requests against an account.

func New

func New(store Store, clock func() time.Time) Scenario

New builds the scenario over the store (positional deps, clock injectable for tests).

func (Scenario) Authenticate

func (s Scenario) Authenticate(
	ctx context.Context,
	account domain.Account,
	cred Credentials,
	mode Mode,
	otp *string,
) (access.Principal, Result, error)

Authenticate resolves the credential to a principal, in the reference's exact error order. A FlowNone credential yields the TOKEN_MISSING 401.

type Store

type Store interface {
	VerifySecondFactor(ctx context.Context, userID uuid.UUID, otp string, now time.Time) (bool, error)
	// TokenByDigest loads a token by its digest; ErrNotFound when none.
	TokenByDigest(ctx context.Context, accountID uuid.UUID, digest string) (domain.Token, error)
	// UserByID loads a user; ErrNotFound when none.
	UserByID(ctx context.Context, accountID uuid.UUID, id uuid.UUID) (domain.User, error)
	// UserByEmail loads a user by downcased email; ErrNotFound when none.
	UserByEmail(ctx context.Context, accountID uuid.UUID, email string) (domain.User, error)
	// LicenseByKey loads the license-auth slice by key; ErrNotFound.
	LicenseByKey(ctx context.Context, accountID uuid.UUID, key string) (domain.LicenseAuth, error)
	// LicenseByID loads the license-auth slice by id; ErrNotFound.
	LicenseByID(ctx context.Context, accountID uuid.UUID, id uuid.UUID) (domain.LicenseAuth, error)
	// ProductByID loads a product bearer; ErrNotFound when none.
	ProductByID(ctx context.Context, accountID uuid.UUID, id uuid.UUID) (domain.Product, error)
	// EnabledSecondFactorSecret loads the user's enabled TOTP secret;
	// ok is false when the user has none.
	EnabledSecondFactorSecret(ctx context.Context, userID uuid.UUID) (secret string, ok bool, err error)
}

Store is the scenario's consumer-side storage port.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL