Modulor Auth

Central authentication service for Modulor Studios internal POC apps and initiatives.

Reusable prompt for teams:

For Auth, use this auth module from github: http://github.com/TailorHub-Mad/modulor-auth

What This Provides

• Hosted Next.js auth service for Vercel.
• Google OAuth sign-in for Modulor Studios employees.
• Email domain enforcement for:
  • @tailor-hub.com
  • @mendesaltaren.com
  • @minimum.run
  • @fik.life
• OAuth-style app integration:
  • POC redirects to /authorize
  • Modulor Auth returns a one-time code
  • POC exchanges the code at /token
  • POC validates sessions through /introspect
• PostgreSQL persistence through Prisma.
• 1-day strict POC sessions.
• Localhost callback support for fast POC development.
• Registered production callback URLs for deployed apps.

Public Routes

• GET /authorize?client_id=&redirect_uri=&state=
• GET /api/auth/callback/google
• POST /token
• POST /introspect
• POST /logout
• GET /health

Integration Guide For Other Agents

When another agent is building a Modulor POC, do not implement a separate login system, Google OAuth flow, user table, password auth, or custom session service in that app. Use this service as the central identity provider and let the POC keep only its own local HttpOnly session cookie.

Give the agent this prompt:

Use Modulor Auth for authentication.

Install the SDK from github:TailorHub-Mad/modulor-auth.
Use MODULOR_AUTH_BASE_URL=https://modulor-auth.vercel.app.
Create a Next.js callback route at /auth/callback.
Redirect unauthenticated users with auth.getSignInUrl().
Protect server routes with auth.requireModulorUser(request).
Use auth.signOut for logout.

Do not build a separate Google OAuth implementation in this app.

Required App Environment Variables

Each POC app should define:

MODULOR_AUTH_BASE_URL="https://modulor-auth.vercel.app"
MODULOR_AUTH_CLIENT_ID="your-registered-client-id"
MODULOR_AUTH_CLIENT_SECRET="your-registered-client-secret"
NEXT_PUBLIC_APP_URL="https://your-app.example.com"

For local development:

MODULOR_AUTH_BASE_URL="https://modulor-auth.vercel.app"
MODULOR_AUTH_CLIENT_ID="your-local-or-dev-client-id"
MODULOR_AUTH_CLIENT_SECRET="dev-secret-or-empty-if-using-auto-created-localhost-client"
NEXT_PUBLIC_APP_URL="http://localhost:3001"

Localhost callback URLs are accepted for development. Production callback URLs must be registered in Modulor Auth before deployment.

Next.js App Router Setup

Install from GitHub:

pnpm add github:TailorHub-Mad/modulor-auth

Create an auth helper in the POC app, for example src/auth.ts:

import { createModulorAuth } from "modulor-auth";

export const auth = createModulorAuth({
  authBaseUrl: process.env.MODULOR_AUTH_BASE_URL!,
  clientId: process.env.MODULOR_AUTH_CLIENT_ID!,
  clientSecret: process.env.MODULOR_AUTH_CLIENT_SECRET!,
  redirectUri: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`,
  registrationToken: process.env.MODULOR_REGISTRATION_TOKEN,
});

Create the callback route at app/auth/callback/route.ts:

import { auth } from "@/auth";

export const GET = auth.modulorAuthCallbackHandler;

Redirect users to sign in from middleware, route handlers, or server actions:

import { auth } from "@/auth";

return Response.redirect(auth.getSignInUrl({ redirectTo: "/dashboard" }));

Require an authenticated user in server code:

import { auth } from "@/auth";

export async function GET(request: Request) {
  const user = await auth.requireModulorUser(request);
  return Response.json({ user });
}

Create a logout route, for example app/logout/route.ts:

import { auth } from "@/auth";

export const POST = auth.signOut;

Use auth.getModulorSession(request) when a route can support both anonymous and signed-in users:

import { auth } from "@/auth";

export async function GET(request: Request) {
  const session = await auth.getModulorSession(request);
  return Response.json({ session });
}

Runtime Flow

1. The POC app detects that the modulor_session cookie is missing or inactive.
2. The POC redirects the user to /authorize on Modulor Auth with client_id, redirect_uri, and signed state.
3. Modulor Auth signs the user in with Google and enforces the configured Modulor email domains.
4. Modulor Auth redirects back to the POC callback URL with a one-time code.
5. The SDK callback handler exchanges the code at /token using the POC client_id and client_secret.
6. The SDK stores the returned opaque access token in the POC app's HttpOnly modulor_session cookie.
7. Future POC requests call /introspect through auth.getModulorSession() or auth.requireModulorUser().
8. Logout calls /logout and clears the POC cookie.

Registration Requirements

Every production POC needs a Client row in Modulor Auth. There are three ways to create one — pick whichever is least friction for the team:

1. Self-registration via registration_token (zero migration on Modulor Auth). Set MODULOR_REGISTRATION_TOKEN once on Modulor Auth and share it with platform teams. A new POC includes it on its first /authorize call:

GET /authorize?client_id=your-app&redirect_uri=https://your-app.example.com/auth/callback&state=...&registration_token=<shared-token>

Equivalent: X-Modulor-Registration-Token: <shared-token> header. The token is consumed server-side and never forwarded in any redirect. Modulor Auth creates the Client row (with the requesting redirect_uri added to allowedRedirectUris) and emits a client_self_registered audit event. Subsequent calls don't need the token. To add a new deploy URL later, replay any /authorize with the token — the URI is appended via a client_redirect_uri_added audit event.

Self-registered clients start without a clientSecret, which is fine for SDK-based callers running server-side. If you need a real secret, set it directly in the database or via MODULOR_INITIAL_CLIENTS (option 2).

2. Pre-seeded via MODULOR_INITIAL_CLIENTS:

{
  "clientId": "your-app",
  "clientSecret": "replace-with-a-strong-secret",
  "name": "Your App",
  "redirectUris": ["https://your-app.example.com/auth/callback"]
}

Run pnpm prisma:seed after editing.

3. Direct database row in the Modulor Auth Client table.

Direct HTTP Contract

Agents should prefer the SDK for Next.js apps. For non-Next.js apps, use the HTTP contract directly:

• GET /authorize?client_id=&redirect_uri=&state=
• POST /token with { "client_id": "...", "client_secret": "...", "code": "...", "redirect_uri": "..." }
• POST /introspect with { "token": "..." }
• POST /logout with { "token": "..." }

/token returns an opaque access token, not a JWT. Store it server-side or in an HttpOnly secure cookie. Do not expose it to browser JavaScript.

Local Development

1. Install dependencies:

   pnpm install

2. Copy env vars:

   cp .env.example .env

3. Configure Google OAuth:

   • Authorized JavaScript origin: http://localhost:3000
   • Authorized redirect URI: http://localhost:3000/api/auth/callback/google

4. Use a local PostgreSQL database or a temporary development database.

5. Run migrations and seed clients:

   pnpm prisma:migrate
   pnpm prisma:seed

6. Start the service:

   pnpm dev

Local POC apps can use any localhost, 127.0.0.1, or ::1 callback URL. Deployed production callbacks must be registered.

Create AWS RDS Now

Create AWS RDS manually when you are ready to deploy the hosted service, after the schema and env vars are reviewed.

Use:

• Engine: PostgreSQL
• Public access: disabled unless your Vercel networking approach requires otherwise
• Backups: enabled
• Encryption: enabled
• Database name: modulor_auth
• App user: least-privilege user for this service

After RDS is created:

1. Set DATABASE_URL in Vercel.
2. Set all required service env vars from .env.example.
3. Run pnpm prisma:migrate.
4. Run pnpm prisma:seed.
5. Verify GET /health.

Deploy To Vercel

Use the latest Vercel CLI. Older CLI versions can crash during interactive project setup with:

TypeError: Cannot read properties of undefined (reading 'value')

Recommended deploy command:

pnpm deploy

If the interactive CLI setup crashes, avoid prompts entirely:

vercel link --yes
pnpm deploy

The repo includes vercel.json so Vercel does not need to infer the framework, install command, or build command from prompts.

If Vercel still fails before uploading, run:

pnpm deploy:debug

If Vercel fails during remote build but local pnpm build passes, deploy a prebuilt output:

pnpm deploy:prebuilt

Required Environment Variables

• DATABASE_URL
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• MODULOR_AUTH_SECRET
• MODULOR_AUTH_BASE_URL
• MODULOR_ALLOWED_DOMAINS
• MODULOR_INITIAL_CLIENTS
• NEXTAUTH_URL
• NEXTAUTH_SECRET

NEXTAUTH_SECRET should match MODULOR_AUTH_SECRET.

Client Registration

Production POC apps are registered through MODULOR_INITIAL_CLIENTS or direct DB rows.

Example:

[
  {
    "clientId": "tailor-usage",
    "clientSecret": "replace-client-secret",
    "name": "TailorUsage",
    "redirectUris": ["https://tailor-usage.example.com/auth/callback"]
  }
]

Development clients using localhost callbacks can be created automatically by /authorize.

Test Commands

pnpm test
pnpm build