@appdirect/auth-bff

AppDirect OIDC Backend-for-Frontend (BFF) SDK for Node.js backends.

This package extracts AppDirect OAuth2/OIDC login, FEJWT session management, and token refresh into a reusable library. The browser never sees client secrets — only HttpOnly cookies and controlled API endpoints.

Features

• Authorization Code flow with AppDirect (/oauth2/authorize, /oauth2/token, /oauth2/userinfo)
• AppDirect session exchange (/auth/token, /auth/refresh) for application session tokens
• FEJWT-as-session — session cookie stores the AppDirect FEJWT (~5 min TTL)
• Lazy auto-refresh — refreshes FEJWT only when expired (~once per TTL), via ensureValidFeJwt()
• Single-flight refresh — concurrent requests share one IdP refresh per warm instance
• Refresh token rotation via HttpOnly refresh_token cookie
• OAuth state CSRF protection via short-lived oauth_state cookie
• CHIPS (Partitioned) cookies for cross-site iframe embeds (preview, shared links)
• Framework-agnostic core + optional adapters for Next.js and Node route handlers
• Full TypeScript types

Install

Published to the public npm registry:

npm install @appdirect/auth-bff

For local development against this repo:

npm install file:../appdirect-auth-bff

Or install from a packed tarball:

npm install ./appdirect-auth-bff-0.0.1.tgz

Quick start — core SDK

Use createAppDirectAuth() in any Node 18+ backend. Flows return data (cookies, redirects, user) — you wire HTTP yourself:

import { createAppDirectAuth } from '@appdirect/auth-bff';

const auth = createAppDirectAuth({
  issuerBaseUrl: process.env.APPDIRECT_ISSUER_BASE_URL!,
  clientId: process.env.APPDIRECT_CLIENT_ID!,
  clientSecret: process.env.APPDIRECT_CLIENT_SECRET!,
  appBaseUrl: process.env.APP_BASE_URL ?? 'http://localhost:3000',
});

// Login: auth.buildLoginRedirect() → authorizeUrl + cookiesToSet
// Callback: auth.handleCallback({ code, state, cookies })
// Session: auth.getMe(), auth.getFeJwt(), auth.refreshSession()

See Usage Reference for the full API.

Quick start — Next.js App Router

1. Configure auth (lib/auth.ts):

import { createNextAuthHandlers } from '@appdirect/auth-bff/next';

export const authHandlers = createNextAuthHandlers({
  issuerBaseUrl: process.env.APPDIRECT_ISSUER_BASE_URL!,
  clientId: process.env.APPDIRECT_CLIENT_ID!,
  clientSecret: process.env.APPDIRECT_CLIENT_SECRET!,
  appBaseUrl: process.env.NEXT_PUBLIC_APP_URL ?? 'http://localhost:3000',
});

2. Add route handlers (app/api/auth/login/route.ts):

import { authHandlers } from '@/lib/auth';
export const GET = (req: Request) => authHandlers.login(req);

Repeat for callback, me, jwt, refresh, and logout — see examples/nextjs-app-router.

Requires next as a peer dependency. On Vercel, set NEXT_PUBLIC_APP_URL to your public deployment URL so post-login redirects use the correct origin.

Quick start — Node API route handlers

For file-based api/auth/* routes or any Node (req, res) serverless handler:

import { createAuthRouteHandlers } from '@appdirect/auth-bff/handlers';

export const handlers = createAuthRouteHandlers({
  issuerBaseUrl: process.env.APPDIRECT_ISSUER_BASE_URL,
  clientId: process.env.APPDIRECT_CLIENT_ID,
  clientSecret: process.env.APPDIRECT_CLIENT_SECRET,
  appBaseUrl: process.env.APP_BASE_URL ?? process.env.BASE_URL ?? 'http://localhost:3000',
  // Cross-site iframe embeds (preview, shared links):
  cookieOptions: { partitioned: true },
});

export default function handler(req, res) {
  return handlers.login(req, res);
}

See examples/handlers.

Custom API routes (e.g. marketplace proxies) can use readAuthCookies and applyCookieMutations from @appdirect/auth-bff/handlers — see Custom API routes in the Usage Reference.

The appdirect-auth-example repo is a full reference app (Next.js UI, Users API, subscription management).

Cross-site iframe embeds

When the app runs inside a third-party iframe (e.g. App Builder preview or a shared-link viewer), enable CHIPS cookies:

cookieOptions: { partitioned: true }

The SDK then forces Secure and defaults SameSite to None (required for third-party contexts). See cookieOptions in the Usage Reference.

Environment variables

| Variable | Description | |----------|-------------| | APPDIRECT_ISSUER_BASE_URL | Marketplace base URL (no trailing slash) | | APPDIRECT_CLIENT_ID | OAuth client ID | | APPDIRECT_CLIENT_SECRET | OAuth client secret | | APP_BASE_URL / BASE_URL | App origin for OAuth redirect URI | | NEXT_PUBLIC_APP_URL | Next.js public app URL (required on Vercel) | | AUTH_BFF_DEBUG | Set to true to enable opt-in [auth-bff:jwt] / [auth-bff:refresh] debug logs |

Register callback: {APP_URL}/api/auth/callback

API routes provided by adapters

| Route | Method | Purpose | |-------|--------|---------| | /api/auth/login | GET | Redirect to AppDirect authorize | | /api/auth/callback | GET | OAuth callback, set session cookies | | /api/auth/me | GET | Current user from FEJWT session | | /api/auth/jwt | GET | FEJWT for Global Header (auto-refresh) | | /api/auth/refresh | GET/POST | Manual token refresh | | /api/auth/logout | GET/POST | Clear session cookies | | /api/auth/import-session | POST | Import session tokens into HttpOnly cookies (iframe preview handoff) |

Documentation

• Architecture — design, flows, cookie model, security
• Implementation Guide — step-by-step integration
• Usage Reference — full API, config options, error codes

Development

npm install
npm run build
npm test
npm run typecheck

Examples

• examples/nextjs-app-router — Next.js 15 App Router (minimal)
• examples/handlers — Node API route handlers
• appdirect-auth-example — Next.js reference app (Users + Billing API demos)

License

MIT