@davydko-mtas/express

Express BFF SDK for MTAS — drop-in OAuth2-inspired authentication for tenant backends. Handles the full server-side login flow: state-CSRF protection, encrypted-cookie sessions, JWKS-based JWT verification, refresh token rotation, and logout token revocation.

Mounts /login, /callback, /logout, /me, /users on your router. Exposes a requireAuth-style middleware for protecting your own routes.

Install

npm install @davydko-mtas/express cookie-parser

cookie-parser is required at runtime (the SDK reads req.cookies). express ≥ 4 must already be installed.

Quick start

const express = require('express');
const cookieParser = require('cookie-parser');
const { createMtasAuth } = require('@davydko-mtas/express');

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

const { mtasRouter, authMiddleware } = createMtasAuth({
  mtasApiUrl: process.env.MTAS_URL,
  mtasUiUrl: process.env.MTAS_FE_URL,
  mtasAppId: process.env.MTAS_APP_ID,
  mtasSecret: process.env.MTAS_SECRET,
  redirectUri: process.env.MTAS_REDIRECT_URI,
  encryptionPassword: process.env.ENCRYPTION_PASSWORD,
  frontendUrl: process.env.APP_FE_URL,
  secureCookies: process.env.NODE_ENV === 'production',
  routerBasePath: '/auth',
});

app.use('/auth', mtasRouter);

// Your protected routes
app.get('/protected', authMiddleware, (req, res) => {
  res.json(req.user);
});

app.listen(3000);

Routes mounted by mtasRouter

| Method | Path | Protected | Description | | ------ | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | GET | /login | no | Sets state CSRF cookie, redirects user to MTAS login page. | | GET | /callback | no | Validates state, exchanges auth code for tokens (server-to-server), seals tokens into encrypted session cookie, redirects to frontendUrl. | | POST | /logout | yes | Revokes refresh token at MTAS, clears session cookie. | | GET | /me | yes | Proxies to MTAS /user-auth/authenticated-user. | | GET | /users | yes | Proxies to MTAS /users (tenant's user list). |

authMiddleware

Attaches authenticated user data to the request:

req.user; // { id, aud, type }  — see MtasUser
req.accessToken; // raw JWT (for forwarding to MTAS)
req.refreshToken; // refresh token (rotates per refresh)

Behavior:

• Verifies the access token locally using MTAS's JWKS (cached in-process, 10 min TTL).
• On verify failure (typical: token expired), automatically calls MTAS to refresh — concurrent requests for the same refresh token are deduplicated so MTAS is hit once.
• On any auth failure throws an HTTP error with .status = 401 (your global error handler should respond accordingly).

How the BFF flow works

1. Browser → your /auth/login → SDK sets state CSRF cookie, redirects to MTAS UI.
2. User authenticates on MTAS UI → MTAS redirects to your /auth/callback?auth_code=...&state=....
3. SDK validates state, exchanges code for tokens server-to-server (HTTP Basic, using your mtasSecret). Tokens never reach the browser.
4. SDK seals { access_token, refresh_token } into an encrypted cookie (iron-session, AES-256-GCM).
5. Subsequent requests → authMiddleware unseals the cookie, verifies the JWT locally via cached JWKS, attaches req.user.

Config reference

All fields required. Hover the Config type in your IDE to see per-field descriptions.

| Field | Description | | -------------------- | -------------------------------------------------------------------------------- | | mtasApiUrl | MTAS API base URL. JWKS is derived as ${mtasApiUrl}/.well-known/jwks.json. | | mtasUiUrl | MTAS UI base URL (login page). | | mtasAppId | Your tenant's MTAS App ID. | | mtasSecret | Your tenant's MTAS App secret. Server-side only. | | redirectUri | URL MTAS redirects to after user login. Must be registered in MTAS for your app. | | encryptionPassword | Cookie encryption password. Minimum 32 characters. | | frontendUrl | Where to send the user after successful login. | | secureCookies | true in production; false for local HTTP dev only. | | routerBasePath | Path you'll mount the router at (e.g. '/auth'). Used for login-fail redirects. |

Types

import type { Config, MtasUser } from '@davydko-mtas/express';

Importing the package also augments Express's Request with user, accessToken, and refreshToken (no extra import needed).

Requirements

• Node.js ≥ 18
• Express ≥ 4 (peer dependency)
• cookie-parser mounted before the SDK router

Notes

• routerBasePath must match the path you mount the SDK at via app.use(...). The SDK uses it to build the login-fail redirect URL.
• All cookies issued by the SDK are httpOnly + sameSite=lax. The Secure flag follows your secureCookies config.
• Errors thrown by the SDK have .status (number) and .message (string). Catch them in your global error handler and respond accordingly.

License

MIT