# PhxAuthPlus

Complete authentication generator for Phoenix 1.8+, aligned with the
official `phx.gen.auth` templates from Phoenix 1.8.9.

Phoenix 1.8 replaced `mix phx.gen.auth` with a magic-link-only generator.
**PhxAuthPlus restores the full email + password experience** — registration,
password login, magic link login, password reset, account confirmation,
"remember me", and settings — while using modern Igniter-based code generation
and the Phoenix 1.8 scope system (`current_scope`).

## Installation

Add to your `mix.exs`:

```elixir
def deps do
  [
    {:phx_auth_plus, "~> 0.3.2", only: [:dev, :test]}
  ]
end
```

Then:

```bash
mix deps.get
mix phx_auth_plus.gen.auth Accounts User users
```

The generator adds the hashing library dependency, configures the test
environment, generates all auth files, and updates your layout and router.

## Quick start

```bash
# Generate auth (LiveView UI, bcrypt on Unix / pbkdf2 on Windows)
mix phx_auth_plus.gen.auth Accounts User users

# Then:
mix ecto.migrate
mix phx.server
```

Visit `http://localhost:4000/users/register`.

## Generated features

| Feature | Description |
|---------|-------------|
| Registration | Email + password signup with validation |
| Password login | Session-based with "remember me" cookie |
| Magic link login | Token-based passwordless login (Phoenix 1.8 style) |
| Password reset | Forgot password flow with email token |
| Account confirmation | Email verification with token |
| Settings | Change password and email (with confirmation) |
| Session tracking | All sessions stored in DB, invalidated on password change |
| Scope system | `current_scope` assign throughout LiveViews and plugs |
| Layout menu | Dynamic auth links in the app header (login/register, email/settings/logout) |
| Auth tests | Generated test suite for UserAuth plug and hooks |

## Usage

```bash
# Default: LiveView UI, bcrypt on Unix / pbkdf2 on Windows
mix phx_auth_plus.gen.auth Accounts User users

# Controller-only UI (no LiveView)
mix phx_auth_plus.gen.auth Accounts User users --no-live

# Use argon2 hashing
mix phx_auth_plus.gen.auth Accounts User users --hashing-lib argon2

# Use binary UUID keys
mix phx_auth_plus.gen.auth Accounts User users --binary-id

# Custom table name
mix phx_auth_plus.gen.auth Accounts User users --table app_users

# Custom web module
mix phx_auth_plus.gen.auth Accounts User users --web MyAppWeb
```

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `--hashing-lib` | bcrypt (Unix) / pbkdf2 (Windows) | Password hashing library |
| `--live` | true | Generate LiveView auth pages |
| `--no-live` | — | Generate controller-based auth pages |
| `--binary-id` | false | Use binary UUID primary keys |
| `--web` | MyAppWeb | Web module name |
| `--context-app` | app name | Context app (umbrella projects) |
| `--table` | plural arg | Database table name |

## Generated files

```
lib/my_app/
├── user.ex              # User schema with changesets
├── user_token.ex        # Token schema (session, magic link, reset, confirm, change email)
├── user_notifier.ex     # Email notification delivery (Swoosh)
├── accounts.ex          # Accounts context with full auth functions
└── scope.ex             # Scope struct for current user

lib/my_app_web/
├── user_auth.ex         # Auth plug + LiveView on_mount hooks
├── user_session_controller.ex  # Session controller (login, logout, update_password)
│
# With --live (default):
├── user_login_live.ex          # Login page (password + magic link)
├── user_registration_live.ex   # Registration page
├── user_settings_live.ex       # Settings page (email + password)
├── user_confirmation_live.ex   # Magic link / confirmation page
├── user_forgot_password_live.ex  # Forgot password page (request reset email)
└── user_reset_password_live.ex   # Reset password page (enter new password)

priv/repo/migrations/
└── *_create_users_auth_tables.exs

test/
├── support/accounts_fixtures.ex    # Test fixtures
└── my_app_web/user_auth_test.exs   # UserAuth tests
```

## Routes

| Path | Method | Description |
|------|--------|-------------|
| `/users/register` | LiveView | Registration |
| `/users/log-in` | LiveView / POST | Login (password or magic link) |
| `/users/log-in/:token` | LiveView | Magic link login / account confirmation |
| `/users/log-out` | DELETE | Logout |
| `/users/forgot-password` | LiveView | Request password reset email |
| `/users/reset-password/:token` | LiveView | Reset password with token |
| `/users/settings` | LiveView | Settings (auth required) |
| `/users/settings/confirm-email/:token` | LiveView | Confirm email change |
| `/users/update-password` | POST | Update password from settings |

## Token validity

| Token type | Context | Validity |
|------------|---------|----------|
| Session | `session` | 14 days |
| Magic link | `login` | 15 minutes |
| Reset password | `reset_password` | 1 day |
| Confirm account | `confirm` | 7 days |
| Change email | `change:{old_email}` | 7 days |

## Email delivery

The generated `UserNotifier` uses Swoosh to build emails. In development,
the local adapter captures emails at `/dev/mailbox`.

To send real emails, configure a Swoosh adapter in `config/runtime.exs`.
See the [GUIDE](GUIDE.md#configuring-the-mailer) for details.

## Customization

See the [GUIDE.md](GUIDE.md) for:

- Adding custom fields to User
- Role-based authorization
- Configuring the mailer for production
- Changing password requirements
- Disabling account confirmation
- Using API tokens
- Umbrella project support

## vs Phoenix 1.8 built-in auth

| Feature | Phoenix 1.8 | PhxAuthPlus |
|---------|-------------|-------------|
| Email + password | Not included | Full support |
| Magic link login | Included | Included |
| Password reset | Not included | Token-based reset |
| Account confirmation | Not included | Email confirmation |
| "Remember me" | Not included | Secure cookies |
| Settings page | Not included | Change email + password |
| Session tracking | Not included | DB-tracked sessions |
| Scope system | `current_scope` | `current_scope` |
| Layout menu | Not included | Dynamic auth links in header |
| Code generation | Manual | Igniter-based (AST) |

## License

MIT