phx_auth_plus

# PhxAuthPlus


Complete email + password authentication generator for Phoenix 1.8+.

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

## Installation


Add to your `mix.exs`:

```elixir

def deps do

  [

    {:phx_auth_plus, "~> 0.1", 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 |
| Login / Logout | Session-based with "remember me" cookie |
| 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 |
| 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/accounts/

├── user.ex              # User schema with changesets

├── user_token.ex        # Token schema (session, reset, confirm, change email)

└── user_notifier.ex     # Email notification delivery (Swoosh)



lib/my_app_web/

├── user_auth.ex         # Auth plug + LiveView hooks



# With --live (default):

└── user_*_live.ex       # Login, registration, settings, forgot/reset, confirmation



# With --no-live:

└── controllers/

    └── user_*_controller.ex



priv/repo/migrations/

└── *_create_users_auth_tables.exs



test/

├── support/accounts_fixtures.ex    # Test fixtures

└── *_user_auth_test.exs            # UserAuth tests

```


## Routes


| Path | Method | Description |
|------|--------|-------------|
| `/users/register` | GET/POST | Registration |
| `/users/log_in` | GET/POST | Login |
| `/users/log_out` | DELETE | Logout |
| `/users/reset_password` | GET/POST | Request password reset |
| `/users/reset_password/:token` | GET/PUT | Reset password with token |
| `/users/confirm` | GET/POST | Resend confirmation |
| `/users/confirm/:token` | GET | Confirm account |
| `/users/settings` | GET/PUT | Settings (auth required) |
| `/users/settings/confirm_email/:token` | GET | Confirm email change |

## Token validity


| Token type | Context | Validity |
|------------|---------|----------|
| Session | `session` | 60 days |
| 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 | Magic links only | Full support |
| Password reset | Magic links only | 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 |
| Code generation | Manual | Igniter-based (AST) |

## Roadmap


### v0.2.0 (planned)

- Generated LiveView tests (registration, login, settings flows)
- `--no-confirm` flag to skip account confirmation

### v0.3.0 (planned)

- OAuth 2.0 provider support (Google, GitHub)
- API token authentication

### v1.0.0 (future)

- Two-factor authentication (TOTP)
- Session management UI (view/revoke active sessions)

## License


MIT