JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 24
  • Score
    100M100P100Q88600F
  • License MIT

Express integration for InAI Auth SDK

Package Exports

  • @inai-dev/express
  • @inai-dev/express/api-routes
  • @inai-dev/express/middleware

Readme

@inai-dev/express

Full Express integration for InAI Auth. Includes middleware with automatic token refresh, route protection with RBAC, and API route handlers.

Installation

npm install @inai-dev/express

Environment Variables

# Required — your publishable key
INAI_PUBLISHABLE_KEY=pk_live_...

Setup

1. Middleware

import express from "express";
import { inaiAuthMiddleware } from "@inai-dev/express/middleware";

const app = express();
app.use(express.json());

app.use(
  inaiAuthMiddleware({
    publicRoutes: ["/", "/health", "/api/public/*"],
  })
);

The middleware automatically:

  • Skips public routes (supports glob patterns with *)
  • Validates the auth token from Authorization: Bearer <token> header or cookies
  • Refreshes expired tokens when a refresh token exists in cookies
  • Attaches req.auth with the AuthObject for authenticated requests
  • Returns 401 Unauthorized for unauthenticated requests on protected routes
  • Works with or without cookie-parser (parses cookies from header as fallback)

Configuration

inaiAuthMiddleware({
  // Auth mode: "app" (default) or "platform" (admin panel auth)
  authMode: "app",

  // Routes that don't require authentication
  publicRoutes: ["/", "/health", "/api/public/*"],
  // Or use a function for dynamic matching
  publicRoutes: (req) => req.path.startsWith("/public"),

  // Custom unauthorized handler (default: 401 JSON response)
  onUnauthorized: (req, res, next) => {
    res.status(401).json({ error: "Please sign in" });
  },

  // Hook: runs before auth check. Return true to skip auth entirely.
  beforeAuth: (req, res) => {
    if (req.headers["x-internal-key"] === "secret") return true;
  },

  // Hook: runs after successful auth
  afterAuth: (auth, req, res) => {
    console.log(`User ${auth.userId} accessed ${req.path}`);
  },

  // JWKS endpoint for ES256 token verification (optional)
  jwksUrl: "https://apiauth.inai.dev/.well-known/jwks.json",

  // InAIAuthClient config (optional if using env vars)
  publishableKey: process.env.INAI_PUBLISHABLE_KEY,
});

All tokens are cryptographically verified using ES256 (ECDSA P-256). Public keys are fetched from the JWKS endpoint and cached for 5 minutes.

2. Route Protection (RBAC)

import { requireAuth } from "@inai-dev/express/middleware";

// Require any authenticated user
app.get("/api/profile", requireAuth(), (req, res) => {
  res.json({ userId: req.auth!.userId });
});

// Require a specific role
app.get("/api/admin", requireAuth({ role: "admin" }), (req, res) => {
  res.json({ message: "Admin area" });
});

// Require a specific permission
app.post("/api/posts", requireAuth({ permission: "posts:write" }), (req, res) => {
  res.json({ message: "Post created" });
});

requireAuth() returns:

  • 401 if no req.auth or no userId
  • 403 if the user lacks the required role or permission

3. API Routes

import { createAuthRoutes } from "@inai-dev/express/api-routes";

app.use("/api/auth", createAuthRoutes({
  publishableKey: process.env.INAI_PUBLISHABLE_KEY,
}));

Note: Requires express.json() middleware to parse request bodies.

Handles the following endpoints automatically:

  • POST /api/auth/login — User login (returns { user } or { mfa_required, mfa_token })
  • POST /api/auth/register — User registration
  • POST /api/auth/mfa-challenge — MFA verification
  • POST /api/auth/refresh — Token refresh
  • POST /api/auth/logout — User logout

4. Auth Helpers

getAuth(req)

Returns the AuthObject from the request (populated by middleware).

import { getAuth } from "@inai-dev/express";

app.get("/api/me", (req, res) => {
  const auth = getAuth(req);
  if (!auth?.userId) {
    return res.status(401).json({ error: "Not signed in" });
  }
  res.json({ userId: auth.userId, orgId: auth.orgId });
});

AuthObject:

Property Type Description
userId string | null Current user ID
tenantId string | null Tenant ID
appId string | null Application ID
envId string | null Environment ID
orgId string | null Active organization ID
orgRole string | null Role in active organization
sessionId string | null Session ID
roles string[] User's global roles
permissions string[] User's global permissions
getToken() () => Promise<string | null> Get the access token
has(params) ({ role?, permission? }) => boolean Check role or permission

For advanced use cases (custom auth flows, manual token management):

import { setAuthCookies, clearAuthCookies } from "@inai-dev/express";

// Set auth cookies after manual authentication
setAuthCookies(res, tokens, user);

// Clear all auth cookies (manual logout)
clearAuthCookies(res);

Token Extraction

import { getTokenFromRequest, getRefreshTokenFromRequest } from "@inai-dev/express";

// Get access token from Authorization header or cookies
const token = getTokenFromRequest(req);

// Get refresh token from cookies
const refreshToken = getRefreshTokenFromRequest(req);

Full Example

import express from "express";
import {
  inaiAuthMiddleware,
  requireAuth,
  createAuthRoutes,
  getAuth,
} from "@inai-dev/express";

const app = express();
app.use(express.json());

// Auth middleware — protects all routes except public ones
app.use(
  inaiAuthMiddleware({
    publicRoutes: ["/", "/health", "/api/auth/*"],
  })
);

// Auth API routes
app.use("/api/auth", createAuthRoutes());

// Public route
app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

// Protected route — any authenticated user
app.get("/api/profile", (req, res) => {
  const auth = getAuth(req);
  res.json({ userId: auth?.userId });
});

// Protected route — admin only
app.get("/api/admin", requireAuth({ role: "admin" }), (req, res) => {
  res.json({ message: "Welcome, admin" });
});

app.listen(3000);

Platform Mode (Admin Panel)

For admin panels that authenticate against the InAI platform API:

app.use(
  inaiAuthMiddleware({
    authMode: "platform",
    publicRoutes: ["/login"],
  })
);

In platform mode, the middleware uses platformRefresh() and platformGetMe() for token refresh, targeting the platform auth endpoints instead of app user endpoints.

Exports Reference

@inai-dev/express

Export Kind Description
inaiAuthMiddleware Function Auth middleware
requireAuth Function RBAC route guard
createAuthRoutes Function Auth API route handlers
getAuth Function Get AuthObject from request
setAuthCookies Function Set auth cookies
clearAuthCookies Function Clear auth cookies
getTokenFromRequest Function Extract access token
getRefreshTokenFromRequest Function Extract refresh token

@inai-dev/express/middleware

Export Kind Description
inaiAuthMiddleware Function Auth middleware with token refresh
requireAuth Function RBAC route guard

@inai-dev/express/api-routes

Export Kind Description
createAuthRoutes Function Create Express Router with auth endpoints

Exported Types

import type {
  InAIExpressMiddlewareConfig,
  RequireAuthConfig,
} from "@inai-dev/express";

import type {
  AuthObject,
  UserResource,
  OrganizationResource,
} from "@inai-dev/express";

Questions & Support

Visit https://inai.dev for documentation, guides, and support.

License

MIT