Skip to main content

Generated from package comments and exported declarations. Edit the Go source, not this file.

auth

import "codeberg.org/hemanta212/playgo/api/auth"

Package auth defines user identity, role, permission, session, and admin-account contracts.

Admin operations use these types to tell players, admins, and super-admins apart, to enforce narrow permissions such as withdrawal approval, and to model privileged commands like admin password resets, which are idempotent so a retry cannot silently reset a password twice.

This package owns the vocabulary that handlers and services reason about. The mechanics of browser authentication and CSRF enforcement live in the internal auth adapters. Worth remembering: any role check performed in a client is a usability affordance, and the checks built on this package are the real boundary.

Constants​

const (
UserRolePlayer UserRole = "player"
UserRoleAdmin UserRole = "admin"
UserRoleSuperAdmin UserRole = "super_admin"

PermissionWithdrawalsApprove Permission = "withdrawals.approve"
)
const (
UsernameBaseMinLength = 3
UsernameBaseMaxLength = 11
)

SystemAccountEmailDomain marks users owned by the provider-health probe system (canary players). It is the single backend marker for "operational account, not a real player": canary creation derives emails from it and the admin read models classify with it (SQL: playgo_is_external_user).

const SystemAccountEmailDomain = "@system.playgo.invalid"

Variables​

var (
ErrEmailTaken = errors.New("email taken")
ErrAdminAlreadyProvisioned = errors.New("admin already provisioned")
ErrInvalidCredentials = errors.New("invalid credentials")
ErrUnauthenticated = errors.New("unauthenticated")
ErrForbidden = errors.New("forbidden")
ErrInvalidCSRFToken = errors.New("invalid csrf token")
ErrPasswordPolicy = errors.New("password policy")
ErrInvalidEmail = errors.New("invalid email")
ErrInvalidDisplayName = errors.New("invalid display name")
ErrInvalidProfileUpdate = errors.New("invalid profile update")
ErrInvalidPasswordlessLogin = errors.New("invalid passwordless login")
ErrPasswordlessLoginRateLimited = errors.New("passwordless login rate limited")
ErrInvalidAdminAccount = errors.New("invalid admin account")
ErrNotFound = errors.New("not found")
ErrConflict = errors.New("conflict")
)
var ErrInvalidUsername = errors.New("invalid username")

func ActorUUID​

func ActorUUID(ctx context.Context, subject uuid.UUID) uuid.UUID

func DefaultUsernameBase​

func DefaultUsernameBase(email string) string

func IsSystemAccountEmail​

func IsSystemAccountEmail(email string) bool

func IsViewEmulation​

func IsViewEmulation(ctx context.Context) bool

func NormalizeUsernameBase​

func NormalizeUsernameBase(value string) string

NormalizeUsernameBase is the shared normalization for game-login bases.

func OperatorActorFromContext​

func OperatorActorFromContext(ctx context.Context) (uuid.UUID, bool)

func UserRoleValues​

func UserRoleValues() []string

func WithCommandActor​

func WithCommandActor(ctx context.Context, actor uuid.UUID) context.Context

func WithEmulationIdentity​

func WithEmulationIdentity(ctx context.Context, identity EmulationIdentity) context.Context

func WithOperatorActor​

func WithOperatorActor(ctx context.Context, actor uuid.UUID) context.Context

func WithoutEmulation​

func WithoutEmulation(ctx context.Context) context.Context

type CreateAdminCommand​

type CreateAdminCommand struct {
Email string
Password string
DisplayName *string
Role UserRole
}

type CurrentUser​

type CurrentUser struct {
Username *string
ID UserID
Email string
DisplayName string
Role UserRole
Status UserStatus
Phone *string
Birthday *string // ISO date YYYY-MM-DD when set.
Address *string
SessionVersion int64
CreatedAt time.Time
}

type EmulationIdentity​

EmulationIdentity is installed only after a session-bound grant is verified. Actor remains the real session owner; Subject is the viewed player.

type EmulationIdentity struct {
Actor, Subject CurrentUser
GrantID uuid.UUID
Act bool
}

func EmulationFromContext​

func EmulationFromContext(ctx context.Context) (EmulationIdentity, bool)

type LoginCommand​

type LoginCommand struct {
Email string
Password string
}

type PasswordlessLoginRequested​

PasswordlessLoginRequested is the generic, non-enumerating response: the same shape whether or not the email already has an account.

type PasswordlessLoginRequested struct {
Email string
ResendAvailableAt time.Time
ExpiresAt time.Time
// DevCode is populated ONLY in non-production when the dev code-reveal hook is
// enabled, so the flow is testable locally without email delivery. Never set in prod.
DevCode *string
}

type PasswordlessVerifyResult​

PasswordlessVerifyResult is the outcome of a passwordless verification: the authenticated user plus whether this verify just activated a brand-new (pending email verification) account. IsNew is true only for that signup-completing first verify; returning logins report false.

type PasswordlessVerifyResult struct {
User CurrentUser
IsNew bool
}

type Permission​

type Permission string

type ProfileFieldUpdate​

ProfileFieldUpdate is a partial-update field: Set indicates the field is part of this update at all; Value is the new value (nil Value with Set=true clears the stored value). Omitted fields (Set=false) are left unchanged.

type ProfileFieldUpdate struct {
Set bool
Value *string
}

type ProfileState​

type ProfileState struct {
Authenticated bool
User *CurrentUser
CSRFToken string
}

type ProvisionAdminCommand​

ProvisionAdminCommand is a one-shot operator bootstrap command. It is intentionally first-admin-only: once any admin user exists, later attempts fail even when the requested email differs.

type ProvisionAdminCommand struct {
Email string
Password string
DisplayName *string
}

type RegisterCommand​

type RegisterCommand struct {
Email string
Password string
DisplayName *string
}

type RequestPasswordlessLoginCommand​

RequestPasswordlessLoginCommand starts the email-first passwordless flow. Email only; works for both new and existing accounts.

type RequestPasswordlessLoginCommand struct {
Email string
AnonymousSubject *uuid.UUID
}

type ResendPasswordlessLoginCommand​

ResendPasswordlessLoginCommand reissues the combined link+code challenge.

type ResendPasswordlessLoginCommand struct {
Email string
AnonymousSubject *uuid.UUID
}

type ResetAdminPasswordCommand​

type ResetAdminPasswordCommand struct {
ActorID UserID
TargetID UserID
Password string
IdempotencyKey string
}

type ResetAdminPasswordResult​

type ResetAdminPasswordResult struct {
OK bool
RequiresRelogin bool
Replayed bool
}

type ResetPlayerPasswordCommand​

type ResetPlayerPasswordCommand struct {
ActorID UserID
TargetID UserID
Password string
IdempotencyKey string
}

type ResetPlayerPasswordResult​

type ResetPlayerPasswordResult struct {
OK bool
Replayed bool
}

type SetPasswordCommand​

SetPasswordCommand sets a password for the authenticated user (the optional password fallback). No current password is required when the account's password was machine-generated at passwordless signup.

type SetPasswordCommand struct {
Password string
}

type SignupPreferencesCommand​

SignupPreferencesCommand atomically saves whichever optional fields were filled.

type SignupPreferencesCommand struct {
Username *string
Password *string
IdempotencyKey string
}

type SignupPreferencesResult​

type SignupPreferencesResult struct {
User CurrentUser
Replayed bool
}

type UpdateAdminCommand​

type UpdateAdminCommand struct {
ID UserID
Role *UserRole
Status *UserStatus
}

type UpdateProfileCommand​

UpdateProfileCommand is a partial update of the authenticated user's editable profile fields. Each field is optional; only fields with Set=true are applied. Email is intentionally absent — it is the login identity and changing it needs a separate verified email-change flow.

type UpdateProfileCommand struct {
DisplayName ProfileFieldUpdate
Phone ProfileFieldUpdate
Birthday ProfileFieldUpdate
Address ProfileFieldUpdate
}

type UserID​

type UserID string

type UserRole​

type UserRole string

func ParseUserRole​

func ParseUserRole(value string) (UserRole, bool)

func (UserRole) CanManageAdmins​

func (r UserRole) CanManageAdmins() bool

func (UserRole) HasPermission​

func (r UserRole) HasPermission(permission Permission) bool

func (UserRole) IsAdmin​

func (r UserRole) IsAdmin() bool

type UserStatus​

type UserStatus string
const (
UserStatusPendingEmailVerification UserStatus = "pending_email_verification"
UserStatusActive UserStatus = "active"
UserStatusSuspended UserStatus = "suspended"
UserStatusBanned UserStatus = "banned"
)

func ParseUserStatus​

func ParseUserStatus(value string) (UserStatus, bool)

type VerifyCodeCommand​

VerifyCodeCommand verifies the 6-digit code for an email's active challenge.

type VerifyCodeCommand struct {
Email string
Code string
}

type VerifyMagicLinkCommand​

VerifyMagicLinkCommand verifies a single-use magic-link token, independent of the device that requested it.

type VerifyMagicLinkCommand struct {
Token string
}

Generated by gomarkdoc