Authentication System¶

This document describes the HoloMUSH authentication architecture for contributors.

Overview¶

HoloMUSH uses a three-layer authentication architecture:

flowchart TB
    subgraph Protocol["Protocol Layer"]
        GH[GatewayHandler]
        WH["WebHandler (future)"]
    end

    subgraph gRPC["gRPC Boundary"]
        CC[CoreClient]
    end

    subgraph Core["Core Server"]
        AS[AuthService]
        CS[CharacterService]
        PRS[PasswordResetService]
    end

    subgraph Repo["Repository Layer"]
        PR[PlayerRepository]
        WSR[WebSessionRepository]
        PRR[PasswordResetRepository]
    end

    GH --> CC
    WH --> CC
    CC --> AS
    CC --> CS
    AS --> PR
    AS --> WSR
    CS --> PR
    PRS --> PR
    PRS --> PRR

Service Responsibilities¶

AuthService¶

Handles core authentication operations.

CharacterService¶

Manages character creation with validation.

Character creation validates:

• Name format (2-32 chars, letters and spaces, normalized to Initial Caps)
• Name uniqueness (case-insensitive)
• Player character limit (default: 5)
• Starting location assignment

PasswordResetService¶

Handles password reset flow.

Security Implementation¶

Timing Attack Prevention¶

The auth service uses a dummy hash for non-existent users to prevent username enumeration:

Login(username, password):
  1. Look up user by username
  2. If not found -> use dummy hash (still verify to maintain constant time)
  3. Verify password against hash (real or dummy)
  4. Return same error for "user not found" and "wrong password"

See internal/auth/auth_service.go:67-76 for the dummy hash constant and internal/auth/auth_service.go:81-130 for the timing-safe implementation.

Password Hashing¶

Passwords are hashed using argon2id with OWASP-recommended parameters:

Implementation: internal/auth/hasher.go:30-36

Constant-Time Token Comparison¶

Session token verification uses crypto/subtle.ConstantTimeCompare to prevent timing attacks that could leak token prefixes.

See internal/auth/session.go:115-125 for the implementation with security comments.

Session Token Design¶

Sessions use opaque random tokens rather than signed JWTs. Key design choices:

See ADR 0001 for the rationale behind choosing opaque tokens over signed JWTs.

Authentication Flows¶

Telnet Flow¶

sequenceDiagram
    participant C as Client
    participant GH as GatewayHandler
    participant CC as CoreClient (gRPC)
    participant A as AuthService

    C->>GH: TCP connect
    GH->>C: Welcome banner

    C->>GH: connect <user> <pass>
    GH->>CC: AuthenticatePlayer(username, password)
    CC->>A: AuthenticatePlayer
    A->>CC: Session + Characters
    CC->>GH: Session + Characters
    GH->>C: Character list

    alt Has characters
        C->>GH: play <charname>
        GH->>CC: SelectCharacter(sessionID, charID)
        CC->>A: SelectCharacter
        GH->>C: Enter world
    else No characters
        C->>GH: create <name>
        GH->>CC: CreateCharacter(playerID, name)
        CC->>A: CreateCharacter
        GH->>C: Enter world
    end

Key Protocol Handler Methods¶

The telnet handler calls through the gRPC CoreClient interface, not service methods directly:

Repository Interfaces¶

PlayerRepository¶

internal/auth/player.go:128-151

Manages player account persistence including username lookups, email lookups, and password updates.

WebSessionRepository¶

internal/auth/session.go:127-156

Manages session persistence including token hash lookups, last-seen updates, character binding, and expiration cleanup.

PasswordResetRepository¶

internal/auth/reset.go

Manages reset token persistence with token hash lookups and player-based cleanup.

Related Documentation¶

• Design Spec - Full authentication design
• ADR 0001 - Token design decision
• Operator Guide - Deployment and configuration