admin

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2026 License: MIT, MIT Imports: 16 Imported by: 0

README

GoModularAuth Admin Plugin (gomodularauth-admin)

gomodularauth-admin is a high-security administrative management plugin for GoModularAuth. It provides privileged operations over Core authentication identities, accounts, credentials, sessions, and multi-tenant organization state.

Installation

go get github.com/BladiCreator/go-modular-auth/plugins/admin

Quick Start

package main

import (
	"context"
	"log"

	auth "github.com/BladiCreator/go-modular-auth"
	"github.com/BladiCreator/go-modular-auth/adapters/memory"
	admin "github.com/BladiCreator/go-modular-auth/plugins/admin"
	"github.com/BladiCreator/go-modular-auth/plugins/admin/plugins"
)

func main() {
	ctx := context.Background()

	// 1. Initialize Adapter
	ad := memory.NewAdapter()

	// 2. Configure GoModularAuth with Admin Plugin
	a, err := auth.New(auth.Config{
		Adapter: ad,
		Plugins: []auth.PluginModule{
			admin.New(
				// Optional: Configure authorization policy
				admin.WithAuthorizerFunc(func(ctx context.Context, p auth.Principal, action, targetUserID string) error {
					if p.Subject == "admin_user_id" {
						return nil // authorized
					}
					return admin.ErrUnauthorized
				}),
			),
		},
	})
	if err != nil {
		log.Fatalf("failed to initialize auth: %v", err)
	}

	// 3. Resolve Admin Capability
	adm, err := auth.Get[plugins.Admin](a)
	if err != nil {
		log.Fatalf("failed to resolve Admin capability: %v", err)
	}

	// 4. Perform Administrative Operations
	adminPrincipal := auth.Principal{Subject: "admin_user_id", Type: auth.PrincipalUser}

	// Disable a user
	err = adm.DisableUser(ctx, adminPrincipal, "usr_target_123", "Terms of Service violation")
	if err != nil {
		log.Fatalf("failed to disable user: %v", err)
	}
}

Detailed guide: doc/plugins/admin.md.

Documentation

Overview

Package admin is a reserved module for administrative capabilities.

Index

Constants

View Source 
const (
	ActionLookupUser         = "admin:lookup_user"
	ActionListUsers          = "admin:list_users"
	ActionDisableUser        = "admin:disable_user"
	ActionEnableUser         = "admin:enable_user"
	ActionRevokeSessions     = "admin:revoke_sessions"
	ActionResetPassword      = "admin:reset_password"
	ActionVerifyEmail        = "admin:verify_email"
	ActionInspectAccounts    = "admin:inspect_accounts"
	ActionInspectCredentials = "admin:inspect_credentials"
	ActionDeleteUser         = "admin:delete_user"
	ActionSetAdmin           = "admin:set_admin"
)

Administrative action identifiers checked by the Authorizer.

View Source 
const (
	EventUserDisabled           auth.EventName = "admin.user.disabled"
	EventUserEnabled            auth.EventName = "admin.user.enabled"
	EventUserDeleted            auth.EventName = "admin.user.deleted"
	EventSessionRevoked         auth.EventName = "admin.session.revoked"
	EventPasswordResetInitiated auth.EventName = "admin.password_reset.initiated"
	EventEmailVerified          auth.EventName = "admin.email.verified"
	EventAdminRoleAssigned      auth.EventName = "admin.role.assigned"
)

Administrative audit event identifiers emitted to GoModularAuth's EventBus.

View Source 
const (
	ModelAdminUsers = "admin_users"
)
View Source 
const PluginID = "admin"

PluginID identifies this plugin in the GoModularAuth runtime.

Variables

View Source 
var (
	// ErrUnauthorized indicates the calling Principal lacks administrative authority.
	ErrUnauthorized = errors.New("admin: unauthorized operation")

	// ErrUserNotFound indicates the target user does not exist in Core or Admin persistence.
	ErrUserNotFound = errors.New("admin: user not found")

	// ErrUserDisabled indicates the user is disabled and prohibited from authenticating.
	ErrUserDisabled = errors.New("admin: user account is disabled")

	// ErrUserAlreadyDisabled indicates the user is already in a disabled state.
	ErrUserAlreadyDisabled = errors.New("admin: user is already disabled")

	// ErrUserNotDisabled indicates the user is already active.
	ErrUserNotDisabled = errors.New("admin: user is not disabled")

	// ErrCannotDisableSelf prevents an administrator from locking their own account.
	ErrCannotDisableSelf = errors.New("admin: cannot disable own administrator account")

	// ErrCannotDeleteSelf prevents an administrator from deleting their own account.
	ErrCannotDeleteSelf = errors.New("admin: cannot delete own administrator account")

	// ErrInvalidInput indicates validation failure on input arguments.
	ErrInvalidInput = errors.New("admin: invalid input parameters")

	// ErrStoreRequired indicates that a persistent store implementation was not supplied.
	ErrStoreRequired = errors.New("admin: store is required")

	// ErrOrganizationsNotInstalled indicates organization-scoped administration was requested but Organizations plugin is not installed.
	ErrOrganizationsNotInstalled = errors.New("admin: organizations plugin not installed or configured")

	// ErrUserNotInOrganization indicates the target user does not belong to the target organization.
	ErrUserNotInOrganization = errors.New("admin: target user does not belong to specified organization")
)

Functions

func RegisterSchema added in v1.3.0 

func RegisterSchema(s *schema.Schema) error

RegisterSchema registers the admin_users model in the compiled schema.

Types

type AccountDetail added in v1.3.0 

type AccountDetail struct {
	ID         string    `json:"id"`
	UserID     string    `json:"user_id"`
	Provider   string    `json:"provider"`
	ProviderID string    `json:"provider_id"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

AccountDetail exposes non-sensitive external account linkage details for administrative inspection.

type Admin added in v1.3.0 

type Admin interface {
	// LookupUser retrieves comprehensive administrative details for a Core User by ID.
	LookupUser(ctx context.Context, p auth.Principal, userID string) (*UserDetail, error)

	// LookupUserByEmail retrieves comprehensive administrative details for a Core User by email.
	LookupUserByEmail(ctx context.Context, p auth.Principal, email string) (*UserDetail, error)

	// ListUsers returns paginated user records matching filter criteria.
	ListUsers(ctx context.Context, p auth.Principal, filter ListFilter) (*UserListResult, error)

	// DisableUser disables a user account, revokes all active sessions, and emits audit events.
	DisableUser(ctx context.Context, p auth.Principal, targetUserID string, reason string) error

	// EnableUser re-enables a disabled user account and emits audit events.
	EnableUser(ctx context.Context, p auth.Principal, targetUserID string) error

	// RevokeUserSessions immediately terminates all active sessions for a target user.
	RevokeUserSessions(ctx context.Context, p auth.Principal, targetUserID string) error

	// InitiatePasswordReset generates a single-use verification token for password reset.
	// Returns the raw verification token to send via out-of-band communication or email adapter.
	InitiatePasswordReset(ctx context.Context, p auth.Principal, targetUserID string) (string, error)

	// VerifyUserEmail marks the target user's email as verified.
	VerifyUserEmail(ctx context.Context, p auth.Principal, targetUserID string) error

	// InspectAccounts returns external provider account linkages for a target user.
	InspectAccounts(ctx context.Context, p auth.Principal, targetUserID string) ([]AccountDetail, error)

	// InspectCredentials returns sanitized credential records for a target user (NEVER exposes secrets or password hashes).
	InspectCredentials(ctx context.Context, p auth.Principal, targetUserID string) ([]CredentialDetail, error)

	// DeleteUser permanently deletes a user, their credentials, accounts, sessions, and admin metadata.
	DeleteUser(ctx context.Context, p auth.Principal, targetUserID string) error

	// SetAdminStatus assigns or revokes administrative status and role for a user.
	SetAdminStatus(ctx context.Context, p auth.Principal, targetUserID string, isAdmin bool, role string) error

	// IsUserDisabled checks if a user is currently disabled (used by hooks and auth workflows).
	IsUserDisabled(ctx context.Context, userID string) (bool, error)

	// ForOrg returns an organization-scoped administrative capability.
	// Requires the Organizations plugin to be configured.
	ForOrg(orgID string) ScopedAdmin
}

Admin defines privileged administrative operations over Core authentication state and selected plugin state. Every administrative operation explicitly requires an authenticated Principal and enforces authorization checks.

type AdminRoleAssignedPayload added in v1.3.0 

type AdminRoleAssignedPayload struct {
	ActorID      string    `json:"actor_id"`
	TargetUserID string    `json:"target_user_id"`
	IsAdmin      bool      `json:"is_admin"`
	Role         string    `json:"role"`
	AssignedAt   time.Time `json:"assigned_at"`
}

AdminRoleAssignedPayload describes an administrative privilege assignment audit event.

type Authorizer added in v1.3.0 

type Authorizer interface {
	Authorize(ctx context.Context, p auth.Principal, action string, targetUserID string) error
}

Authorizer evaluates whether an authenticated Principal is authorized to perform an administrative action.

type AuthorizerFunc added in v1.3.0 

type AuthorizerFunc func(ctx context.Context, p auth.Principal, action string, targetUserID string) error

AuthorizerFunc allows ordinary functions to act as an Authorizer.

func (AuthorizerFunc) Authorize added in v1.3.0 

func (f AuthorizerFunc) Authorize(ctx context.Context, p auth.Principal, action string, targetUserID string) error

Authorize implements Authorizer.

type Capability added in v1.3.0 

type Capability = Admin

Capability is an alias for Admin to support standard capability discovery conventions.

type Config 

type Config struct {
	Authorizer    Authorizer
	Organizations organizations.Organization
	CacheTTL      time.Duration
}

Config encapsulates configuration settings for the admin plugin.

type CredentialDetail added in v1.3.0 

type CredentialDetail struct {
	ID        string     `json:"id"`
	UserID    string     `json:"user_id"`
	AccountID string     `json:"account_id,omitempty"`
	Type      string     `json:"type"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
}

CredentialDetail exposes sanitized credential metadata.

type EmailVerifiedPayload added in v1.3.0 

type EmailVerifiedPayload struct {
	ActorID      string    `json:"actor_id"`
	TargetUserID string    `json:"target_user_id"`
	VerifiedAt   time.Time `json:"verified_at"`
}

EmailVerifiedPayload describes an administrative email verification override.

type ListFilter added in v1.3.0 

type ListFilter struct {
	Limit  int
	Offset int
	Search string // Prefix or substring match for email
	Status string // "all", "active", "disabled"
}

ListFilter specifies parameters for querying administrative user lists.

type Module added in v1.3.0 

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

Module implements auth.PluginModule using plugin-sdk.

func New 

func New(opts ...Option) *Module

New creates an installable admin PluginModule with optional configurations.

func (*Module) ID added in v1.3.0 

func (m *Module) ID() string

ID returns the module's unique identifier.

func (*Module) Init added in v1.3.0 

func (m *Module) Init(h *auth.Host) error

Init configures infrastructure and provides the typed Capability into GoModularAuth via plugin-sdk.

func (*Module) RegisterSchema added in v1.3.0 

func (m *Module) RegisterSchema(s *schema.Schema) error

RegisterSchema contributes admin_users model to the compiled schema.

type Option 

type Option func(*Config)

Option configures administrative plugin settings.

func WithAuthorizer added in v1.3.0 

func WithAuthorizer(a Authorizer) Option

WithAuthorizer provides a custom authorization policy implementation.

func WithAuthorizerFunc added in v1.3.0 

func WithAuthorizerFunc(fn func(ctx context.Context, p auth.Principal, action string, targetUserID string) error) Option

WithAuthorizerFunc provides an authorization function.

func WithCacheTTL added in v1.3.0 

func WithCacheTTL(ttl time.Duration) Option

WithCacheTTL configures the TTL for cached administrative flags.

func WithOrganizations added in v1.3.0 

func WithOrganizations(orgs organizations.Organization) Option

WithOrganizations configures integration with the Organizations plugin for organization-scoped administration.

type PasswordResetInitiatedPayload added in v1.3.0 

type PasswordResetInitiatedPayload struct {
	ActorID      string    `json:"actor_id"`
	TargetUserID string    `json:"target_user_id"`
	InitiatedAt  time.Time `json:"initiated_at"`
}

PasswordResetInitiatedPayload describes an administrative password reset initiation. CRITICAL: NEVER includes reset tokens or secret material in the event payload.

type ScopedAdmin added in v1.3.0 

type ScopedAdmin interface {
	// LookupUser retrieves administrative details for a user belonging to the organization.
	LookupUser(ctx context.Context, p auth.Principal, userID string) (*UserDetail, error)

	// ListUsers returns paginated user records belonging to the organization.
	ListUsers(ctx context.Context, p auth.Principal, filter ListFilter) (*UserListResult, error)

	// DisableUser disables a user within the organization context and revokes active sessions.
	DisableUser(ctx context.Context, p auth.Principal, targetUserID string, reason string) error

	// EnableUser re-enables a disabled user within the organization context.
	EnableUser(ctx context.Context, p auth.Principal, targetUserID string) error

	// RevokeUserSessions immediately terminates all active sessions for a target member.
	RevokeUserSessions(ctx context.Context, p auth.Principal, targetUserID string) error

	// InspectAccounts returns external provider account linkages for a target member.
	InspectAccounts(ctx context.Context, p auth.Principal, targetUserID string) ([]AccountDetail, error)

	// InspectCredentials returns sanitized credential records for a target member.
	InspectCredentials(ctx context.Context, p auth.Principal, targetUserID string) ([]CredentialDetail, error)

	// RemoveUser removes the user from the organization.
	RemoveUser(ctx context.Context, p auth.Principal, targetUserID string) error
}

ScopedAdmin provides organization-scoped administrative operations. All operations verify that the calling Principal has administrative rights in the target organization and that the target user belongs to the target organization.

type ScopedAdminPrincipal added in v1.3.0 

type ScopedAdminPrincipal struct {
	Principal      auth.Principal
	OrganizationID string
}

ScopedAdminPrincipal encapsulates an authenticated Principal along with an optional organization scope.

type SessionDetail added in v1.3.0 

type SessionDetail struct {
	ID        string     `json:"id"`
	UserID    string     `json:"user_id"`
	CreatedAt time.Time  `json:"created_at"`
	ExpiresAt time.Time  `json:"expires_at"`
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
}

SessionDetail exposes active session metadata without exposing raw session tokens or hashes.

type SessionRevokedPayload added in v1.3.0 

type SessionRevokedPayload struct {
	ActorID      string    `json:"actor_id"`
	TargetUserID string    `json:"target_user_id"`
	RevokedAt    time.Time `json:"revoked_at"`
}

SessionRevokedPayload describes a session revocation audit event.

type UserDeletedPayload added in v1.3.0 

type UserDeletedPayload struct {
	ActorID      string    `json:"actor_id"`
	TargetUserID string    `json:"target_user_id"`
	DeletedAt    time.Time `json:"deleted_at"`
}

UserDeletedPayload describes a user deletion audit event.

type UserDetail added in v1.3.0 

type UserDetail struct {
	User        *user.User         `json:"user"`
	Record      *UserRecord        `json:"record"`
	Accounts    []AccountDetail    `json:"accounts"`
	Credentials []CredentialDetail `json:"credentials"`
	Sessions    []SessionDetail    `json:"sessions,omitempty"`
}

UserDetail provides comprehensive administrative inspection data for a Core User.

type UserDisabledPayload added in v1.3.0 

type UserDisabledPayload struct {
	ActorID      string    `json:"actor_id"`
	TargetUserID string    `json:"target_user_id"`
	Reason       string    `json:"reason"`
	DisabledAt   time.Time `json:"disabled_at"`
}

UserDisabledPayload describes a user disable audit event.

type UserEnabledPayload added in v1.3.0 

type UserEnabledPayload struct {
	ActorID      string    `json:"actor_id"`
	TargetUserID string    `json:"target_user_id"`
	EnabledAt    time.Time `json:"enabled_at"`
}

UserEnabledPayload describes a user enable audit event.

type UserListResult added in v1.3.0 

type UserListResult struct {
	Users  []*UserRecord `json:"users"`
	Total  int           `json:"total"`
	Limit  int           `json:"limit"`
	Offset int           `json:"offset"`
}

UserListResult encapsulates a paginated set of administrative user summaries.

type UserRecord added in v1.3.0 

type UserRecord struct {
	UserID         string            `json:"user_id"`
	Email          string            `json:"email"`
	Disabled       bool              `json:"disabled"`
	DisabledAt     *time.Time        `json:"disabled_at,omitempty"`
	DisabledReason string            `json:"disabled_reason,omitempty"`
	IsAdmin        bool              `json:"is_admin"`
	Role           string            `json:"role,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
	CreatedAt      time.Time         `json:"created_at"`
	UpdatedAt      time.Time         `json:"updated_at"`
}

UserRecord represents administrative metadata and lifecycle state associated with a Core User.

func (*UserRecord) Active added in v1.3.0 

func (r *UserRecord) Active() bool

Active reports whether the user is not disabled.

Source Files

View all Source files

Directories

Path Synopsis
Package cache provides caching support for high-frequency administrative queries.
 Package cache provides caching support for high-frequency administrative queries.
Package events exports administrative audit event types for GoModularAuth.
 Package events exports administrative audit event types for GoModularAuth.
Package migrations contains SQL schema migrations for the admin plugin.
 Package migrations contains SQL schema migrations for the admin plugin.
Package plugins exposes capability aliases for GoModularAuth plugins.
 Package plugins exposes capability aliases for GoModularAuth plugins.

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.