@quanticjs/auth-web-bff 4.2.0

package/dist/bff.controller.d.ts

@@ -0,0 +1,11 @@
+import { Request, Response } from 'express';
+import { BffService } from './bff.service';
+export declare class BffController {
+    private readonly bffService;
+    constructor(bffService: BffService);
+    login(returnTo: string, res: Response): void;
+    callback(code: string, state: string, req: Request, res: Response): Promise<void>;
+    refresh(req: Request, res: Response): Promise<void>;
+    logout(req: Request, res: Response): Promise<void>;
+    me(req: Request, res: Response): Promise<void>;
+}

package/dist/bff.controller.js

@@ -0,0 +1,147 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BffController = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const core_1 = require("@quanticjs/core");
+const bff_service_1 = require("./bff.service");
+const VERIFIER_COOKIE = 'pkce_verifier';
+let BffController = class BffController {
+    bffService;
+    constructor(bffService) {
+        this.bffService = bffService;
+    }
+    login(returnTo, res) {
+        const { url, codeVerifier } = this.bffService.getAuthorizationUrl(returnTo);
+        res.cookie(VERIFIER_COOKIE, codeVerifier, {
+            httpOnly: true,
+            sameSite: 'lax',
+            path: '/auth/callback',
+            maxAge: 5 * 60 * 1000,
+        });
+        res.redirect(url);
+    }
+    async callback(code, state, req, res) {
+        const codeVerifier = req.cookies?.[VERIFIER_COOKIE];
+        if (!codeVerifier || !code) {
+            res.redirect('/auth/login');
+            return;
+        }
+        res.clearCookie(VERIFIER_COOKIE, { path: '/auth/callback' });
+        try {
+            const { sessionId, returnTo } = await this.bffService.handleCallback(code, state, codeVerifier);
+            res.cookie(this.bffService.getCookieName(), sessionId, this.bffService.getCookieOptions());
+            res.redirect(returnTo);
+        }
+        catch {
+            res.redirect('/auth/login?error=callback_failed');
+        }
+    }
+    async refresh(req, res) {
+        const sessionId = req.cookies?.[this.bffService.getCookieName()];
+        if (!sessionId) {
+            res.status(401).json({ message: 'No session' });
+            return;
+        }
+        const accessToken = await this.bffService.refreshSession(sessionId);
+        if (!accessToken) {
+            res.clearCookie(this.bffService.getCookieName()).status(401).json({ message: 'Session expired' });
+            return;
+        }
+        res.json({ success: true });
+    }
+    async logout(req, res) {
+        const cookieName = this.bffService.getCookieName();
+        const sessionId = req.cookies?.[cookieName];
+        if (sessionId) {
+            await this.bffService.destroySession(sessionId);
+        }
+        res.clearCookie(cookieName, this.bffService.getCookieOptions()).json({ success: true });
+    }
+    async me(req, res) {
+        const cookieName = this.bffService.getCookieName();
+        const sessionId = req.cookies?.[cookieName];
+        if (!sessionId) {
+            res.status(401).json({ message: 'Not authenticated' });
+            return;
+        }
+        const userInfo = await this.bffService.getUserInfo(sessionId);
+        if (!userInfo) {
+            res.clearCookie(cookieName).status(401).json({ message: 'Session expired' });
+            return;
+        }
+        res.json(userInfo);
+    }
+};
+exports.BffController = BffController;
+__decorate([
+    (0, core_1.Public)(),
+    (0, common_1.Get)('login'),
+    (0, swagger_1.ApiOperation)({ summary: 'Redirect to Keycloak login' }),
+    __param(0, (0, common_1.Query)('returnTo')),
+    __param(1, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", void 0)
+], BffController.prototype, "login", null);
+__decorate([
+    (0, core_1.Public)(),
+    (0, common_1.Get)('callback'),
+    (0, swagger_1.ApiOperation)({ summary: 'OIDC callback — exchange code for tokens' }),
+    __param(0, (0, common_1.Query)('code')),
+    __param(1, (0, common_1.Query)('state')),
+    __param(2, (0, common_1.Req)()),
+    __param(3, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BffController.prototype, "callback", null);
+__decorate([
+    (0, core_1.Public)(),
+    (0, common_1.Post)('refresh'),
+    (0, common_1.HttpCode)(200),
+    (0, swagger_1.ApiOperation)({ summary: 'Refresh access token' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], BffController.prototype, "refresh", null);
+__decorate([
+    (0, core_1.Public)(),
+    (0, common_1.Post)('logout'),
+    (0, common_1.HttpCode)(200),
+    (0, swagger_1.ApiOperation)({ summary: 'Logout — clear session' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], BffController.prototype, "logout", null);
+__decorate([
+    (0, core_1.Public)(),
+    (0, common_1.Get)('me'),
+    (0, swagger_1.ApiOperation)({ summary: 'Get current user info' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], BffController.prototype, "me", null);
+exports.BffController = BffController = __decorate([
+    (0, swagger_1.ApiTags)('auth'),
+    (0, common_1.Controller)('auth'),
+    __metadata("design:paramtypes", [bff_service_1.BffService])
+], BffController);

package/dist/bff.middleware.d.ts

@@ -0,0 +1,8 @@
+import type { NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { BffService } from './bff.service';
+export declare class BffMiddleware implements NestMiddleware {
+    private readonly bffService;
+    constructor(bffService: BffService);
+    use(req: Request, _res: Response, next: NextFunction): Promise<void>;
+}

package/dist/bff.middleware.js

@@ -0,0 +1,35 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BffMiddleware = void 0;
+const common_1 = require("@nestjs/common");
+const bff_service_1 = require("./bff.service");
+let BffMiddleware = class BffMiddleware {
+    bffService;
+    constructor(bffService) {
+        this.bffService = bffService;
+    }
+    async use(req, _res, next) {
+        const sessionId = req.cookies?.[this.bffService.getCookieName()];
+        if (!sessionId)
+            return next();
+        const accessToken = await this.bffService.getAccessToken(sessionId);
+        if (accessToken) {
+            req.headers.authorization = `Bearer ${accessToken}`;
+        }
+        next();
+    }
+};
+exports.BffMiddleware = BffMiddleware;
+exports.BffMiddleware = BffMiddleware = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [bff_service_1.BffService])
+], BffMiddleware);

package/dist/bff.module.d.ts

@@ -0,0 +1,6 @@
+import { DynamicModule, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import { type BffModuleOptions } from './interfaces';
+export declare class BffModule implements NestModule {
+    static forRoot(options: BffModuleOptions): DynamicModule;
+    configure(consumer: MiddlewareConsumer): void;
+}

package/dist/bff.module.js

@@ -0,0 +1,36 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var BffModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BffModule = void 0;
+const common_1 = require("@nestjs/common");
+const bff_controller_1 = require("./bff.controller");
+const bff_service_1 = require("./bff.service");
+const bff_middleware_1 = require("./bff.middleware");
+const interfaces_1 = require("./interfaces");
+let BffModule = BffModule_1 = class BffModule {
+    static forRoot(options) {
+        return {
+            module: BffModule_1,
+            controllers: [bff_controller_1.BffController],
+            providers: [
+                { provide: interfaces_1.BFF_OPTIONS, useValue: options },
+                bff_service_1.BffService,
+            ],
+            exports: [bff_service_1.BffService],
+            global: true,
+        };
+    }
+    configure(consumer) {
+        consumer.apply(bff_middleware_1.BffMiddleware).forRoutes('*');
+    }
+};
+exports.BffModule = BffModule;
+exports.BffModule = BffModule = BffModule_1 = __decorate([
+    (0, common_1.Module)({})
+], BffModule);

package/dist/bff.service.d.ts

@@ -0,0 +1,33 @@
+import { OnModuleInit } from '@nestjs/common';
+import type { Redis } from 'ioredis';
+import { type BffModuleOptions, type SessionData } from './interfaces';
+export declare class BffService implements OnModuleInit {
+    private readonly options;
+    private readonly redis;
+    private client;
+    private internalKeycloakBase;
+    private publicKeycloakBase;
+    private readonly sessionTtl;
+    private readonly sessionPrefix;
+    private readonly cookieName;
+    constructor(options: BffModuleOptions, redis: Redis | undefined);
+    onModuleInit(): Promise<void>;
+    getAuthorizationUrl(returnTo?: string): {
+        url: string;
+        codeVerifier: string;
+    };
+    handleCallback(code: string, state: string, codeVerifier: string): Promise<{
+        sessionId: string;
+        returnTo: string;
+    }>;
+    getSession(sessionId: string): Promise<SessionData | null>;
+    getAccessToken(sessionId: string): Promise<string | null>;
+    refreshSession(sessionId: string, session?: SessionData): Promise<string | null>;
+    destroySession(sessionId: string): Promise<void>;
+    getUserInfo(sessionId: string): Promise<Record<string, unknown> | null>;
+    getCookieOptions(): Record<string, unknown>;
+    getCookieName(): string;
+    private saveSession;
+    private toPublicKeycloakUrl;
+    private getCallbackUrl;
+}

package/dist/bff.service.js

@@ -0,0 +1,193 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BffService = void 0;
+const common_1 = require("@nestjs/common");
+const openid_client_1 = require("openid-client");
+const uuid_1 = require("uuid");
+const core_1 = require("@quanticjs/core");
+const interfaces_1 = require("./interfaces");
+let BffService = class BffService {
+    options;
+    redis;
+    client;
+    internalKeycloakBase;
+    publicKeycloakBase;
+    sessionTtl;
+    sessionPrefix;
+    cookieName;
+    constructor(options, redis) {
+        this.options = options;
+        this.redis = redis;
+        this.sessionTtl = options.session?.ttlSeconds ?? 7 * 24 * 3600;
+        this.sessionPrefix = options.session?.prefix ?? 'session:';
+        this.cookieName = options.session?.cookieName ?? 'sid';
+    }
+    async onModuleInit() {
+        const { keycloak } = this.options;
+        this.publicKeycloakBase = keycloak.url;
+        this.internalKeycloakBase = keycloak.internalUrl ?? keycloak.url;
+        const issuerUrl = `${this.internalKeycloakBase}/realms/${keycloak.realm}`;
+        const issuer = await openid_client_1.Issuer.discover(issuerUrl);
+        this.client = new issuer.Client({
+            client_id: keycloak.clientId,
+            client_secret: keycloak.clientSecret,
+            redirect_uris: [this.getCallbackUrl()],
+            response_types: ['code'],
+        });
+    }
+    getAuthorizationUrl(returnTo) {
+        const state = Buffer.from(JSON.stringify({ returnTo: returnTo || '/' })).toString('base64url');
+        const codeVerifier = openid_client_1.generators.codeVerifier();
+        const codeChallenge = openid_client_1.generators.codeChallenge(codeVerifier);
+        let url = this.client.authorizationUrl({
+            scope: 'openid email profile',
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+        });
+        url = this.toPublicKeycloakUrl(url);
+        return { url, codeVerifier };
+    }
+    async handleCallback(code, state, codeVerifier) {
+        const tokenSet = await this.client.callback(this.getCallbackUrl(), { code, state, iss: this.client.issuer.metadata.issuer }, { code_verifier: codeVerifier, state });
+        const claims = tokenSet.claims();
+        const sessionId = (0, uuid_1.v4)();
+        const sessionData = {
+            accessToken: tokenSet.access_token,
+            refreshToken: tokenSet.refresh_token,
+            idToken: tokenSet.id_token,
+            expiresAt: tokenSet.expires_at ?? Math.floor(Date.now() / 1000) + 300,
+            keycloakId: claims.sub,
+            email: claims.email ?? '',
+            displayName: claims.name ?? claims.preferred_username ?? '',
+            roles: claims.realm_access
+                ? claims.realm_access.roles
+                : [],
+            username: claims.preferred_username,
+        };
+        await this.saveSession(sessionId, sessionData);
+        let returnTo = '/';
+        try {
+            const parsed = JSON.parse(Buffer.from(state, 'base64url').toString());
+            returnTo = parsed.returnTo || '/';
+        }
+        catch {
+            // ignore
+        }
+        return { sessionId, returnTo };
+    }
+    async getSession(sessionId) {
+        if (!this.redis)
+            return null;
+        const raw = await this.redis.get(this.sessionPrefix + sessionId);
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    async getAccessToken(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (!session)
+            return null;
+        if (Date.now() / 1000 < session.expiresAt - 30) {
+            return session.accessToken;
+        }
+        return this.refreshSession(sessionId, session);
+    }
+    async refreshSession(sessionId, session) {
+        const sess = session ?? (await this.getSession(sessionId));
+        if (!sess)
+            return null;
+        try {
+            const tokenSet = await this.client.refresh(sess.refreshToken);
+            const claims = tokenSet.claims();
+            const updated = {
+                ...sess,
+                accessToken: tokenSet.access_token,
+                refreshToken: tokenSet.refresh_token ?? sess.refreshToken,
+                idToken: tokenSet.id_token ?? sess.idToken,
+                expiresAt: tokenSet.expires_at ?? Math.floor(Date.now() / 1000) + 300,
+                roles: claims.realm_access
+                    ? claims.realm_access.roles
+                    : sess.roles,
+            };
+            await this.saveSession(sessionId, updated);
+            return updated.accessToken;
+        }
+        catch {
+            await this.destroySession(sessionId);
+            return null;
+        }
+    }
+    async destroySession(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (!this.redis)
+            return;
+        if (session?.accessToken) {
+            try {
+                await this.client.revoke(session.accessToken, 'access_token');
+            }
+            catch {
+                // best-effort revocation
+            }
+        }
+        await this.redis.del(this.sessionPrefix + sessionId);
+    }
+    async getUserInfo(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (!session)
+            return null;
+        return {
+            keycloakId: session.keycloakId,
+            email: session.email,
+            displayName: session.displayName,
+            roles: session.roles,
+            username: session.username,
+        };
+    }
+    getCookieOptions() {
+        return {
+            httpOnly: true,
+            secure: process.env.NODE_ENV === 'production',
+            sameSite: 'lax',
+            path: '/',
+            maxAge: this.sessionTtl * 1000,
+        };
+    }
+    getCookieName() {
+        return this.cookieName;
+    }
+    async saveSession(sessionId, data) {
+        if (!this.redis)
+            throw new Error('Redis not available');
+        await this.redis.setex(this.sessionPrefix + sessionId, this.sessionTtl, JSON.stringify(data));
+    }
+    toPublicKeycloakUrl(url) {
+        if (this.internalKeycloakBase === this.publicKeycloakBase)
+            return url;
+        return url.replace(this.internalKeycloakBase, this.publicKeycloakBase);
+    }
+    getCallbackUrl() {
+        const callbackPath = this.options.callbackPath ?? '/auth/callback';
+        return `${this.options.publicUrl}${callbackPath}`;
+    }
+};
+exports.BffService = BffService;
+exports.BffService = BffService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(interfaces_1.BFF_OPTIONS)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(core_1.REDIS_CLIENT)),
+    __metadata("design:paramtypes", [Object, Object])
+], BffService);

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { BffModule } from './bff.module';
+export { BffService } from './bff.service';
+export { BffController } from './bff.controller';
+export { BffMiddleware } from './bff.middleware';
+export { BFF_OPTIONS } from './interfaces';
+export type { BffModuleOptions, SessionData } from './interfaces';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BFF_OPTIONS = exports.BffMiddleware = exports.BffController = exports.BffService = exports.BffModule = void 0;
+var bff_module_1 = require("./bff.module");
+Object.defineProperty(exports, "BffModule", { enumerable: true, get: function () { return bff_module_1.BffModule; } });
+var bff_service_1 = require("./bff.service");
+Object.defineProperty(exports, "BffService", { enumerable: true, get: function () { return bff_service_1.BffService; } });
+var bff_controller_1 = require("./bff.controller");
+Object.defineProperty(exports, "BffController", { enumerable: true, get: function () { return bff_controller_1.BffController; } });
+var bff_middleware_1 = require("./bff.middleware");
+Object.defineProperty(exports, "BffMiddleware", { enumerable: true, get: function () { return bff_middleware_1.BffMiddleware; } });
+var interfaces_1 = require("./interfaces");
+Object.defineProperty(exports, "BFF_OPTIONS", { enumerable: true, get: function () { return interfaces_1.BFF_OPTIONS; } });

package/dist/interfaces.d.ts

@@ -0,0 +1,28 @@
+export interface BffModuleOptions {
+    keycloak: {
+        url: string;
+        internalUrl?: string;
+        realm: string;
+        clientId: string;
+        clientSecret: string;
+    };
+    session?: {
+        ttlSeconds?: number;
+        cookieName?: string;
+        prefix?: string;
+    };
+    publicUrl: string;
+    callbackPath?: string;
+}
+export interface SessionData {
+    accessToken: string;
+    refreshToken: string;
+    idToken?: string;
+    expiresAt: number;
+    keycloakId: string;
+    email: string;
+    displayName: string;
+    roles: string[];
+    username?: string;
+}
+export declare const BFF_OPTIONS: unique symbol;

package/dist/interfaces.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BFF_OPTIONS = void 0;
+exports.BFF_OPTIONS = Symbol('BFF_OPTIONS');

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@quanticjs/auth-web-bff",
+  "version": "4.2.0",
+  "description": "BFF authentication module — Keycloak OIDC, Redis sessions, httpOnly cookies",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@quanticjs/core": "^4.2.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/config": "^3.0.0 || ^4.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@nestjs/swagger": "^7.0.0 || ^11.0.0",
+    "cookie-parser": "^1.4.0",
+    "express": "^4.18.0 || ^5.0.0",
+    "ioredis": "^5.0.0",
+    "openid-client": "^5.7.0",
+    "uuid": "^9.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT"
+}