elevation

package
v1.10.21 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 14 Imported by: 0

Documentation

Overview

Package elevation is the admin console unlock ("sudo mode"): signing in gives an admin the workspace side, and the platform console additionally needs a short-lived unlock proved with a second factor. The unlock is an opaque, revocable token bound to the login session's jti, so a stolen unlock is useless without the session, and signing out or revoking the session kills it.

It protects against an unattended browser, a stolen session cookie or a phished password alone. It does not protect against XSS on the same origin, which can ride an unlocked session.

Index

Constants

View Source
const (
	CookieName = "miabi_admin_unlock"
	HeaderName = "X-Miabi-Admin-Elevation"
)

CookieName carries the unlock for browser clients; HeaderName carries it for the CLI.

Variables

View Source
var (
	ErrRequired      = &CodedError{"ADMIN_ELEVATION_REQUIRED", "the admin console is locked: confirm your second factor to unlock it"}
	ErrSetupRequired = &CodedError{"ADMIN_2FA_SETUP_REQUIRED", "set up two-factor authentication before unlocking the admin console"}
	ErrStale         = &CodedError{"ADMIN_ELEVATION_STALE", "this action needs a recent unlock: confirm your second factor again"}
	ErrIPNotAllowed  = &CodedError{"ADMIN_IP_NOT_ALLOWED", "the admin console is not reachable from this address"}
	ErrLocked        = &CodedError{"ADMIN_ELEVATION_LOCKED", "too many wrong codes: the admin console unlock is locked for a while"}
	ErrInvalidCode   = &CodedError{"ADMIN_ELEVATION_INVALID_CODE", "invalid code"}
	ErrNotRequired   = errors.New("the admin console unlock is not enabled")
)

Functions

func ClearLockout added in v1.10.18

func ClearLockout(ctx context.Context, rdb *redis.Client, userID uint) error

ClearLockout drops a user's console-unlock lockout and failure count, for host-side recovery.

func IPAllowed

func IPAllowed(set secpolicy.AdminAccess, ip string) bool

IPAllowed reports whether ip may reach the admin console under the settings.

Types

type CodedError

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

CodedError carries a stable machine code into the API error envelope, so the web client can tell "unlock the console" from any other 403 without parsing messages.

func (*CodedError) Code

func (e *CodedError) Code() string

Code satisfies the error handler's Code() hook.

func (*CodedError) Error

func (e *CodedError) Error() string

type Notifier

type Notifier interface {
	NotifyAdmins(item models.Notification) error
}

Notifier tells the other admins about a lockout. Satisfied by *alerting.AdminNotifier.

type PolicySource

type PolicySource interface {
	AdminAccessPolicy() (secpolicy.AdminAccess, bool)
}

PolicySource yields the Enterprise admin_access policy. Satisfied by *secpolicy.Service.

type Record

type Record struct {
	UserID    uint      `json:"user_id"`
	JTI       string    `json:"jti"`
	CreatedAt time.Time `json:"created_at"`
	LastUsed  time.Time `json:"last_used"`
	ExpiresAt time.Time `json:"expires_at"`
}

Record is an unlock as stored in Redis, keyed by the token's hash.

func (Record) IdleExpiresAt

func (r Record) IdleExpiresAt(idle time.Duration) time.Time

IdleExpiresAt is when the unlock lapses without further use.

type SecondFactor

type SecondFactor interface {
	VerifySecondFactor(user *models.User, code string) error
}

SecondFactor verifies a TOTP or recovery code. Satisfied by *auth.Service.

type Service

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

Service issues and checks unlocks.

func NewService

func NewService(rdb *redis.Client, policy PolicySource, factor SecondFactor, community bool) *Service

NewService builds the unlock service. community is MIABI_ADMIN_UNLOCK: Community's switch for the TOTP unlock with default timings, which the Enterprise policy supersedes.

func (*Service) Check

func (s *Service) Check(ctx context.Context, userID uint, jti, token string) (Record, error)

Check validates an unlock for the session and extends its idle window. It returns ErrRequired for anything that is not a live unlock of this user's this session.

func (*Service) Elevate

func (s *Service) Elevate(ctx context.Context, user *models.User, jti string, sessionExp time.Time, code string) (string, Record, error)

Elevate verifies a second factor and issues an unlock bound to the session jti. The unlock never outlives sessionExp. Every attempt is reported to audit by the caller.

func (*Service) Fresh

func (s *Service) Fresh(rec Record) bool

Fresh reports whether rec is recent enough for a sensitive action.

func (*Service) LockedUntil

func (s *Service) LockedUntil(ctx context.Context, userID uint) time.Time

LockedUntil reports when a user's unlock lockout ends; zero when not locked.

func (*Service) Peek

func (s *Service) Peek(ctx context.Context, userID uint, jti, token string) (Record, error)

Peek is Check without touching the idle window, for status reads.

func (*Service) Revoke

func (s *Service) Revoke(ctx context.Context, token string)

Revoke deletes an unlock.

func (*Service) SetNotifier

func (s *Service) SetNotifier(n Notifier)

SetNotifier wires lockout notices to the other admins.

func (*Service) Settings

func (s *Service) Settings() secpolicy.AdminAccess

Settings resolves the unlock in force: the Enterprise policy when enforced, else Community's switch with default timings, else none. Required=false means the console needs no unlock, though an Enterprise allowlist may still apply.

Jump to

Keyboard shortcuts

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