open-serverless-auth

This is the official unified toolkit for Open Serverless Auth. It provides Edge Middleware to effortlessly protect your downstream applications and powerful Server Actions/Components helpers to retrieve active user data seamlessly.

The goal of this package is to make standing up a centralized authentication architecture incredibly straightforward.

Installation

npm install open-serverless-auth

1. For Downstream Clients (Integrating Applications)

If you are building a peripheral application (e.g., app.yourdomain.com, admin.yourdomain.com) that needs to tie into your auth hub, use these tools to protect your Next.js application effortlessly.

A. Edge Middleware Protection

Create a middleware.ts file in the root of your Next.js application (or your src/ directory). This intercepts incoming requests and redirects unauthorized users to the auth hub:

import { createAuthMiddleware } from 'open-serverless-auth';

export const middleware = createAuthMiddleware({
  // Optionally define overrides if process.env.DOMAIN isn't sufficient
  // domain: process.env.NEXT_PUBLIC_DOMAIN,
});

export const config = {
  // Only protect specific routes, avoiding static assets and raw api paths if needed
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

B. Retrieving User Data (Server Components)

To get the fully typed, verified user object natively inside your downstream Next.js applications, use the exported getUserData() helper:

// app/page.tsx
import { getUserData } from 'open-serverless-auth';
import { redirect } from 'next/navigation';

export default async function Dashboard() {
  const user = await getUserData();

  if (!user) {
    redirect('/unauthorized');
  }

  return <h1>Welcome back, {user.email}! Role: {user.role}</h1>;
}

C. Development & Testing Bypass Tips

Testing your client apps locally can be tedious if you are forced to run the central auth server constantly just to get a session cookie. We've introduced a built-in bypassing mechanism:

// middleware.ts
import { createAuthMiddleware } from 'open-serverless-auth';

export const middleware = createAuthMiddleware({
  // This object is injected natively into local request headers and bypasses redirections!
  devBypassUser: {
    id: "local-dev-id",
    email: "[email protected]",
    role: "ADMIN",
    rules: { customPermission: true }
  }
});

Security Note: The middleware explicitly checks that process.env.NODE_ENV !== 'production'. Since Vercel and Next.js force this flag to exactly 'production' upon deployment, the dummy configuration is completely ignored and physically safe in live environments.

D. Frontend Application Templates

When setting up new client applications (the ones actually using open-serverless-auth alongside your hub), it is highly recommended to start from a Next.js App Router template (e.g. npx create-next-app@latest). Simply wire up the middleware to point to your process.env.DOMAIN, and use getUserData(). The auth system operates seamlessly via cross-subdomain cookies, meaning you won't need to build any custom login UIs on your client apps!

2. For the Central Auth Server (Hub Deployment)

If you are the systems administrator deploying the actual Identity Provider handling definitions, emails, and passwords, these instructions map out deploying the core repository.

Setting Up the Central Auth Server on Vercel

While the functions above handle clients connecting to your authentication ecosystem, you also need to deploy the actual Auth Hub Server itself.

1. Deploy the Hub: Fork the centralized Open Serverless Auth repository and deploy it as a new Project on Vercel.
2. Assign the Domain: Map this project to your authentication subdomain (e.g., auth.yourdomain.com).
3. Environment Setup: Make sure you provide DATABASE_URL (using Neon Serverless Postgres), DOMAIN="yourdomain.com", and your SMTP variables in the Vercel project environment configuration.
4. Build command: Simply use npm run build. Vercel automatically deploys the Next.js edge functions natively.