feat(express): add express integration package (@aura-stack/express)

apps/express/README.md

@@ -1,49 +1,55 @@
 <div align="center">
-
+ 
 <h1>Aura Auth + Express</h1>
-
+ 
 **Integration Example App**
-
+ 
 [Official Docs](https://aura-stack-auth.vercel.app/docs/oauth) · [Express](https://expressjs.com/)
-
+ 
 </div>
-
+ 
 ---
-
+ 
 ## Overview
-
-This project demonstrates Aura Auth authentication using [OAuth 2.0 providers](https://aura-stack-auth.vercel.app/docs/) in an [Express](https://expressjs.com/) application.
-
+
+This project demonstrates **Aura Auth** authentication using [OAuth 2.0 providers](https://aura-stack-auth.vercel.app/docs/) in an [Express](https://expressjs.com/) application.
+
+This integration utilizes the dedicated [`@aura-stack/express`](../../packages/express) package, which provides standard middlewares and first-class TypeScript support for Express applications.
+
+## Features Demo
+
+- **Type-safe Middleware**: Uses `withAuth` to protect routes and infer session shapes.
+- **Unified Auth Handler**: Reuses framework-agnostic core logic via `toHandler`.
+- **Global Context**: Demonstrates how `res.locals.session` is automatically populated and typed.
+
 ## Getting Started
-
-You can run the documentation site locally for development or contribution.
-
+
 ### From the repository root
-
+ 
 ```bash
 pnpm dev --filter=express
 ```
-
+ 
 ### Or manually from the app directory
-
+ 
 ```bash
 cd apps/express
 pnpm install
 pnpm dev
 ```
-
+ 
 Once started, open your browser at `http://localhost:3000` to view the app.
-
+ 
 ## Documentation
-
+ 
 Visit the [**official documentation website**](https://aura-stack-auth.vercel.app).
-
+ 
 ## License
-
+ 
 Licensed under the [MIT License](LICENSE). © [Aura Stack](https://github.com/aura-stack-ts)
-
+ 
 ---
-
+ 
 <p align="center">
   Made with ❤️ by <a href="https://github.com/aura-stack-ts">Aura Stack team</a>
 </p>

apps/express/package.json

@@ -8,26 +8,28 @@
     "dev": "tsx --env-file=.env --watch src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
-    "test:run": "vitest run",
     "type-check": "tsc --noEmit",
     "format": "oxfmt",
     "format:check": "oxfmt --check"
   },
   "dependencies": {
     "@aura-stack/auth": "workspace:*",
+    "@aura-stack/express": "workspace:*",
     "express": "^4.18.2"
   },
   "devDependencies": {
     "@aura-stack/tsconfig": "workspace:*",
     "@types/express": "^4.17.21",
     "@types/node": "^20.10.6",
-    "@types/supertest": "^6.0.3",
-    "supertest": "^7.2.2",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3"
   },
   "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "author": "Aura Stack <aurastackjs@gmail.com> | Hernan Alvarado <halvaradop.dev@gmail.com>",
+  "homepage": "https://aura-stack-auth.vercel.app",
+  "bugs": {
+    "url": "https://github.com/aura-stack-ts/auth/issues"
+  },
+  "license": "MIT",
   "packageManager": "pnpm@10.15.0"
 }

apps/express/src/app.ts

@@ -0,0 +1,21 @@
+import express, { type Express } from "express"
+import { toHandler, withAuth } from "@/lib/auth.js"
+
+const app: Express = express()
+
+app.use(express.json())
+app.use(express.urlencoded({ extended: true }))
+
+app.all("/api/auth/*", toHandler)
+
+app.get("/api/protected", withAuth, (_, res) => {
+    if (!res.locals.session) {
+        return res.status(401).json({ message: "Unauthorized" })
+    }
+    return res.json({
+        message: "You have access to this protected resource.",
+        session: res.locals.session,
+    })
+})
+
+export { app }

apps/express/src/index.ts

@@ -1,4 +1,4 @@
-import { app } from "@/server.js"
+import { app } from "@/app.js"
 
 const PORT = process.env.PORT ?? 3000
 

apps/express/src/lib/auth.ts

@@ -0,0 +1,10 @@
+import { createAuth, builtInOAuthProviders, type BuiltInOAuthProvider } from "@aura-stack/express"
+
+export const oauth = Object.keys(builtInOAuthProviders) as BuiltInOAuthProvider[]
+
+export const auth = createAuth({
+    oauth: ["github"],
+    basePath: "/api/auth",
+})
+
+export const { api, jose, toHandler, withAuth } = auth

apps/express/tsconfig.json

@@ -1,12 +1,10 @@
 {
   "extends": "@aura-stack/tsconfig/tsconfig.base.json",
   "compilerOptions": {
-    "outDir": "dist",
     "paths": {
-      "@/*": ["./src/*"],
-      "@test/*": ["./test/*"]
-    },
-    "baseUrl": "./"
+      "@/*": ["./src/*"]
+    }
   },
-  "include": ["src", "test"]
+  "include": ["src"],
+  "exclude": ["dist", "node_modules"]
 }

packages/express/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog - `@aura-stack/express`
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+
+- Introduced a seamless Express integration package that encapsulates the core authentication logic into middleware and handlers for session management and authentication flows. [#138](https://github.com/aura-stack-ts/auth/pull/138)

packages/express/README.md

@@ -0,0 +1,101 @@
+<div align="center">
+
+<h1><b>@aura-stack/express</b></h1>
+
+**Type-safe Express middleware and utilities for the Aura Stack authentication library**
+
+[![npm version](https://img.shields.io/npm/v/@aura-stack/express.svg)](https://www.npmjs.com/package/@aura-stack/express)
+[![JSR version](https://jsr.io/badges/@aura-stack/express)](https://jsr.io/@aura-stack/express)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+[Official Docs](https://aura-stack-auth.vercel.app/docs) · [Express Package Docs](https://aura-stack-auth.vercel.app/docs/packages/express)
+
+</div>
+
+## Overview
+
+`@aura-stack/express` provides a seamless integration layer for **Express** applications using **Aura Auth**. It encapsulates the core authentication logic into standard Express middlewares, ensuring that your session state is correctly typed and accessible throughout your application's middleware chain.
+
+By leveraging TypeScript's global augmentation and middleware inference, it provides a "zero-effort" typed experience for your protected routes.
+
+## Features
+
+- **Standard Middleware** — Use `withAuth` as a standard middleware in your route definitions.
+- **Deep Type Inference** — Automatically infers your custom `User` and `Session` shapes from the initial configuration.
+- **Global Augmentation** — Adds first-class support for `res.locals.session` directly to Express types.
+- **Framework-Agnostic Core** — Bridge Web Request/Response API handlers to Express without sacrificing performance.
+- **Typed Propagation** — Middleware correctly propagates types to subsequent handlers in the route chain.
+
+## Installation
+
+```bash
+pnpm add @aura-stack/express
+```
+
+## Quick Start
+
+### 1. Configure Auth
+
+Create your authentication instance. This typically goes in a shared file like `lib/auth.ts`.
+
+```tsx
+import { createAuth } from "@aura-stack/express"
+
+export const auth = createAuth({
+  oauth: ["github"],
+  session: {
+    strategy: "jwt",
+    maxAge: 30 * 24 * 60 * 60, // 30 days
+  },
+})
+
+export const { toHandler, withAuth } = auth
+```
+
+### 2. Mount Auth Endpoints
+
+Mount the authentication endpoints on your desired base path (default: `/api/auth`).
+
+```tsx
+import express from "express"
+import { toHandler } from "./lib/auth"
+
+const app = express()
+
+// All Aura Auth routes (sign-in, sign-out, session, etc.)
+app.all("/api/auth/*", toHandler)
+```
+
+### 3. Protect Your Routes
+
+Use the `withAuth` middleware to protect routes. The session will be automatically available and **fully typed** in `res.locals.session`.
+
+```tsx
+import { withAuth } from "./lib/auth"
+
+app.get("/api/protected", withAuth, (req, res) => {
+  // session is automatically available and typed!
+  const session = res.locals.session
+
+  if (!session) {
+    return res.status(401).json({ error: "Unauthorized" })
+  }
+
+  // TypeScript knows about session.user.name, email, etc.
+  res.json({ message: `Hello, ${session.user.name}!` })
+})
+```
+
+## Documentation
+
+Visit the [**official documentation website**](https://aura-stack-auth.vercel.app) for more detailed guides and API references.
+
+## License
+
+Licensed under the [MIT License](../../LICENSE). © [Aura Stack](https://github.com/aura-stack-ts)
+
+---
+
+<p align="center">
+  Made with ❤️ by <a href="https://github.com/aura-stack-ts">Aura Stack team</a>
+</p>

packages/express/deno.json

@@ -0,0 +1,19 @@
+{
+  "name": "@aura-stack/express",
+  "version": "0.0.0",
+  "license": "MIT",
+  "tasks": {
+    "dev": "deno run --watch src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./oauth": "./src/oauth/index.ts"
+  },
+  "imports": {
+    "@/": "./src/"
+  },
+  "publish": {
+    "include": ["src/**/*.ts", "README.md", "CHANGELOG.md"]
+  },
+  "exclude": ["dist", "node_modules"]
+}