@aura-stack/auth

Overview

The @aura-stack/auth package provides a framework-agnostic authentication core for TypeScript applications, built on modern standards like OAuth 2.0 and OpenID Connect (future support planned).
It offers secure, type-safe, and composable primitives designed for an exceptional developer experience (DX).

Inspired by Auth.js, this package focuses on clarity, security, and flexibility, providing everything needed to implement authentication and authorization in a clean and extensible way.

Features

OAuth 2.0 support — Integrate multiple providers effortlessly.
Type-safe API — Built entirely in TypeScript with strong type inference.
Secure sessions — Backed by JOSE (JWT, JWS, and JWE) for signing and encryption.
Framework agnostic — Works seamlessly with any HTTP framework or runtime.
Router integration — Compatible with @aura-stack/router for effortless endpoint mounting.

Installation

npm install @aura-stack/auth

Getting Started

Create an auth instance

Use createAuth to configure your authentication providers. The API is intentionally lightweight, flexible, and independent of any framework.

@aura-stack/auth integrates naturally with @aura-stack/router under the hood. Simply mount the returned handlers within your application’s routing layer

auth.ts

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

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

export const { handlers } = auth

Environment variables

This package expects two main types of environment variables:

A secret key for signing and encrypting sessions (recommended: 32 bytes / 256 bits).
OAuth credentials for each provider integration.

Create a .env file in your project root:

.env

# 32-byte (256-bit) secret used for signing and encrypting sessions
AURA_AUTH_SECRET="base64-or-hex-32-bytes"

# OAuth provider credentials
AURA_AUTH_GITHUB_CLIENT_ID=your_client_id
AURA_AUTH_GITHUB_CLIENT_SECRET=your_client_secret

Never hard-code credentials in your source code. Always store secrets in environment variables and consider using secret-scanning tools (e.g., GitGuardian) to prevent leaks

API Reference

`createAuth(config?: AuthConfig)`

Creates a new Aura Auth instance configured for your environment and providers.

Parameter	Type	Description
`oauth`	`Array<string \| OAuthProviderConfig>`	List of OAuth providers. You can specify provider IDs (e.g., "github") or custom provider configurations.

Returns

Return	Type	Description
`handlers`	HTTP handlers (from`createRouter`)	Route handlers you can mount in your app to expose authentication endpoints (`/signIn/:oauth`, `/callback/:oauth`, `/session`, etc.). Mount at your desired base path (default: `/auth`).

Example

auth.ts

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

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

Default Routes

When you create an auth instance, the following endpoints are commonly available (mount path is configurable):

Route	Method	Description
`/auth/signin`	GET	Initiates the OAuth sign-in flow
`/auth/callback`	GET	Handles the OAuth callback
`/auth/session`	GET	Returns current session informationon

All routes are relative to your configured base path (default: /auth).

Configuration

Multiple OAuth Providers

You can define multiple providers easily:

auth.ts

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

const auth = createAuth({
  oauth: [
    "github",
    {
      id: "oauth-integration",
      name: "OAuth",
      authorizeURL: "https://example.com/oauth/authorize",
      accessToken: "https://example.com/oauth/token",
      scope: "profile email",
      responseType: "code",
      userInfo: "https://example.com/oauth/userinfo",
      clientId: process.env.AURA_AUTH_GITHUB_CLIENT_ID!,
      clientSecret: process.env.AURA_AUTH_GITHUB_CLIENT_SECRET!,
    },
  ],
})

Best Practices

Use Environment Variables: Always store credentials in environment variables
HTTPS in Production: Use HTTPS for all authentication endpoints in production
Secure Cookies: Configure secure cookie options for production
Error Handling: Implement proper error handling for auth flows
Session Validation: Always validate sessions on the server side

@aura-stack/auth

On this page