Password Plugin

The password plugin provides email/password authentication with a full account lifecycle: sign-up, sign-in, forgot password, reset password, change password, and email verification. It is the most commonly used plugin and is typically the first one added to any Authsome engine.

Setup

import (
    "github.com/xraph/authsome"
    "github.com/xraph/authsome/plugins/password"
)

eng, err := authsome.NewEngine(
    authsome.WithStore(store),
    authsome.WithPlugin(password.New()),
    authsome.WithConfig(authsome.Config{
        AppID: "myapp",
        Password: authsome.PasswordConfig{
            MinLength:        10,
            RequireUppercase: true,
            RequireLowercase: true,
            RequireDigit:     true,
            RequireSpecial:   false,
            Algorithm:        "bcrypt",
            BcryptCost:       12,
            CheckBreached:    true,
        },
    }),
)

The plugin constructor accepts optional per-plugin configuration:

password.New(password.Config{
    AllowedDomains: []string{"mycompany.com", "partner.com"},
})

Implemented interfaces

Sign-up flow

POST /v1/auth/signup

{
  "email": "alice@example.com",
  "password": "Secure!Pass99",
  "username": "alice",
  "name": "Alice Liddell",
  "app_id": "myapp"
}

The engine performs these checks before creating the user:

1. Validates the password against the policy (length, complexity)
2. Checks HaveIBeenPwned if CheckBreached: true
3. Validates email domain against AllowedDomains (if configured)
4. Verifies email uniqueness within the app
5. Hashes the password with the configured algorithm
6. Calls BeforeSignUp plugin hooks
7. Creates the user record and session

Sign-in flow

POST /v1/auth/signin

{
  "email": "alice@example.com",
  "password": "Secure!Pass99",
  "app_id": "myapp"
}

The engine checks in order: account lockout status, user existence, ban status, password verification, password expiry, and transparent rehash if the algorithm has changed.

Password hashing

bcrypt (default)

Password: authsome.PasswordConfig{
    Algorithm:  "bcrypt",
    BcryptCost: 12,
}

Each cost increment doubles computation time. A cost of 12 takes approximately 250ms on modern hardware.

argon2id

Password: authsome.PasswordConfig{
    Algorithm: "argon2id",
    Argon2: authsome.Argon2Config{
        Memory:      65536,
        Iterations:  3,
        Parallelism: 2,
        SaltLength:  16,
        KeyLength:   32,
    },
}

argon2id is memory-hard, making GPU brute-force attacks significantly more expensive.

Transparent algorithm migration

When you change Algorithm, existing users are migrated automatically on their next successful sign-in. The engine detects the old hash format and re-hashes with the new algorithm -- no migration scripts needed.

Password policies

Password: authsome.PasswordConfig{
    MinLength:        12,
    RequireUppercase: true,
    RequireLowercase: true,
    RequireDigit:     true,
    RequireSpecial:   true,
    CheckBreached:    true,
    HistoryCount:     5,
    MaxAgeDays:       90,
}

Password reset flow

Request reset: POST /v1/auth/forgot-password

{"email": "alice@example.com", "app_id": "myapp"}

The engine creates a reset token with 1-hour expiry. The response is always 200 OK regardless of whether the email exists, preventing email enumeration.

Confirm reset: POST /v1/auth/reset-password

{
  "token": "the-reset-token",
  "new_password": "NewSecure!Pass99"
}

The engine validates the token, enforces the password policy, updates the hash, consumes the token, and revokes all existing sessions.

Change password flow

POST /v1/auth/change-password

{
  "current_password": "Secure!Pass99",
  "new_password": "EvenBetter!Pass123"
}

Requires a valid session token in the Authorization: Bearer header.

API routes