DEV Community: 2am.tech

Meet Polaris: A Complete PHP Identity Stack in One Line of Config (Part 1)

Antonio Ramirez Cobos — Wed, 05 Aug 2026 14:25:37 +0000

This blog post series picks up where I left off in how AI agents revived my old PHP framework project.

In my previous post, I wrote about how a swarm of AI agents helped me revive a PHP framework I had abandoned years ago. That post was the origin story. This little series is the first real proof that the revival was worth it.

Because a framework on its own is just plumbing. What I really wanted to know was simpler and scarier: could I build a serious, production-grade feature on top of it without hating my life? Not another to-do list demo. The thing every app needs, nobody enjoys writing, and that ruins your week when you get it wrong.

Authentication.

So I built Polaris. It is the official identity module for Univeros, and this post is the tour. The four how-tos that follow get hands-on with each piece. Here I just want to show you the shape of the thing and why it is built the way it is.

I named it Polaris on purpose. Polaris is the fixed star sailors navigated by, and identity plays the same role in an application. Everything else eventually comes back to "Who is this, and what are they allowed to do?"

The Thirty-Second Version

Install it:

composer require univeros/polaris

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

Give it the secrets it needs (from your environment or a secret manager, never from a file in the repo):

export APP_KEY="…"                                # 32-byte base64, seeds the peppers + encrypter
export AUTH_JWT_PRIVATE_KEY="$(cat private.pem)"  # signs access tokens
export AUTH_JWT_PUBLIC_KEY="$(cat public.pem)"    # verification + the JWKS endpoint

Run the migrations and confirm it is alive:

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

That is it. That single new Module() contributes every /auth, /users, and /orgs route, the Cycle ORM entities, the migrations, the authentication and authorization middleware, and the container bindings. Fifty-two endpoints, wired and ready, with zero per-module bootstrapping on your side.

Why a Module, and Why “Drop-In” Is More than a Buzzword

Here is something I learned the hard way over the years. Most auth code doesn’t die because the crypto is wrong, but because it is welded to the app that hosts it. You write a beautiful login flow for project A, then project B comes along and you spend two days surgically extracting it. By the time you’re done you’ve introduced three new bugs.

Univeros has a module contract system, and Polaris leans on it completely. A module declares what it provides (routes, entities, migrations, middleware, container bindings) and the host wires it all in automatically. There is no "now go register these fifteen services" step:

final class Module implements
    ModuleInterface,
    RoutesProviderInterface,
    MiddlewareProviderInterface,
    EntityDirectoriesProviderInterface,
    MigrationDirectoriesProviderInterface
{
    public function name(): string
    {
        return 'univeros/polaris';
    }

    public function apply(Container $container): void
    {
        $authConfig = AuthConfig::fromArray($this->authConfigArray());
        $secrets = Secrets::fromEnvironment($this->environment());

        $container->instance(AuthConfig::class, $authConfig);
        $container->instance(Secrets::class, $secrets);

        (new IdentityBindings())->apply($container);
        (new TokenBindings())->apply($container, $authConfig, $secrets);
        (new SessionBindings())->apply($container);
        (new HttpBindings())->apply($container);
        (new MfaBindings())->apply($container, $authConfig, $secrets);
        (new OrganizationBindings())->apply($container);
    }
}

Notice that apply() builds the config and secrets eagerly. That is deliberate. Forget to set AUTH_JWT_PRIVATE_KEY, and the app does not boot with a quietly insecure fallback and bite you in production three weeks later. It fails immediately, with a clear message. Fail loud. Fail early.

The Shape of Every Endpoint

Before diving into the how-tos, there’s one pattern worth knowing. Once you see it, the rest of the module reads the same way. Univeros uses an Action, Input, Domain, Responder shape (it is basically Action-Domain-Responder with a typed input DTO in front). Every endpoint is the same quad:

HTTP edge   Action            thin route target: declares input, responder, domain, required permissions
            Input (readonly)  a typed request DTO with validation rules()
            Responder         turns a Payload into JSON or an RFC 9457 Problem Details body
Domain      *Service          the business logic: transactional, emits PSR-14 events
            Contracts/*       ports: SmsSender, OtpMailer, PasswordHasher, Clock, and friends
Persistence Entity/* (Cycle)  UUID-v7 entities mapped into the host ORM schema
Security    token machinery   implements the framework's Altair\Http auth contracts

The domains stay thin. They validate the edge, call a service, and translate outcomes into HTTP. All the real work (hashing, lockout, token minting, event dispatch) lives in the services. That separation keeps the codebase from rotting, and it is why each how-to in this series can show you a real, unedited domain class that still fits on a single screen.

What You Actually Get

Authentication: Register, email verification, password login, /auth/me, logout / logout-all (Part 2, coming soon)
Tokens: Asymmetric JWT access tokens (RS256/EdDSA) plus opaque rotating refresh tokens with reuse detection; a JWKS endpoint (Part 2, coming soon)
Sessions: Per-device session list, individual and global revocation (Part 2, coming soon)
MFA / OTP: TOTP (QR), SMS OTP, email OTP, recovery codes, the login-MFA gate, step-up (Part 3, coming soon)
Passwords: Argon2id, policy enforcement, breached-password hook, reset and change (Part 2, coming soon)
Multi-tenant RBAC: Organizations, memberships, roles, permissions, invitations, org switching (Part 4, coming soon)
Authorization: Declarative permission guard middleware plus a programmatic Gate (Part 4, coming soon)
Providers & events: Pluggable SMS/email/breach ports, PSR-14 domain events (Part 5, coming soon)

Security Posture, Stated Plainly

I am not going to wave my hands and say "secure by design." Here is what that phrase actually cashes out to:

Passwords hashed with Argon2id, transparently rehashed when parameters change, with timing-equalized verification.
Access tokens signed with asymmetric keys (RS256 or EdDSA) with kid-based rotation. Resource servers verify with the public key alone.
Refresh tokens, OTP codes, recovery codes, verification tokens, and reset tokens are never stored in plaintext. They are hashed or kept as keyed HMACs.
Rotating refresh tokens with family-based reuse detection.
Rate limiting on every sensitive endpoint, sliding-window account lockout, and anti-enumeration on register, resend, and forgot-password.
An audit log fed by the event stream.

The standards it follows are the boring, correct ones: JWT (RFC 7519), JWKS (RFC 7517), TOTP (RFC 6238), OAuth 2.0 refresh semantics and the Security BCP (RFC 9700), Problem Details (RFC 9457), and OWASP ASVS for password storage. The full threat model lives in the reference docs.

So, Did the Framework Hold Up?

That was the whole point of this exercise. Part one of the Univeros series asked whether AI agents could resurrect a dead PHP framework. This series is the honest test: could I build something genuinely hard on top of it?

I think the answer is yes, and the evidence is in the shape of the code. Polaris is fifty-two endpoints, full MFA, multi-tenant RBAC, rotating tokens with theft detection, and an audit trail, and yet every endpoint is the same readable quad. The framework's module system meant the whole thing installs in one line.

The agents helped a lot with the grind: the RFC 6238 test vectors, functional tests for fifty-two endpoints, keeping the docs in sync with code. But the design decisions (authority comes from the database, not the token; last-owner protection; fail-open breach checks) came from years of getting auth wrong and remembering the scars. The agents are fast hands. The judgment is still mine.

Where to Go Next

Pick the piece you need:

Part 2: Logins that do not leak covers register, email verification, password login, JWT access tokens, and rotating refresh tokens with reuse detection. (coming soon)
Part 3: Real MFA in an afternoon covers TOTP/QR, SMS, email, recovery codes, the login gate, and step-up. (coming soon)
Part 4: One user, many orgs covers organizations, roles, permissions, the Gate, and the tenant invariants. (coming soon)
Part 5: Bring your own providers and events covers the SMS/email/breach ports and the PSR-14 event stream. (coming soon)

The reference docs live at polaris.univeros.io. The framework is at univeros.io. The source is on GitHub.

composer require univeros/polaris

One line. A whole identity stack. The fixed star your app navigates by. See you in part 2.

HAI: How to Get Your Team to Work Best with AI

Aleksandar Panic — Wed, 05 Aug 2026 14:17:05 +0000

Your team is already using AI to write code. The problem is that everyone is doing it differently. One developer is in Claude Code, another in Copilot, someone on the new team swears by Cursor, and there is always one person on Codex. Each of them has set up their assistant by hand, with their own prompts, their own half-remembered configuration, and no shared idea of how the AI should approach a ticket.

So the result is inconsistent, the knowledge lives in people's heads, and none of the assistants can actually see the Jira ticket or the Confluence spec the work is based on. You end up pasting context into a chat window, over and over, for every assistant on the team.

Helper AI (HAI) is a free, open-source npm CLI that gives your whole team one shared AI workflow, whatever editor each member happens to use. It sets up Claude Code, Copilot, Cursor, and Codex the same way, with the same subagents and the same slash-commands, then pulls your Jira tickets and Confluence specs into plain Markdown the AI can actually read.

Everyone keeps their editor. Everyone gets the same setup. And every assistant on the team can finally reach the tickets and specs the work depends on.

The Same Setup, Wherever Your Developers Work

Four developers on four different editors should not mean four different AI workflows, four different sets of prompts, and four different results on the same kind of task.

HAI installs into each environment where that environment expects to find things. Claude Code gets its config in .mcp.json, Copilot in .vscode/mcp.json, Cursor in .cursor/mcp.json, and Codex in .codex/config.toml. There is an "Any editor" mode too, which lays everything out under .ai/ for manual wiring. Whichever one a developer runs, they get the same MCP server, the same seven subagents, and the same six commands. The team matches without anyone agreeing on an editor first.

Your Tickets and Specs, as Readable Markdown

A lot of the context an AI needs to do a task well does not live in the codebase. The reasoning is in a ticket. The acceptance criteria are in a spec. The screenshot showing the bug is an authenticated attachment nobody can fetch without credentials.

HAI closes that gap. Jira issues and Confluence pages land in a local .ai/ directory as plain Markdown, with comments, links, custom fields, and the page tree kept intact. Because it is Markdown on disk, your assistant reads it the same way it reads your source. It is all git-ignored by default, with no database and nothing proprietary, so switching ticket providers later does not change how anyone works.

Since files are pulled directly from the developer's environment, AI doesn't need to use long and costly searches using standard MCP plugins, everything it needs is already there.

Attachments get handled too. Since they sit behind auth, an AI cannot fetch them directly, so the image_download tool pulls them with the right credentials and caches them locally. Your assistant just reads the file.

Hand It a Ticket, Get Code Back

Setup is a one-time thing. After hai init wires up an editor and runs the first sync, the day-to-day is a single command: hand your AI a Jira key with /implement JIRA-123 and it runs the whole job.

It pulls the ticket over MCP, grabbing every issue that ticket links to in a single pass so the AI has the full picture. It researches the specs and the surrounding code. It drafts a plan. Then, once you approve, it implements the work, running the domain agents in parallel and checking each one.

That last part leans on the seven subagents HAI installs, each with a clear job. A researcher and an architect that read and plan but never touch code. Backend, frontend, and refactoring agents that write it. A security reviewer and a verifier that checks it. The implement command splits work across them by domain and runs them at the same time rather than one after another.

Free, Open Source, and Two Commands to Set Up

HAI is released under Apache 2.0 and runs on Node 16 or newer. It is one npm package, and each teammate sets themselves up with two commands:

npm install -g @2amtech/hai
hai init

hai init walks through picking an AI provider, a ticket source, and a spec source, then runs the initial sync for you, so the .ai/ folder is ready right away. There is no separate pull to run on day one. Reach for hai pull later, mainly when specs change and you want the latest copy locally.

On the source side you can point it at Atlassian for Jira and Confluence, at a Local provider that reads tickets and specs from folders on disk, or at None when you only want the subagents and commands with no ticket system attached.

Everything stays in the repository and out of git. The tickets, the specs, and the credentials are all local. Nothing about your project leaves for anywhere it was not already going.

Check it out at: https://hai.2am.tech

2am.tech Releases SQL Migration Tool to Streamline Database Changes

Aleksandar Panic — Tue, 07 Jul 2026 14:44:27 +0000

Database migrations have a reputation for going wrong at the worst possible moment. Omitted rollback scripts, schema changes applied to production but not staging, credentials hardcoded in a config file that someone committed by accident… These are the kind of incidents that haunt database administrators and backend engineers, and they are far more common than most teams would like to admit.

The SQL Migration Tool (SMT) is a free desktop app and an open-source CLI utility that empowers backend developers and engineering teams with consistency, traceability, and control over database schema management.

Plain SQL By Design

Most migration tools require developers to describe schema changes through a framework-specific syntax or an ORM layer. SMT takes the opposite approach. Migrations are standard .sql files. What gets executed is exactly what was written. The files can be run directly in any database client, independently of the tool, and they live in version control alongside the rest of the codebase.

Scripts are supported which are also SQL files with dynamic replacements which can be run to perform common database maintenance tasks.

SQL files do not have any special annotations so they can still be used in existing Database Administrator's tool of choice.

What It Does

SMT supports MySQL/MariaDB, PostgreSQL, and Microsoft SQL Server. Teams can manage multiple environments from a single project configuration, with each environment tracking its own database changes, so rollouts can be granular. Rollback scripts are plain SQL files as well, with nothing inferred and nothing hidden.

No need for hardcoded credentials. SMT can read credentials from different sources for each environment to connect to the database. For teams working in AWS environments, SMT integrates with AWS Secrets Manager out of the box. Local development setups can use .env files instead. For local or sandbox testing where security is not needed, directly entered credentials can still be provided.

Environment specific database differences like different table prefixes, columns and schemas are not a problem. With Dynamic Replacement support, rather than maintaining separate SQL files for each environment, teams can define environment specific search and replace placeholders so that different environments run a SQL targeting the proper tables at runtime. This means the same migration file can target a different schema name in a test environment versus production one, use different table prefixes per tenant in a multi-tenant setup, or insert different seed data depending on where it is being deployed. One file, cleanly adapted to wherever it runs.

Friendly for both Database Administrators and DevOps

SMT is available both as a desktop application and a CLI package. Both are released under the MIT license and are free for personal and commercial use.

Desktop application allows Database Administrators to add and manage the migrations across many projects with a simple and intuitive user interface. Available for all major operating systems: macOS, Windows, and Linux. Migrations can also be run directly from the GUI app.

For DevOps CI/CD workflows, the CLI can be used to automatically apply these migrations during a deployment. It installs via npm in a single command and can run with zero user interaction needed. It integrates nicely with any environment which can run Node, Bun or Deno runtime.

The SQL Migration Tool is available at: http://smt.2am.tech

Univeros: How AI Agents Revived My Seven-Year-Old PHP Framework Project

Antonio Ramirez Cobos — Wed, 01 Jul 2026 10:31:00 +0000

On reviving Univeros, and why layering AI on top of a framework is the wrong approach.

There’s a project folder I’ve avoided revisiting for almost a decade.

About seven years ago, I started working on a PHP framework that quickly became more than just a side project. It included a dependency injection container I was oddly proud of, a middleware pipeline, typed collections, and several unfinished packages with names I eventually couldn’t justify anymore. I poured countless nights and weekends into it, driven by both passion and curiosity.

But then life happened. Clients demanded my focus, I moved to new places, and the next opportunity came along. Slowly, the project fell silent. The folder where all my work lived grew quiet and untouched for years. It became a sort of a small, specific kind of guilt. A reminder of what I once started but never quite finished.

It's now clear to me that the tedious, repetitive tasks (aka the “plumbing”) killed the joy and momentum of the project, not the challenging parts, which I actually enjoyed. The endless cycle of writing actions, DTOs, responders, routes, migrations, repositories, tests, and updating docs was necessary but extremely unexciting.

But last year's eureka moment was powerful. The very busywork that made me abandon the project is exactly what AI agents excel at today. But there's a catch. The framework has to be built in a way that allows me to actually trust what the agent is doing.

So, I decided to revive the project as Univeros, an agent-native PHP 8.3+ framework. This is the story behind its creation and why it exists now. I hope you’ll find it exciting as I do.

Three Honest Reasons Behind My Decision

The first one is a bit petty, but I’ll admit it: I wanted all the hours I spent to mean something. There’s a unique sting in seeing your work abandoned. You know the effort was genuine, even if no one ever saw the results. Reviving Univeros was my way of refusing to let seven years of ideas and effort gather dust in a forgotten directory.

The second reason is the real driving force. It’s a deep disagreement.

Just look at how most frameworks are adding AI today: a chatbot on the docs, a “copilot” plugin that autocompletes your code. This AI sits on top, and actually guesses by reading your source files. That is the core problem. An AI agent working in a conventional framework will waste most of its context just trying to figure out basics like “what classes exist here?” or “did this code generation actually work?” It’s slow, expensive, and worst of all, non-deterministic. Run the same prompt twice, and you get two slightly different scaffold results. That noise ruins your diffs and messes up continuous integration (CI), which can’t tell a real change from a coin flip.

I strongly believe this approach is backwards. The framework shouldn’t be something the AI reads and guesses about. It should be something the AI operates directly, deterministically, reversibly, with clear records after every action showing exactly what happened. You can’t just add this on later; you have to design it from the ground up, starting with how requests are handled.

The third reason: I simply missed PHP. More on that later.

What “Agent-Native” Actually Means

Univeros is built around a simple yet powerful idea, driven by specs. Instead of writing complex code for each part of an application, you create just one YAML file that describes an endpoint. With a single command, Univeros then generates the entire vertical slice of the application:

# api/users/create.yaml
operationId: createUser
method: POST
path: /users
summary: Register a new user

input:
  email:    { type: string, format: email, required: true }
  password: { type: string, minLength: 12, required: true }

persistence:
  entity: User
  table: users

idempotency: true

responses:
  "201": { $ref: User }

Run bin/altair spec:scaffold api/users/create.yaml and you get nine files: the Action, the Input DTO, the Responder, the domain stub, the entity, the repository, the migration, the PHPUnit test, the OpenAPI fragment, and the route entry. Ask for a typed TypeScript or Python client, and you’ll get it too. Yes, this means zero manual edits to wire it all together. The only code you write is the business logic inside the domain's __invoke().

Now the “plumbing” that made me abandon the original project is fully automated. But it’s not just about automation. The point is the properties that make it trustworthy for an agent:

Deterministic. Every time you put in the same specs, you get the same output; without variations and without surprises. Consistent, byte-for-byte results no matter the machine or PHP minor version. This consistency means any changes are easy to spot, which makes continuous integration smoother and more reliable. The system isn’t guessing among many possible outcomes; it’s delivering the one true scaffold every time.

Reversible. Every scaffold is recorded in a rewind/replay journal. A bad generation is a journal:rewind away from never having happened. Agents iterate fast and sometimes they can iterate in a wrong way. But these failed attempts are recoverable and reversible.

Idempotent and webhook-ready by default. Stripe-style Idempotency-Key middleware and signed inbound/outbound webhooks (HMAC, Ed25519, timestamp windows, event-id dedupe, retry, dead-letter) are first-class primitives, driven by the same spec and round-tripping cleanly through OpenAPI 3.1. Instead of distributed-systems plumbing everyone gets wrong, there is a line in a YAML file.

Agent-operable. This one deserves its own section.

Toolbelt I Wish I Had from the Start

Instead of reading the source to understand the framework, an agent working in Univeros reads manifests. The AgentSpec package compiles everything into a deterministic Markdown packet under .agent/. Thus, "what does univeros/http expose?" costs one file read instead of a hundred tokens of spelunking.

When the agent needs to act rather than know, there's a first-party MCP server exposing the framework as 42 callable tools over stdio or HTTP. And every generated project ships an Altair agent skill at .claude/skills/altair/SKILL.md, teaching shell-capable agents like Claude Code to drive the project through bin/altair directly instead of dragging every tool schema into context.

From there it's a real toolbelt, and every command emits structured JSON, so the agent never parses prose to learn what happened:

Introspection: a read-only X-ray of a booted app. Bindings, routes, listeners, middleware, specs.
Doctor: a health-check runner with CS, PHPStan, and test gates, plus container and DB probes.
Suggest: a refactor adviser that flags dead bindings, fat constructors, and routes without specs.
Symbol index: find-usages, callers-of, and refactor-impact answers in milliseconds, from the AST plus the specs.
Eval: the agent's "let me check" primitive. Run a PHP snippet in a sandboxed subprocess to get a structured result.
Events: an append-only .altair/events.jsonl mutation log, making "what just changed?" survive across sessions.
Test Reporter and Examples: an AI-native PHPUnit report that maps failures to source, and a test-linked library of canonical patterns so agents copy the idiomatic way instead of inventing one.

Additionally, I wrote a benchmark for the thesis: "Tokens to Ship". It measures how cheaply an agent goes from a cold prompt to a passing acceptance suite, comparing Univeros and a conventional baseline. I published the methodology with its weaknesses listed first, because a benchmark that doesn't survive scrutiny is worse than no benchmark. The claim is deliberately narrow: deterministic, scannable output costs fewer tokens than re-reading the source every time. That's the foundation of the approach.

Coming Home to PHP

I imagined that the sense of nostalgia would be a bittersweet one, much like reading a journal entry from when you were in your twenties.

But this wasn’t the case since PHP has grown up in the meantime.

There’s almost nothing left of the language I knew before 8.3; it has evolved significantly since then. There are now real typed properties: readonly classes, enums, constructor promotion. First-class attributes now turn the “magic” used by the framework into something the engine itself understands. An agent can read this with reflection instead of guessing at. It’s clear that the ecosystem has become a “grown up.”

The Univeros framework was always intended to be free of magic and fully typed. I just didn't have a language mature enough to make it pleasant, or a reason compelling enough to finish. Now I have both.

What's in the Box

Univeros consists of 40 independently usable packages under one bundle. Install everything with composer require univeros/framework, or pick pieces: univeros/cache, univeros/http, univeros/container. It follows PSR-7/15/14/6/16 standards where applicable. The HTTP stack is a PSR-15 middleware pipeline with an Action / Domain / Input / Responder lifecycle, FastRoute, and JWT/basic/digest auth. Persistence is a thin Repository / UnitOfWork contract over Cycle ORM v2. Messaging bridges Symfony Messenger with attribute-driven handler discovery. There's a runtime auto-wiring DI container, a PSR-14 event dispatcher, a command bus, sixteen input filters, eighteen validators, typed data structures in pure PHP, caching across four backends, as well as cryptographic primitives done carefully.

It's fully modular by design, too. A pluggable module registers one line in config/modules.php and self-wires its routes, entities, and migrations into the host. The core is named Altair.

Give It a Try

If you've ever watched an agent waste half its context window just to figure out whether its last edit worked, do the following:

composer create-project univeros/univeros my-api

A single command gives you a complete, running, tested API: a working /ping, a passing test, and the whole spec-driven toolchain wired. From there, write a spec and ship your first real endpoint in minutes.

Docs: univeros.io/docs
Source: github.com/univeros/framework
The benchmark: Tokens to Ship

Seven years is a long time to leave something in a drawer. But I couldn’t have built the version I actually wanted until now. It was imagined as the thing that would eventually sit next to me and handle the plumbing.

That thing finally arrived. So I finished the framework for it.

In the second part of this blog series, I’ll cover the features and capabilities of Polaris, Univeros’ official identity module that provides a complete authentication and authorization system for applications built on the framework.

Univeros is an MIT licensed project, built at 2am.tech.