authkit

type APIKeyValidator interface {
	ValidateKey(ctx context.Context, rawKey string) (*User, error)
}

type AuditEvent struct {
	Type     string
	TenantID string
	Actor    string
	Subject  string
	IP       string
	At       time.Time
	Meta     map[string]any
}

type AuditSink interface {
	Emit(ctx context.Context, ev AuditEvent)
}

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

type AuthCodeStore interface {
	ClaimAuthCode(ctx context.Context, jti string, expiresAt time.Time) (ok bool, err error)
}

type AuthMode string

type BcryptHasher struct {
	// Cost overrides the bcrypt cost. Zero means the default (12).
	Cost int
}

type CSRFConfig struct {
	// Enable turns on the CSRF middleware (signed double-submit) for
	// cookie-authenticated, state-changing requests. Token-authenticated
	// requests are always exempt.
	Enable bool

	// TrustedOrigins, when non-empty, additionally requires the Origin header
	// (when present) of unsafe requests to match one of these origins
	// (scheme://host[:port]). Defense in depth on top of the signed
	// double-submit token.
	TrustedOrigins []string
}

type Config struct {
	// Mode controls which authentication methods are enabled.
	// Defaults to AuthModeOAuth.
	Mode AuthMode

	// AppName is the product name shown to users where one is needed (e.g. the
	// issuer in authenticator apps for TOTP). Defaults to "App".
	AppName string

	// SessionSecret signs session cookies, CSRF tokens, and the short-lived
	// pending-step tokens. Must be at least 32 bytes of random data.
	SessionSecret string

	// SecureCookie controls the Secure flag (and __Host- prefix) on cookies.
	// Set to true in production (HTTPS only). Defaults to false.
	SecureCookie bool

	// CookiePrefix namespaces every cookie authkit sets (session ID, CSRF,
	// pending 2FA, platform, trusted device), so two authkit-based apps on one
	// host never collide. Defaults to "authkit".
	CookiePrefix string

	// AfterLoginURL is the URL the user is redirected to after a successful
	// browser login. Defaults to "/".
	AfterLoginURL string

	// AfterLogoutURL is the URL the user is redirected to after logout.
	// Defaults to "/".
	AfterLogoutURL string

	// Logger receives authkit's diagnostic output as structured logs. When
	// nil, slog.Default() is used. Secrets and tokens are never logged.
	Logger *slog.Logger

	// ClientIP resolves the client IP for throttling and audit events. When
	// nil, the host portion of RemoteAddr is used and forwarding headers are
	// deliberately NOT trusted — behind a reverse proxy, supply a function
	// that reads your vetted header.
	ClientIP func(*http.Request) string

	// ErrorWriter, when set, replaces authkit's JSON error envelope with the
	// host's own rendering. See the ErrCode* constants for the code catalog.
	ErrorWriter ErrorWriter

	// OAuth configures browser OAuth providers.
	// Required when Mode is AuthModeOAuth or AuthModeBoth.
	OAuth OAuthConfig

	// UserStore provides user persistence for password-based authentication.
	// Required when Mode is AuthModePassword or AuthModeBoth.
	UserStore UserStore

	// PasswordHasher hashes and verifies passwords. Defaults to bcrypt with
	// cost 12. Supply Argon2 or another KDF by implementing the interface.
	PasswordHasher PasswordHasher

	// PasswordPolicy configures password validation rules.
	// If nil, defaults are used (minimum 8 characters).
	PasswordPolicy *PasswordPolicy

	// RBAC configures the role policy. If FilePath is empty and Provider is
	// nil, all authenticated users receive an empty role with no permissions.
	RBAC RBACConfig

	// APIKeyValidator enables API key authentication alongside sessions.
	// When set, Require and RequireAuth middleware check the Authorization:
	// Bearer (or X-API-Key) header first. RequireSession and RequireSessionAuth
	// skip API key auth entirely (session-only routes).
	APIKeyValidator APIKeyValidator

	// AuditSink receives security audit events (login, logout, refresh, revoke,
	// 2fa_*, role_change, permission_change, impersonate). If nil, a
	// NopAuditSink is installed so authkit can emit unconditionally.
	AuditSink AuditSink

	// Throttler rate-limits password login and 2FA attempts (per account+IP).
	// When nil, no throttling is applied.
	Throttler LoginThrottler

	// LivePermissionResolution makes Require/RequireAuth re-resolve a session
	// user's permissions from the PolicyProvider on every request (through a
	// short TTL cache), so role and permission changes take effect within the
	// cache window rather than only on next login. Multi-tenant deploys want
	// this on; single-tenant deploys can leave it off (cheaper login-time
	// cache). API-key credentials always resolve live regardless of this flag.
	LivePermissionResolution bool

	// PermissionCacheTTL bounds how stale a live-resolved permission set may be.
	// Defaults to 30s when LivePermissionResolution is enabled.
	PermissionCacheTTL time.Duration

	// Sessions configures revocable server-side sessions.
	Sessions SessionConfig

	// CSRF configures CSRF protection for cookie-authenticated requests.
	CSRF CSRFConfig

	// TwoFactor configures TOTP two-step authentication.
	TwoFactor TwoFactorConfig

	// Tokens configures the OAuth2/PKCE token layer for native clients.
	Tokens TokenConfig

	// Platform configures the platform-operator (super-admin) axis.
	Platform PlatformConfig

	// Reset configures the self-service password-reset flow.
	Reset ResetConfig

	// Devices configures the device-principal axis.
	Devices DeviceConfig
}

type Device struct {
	AgentID  string
	Name     string
	TenantID string
	Attrs    map[string]string
	// contains filtered or unexported fields
}

type DeviceConfig struct {
	// Validator enables the device principal axis. When set, RequireDevice and
	// AuthenticateDevice validate opaque device tokens against it. When nil,
	// device auth is disabled.
	Validator DeviceTokenValidator

	// Capabilities is the fixed allow-list of capability strings a device
	// principal may ever hold. It is declared here, in code, precisely so a
	// device can never acquire a capability through policy data. Required when
	// Validator is set.
	Capabilities []string
}

type DeviceRecord struct {
	AgentID  string
	Name     string
	TenantID string
	Attrs    map[string]string
}

type DeviceTokenValidator interface {
	ValidateDeviceToken(ctx context.Context, rawToken string) (*DeviceRecord, error)
}

type ErrorWriter func(w http.ResponseWriter, r *http.Request, status int, code, desc string)

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

type LoginThrottler interface {
	// Allow reports whether an attempt for key may proceed. When locked out, ok
	// is false and retryAfter is the remaining lockout duration.
	Allow(ctx context.Context, key string) (retryAfter time.Duration, ok bool)
	// RecordFailure registers a failed attempt (advancing backoff/lockout).
	RecordFailure(ctx context.Context, key string) error
	// Reset clears the failure state for key after a successful login.
	Reset(ctx context.Context, key string) error
}

type NopAuditSink struct{}

type OAuthConfig struct {
	// Providers is the list of OAuth providers to enable using the built-in
	// convenience wrappers (bitbucket, github, google, gitlab).
	// Required when Mode is AuthModeOAuth or AuthModeBoth, unless GothProviders
	// is supplied instead.
	Providers []ProviderConfig

	// GothProviders is a list of pre-constructed goth.Provider values.
	// Use this to enable any of the 80+ providers that goth supports beyond the
	// built-in convenience wrappers. Import the provider package you need from
	// github.com/markbates/goth/providers/*, construct the provider, and pass
	// it here. It is merged with any providers built from Providers.
	GothProviders []goth.Provider

	// CallbackBaseURL is the externally-reachable base URL of the service
	// (e.g. "https://example.com"). The OAuth callback URLs are derived as
	// {CallbackBaseURL}/auth/{provider}/callback.
	// Required when Mode is AuthModeOAuth or AuthModeBoth.
	CallbackBaseURL string
}

type PasswordHasher interface {
	Hash(password string) (string, error)
	Verify(hashedPassword, password string) bool
}

type PasswordPolicy struct {
	// MinLength is the minimum password length. Defaults to 8.
	MinLength int

	// MaxLength caps the password length in bytes. Defaults to 72, the hard
	// limit of the default bcrypt hasher (longer inputs would otherwise be
	// rejected by the KDF with an opaque error). Raise it when using a hasher
	// without that limit (e.g. Argon2).
	MaxLength int
}

type PasswordResetStore interface {
	// CreateResetToken stores a hashed token bound to (email, kind) with expiry.
	CreateResetToken(ctx context.Context, tokenHash, email, kind string, expiresAt time.Time) error
	// ConsumeResetToken atomically marks the token used (only if unused and
	// unexpired) and returns the email it binds. ok is false when the token is
	// unknown, already used, expired, or of the wrong kind.
	ConsumeResetToken(ctx context.Context, tokenHash, kind string) (email string, ok bool, err error)
}

type PasswordUser struct {
	Email          string
	Name           string
	HashedPassword string

	// TenantID binds this credential to one tenant (email is global, so the
	// lookup determines the tenant). Attrs carries host-defined principal
	// attributes. Both are copied onto the authenticated User.
	TenantID string
	Attrs    map[string]string

	// MustChangePassword is set when the credential is a temporary/onboarding
	// one the user must replace before doing anything else. When true, Login
	// stops before 2FA and asks the client to collect a new password (see
	// ChangeFirstPassword); the store clears it on the next UpdatePassword.
	MustChangePassword bool
}

type PlatformAdmin struct {
	Email string
	Name  string
	Role  string
	// contains filtered or unexported fields
}

type PlatformAdminRecord struct {
	Email          string
	Name           string
	HashedPassword string
	Role           string
	TOTPSecret     string
	TOTPConfirmed  bool
}

type PlatformAdminStore interface {
	GetPlatformAdmin(ctx context.Context, email string) (*PlatformAdminRecord, error)

	// UpdatePassword sets the hashed password for the platform admin with
	// this email. Called by the platform password-reset flow; it does NOT touch
	// the TOTP secret (2FA stays mandatory). Platform admins are not
	// tenant-scoped.
	UpdatePassword(ctx context.Context, email, hashedPassword string) error

	// EnrollPlatformTOTP stores (or replaces) a PENDING secret + recovery hashes
	// for an admin who has not confirmed 2FA yet (mirrors the user TOTPStore).
	EnrollPlatformTOTP(ctx context.Context, email, secret string, recoveryCodeHashes []string) error
	// ConfirmPlatformTOTP activates a pending secret on first successful verify.
	// Idempotent: a no-op once confirmed.
	ConfirmPlatformTOTP(ctx context.Context, email string) error
	// ConsumePlatformRecovery atomically marks a recovery code used (single-use)
	// and reports whether it matched an unused code.
	ConsumePlatformRecovery(ctx context.Context, email, codeHash string) (bool, error)
}

type PlatformConfig struct {
	// Store + Policy enable the platform principal axis (separate from tenant
	// users). Platform login always requires TOTP.
	Store  PlatformAdminStore
	Policy PlatformPolicy

	// EnableImpersonation gates break-glass single-tenant access.
	EnableImpersonation bool
}

type PlatformPolicy interface {
	PermissionsForPlatformRole(role string) []string
}

type PlatformTOTPReplayGuard interface {
	ClaimPlatformTOTPTimestep(ctx context.Context, email string, timestep int64) (ok bool, err error)
}

type Policy struct {
	// Roles maps role names to their definition.
	Roles map[string]RolePolicy `yaml:"roles"`

	// DefaultRole is assigned to authenticated users whose email is not listed
	// under any role. Leave empty to deny access to unlisted users.
	DefaultRole string `yaml:"default_role"`
}

type PolicyProvider interface {
	// RoleFor returns the role name and permission list for the given email.
	// Called on every login and API key auth. Return empty strings/nil when
	// the user has no assigned role.
	RoleFor(ctx context.Context, email string) (role string, permissions []string)

	// PermissionsForRole returns the permissions for a named role. The ctx
	// carries the tenant (via TenantIDFromCtx) so role definitions can be
	// per-tenant — a DB-backed provider scopes its lookup to that tenant.
	// Used to resolve permissions for API key users and for per-request live
	// resolution (LivePermissionResolution).
	PermissionsForRole(ctx context.Context, role string) []string
}

type PolicyReloader interface {
	Reload() error
}

type ProviderConfig struct {
	// Name is the provider identifier for the built-in wrappers: "bitbucket", "github", "google", or "gitlab".
	// For any other provider, use Config.GothProviders instead.
	Name string

	// ClientID and ClientSecret are the OAuth application credentials.
	ClientID     string
	ClientSecret string

	// Scopes overrides the default scopes for the provider.
	// Leave nil to use the sensible defaults (email + profile).
	Scopes []string
}

type RBACConfig struct {
	// FilePath is the path to the rbac.yaml policy file.
	// Used when Provider is nil.
	FilePath string

	// Provider supplies a custom PolicyProvider implementation (e.g. a
	// database-backed or layered provider). When set, FilePath is ignored.
	Provider PolicyProvider
}

type RefreshToken struct {
	ID        string
	UserEmail string
	TenantID  string
	ChainID   string
	ParentID  string
	IssuedAt  time.Time
	ExpiresAt time.Time
	UsedAt    *time.Time
	RevokedAt *time.Time
}

type RefreshTokenStore interface {
	// Create stores a new refresh token.
	Create(ctx context.Context, t *RefreshToken) error
	// Get returns the token for the raw value, or nil if not found.
	Get(ctx context.Context, rawToken string) (*RefreshToken, error)
	// Rotate atomically marks rawOld used and stores next (its child). It MUST
	// fail (and change nothing) if rawOld is already used or revoked.
	Rotate(ctx context.Context, rawOld string, next *RefreshToken) error
	// RevokeChain revokes every token sharing chainID (reuse response).
	RevokeChain(ctx context.Context, chainID string) error
	// RevokeAllForUser revokes every refresh token belonging to one user, so a
	// credential change or "log out everywhere" cuts off the bearer axis too,
	// not just cookie sessions. tenantID scopes the revoke; email identifies
	// the user.
	RevokeAllForUser(ctx context.Context, tenantID, email string) error
}

type ResetConfig struct {
	// Store persists single-use, hashed reset tokens; Delivery sends the raw
	// token out-of-band (email/SMS). Both are required to enable the
	// ForgotPassword/ResetPassword (and platform) handlers.
	Store    PasswordResetStore
	Delivery ResetDelivery

	// TTL bounds a token's validity (default 30m).
	TTL time.Duration
}

type ResetDelivery interface {
	SendPasswordReset(ctx context.Context, req ResetRequest) error
}

type ResetRequest struct {
	Email string
	Name  string
	Kind  string
	Token string
	TTL   time.Duration
}

type ResetToken struct {
	TokenHash string
	Email     string
	Kind      string
	ExpiresAt time.Time
	UsedAt    *time.Time
}

type RolePolicy struct {
	// Permissions is the list of allowed permissions for this role.
	// Use "*" to grant all permissions (admin).
	Permissions []string `yaml:"permissions"`

	// Members is the list of email addresses assigned to this role.
	Members []string `yaml:"members"`
}

type Session struct {
	ID          string
	TenantID    string
	Email       string
	Name        string
	Provider    string
	Role        string
	Permissions []string

	// Attrs carries the principal's host-defined attributes (see User.Attrs).
	Attrs map[string]string

	// Platform marks a platform-operator session — no tenant. Tenant and
	// platform sessions use different cookies, so they never cross.
	Platform bool

	// CreatedAt anchors the absolute timeout; LastSeenAt anchors the idle
	// timeout (advanced by Touch on a sliding basis).
	CreatedAt  time.Time
	LastSeenAt time.Time
}

type SessionConfig struct {
	// Store enables revocable, server-side sessions. When set, the cookie
	// carries only an opaque session ID and all identity state lives in the
	// store, allowing instant revocation and "log out everywhere". When nil,
	// authkit falls back to the legacy encrypted-cookie session.
	Store SessionStore

	// IdleTimeout expires a session after inactivity (sliding). Defaults to 30m.
	IdleTimeout time.Duration

	// AbsoluteTimeout caps a session's total lifetime regardless of activity.
	// Defaults to 24h.
	AbsoluteTimeout time.Duration
}

type SessionStore interface {
	// Create persists a new session. Returns an error only on infrastructure failure.
	Create(ctx context.Context, s *Session) error
	// Get returns the session for id, or nil when it does not exist.
	Get(ctx context.Context, id string) (*Session, error)
	// Touch advances LastSeenAt for sliding idle renewal.
	Touch(ctx context.Context, id string, lastSeen time.Time) error
	// Revoke deletes a single session (logout / fixation rotation).
	Revoke(ctx context.Context, id string) error
	// RevokeAllForUser deletes every session for a user ("log out everywhere").
	RevokeAllForUser(ctx context.Context, tenantID, email string) error
}

type SigningKey struct {
	KID     string
	Private ed25519.PrivateKey
}

type TOTPManager interface {
	// Disable removes the user's TOTP secret and all recovery codes (turning 2FA
	// off). Idempotent: a no-op when none is stored.
	Disable(ctx context.Context, tenantID, email string) error
	// ReplaceRecoveryCodes deletes the user's existing recovery codes and stores
	// the given hashed set, without touching the confirmed TOTP secret.
	ReplaceRecoveryCodes(ctx context.Context, tenantID, email string, recoveryCodeHashes []string) error
}

type TOTPReplayGuard interface {
	ClaimTOTPTimestep(ctx context.Context, tenantID, email string, timestep int64) (ok bool, err error)
}

type TOTPStore interface {
	// Enroll stores (or replaces) the user's TOTP secret and the hashed recovery
	// codes as PENDING — provisioned but NOT yet confirmed. The user is not
	// considered to have working 2FA until they prove possession of the
	// authenticator with a valid code (see Confirm). This two-phase model is what
	// lets a user who abandons enrollment (got the QR, never added it) be sent
	// back to enroll on the next login instead of being locked at the verify step.
	Enroll(ctx context.Context, tenantID, email, secret string, recoveryCodeHashes []string) error
	// Confirm marks a pending secret confirmed (activated). Called once, on the
	// user's first successful verification. MUST be idempotent: a no-op when the
	// secret is already confirmed or absent.
	Confirm(ctx context.Context, tenantID, email string) error
	// Secret returns the user's TOTP secret (empty when none is stored) and whether
	// it has been CONFIRMED. A non-empty secret with confirmed=false is a pending
	// enrollment: it can be validated (to confirm it) but does not by itself mean
	// the user has set up 2FA.
	Secret(ctx context.Context, tenantID, email string) (secret string, confirmed bool, err error)
	// ConsumeRecovery atomically marks a recovery code used (single-use) and
	// reports whether it matched an unused code.
	ConsumeRecovery(ctx context.Context, tenantID, email, codeHash string) (bool, error)
}

type TokenConfig struct {
	// Enable turns on the OAuth2/PKCE token endpoints and the bearer-JWT
	// verifier. Requires SigningKeys and RefreshStore.
	Enable bool

	// SigningKeys is the Ed25519 rotation ring; the first key signs new access
	// tokens, all keys verify (and are published via JWKS).
	SigningKeys []SigningKey

	// AccessTTL is the access-JWT lifetime (default 15m); RefreshTTL the
	// refresh-token lifetime (default 30d).
	AccessTTL  time.Duration
	RefreshTTL time.Duration

	// RefreshStore persists opaque refresh tokens (rotation + reuse detection).
	RefreshStore RefreshTokenStore

	// AuthCodes, when set, makes PKCE authorization codes single-use: the
	// code's jti is claimed at redemption so a code cannot be exchanged twice
	// within its short TTL. Optional (nil keeps the stateless,
	// replayable-within-TTL behavior); a short-TTL store is the natural backing.
	AuthCodes AuthCodeStore

	// Issuer is the JWT `iss` claim; ClientID the public native client id
	// (also the JWT audience); RedirectURIs the allowed PKCE redirect URIs.
	Issuer       string
	ClientID     string
	RedirectURIs []string
}

type TrustedDeviceStore interface {
	// Trust records a trusted device for (tenant, email) and returns the opaque
	// cookie token. ttl bounds its lifetime.
	Trust(ctx context.Context, tenantID, email string, ttl time.Duration) (token string, err error)
	// IsTrusted reports whether token is a live trusted device for (tenant, email).
	IsTrusted(ctx context.Context, tenantID, email, token string) (bool, error)
	// RevokeAllForUser drops every trusted device for a user.
	RevokeAllForUser(ctx context.Context, tenantID, email string) error
}

type TwoFactorConfig struct {
	// Store enables two-step auth (TOTP). When set, a user whose role is in
	// RequireForRoles must complete a TOTP challenge after the password step.
	// When nil, 2FA is disabled.
	Store TOTPStore

	// RequireForRoles lists the roles that must complete 2FA. Only consulted
	// when Store is set.
	RequireForRoles []string

	// TrustedDevices enables a "trust this device" option at the 2FA step: a
	// remembered device skips the TOTP prompt (the password is still required)
	// for TrustedDeviceTTL. The token is opaque + server-side, so it is
	// revocable (logout-everywhere, password change/reset, and disabling 2FA
	// all drop it). When nil, every 2FA login prompts for TOTP. NOT used for
	// platform admins (their 2FA is mandatory and never skipped).
	TrustedDevices TrustedDeviceStore

	// TrustedDeviceTTL bounds how long a trusted device skips 2FA. Defaults to 30d.
	TrustedDeviceTTL time.Duration
}

type User struct {
	Email     string `json:"email"`
	Name      string `json:"name"`
	AvatarURL string `json:"avatarUrl"`
	Provider  string `json:"provider"`
	Role      string `json:"role"`

	// TenantID binds the principal to one tenant — the hard security boundary
	// in a multi-tenant deployment. Populated in every credential path:
	// UserStore (password), the OAuth callback mapping, and APIKeyValidator.
	// Single-tenant applications simply leave it empty.
	TenantID string `json:"tenantId,omitempty"`

	// Attrs carries host-defined principal attributes (for example an
	// organizational sub-scope, locale, or plan tier). authkit round-trips it
	// through sessions and access-token claims but never interprets it: keys
	// and meaning belong to the host application. Keep values small — they
	// travel in the session record and the JWT.
	Attrs map[string]string `json:"attrs,omitempty"`
	// contains filtered or unexported fields
}

type UserRoleStore interface {
	// GetOverride returns the role and permissions for email if a UI-managed
	// override exists. Return found=false when no override has been set for
	// this user — authkit will fall back to the YAML baseline.
	// The email argument is always lower-cased and trimmed before being passed.
	GetOverride(ctx context.Context, email string) (role string, permissions []string, found bool, err error)

	// SetOverride creates or replaces the role override for a user.
	// Prefer calling LayeredPolicyProvider.SetOverride instead — it validates
	// the role name and permission strings before writing to the store.
	SetOverride(ctx context.Context, email, role string, permissions []string) error

	// DeleteOverride removes the override for email, reverting that user to
	// whatever the YAML baseline assigns them.
	DeleteOverride(ctx context.Context, email string) error
}

type UserStore interface {
	// CreateUser persists a new user with the given email and pre-hashed
	// password. Implementations MUST return ErrUserExists if the email is
	// already taken.
	CreateUser(ctx context.Context, email, name, hashedPassword string) error

	// GetUserByEmail retrieves a user by email. Returns ErrUserNotFound if
	// no user matches.
	GetUserByEmail(ctx context.Context, email string) (*PasswordUser, error)

	// UpdatePassword sets the hashed password for the user with this (global)
	// email. Called by the password-reset and password-change flows. ctx
	// carries the user's tenant, so a tenant-scoped store can apply its own
	// row-level scoping.
	UpdatePassword(ctx context.Context, email, hashedPassword string) error
}