Production-minded authentication for Phoenix 1.8+ — sessions, passwords, email flows, OAuth, MFA, passkeys, optional organizations and admin tooling — without treating security-sensitive code as throwaway scaffolding.
TL;DR
- Problem: Pow does not support Phoenix 1.8+. Rolling your own auth across crypto, sessions, MFA, and OAuth is slow and risky.
- What Sigra is: A library of hardened primitives plus generators that emit normal Phoenix modules into your repo — you patch UX and policy; you
mix deps.updatethe sensitive core. - When to leave: You want a hosted identity product (Auth0-as-app) or a framework that hides all auth code from the repo entirely — different tradeoffs.
| You are… | Do this first |
|---|---|
| Evaluating | Skim Where code lives (diagram), What ships, then open HexDocs for API depth. |
| Integrating | Run First integration (diagram + commands), read Prerequisites, then follow Installation and Getting started. |
| Contributing | Match toolchain pins in .tool-versions, run Postgres-backed tests per CLAUDE.md in the repo, read CONTRIBUTING.md; use the reference example app as the integration host. |
| Maintaining / releasing | See MAINTAINING.md for version bumps, Hex and GitHub releases, and planning hygiene for maintainers. |
Public HTTPS hosts need aligned origins, proxy-forwarded TLS, session cookies, and a deliberate mail-delivery posture before you take real traffic. Treat the deployment recipe as the single checklist hub — skim it once per environment.
- Production checklist (read first) — scheme, cookies, LiveView origins, staging parity.
- Mail: inline vs Oban (TL;DR) — when background delivery is worth the operational cost.
Milestone planning (maintainers): Product north star and scope boundaries for GSD live in .planning/PROJECT.md under North Star (milestones) (with Core Value and Out of Scope).
flowchart LR
subgraph SigraPkg [Sigra_hex_package]
directionTB
LibCore[Crypto_tokens_MFA_OAuth_plugs]
LibBehaviours[Behaviours_and_options]
end
subgraph HostRepo [Your_application]
directionTB
GenCtx[Generated_contexts_schemas]
GenWeb[Generated_routes_LiveViews]
end
SigraPkg -->|"call_into_Sigra"| GenCtx
SigraPkg -->|"call_into_Sigra"| GenWeb
GenWeb -->|"you_edit_copy_and_policy"| GenWeb
- Left: ships on Hex; security fixes ride
mix deps.update. - Right: plain Elixir under
lib/my_app/andlib/my_app_web/— code review and product iteration happen there.
flowchart TD
A[mix_deps_get]
B["mix_sigra_install_Context_Schema_table"]
C[mix_ecto_migrate]
D[mix_phx_server]
A --> B --> C --> D
-
Dependency (
mix.exs):{:sigra, "~> 0.2"}
-
Scaffold (from app root; names must match your domain):
mix deps.get mix sigra.install Accounts User users
-
Database + run:
mix ecto.migrate mix phx.server
Branching installer flags (--no-live, --admin, --api, …) are summarized below; every switch and default is documented in source (lib/mix/tasks/) and, when published, on HexDocs alongside the API reference.
| Requirement | Notes |
|---|---|
| Elixir | ~> 1.18 (see mix.exs); align local toolchains with .tool-versions on GitHub. |
| Phoenix | 1.8.x baseline the library targets. |
| Database | Ecto + typical Postgres setup for the happy path; other adapters are handled in generated migrations where applicable. |
| Mailer | Email flows expect Swoosh (or compatible) wiring — see Installation. |
| Intent | Example flags | Read more |
|---|---|---|
| Controllers only (no LiveView UI) | --no-live |
mix sigra.install source, HexDocs |
| API / JWT surface | --api, or --jwt (implies API pieces) |
API authentication, sigra.install source |
| Admin LiveView suite | default on; --no-admin to omit |
sigra.install source |
| Passkeys | default on; --no-passkeys to omit |
Passkeys recipe |
| Organizations | default on; --no-organizations to omit |
Multi-tenant recipe |
| UUID primary keys | default on; --no-binary-id for bigint IDs |
sigra.install source |
| OAuth slice only (existing install) | mix sigra.gen.oauth … |
OAuth flow, sigra.gen.oauth source |
One clause each — depth lives in HexDocs and the guides linked in the next section.
| Area | You get |
|---|---|
| Identity | Argon2id passwords, optional bcrypt → Argon2id upgrade on login, remember-me, sudo / step-up hooks. |
| Sessions | Database-backed sessions, device/IP metadata hooks, revocation patterns the generators wire up. |
| Registration, confirmation (link + code), magic link, reset, lifecycle mailers — Swoosh-shaped templates in the host. | |
| MFA | TOTP (NimbleTOTP), backup codes, lockout-aware verification; trust-this-device patterns in the example app. |
| OAuth | Assent-backed strategies, encrypted token fields when Cloak is in play; optional mix sigra.gen.oauth for incremental adoption. |
| Passkeys | WebAuthn via wax_ when enabled — registration + authentication ceremonies with host-owned credential rows. |
| Organizations | Logical multi-tenancy (memberships, invitations, scoped plugs) when enabled — not “separate DB per tenant”. |
| Admin | Optional installer-generated admin LiveView (global + org lenses), impersonation guardrails, audit surfaces when enabled. |
| Audit | Structured audit logging hooks feeding explorer/export flows where the installer emitted them. |
| Topic | Guide |
|---|---|
| Installation & env | introduction/installation.md |
| First happy path | introduction/getting-started.md |
| Upgrade notes | v1.0 → v1.1 · toward v1.7 · toward v1.8 |
| Registration | flows/registration.md |
| Login / logout | flows/login-and-logout.md |
| Password reset | flows/password-reset.md |
| Account lifecycle | flows/account-lifecycle.md |
| OAuth | flows/oauth.md |
| MFA | flows/mfa.md |
| API / JWT | flows/api-authentication.md |
| Audit logging | flows/audit-logging.md, audit semantics |
| Deployment | recipes/deployment.md |
| Testing | recipes/testing.md |
| Passkeys | recipes/passkeys.md |
| Multi-tenant patterns | recipes/multi-tenant.md |
| Custom user fields | recipes/custom-user-fields.md |
| Subdomain auth | recipes/subdomain-auth.md |
| Topic | Default stance |
|---|---|
| Passwords | Argon2id via configured hasher; bcrypt verify-and-upgrade path when enabled. |
| Tokens | HMAC-protected, time-bounded patterns for magic links, reset, confirmation — stored references, not “guessable IDs only”. |
| Enumeration | Safer defaults on account discovery flows (details in HexDocs per flow). |
| Step-up | Sudo / MFA challenge patterns integrate with Phoenix plugs and LiveView mounts as generated. |
For threat-model detail and per-flow guarantees, use HexDocs and the guides above — the README stays a map, not a spec.
Sigra keeps an evidence hub (what we ran versus waived for GA cuts, how CI maps to human UAT rows, and pointers to planning artifacts on GitHub). That material is not a compliance certificate for your application — integration and deployment risk stay with the host.
- GA evidence and audit posture — router page; same content ships on HexDocs.
- UAT versus CI coverage — machine versus human boundaries.
Coordinated disclosure: SECURITY.md.
The test/example tree is a real Phoenix app living inside this repo: it tracks what mix sigra.install (and friends) emit, compiles under --warnings-as-errors in CI, and backs Playwright browser smoke (golden path, org flows, admin checkpoints, GA shift-left specs). It is not a second product — it is the executable contract that installer drift tests and reviewer artifacts refer to. When in doubt about “what does the generator actually produce?”, read that tree or the HexDocs task reference.
- Workflow & CI —
CONTRIBUTING.md(Playwright artifacts, installer audit jobs, Pages mirror). - Local parity —
CLAUDE.mdon GitHub (Postgres one-liner,mix testexpectations). - Bugs & ideas — GitHub Issues.
MIT — see LICENSE.