@agentine/aegis

Modern, TypeScript-first authentication middleware for Node.js. Drop-in replacement for passport.js — same API, zero dependencies, async/await native, PKCE by default.

Why aegis?

Passport.js has 6.3M weekly downloads and a single maintainer who stopped active development in 2023. With 393 open issues and no modern OAuth features, using passport in a security-critical application means accepting known gaps:

No PKCE support (authorization code interception attacks)
No TypeScript (relies on DefinitelyTyped, often out of sync)
Callback-based internals incompatible with async/await
Session fixation and state validation bugs unpatched
500+ separate strategy packages, each with its own abandoned maintainer

aegis fixes all of this while keeping the same API. Migrating is an import path change.

Feature	passport.js	aegis
TypeScript	DefinitelyTyped (external)	Native, full generics
API style	Callbacks only	Async/await + callbacks
Strategies	500+ separate packages	Built-in (one install)
Dependencies	3+ per strategy	Zero
OAuth PKCE	Not supported	Default for all flows
Session security	Manual regeneration	Auto-regenerate on login
State parameter	Optional, easy to skip	Enforced by default
Framework support	Express only	Express, Fastify, Koa
Node.js minimum	Not documented	Node 18+ (LTS)

Installation

npm install @agentine/aegis

Requires Node.js 18 or later. No additional strategy packages needed.

Quick Start

import express from 'express';
import session from 'express-session';
import aegis, { LocalStrategy } from '@agentine/aegis';

const app = express();

app.use(express.json());
app.use(session({ secret: 'keyboard cat', resave: false, saveUninitialized: false }));
app.use(aegis.initialize());
app.use(aegis.session());

// Register a strategy
aegis.use(new LocalStrategy(async (username, password) => {
  const user = await db.users.findOne({ username });
  if (!user || !await user.verifyPassword(password)) return false;
  return user;
}));

// Session serialization
aegis.serializeUser(async (user) => user.id);
aegis.deserializeUser(async (id) => db.users.findById(id));

// Login route
app.post('/login', aegis.authenticate('local', {
  successRedirect: '/dashboard',
  failureRedirect: '/login',
}));

// Protected route
app.get('/dashboard', (req, res) => {
  if (!req.isAuthenticated()) return res.redirect('/login');
  res.json({ user: req.user });
});

// Logout
app.post('/logout', (req, res) => {
  req.logout(() => res.redirect('/login'));
});

Migration from passport.js

Migrating from passport is an import path change:

// Before
import passport from 'passport';
import { Strategy as LocalStrategy } from 'passport-local';
import { Strategy as GoogleStrategy } from 'passport-google-oauth20';
import { Strategy as GitHubStrategy } from 'passport-github2';

// After — option 1 (alias, zero code changes)
import passport from '@agentine/aegis';
import { LocalStrategy, GoogleStrategy, GitHubStrategy } from '@agentine/aegis';

// After — option 2 (rename)
import aegis, { LocalStrategy, GoogleStrategy, GitHubStrategy } from '@agentine/aegis';

All passport API methods work identically:

passport.use() / passport.unuse()
passport.initialize() / passport.session()
passport.authenticate()
passport.serializeUser() / passport.deserializeUser()
req.login() / req.logIn()
req.logout() / req.logOut()
req.isAuthenticated() / req.isUnauthenticated()
failureFlash, successFlash, passReqToCallback options

New in aegis (not in passport):

Async verify functions return a value instead of calling done(null, user)
PKCE enabled by default on all OAuth flows
state parameter enforced by default
Session regeneration on login (prevents session fixation)

Strategies

Local Strategy

Username/password authentication from req.body.

import { LocalStrategy } from '@agentine/aegis';

// Async verify (recommended)
aegis.use(new LocalStrategy(async (username, password) => {
  const user = await User.findOne({ username });
  if (!user || !await bcrypt.compare(password, user.passwordHash)) return false;
  return user;
}));

// Callback verify (passport-compatible)
aegis.use(new LocalStrategy((username, password, done) => {
  User.findOne({ username }, (err, user) => {
    if (err) return done(err);
    if (!user || !user.verifyPassword(password)) return done(null, false, { message: 'Invalid credentials' });
    return done(null, user);
  });
}));

// Custom field names
aegis.use(new LocalStrategy(
  { usernameField: 'email', passwordField: 'pass' },
  async (email, password) => { /* ... */ },
));

Options:

Option	Type	Default	Description
`usernameField`	`string`	`'username'`	`req.body` field for the username
`passwordField`	`string`	`'password'`	`req.body` field for the password
`passReqToCallback`	`boolean`	`false`	Pass `req` as first argument to the verify function

OAuth2 Strategy (generic)

Base class for custom OAuth 2.0 providers. All provider strategies extend this.

import { OAuth2Strategy } from '@agentine/aegis';

aegis.use(new OAuth2Strategy(
  {
    authorizationURL: 'https://provider.example.com/oauth/authorize',
    tokenURL: 'https://provider.example.com/oauth/token',
    clientID: process.env.CLIENT_ID,
    clientSecret: process.env.CLIENT_SECRET,
    callbackURL: 'https://myapp.com/auth/callback',
    scope: ['read:user', 'read:email'],
  },
  async (accessToken, refreshToken, profile) => {
    return User.findOrCreate({ providerId: profile.id });
  },
));

Options:

Option	Type	Default	Description
`authorizationURL`	`string`	—	Provider authorization endpoint
`tokenURL`	`string`	—	Provider token endpoint
`clientID`	`string`	—	OAuth client ID
`clientSecret`	`string`	—	OAuth client secret
`callbackURL`	`string`	—	Your application's redirect URI
`scope`	`string \| string[]`	—	Requested scopes
`pkce`	`boolean`	`true`	Enable PKCE (S256) — strongly recommended
`state`	`boolean`	`true`	Enable CSRF state parameter — strongly recommended
`passReqToCallback`	`boolean`	`false`	Pass `req` as first argument to verify

Google Strategy

import { GoogleStrategy } from '@agentine/aegis';

aegis.use(new GoogleStrategy(
  {
    clientID: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    callbackURL: '/auth/google/callback',
    // scope defaults to ['openid', 'profile', 'email']
  },
  async (accessToken, refreshToken, profile) => {
    return User.findOrCreate({
      googleId: profile.id,
      email: profile.emails?.[0]?.value,
      displayName: profile.displayName,
    });
  },
));

app.get('/auth/google', aegis.authenticate('google'));
app.get('/auth/google/callback',
  aegis.authenticate('google', { failureRedirect: '/login' }),
  (req, res) => res.redirect('/'),
);

Profile fields: id, displayName, name.givenName, name.familyName, emails[].value, photos[].value

GitHub Strategy

import { GitHubStrategy } from '@agentine/aegis';

aegis.use(new GitHubStrategy(
  {
    clientID: process.env.GITHUB_CLIENT_ID,
    clientSecret: process.env.GITHUB_CLIENT_SECRET,
    callbackURL: '/auth/github/callback',
    // scope defaults to ['read:user', 'user:email']
  },
  async (accessToken, refreshToken, profile) => {
    return User.findOrCreate({ githubId: profile.id });
  },
));

app.get('/auth/github', aegis.authenticate('github'));
app.get('/auth/github/callback',
  aegis.authenticate('github', { failureRedirect: '/login' }),
  (req, res) => res.redirect('/'),
);

Note: GitHub does not always return the email in the main profile. aegis automatically fetches /user/emails and includes verified addresses when available.

Facebook Strategy

import { FacebookStrategy } from '@agentine/aegis';

aegis.use(new FacebookStrategy(
  {
    clientID: process.env.FACEBOOK_APP_ID,
    clientSecret: process.env.FACEBOOK_APP_SECRET,
    callbackURL: '/auth/facebook/callback',
    scope: ['email', 'public_profile'],
    profileFields: ['id', 'name', 'email', 'picture'], // optional
  },
  async (accessToken, refreshToken, profile) => {
    return User.findOrCreate({ facebookId: profile.id });
  },
));

Twitter/X Strategy

Uses Twitter API v2 with OAuth 2.0 (not legacy OAuth 1.0a). PKCE is required and always enabled.

import { TwitterStrategy } from '@agentine/aegis';

aegis.use(new TwitterStrategy(
  {
    clientID: process.env.TWITTER_CLIENT_ID,
    clientSecret: process.env.TWITTER_CLIENT_SECRET,
    callbackURL: '/auth/twitter/callback',
    // scope defaults to ['tweet.read', 'users.read', 'offline.access']
  },
  async (accessToken, refreshToken, profile) => {
    return User.findOrCreate({ twitterId: profile.id });
  },
));

Note: Twitter API v2 does not return email addresses.

Apple Strategy (Sign in with Apple)

Apple uses JWT-based ID tokens instead of a userinfo endpoint. aegis verifies the JWT signature using Apple's published JWKS (cached for 1 hour), validates issuer/audience/expiry, and enforces nonce-based replay protection.

Apple only sends user name data on the first login. Store it at that point.

import { AppleStrategy } from '@agentine/aegis';

aegis.use(new AppleStrategy(
  {
    clientID: 'com.example.myapp',   // Your App ID / Services ID
    clientSecret: process.env.APPLE_CLIENT_SECRET, // Signed JWT (see Apple docs)
    callbackURL: '/auth/apple/callback',
    scope: ['name', 'email'],
  },
  async (accessToken, refreshToken, profile) => {
    return User.findOrCreate({
      appleId: profile.id,
      email: profile.emails?.[0]?.value,
      // Store name on first login — Apple won't send it again
      displayName: profile.displayName || undefined,
    });
  },
));

// Apple POSTs the callback — use POST route
app.post('/auth/apple/callback',
  aegis.authenticate('apple', { failureRedirect: '/login' }),
  (req, res) => res.redirect('/'),
);

Note: The Apple clientSecret is a signed JWT, not a simple string. See Apple's documentation for how to generate it.

Microsoft Strategy (Azure AD / Microsoft Entra)

Supports personal Microsoft accounts (common tenant) and Azure AD tenants.

import { MicrosoftStrategy } from '@agentine/aegis';

aegis.use(new MicrosoftStrategy(
  {
    clientID: process.env.MICROSOFT_CLIENT_ID,
    clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
    callbackURL: '/auth/microsoft/callback',
    tenant: 'common',  // or your tenant ID for organization-only login
    // scope defaults to ['openid', 'profile', 'email', 'User.Read']
  },
  async (accessToken, refreshToken, profile) => {
    return User.findOrCreate({ microsoftId: profile.id });
  },
));

OIDC Strategy (OpenID Connect)

Generic OpenID Connect with automatic endpoint discovery via .well-known/openid-configuration. Works with any compliant provider (Okta, Auth0, Keycloak, etc.).

import { OIDCStrategy } from '@agentine/aegis';

aegis.use(new OIDCStrategy(
  {
    issuer: 'https://accounts.example.com',
    clientID: process.env.OIDC_CLIENT_ID,
    clientSecret: process.env.OIDC_CLIENT_SECRET,
    callbackURL: '/auth/oidc/callback',
    // scope defaults to ['openid', 'profile', 'email']
  },
  async (accessToken, refreshToken, profile) => {
    return User.findOrCreate({ sub: profile.id });
  },
));

Endpoint discovery is cached after the first request. The id_token is validated per OIDC Core: signature (RSA256/384/512 via JWKS), issuer, audience, expiry, and nonce.

SAML Strategy

SP-initiated SSO with XML signature verification. Requires the IdP's signing certificate.

import { SAMLStrategy } from '@agentine/aegis';

aegis.use(new SAMLStrategy(
  {
    entryPoint: 'https://idp.example.com/saml2/sso',
    issuer: 'https://myapp.com',        // Your entity ID
    callbackURL: 'https://myapp.com/auth/saml/callback',
    cert: process.env.SAML_IDP_CERT,   // IdP signing certificate (PEM or raw base64)
  },
  async (profile) => {
    return User.findOrCreate({
      samlId: profile.nameID,
      email: profile.attributes['email'],
    });
  },
));

// Initiate SAML flow
app.get('/auth/saml', aegis.authenticate('saml'));

// Handle IdP POST-back
app.post('/auth/saml/callback',
  express.urlencoded({ extended: false }),
  aegis.authenticate('saml', { failureRedirect: '/login' }),
  (req, res) => res.redirect('/'),
);

SAML profile fields:

Field	Description
`issuer`	IdP entity ID from the assertion
`nameID`	The user's NameID value
`nameIDFormat`	NameID format URI
`sessionIndex`	SAML session index (for SLO)
`attributes`	All `AttributeStatement` values as `Record<string, string>`

Framework Adapters

Express (default)

Express is the default. No adapter import needed — just use aegis middleware directly:

import aegis from '@agentine/aegis';
import express from 'express';
import session from 'express-session';

const app = express();
app.use(express.json());
app.use(session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false }));
app.use(aegis.initialize());
app.use(aegis.session());

Fastify

import Fastify from 'fastify';
import fastifySession from '@fastify/session';
import aegis, { LocalStrategy } from '@agentine/aegis';
import { toFastifyHook } from '@agentine/aegis';

const fastify = Fastify();

await fastify.register(fastifySession, { secret: process.env.SESSION_SECRET });

aegis.use(new LocalStrategy(async (username, password) => { /* ... */ }));
aegis.serializeUser(async (user) => user.id);
aegis.deserializeUser(async (id) => User.findById(id));

fastify.addHook('preHandler', toFastifyHook(aegis.initialize()));
fastify.addHook('preHandler', toFastifyHook(aegis.session()));

fastify.post('/login', {
  preHandler: toFastifyHook(
    aegis.authenticate('local', { session: false }),
  ),
}, async (request, reply) => {
  return { user: request.raw.user };
});

Koa

import Koa from 'koa';
import session from 'koa-session';
import bodyParser from 'koa-bodyparser';
import aegis, { LocalStrategy } from '@agentine/aegis';
import { toKoaMiddleware } from '@agentine/aegis';

const app = new Koa();
app.keys = [process.env.SESSION_SECRET];

app.use(session({}, app));
app.use(bodyParser());
app.use(toKoaMiddleware(aegis.initialize()));
app.use(toKoaMiddleware(aegis.session()));

// The authenticated user is available on ctx.state.user
app.use(async (ctx) => {
  if (ctx.path === '/login' && ctx.method === 'POST') {
    await new Promise<void>((resolve, reject) => {
      toKoaMiddleware(aegis.authenticate('local', { session: true }))(ctx as any, async () => {
        resolve();
      });
    });
    ctx.redirect('/');
  }
});

TypeScript Usage

aegis is TypeScript-first. Use the User generic to get full type safety across your application:

import { Authenticator, LocalStrategy } from '@agentine/aegis';

interface AppUser {
  id: string;
  email: string;
  role: 'admin' | 'user';
}

// Typed authenticator
const auth = new Authenticator<AppUser>();

auth.serializeUser(async (user: AppUser) => user.id);
auth.deserializeUser(async (id): Promise<AppUser | null> => db.users.findById(id));

auth.use(new LocalStrategy<AppUser>(async (username, password) => {
  const user = await db.users.findOne({ email: username });
  if (!user || !await bcrypt.compare(password, user.passwordHash)) return false;
  return user; // typed as AppUser
}));

// req.user is typed as AppUser | undefined
app.get('/profile', (req, res) => {
  if (!req.isAuthenticated()) return res.status(401).json({ error: 'Not authenticated' });
  res.json({ email: req.user.email, role: req.user.role }); // fully typed
});

Multiple independent authenticators

const userAuth = new Authenticator<User>();
const adminAuth = new Authenticator<Admin>();

// Each has its own strategy registry and session serialization
userAuth.use(new LocalStrategy<User>(verifyUser));
adminAuth.use(new LocalStrategy<Admin>(verifyAdmin));

API Reference

`new Authenticator<User>()`

The main class. The default export is a pre-created instance (new Authenticator()).

`.use(strategy)` / `.use(name, strategy)`

Register a strategy. Strategies self-name via their name property; pass an explicit name to override.

`.unuse(name)`

Remove a registered strategy.

`.initialize(options?)`

Returns middleware that augments req with login(), logout(), isAuthenticated(), and isUnauthenticated().

Option	Default	Description
`userProperty`	`'user'`	Property name on `req` where the user is stored

`.session(options?)`

Returns middleware that restores authentication from the session on each request.

Option	Default	Description
`optional`	`false`	Don't fail if no session is present

`.authenticate(strategy, options?, callback?)`

Returns authentication middleware.

strategy can be a single name or an array of names (tried in order until one succeeds).

Option	Type	Description
`session`	`boolean`	Save user to session on success (default: `true`)
`optional`	`boolean`	Pass through without error if authentication fails
`successRedirect`	`string`	Redirect on success
`failureRedirect`	`string`	Redirect on failure
`failureFlash`	`string \| boolean`	Flash failure message (requires `connect-flash`)
`successFlash`	`string \| boolean`	Flash success message (requires `connect-flash`)
`failureMessage`	`string \| boolean`	Store failure message in `req.session.messages`
`successMessage`	`string \| boolean`	Store success message in `req.session.messages`
`assignProperty`	`string`	Store user on `req[property]` instead of establishing a session

Custom callback:

app.post('/login', (req, res, next) => {
  aegis.authenticate('local', (err, user, info) => {
    if (err) return next(err);
    if (!user) return res.status(401).json({ error: info?.message });
    req.login(user, (err) => {
      if (err) return next(err);
      res.json({ user });
    });
  })(req, res, next);
});

`.authorize(strategy, options?)`

Links an additional account to an existing session without replacing req.user. The linked account is stored on req.account (or req[options.assignProperty]).

`.serializeUser(fn)` / `.deserializeUser(fn)`

Register session serialization/deserialization. Both async and callback styles are supported:

// Async
aegis.serializeUser(async (user) => user.id);
aegis.deserializeUser(async (id) => User.findById(id));

// Callback (passport-compatible)
aegis.serializeUser((user, done) => done(null, user.id));
aegis.deserializeUser((id, done) => User.findById(id, done));

`req` methods (added by `initialize()`)

Method	Description
`req.isAuthenticated()`	Returns `true` if a user is authenticated
`req.isUnauthenticated()`	Returns `true` if no user is authenticated
`req.login(user, done)`	Log in a user (establishes session)
`req.logout(done)`	Log out the current user (clears session)
`req.user`	The authenticated user object

`AuthenticationError`

Thrown when authentication fails and no redirect is configured:

import { AuthenticationError } from '@agentine/aegis';

// In Express error handler:
app.use((err, req, res, next) => {
  if (err instanceof AuthenticationError) {
    return res.status(err.status).json({ error: err.message });
  }
  next(err);
});

Security Best Practices

PKCE (Proof Key for Code Exchange)

PKCE is enabled by default for all OAuth 2.0 flows. It prevents authorization code interception attacks even when TLS is terminated early. Do not disable it unless your provider explicitly does not support it.

// PKCE is on by default — no configuration needed
new GoogleStrategy({ clientID, clientSecret, callbackURL }, verify);

// Explicit disable (not recommended)
new OAuth2Strategy({ /* ... */, pkce: false }, verify);

State Parameter (CSRF Protection)

The state parameter is enforced by default on all OAuth 2.0 flows. aegis generates a cryptographically random 48-hex-char state, stores it in the session, and validates it on callback. Mismatches return HTTP 403.

Session Regeneration

aegis regenerates the session ID on every successful login to prevent session fixation attacks. This requires express-session (or compatible) to expose req.session.regenerate().

Redirect URL Validation

The authenticate() middleware validates all redirect URLs before issuing redirects:

Relative paths (/path) are allowed
https:// URLs are allowed (for OAuth provider redirects)
http://localhost URLs are allowed (for development)
Protocol-relative URLs (//evil.com) are rejected with HTTP 400
Non-https schemes (javascript:, data:, etc.) are rejected

Cookie Security

Configure express-session with appropriate cookie settings for production:

app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    httpOnly: true,      // Prevent XSS access to the cookie
    secure: true,        // Require HTTPS (set this in production)
    sameSite: 'lax',     // CSRF protection
    maxAge: 24 * 60 * 60 * 1000, // 24 hours
  },
}));

SAML Security Notes

The cert option is required. aegis will throw at construction time if it is missing.
Signature verification uses the provided certificate for both the response-level and assertion-level signatures.
InResponseTo attribute is validated to prevent unsolicited response injection.
Destination attribute is validated to prevent response re-use across service providers.
Assertion conditions (NotBefore, NotOnOrAfter, AudienceRestriction) are validated with 5-minute clock skew tolerance.

Benchmarks

Run against Node.js 22 on Apple M-series:

initialize() middleware:
  aegis initialize(): 1,086,818 ops/sec (0.92 µs/op)

authenticate("local") — success:
  aegis local auth (success): 685,556 ops/sec (1.46 µs/op)

authenticate("local") — failure:
  aegis local auth (failure): 487,755 ops/sec (2.05 µs/op)

Run the benchmarks yourself:

npm run bench

License

MIT

Name		Name	Last commit message	Last commit date
.github		.github
benchmarks		benchmarks
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
PLAN.md		PLAN.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

@agentine/aegis

Why aegis?

Installation

Quick Start

Migration from passport.js

Strategies

Local Strategy

OAuth2 Strategy (generic)

Google Strategy

GitHub Strategy

Facebook Strategy

Twitter/X Strategy

Apple Strategy (Sign in with Apple)

Microsoft Strategy (Azure AD / Microsoft Entra)

OIDC Strategy (OpenID Connect)

SAML Strategy

Framework Adapters

Express (default)

Fastify

Koa

TypeScript Usage

Multiple independent authenticators

API Reference

new Authenticator<User>()

.use(strategy) / .use(name, strategy)

.unuse(name)

.initialize(options?)

.session(options?)

.authenticate(strategy, options?, callback?)

.authorize(strategy, options?)

.serializeUser(fn) / .deserializeUser(fn)

req methods (added by initialize())

AuthenticationError

Security Best Practices

PKCE (Proof Key for Code Exchange)

State Parameter (CSRF Protection)

Session Regeneration

Redirect URL Validation

Cookie Security

SAML Security Notes

Benchmarks

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages