What is Aura Auth

Modern, type-safe authentication for TypeScript — built for security, extensibility, and developer experience.

What is `@aura-stack/auth`

Aura Auth is an open-source authentication and authorization library for modern TypeScript applications.
Inspired by Auth.js, it provides a type-safe and framework-agnostic API to implement secure authentication flows with an emphasis on developer experience, security, and modularity.

This project is under active development. Aura Auth is framework-agnostic and targets native TypeScript runtimes. If you'd like to contribute framework adapters (Express, Hono, Next.js, etc.), contributions and PRs are always welcome.

Highlights

lock

OAuth 2.0

Utilities for common OAuth 2.0 flows (authorization URL, token exchange, userinfo) with examples for popular providers.

code

Type-first API

Written entirely in TypeScript with strong types, full IntelliSense, and predictable ergonomics.

puzzle

Composable

Built from small, focused packages — use only what you need (auth handlers, JOSE helpers, cookie utilities).

shield

Secure by default

Enforces opinionated defaults for secure cookies, PKCE, state validation, and token verification.

Getting started

This guide walks you through installing and setting up a basic authentication flow using Aura Auth.

Install

We recommend using pnpm in monorepos for optimal performance, but npm and yarn are also supported.

npm install @aura-stack/auth

Using pnpm in a monorepo improves install performance and disk usage.

Environment setup

Store all secrets and provider credentials as environment variables. By convention, Aura Auth uses the following naming pattern:

AURA_AUTH_{PROVIDER}_CLIENT_ID
AURA_AUTH_{PROVIDER}_CLIENT_SECRET
AURA_AUTH_SECRET (used to sign and encrypt sessions)

Create a .env file (do not commit it):

.env

# 32-byte (256-bit) secret used to sign and encrypt sessions. Use a secure random value.
AURA_AUTH_SECRET="base64-or-hex-32-bytes"

# GitHub OAuth credentials
AURA_AUTH_GITHUB_CLIENT_ID=your_github_client_id
AURA_AUTH_GITHUB_CLIENT_SECRET=your_github_client_secret

Never commit your .env file. Always use a secret manager in production.

Create an Auth instance

Use createAuth to configure providers and obtain HTTP handlers that can be integrated into your router or framework.

auth.ts

import { createAuth } from "@aura-stack/auth"

const auth = createAuth({
  oauth: [],
})

export const { handlers } = auth

The returned handlers include pre-built routes used in OAuth flows (/signIn/:oauth, /callback/:oauth, /session, etc.). You can mount them in Express, Hono, Next.js, or any runtime that supports native Request and Response APIs.