PHPackages univeros/polaris - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. univeros/polaris ActiveLibrary[Authentication & Authorization](/categories/authentication) univeros/polaris ================ Authentication, MFA/OTP, and user & organization management for Univeros apps. v1.0.0(1mo ago)197↓30%proprietaryPHPPHP >=8.3CI passing Since Jun 11Pushed 1mo agoCompare [ Source](https://github.com/univeros/polaris)[ Packagist](https://packagist.org/packages/univeros/polaris)[ Docs](https://univeros.io)[ RSS](/packages/univeros-polaris/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (12)Versions (2)Used By (0) Polaris ======= [](#polaris) > **Authentication, MFA & user management for the [Univeros](https://univeros.io) framework.**One line in `config/modules.php` — a complete, production-grade identity stack. [![PHP](https://camo.githubusercontent.com/38027453aeb7eb818641c9de8f82b7624c3558d92634f1946edc715c3ddf8956/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332532422d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/38027453aeb7eb818641c9de8f82b7624c3558d92634f1946edc715c3ddf8956/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332532422d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)[![Univeros module](https://camo.githubusercontent.com/818cd9c459c030f12c0ac46240963a3d3fa90b7f1a154bfc9dcc3d9d060a69c4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f556e697665726f732d6d6f64756c652d316437366462)](https://camo.githubusercontent.com/818cd9c459c030f12c0ac46240963a3d3fa90b7f1a154bfc9dcc3d9d060a69c4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f556e697665726f732d6d6f64756c652d316437366462)[![Multi-tenant](https://camo.githubusercontent.com/a24ff4aa5cb88ca78d31bf129254df6b91778022f81d2ed2d78166cabfa3cf45/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6d756c74692d2d74656e616e742d524241432d303035326363)](https://camo.githubusercontent.com/a24ff4aa5cb88ca78d31bf129254df6b91778022f81d2ed2d78166cabfa3cf45/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6d756c74692d2d74656e616e742d524241432d303035326363)[![MFA](https://camo.githubusercontent.com/98f4ffdedd37c10ba38250905ec375daba5c3713c96d537ebcf57299e025f493/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d46412d544f5450253230254332254237253230534d53253230254332254237253230656d61696c2d643933663062)](https://camo.githubusercontent.com/98f4ffdedd37c10ba38250905ec375daba5c3713c96d537ebcf57299e025f493/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d46412d544f5450253230254332254237253230534d53253230254332254237253230656d61696c2d643933663062)[![Status](https://camo.githubusercontent.com/a4a1fe38faaaea5c5ebf195ca43fbd4502108e9cfa9186b04a3a9a45b3f4e912/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d696e253230646576656c6f706d656e742d6f72616e6765)](https://camo.githubusercontent.com/a4a1fe38faaaea5c5ebf195ca43fbd4502108e9cfa9186b04a3a9a45b3f4e912/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d696e253230646576656c6f706d656e742d6f72616e6765) 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 ----------- [](#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 -------- [](#features) AreaWhat you get**Authentication**Register, email verification, password login, `/auth/me`, logout / logout-all**Tokens**Asymmetric JWT access tokens (RS256/EdDSA) + opaque **rotating refresh tokens** with reuse detection; JWKS endpoint**Sessions**Per-device session list, individual + global revocation**MFA / OTP****TOTP (QR)**, **SMS OTP**, **email OTP**, recovery codes, login-MFA gate, step-up**Passwords**Argon2id, policy enforcement, breached-password hook, reset & change (logout-everywhere)**Multi-tenant RBAC**Organizations, memberships, roles, permissions, invitations, org switching**Authorization**Declarative permission guard middleware + a programmatic `Gate` with policies**Security**Rate limiting, account lockout, anti-enumeration, audit log, key rotation**Ops**PSR-14 domain events, notification fan-out, transient-row pruning, observability--- Quick start ----------- [](#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 ------------ [](#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 ----------- [](#api-surface) A representative slice (full catalog in [`docs/auth/api-reference.md`](docs/auth/api-reference.md)): MethodPathPurpose`POST``/auth/register`Create account, send verification`POST``/auth/login`Password login → tokens **or** MFA challenge`POST``/auth/token/refresh`Rotate refresh → new access + refresh`POST``/auth/mfa/totp/enroll`Start TOTP enrollment → secret + QR`POST``/auth/mfa/verify`Complete MFA → tokens`GET``/auth/sessions`List active devices/sessions`POST``/orgs`Create an organization (creator → owner)`POST``/orgs/{id}/invites`Invite a member`POST``/auth/switch-org`Switch active org → re-scoped token> **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/`](api/) via `bin/altair spec:scaffold`. --- Multi-factor authentication --------------------------- [](#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`](docs/auth/mfa-otp.md). --- Multi-tenant RBAC ----------------- [](#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`](docs/auth/rbac.md). --- Security -------- [](#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`](docs/auth/security.md). --- Documentation ------------- [](#documentation) The complete, authoritative specification lives in [`docs/auth/`](docs/auth/): DocContents[README](docs/auth/README.md)Overview, goals, framework integration[data-model](docs/auth/data-model.md)Entities, tables, relationships, migrations[flows](docs/auth/flows.md)Register, login, refresh rotation, sessions, password[mfa-otp](docs/auth/mfa-otp.md)TOTP/QR, SMS, email, recovery, step-up[rbac](docs/auth/rbac.md)Orgs, memberships, roles, permissions, guard[api-reference](docs/auth/api-reference.md)Full endpoint catalog + error format[security](docs/auth/security.md)Threat model, crypto, key management[configuration](docs/auth/configuration.md)Config schema, env, bindings, deps[events](docs/auth/events.md)PSR-14 domain events[testing](docs/auth/testing.md)Test strategy + acceptance criteria[implementation-plan](docs/auth/implementation-plan.md)Phased build orderAgent-oriented orientation is in [`AGENT.md`](AGENT.md). --- Roadmap & status -------------------- [](#roadmap--status) Polaris is in **active development**, built in five phases tracked on GitHub: PhaseMilestone**0 — Foundation**identity, config/secrets, deps, CI**1 — Identity core**register, login, JWT + rotating refresh, sessions**2 — MFA & OTP**TOTP/QR, SMS, email, recovery, step-up**3 — Multi-tenant RBAC**orgs, roles, permissions, invitations**4 — Hardening & ops**audit, observability, key rotation, sign-offProgress lives in the [milestones](https://github.com/univeros/polaris/milestones)and [issues](https://github.com/univeros/polaris/issues); each phase has an `epic`tracking issue. --- Testing ------- [](#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`](docs/auth/testing.md). --- Contributing ------------ [](#contributing) Issues and pull requests are welcome on [github.com/univeros/polaris](https://github.com/univeros/polaris). Please read [`AGENT.md`](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 ------- [](#license) Proprietary. © Univeros. See `composer.json`. ### Health Score 42 — FairBetter than 88% of packages Maintenance90 Actively maintained with recent releases Popularity15 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 46d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/566016?v=4)[Antonio Ramirez](/maintainers/tonydspaniard)[@tonydspaniard](https://github.com/tonydspaniard) --- Top Contributors [![tonydspaniard](https://avatars.githubusercontent.com/u/566016?v=4)](https://github.com/tonydspaniard "tonydspaniard (48 commits)") --- Tags jwtotptotpAuthenticationrbacUsersMFAuniverosaltair ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/univeros-polaris/health.svg) ``` [![Health](https://phpackages.com/badges/univeros-polaris/health.svg)](https://phpackages.com/packages/univeros-polaris) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k34.4k16](/packages/tempest-framework)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 85036.3k](/packages/flow-php-flow)[scheb/2fa-totp Extends scheb/2fa-bundle with two-factor authentication using TOTP 293.3M52](/packages/scheb-2fa-totp)[n1ebieski/ksef-php-client PHP API client that allows you to interact with the API Krajowego Systemu e-Faktur 9067.8k](/packages/n1ebieski-ksef-php-client)[open-dxp/opendxp Content & Product Management Framework (CMS/PIM) 9421.6k64](/packages/open-dxp-opendxp)[rcsofttech/audit-trail-bundle Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking. 1189.8k](/packages/rcsofttech-audit-trail-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)