Sigra

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.update the 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.

---

Pick your lane

You are…	Do this first
Evaluating	Run scripts/uat/up.sh — one command boots the seeded Vaultr demo behind Traefik and auto-opens it (no second terminal). See the Demo Showcase for the guided walkthrough, then open HexDocs for API depth.
Greenfield Phoenix app	Read Installation, then follow Getting started for first-run auth flows.
Existing Sigra app / upgrade	Follow Upgrading to v1.0 for the operational preflight, generated-host review, and rollback path.
Migrating from another auth stack	Use Migrating from phx.gen.auth and Migrating from Pow, Guardian, and Ueberauth to choose the right cutover lane.
Advanced control	Use the Sigra 1.0 contract, Generator and install options, Deployment, and Troubleshooting install.

Before production

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).

---

Where code lives

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

Loading

• Left: ships on Hex; security fixes ride mix deps.update.
• Right: plain Elixir under lib/my_app/ and lib/my_app_web/ — code review and product iteration happen there.

---

First integration

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

Loading

1. Dependency (mix.exs):

   {:sigra, "~> 1.0"}

   This is the selected 1.0 contract line. If Hex package metadata advertises a newer installable line, treat Hex as the current package truth and use the version constraint appropriate for your target. For version, stack, ownership, and non-goal boundaries, read the Sigra 1.0 contract.

2. Scaffold (from app root; names must match your domain):

   mix deps.get
   mix sigra.install Accounts User users

3. 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.

---

Prerequisites

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.

---

Installer at a glance

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

---

What ships in the box

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.
Email	Registration, confirmation (link + code), magic link, reset, lifecycle mailers — Swoosh-shaped templates in the host.
Branding	Generated auth forms and emails ship with Light/Dark/System styling, config/admin brand tokens, and host-owned full-control templates.
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 map → guides

Topic	Guide
Installation & env	introduction/installation.md
First happy path	introduction/getting-started.md
Companion library suite	introduction/suite-integration.md
Upgrade notes	pre-1.0 -> v1.0 · v1.0 → v1.1 · toward v1.7 · toward v1.8
Migration lanes	from phx.gen.auth · from Pow/Guardian/Ueberauth
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
Auth branding	recipes/auth-branding.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

---

Security posture (headlines)

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, SECURITY.md, and the Sigra 1.0 contract for the full invariants and non-goals — the README stays a map, not a spec.

Release evidence (maintainers and auditors)

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.

• Sigra Hex 1.0.0 launch announcement — canonical launch narrative, audience guidance, proof links, and first-14-day triage pointer.
• Sigra alternatives comparison — boundary-first comparison against phx.gen.auth, Pow/Guardian/Ueberauth-style composition, hosted auth, and Sigra's hybrid model.
• Sigra launch evidence bundle — attachable release proof router with post-publish placeholders and proof boundaries.
• GA evidence and audit posture — router page; same content ships on HexDocs.
• UAT versus CI coverage — machine versus human boundaries.

Coordinated disclosure: SECURITY.md.

---

Reference host: test/example

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.

---

Contributing & issues

• Workflow & CI — CONTRIBUTING.md (Playwright artifacts, installer audit jobs, Pages mirror).
• Local parity — CLAUDE.md on GitHub (Postgres one-liner, mix test expectations).
• Bugs & ideas — GitHub Issues.

---

License

MIT — see LICENSE.