README

Authentication, MFA & user management for the Univeros framework. One line in config/modules.php — a complete, production-grade identity stack.

Polaris is the official authentication & user-management module for Univeros / Altair applications. A host registers one class and the app gains email-verified login, JWT access tokens with rotating refresh tokens, multi-factor authentication (TOTP/QR, SMS, email), single-use recovery codes, multi-tenant organizations with role-based access control, and a hardened security posture — contributed as routes, Cycle entities, migrations, and middleware with no further host wiring.

The name is the idea: Polaris is the fixed star your application's identity navigates by.

Why Polaris

• 🔌 Drop-in. Implements the standard Univeros module contracts. Register it, run migrations, done — no per-module bootstrapping.
• 🔐 Secure by default. Argon2id passwords, asymmetric JWT signing, refresh tokens & OTP codes hashed at rest, rotation with theft detection, rate limiting, lockout, audit logging, and no user enumeration.
• 🏢 Multi-tenant. First-class organizations, memberships, and per-org roles — one user, many orgs, different permissions in each.
• 📱 MFA-first. TOTP authenticator apps (provisioned by QR), SMS OTP, and email OTP, plus recovery codes and step-up authentication for sensitive actions.
• 🧩 Framework-native. Builds on the existing Altair\Http auth contracts (TokenGeneratorInterface, IdentityProviderInterface, …) instead of inventing parallel machinery, and is operated entirely through bin/altair.
• 📦 Dependency-light & portable. SMS and email delivery are pluggable ports — no vendor SDK is baked into the core.

Features

Quick start

composer require univeros/polaris

// config/modules.php
return [
    new Univeros\Polaris\Module(),
];

Provide the secrets (env / secret manager):

export APP_KEY="…"                              # 32-byte base64
export AUTH_JWT_PRIVATE_KEY="$(cat private.pem)" # signs access tokens
export AUTH_JWT_PUBLIC_KEY="$(cat public.pem)"   # verification / JWKS

Apply the migrations and verify:

bin/altair db:migrate
bin/altair routes:list --format=json | grep auth
bin/altair doctor

That single registration contributes every /auth, /users, and /orgs route, the entities, the migrations, the auth/authorization middleware, and the container bindings. Bind production SMS/email providers in your host container when you're ready — Polaris ships dev (log) drivers so flows work out of the box.

How it works

Every endpoint follows the framework's Action → Input → Domain → Responder shape, and Polaris plugs into the framework's existing auth seams rather than replacing them:

HTTP edge   Action            thin route target — declares input/responder/domain + required permissions
            Input (readonly)  typed request DTO with validation rules()
            Responder         Payload → JSON / RFC 9457 Problem Details
Domain      *Service          business logic, transactional, emits PSR-14 events
            Contracts/*       ports: SmsSender, OtpMailer, PasswordHasher, Clock, …
Persistence Entity/* (Cycle)  UUID-v7 entities → host ORM schema
Security    token machinery   implements Altair\Http\Contracts\* (TokenFactory, IdentityProvider, …)

Login returns a short-lived JWT access token plus a rotating refresh token; presenting an already-rotated refresh token is treated as theft and revokes the entire token family.

API surface

A representative slice (full catalog in docs/auth/api-reference.md):

Versioning & mounting are the host's responsibility. Polaris contributes relative, unversioned routes; the host front controller mounts them under whatever scheme (e.g. a /v1 prefix) it uses for its own surface.

Endpoints are generated from YAML specs under api/ via bin/altair spec:scaffold.

Multi-factor authentication

Three factor types, one uniform verification flow:

• TOTP (authenticator app) — RFC 6238 via spomky-labs/otphp; enrolled by scanning a QR code (otpauth:// provisioning URI). Secrets are encrypted at rest.
• SMS OTP — 6-digit codes delivered through your SmsSenderInterface binding.
• Email OTP — 6-digit codes delivered through your OtpMailerInterface binding.
• Recovery codes — 10 single-use codes, hashed at rest.
• Step-up — sensitive operations (password change, removing a factor, deleting an org) require a recent strong authentication.

SMS and email delivery are provider-agnostic ports — bind Twilio, Vonage, SES, SMTP, or anything else; dev Log drivers ship in the box. Details in docs/auth/mfa-otp.md.

Multi-tenant RBAC

Identity is global; authority is scoped to an organization:

User ──< Membership >── Organization
              └──< roles >── permissions   (per-org; system roles when org is null)

Org creators become owner; admin/member templates are seeded per org and fully customizable. The access token carries the active org and resolved roles, so authorization is mostly stateless; an AuthorizationMiddleware enforces per-endpoint permissions and a Gate handles the rules permissions can't express (last-owner protection, role hierarchy). Cross-tenant access is denied by design. See docs/auth/rbac.md.

Security

Polaris follows established standards — JWT (RFC 7519), JWKS (RFC 7517), TOTP (RFC 6238), OAuth 2.0 refresh semantics + Security BCP (RFC 9700), Problem Details (RFC 9457), and OWASP ASVS for password storage. Secrets are never stored in plaintext (hashed or encrypted at rest), comparisons are constant-time, and signing keys are asymmetric with kid-based rotation. Full threat model in docs/auth/security.md.

Documentation

The complete, authoritative specification lives in docs/auth/:

Agent-oriented orientation is in AGENT.md.

Roadmap & status

Polaris is in active development, built in five phases tracked on GitHub:

Progress lives in the milestones and issues; each phase has an epic tracking issue.

Testing

composer install
vendor/bin/phpunit

The target is ≥ 80 % coverage with unit, integration, and E2E layers, with TOTP validated against RFC 6238 vectors and OTP channels exercised through in-memory senders. See docs/auth/testing.md.

Contributing

Issues and pull requests are welcome on github.com/univeros/polaris. Please read AGENT.md and the relevant spec doc first, follow the conventions (strict types, immutability, small files, tests-first), and run composer qa before opening a PR.

License

Proprietary. © Univeros. See composer.json.