@mahulu/sso-client 1.0.0

package/README.md

@@ -0,0 +1,401 @@
+# SSO Mahulu - Node.js Client Package
+
+> Node.js SDK untuk integrasi OAuth 2.0 dengan SSO Mahulu (Identity Provider Pemerintah Mahulu Hulu)
+
+## Persyaratan
+
+- Node.js >= 16.x
+- OAuth Client Credentials dari admin SSO Mahulu
+
+## Instalasi
+
+```bash
+npm install @mahulu/sso-client
+
+# Jika menggunakan Express.js:
+npm install express express-session
+```
+
+## Quick Start (Express.js)
+
+### 1. Setup Express + SSO
+
+```javascript
+const express = require('express');
+const session = require('express-session');
+const { createExpressMiddleware } = require('@mahulu/sso-client');
+
+const app = express();
+
+// Setup session (wajib)
+app.use(
+    session({
+        secret: 'your-random-secret-key',
+        resave: false,
+        saveUninitialized: false,
+        cookie: { secure: process.env.NODE_ENV === 'production' },
+    }),
+);
+
+// Setup SSO
+const sso = createExpressMiddleware({
+    baseUrl: process.env.SSO_MAHULU_BASE_URL, // https://sso.mahulu.go.id
+    clientId: process.env.SSO_MAHULU_CLIENT_ID, // dari admin SSO
+    clientSecret: process.env.SSO_MAHULU_CLIENT_SECRET, // dari admin SSO
+    redirectUri: process.env.SSO_MAHULU_REDIRECT_URI, // http://localhost:3000/auth/sso/callback
+    redirectAfterLogin: '/dashboard',
+    redirectOnError: '/login',
+});
+
+// Register routes
+app.get('/auth/sso/redirect', sso.redirect); // Redirect ke SSO
+app.get('/auth/sso/callback', sso.callback); // Handle callback
+app.post('/auth/sso/logout', sso.logout); // Logout
+```
+
+### 2. Environment Variables
+
+Buat file `.env`:
+
+```env
+SSO_MAHULU_BASE_URL=https://sso.mahulu.go.id
+SSO_MAHULU_CLIENT_ID=your-client-id-dari-admin
+SSO_MAHULU_CLIENT_SECRET=your-client-secret-dari-admin
+SSO_MAHULU_REDIRECT_URI=http://localhost:3000/auth/sso/callback
+```
+
+### 3. Tombol Login di Frontend
+
+```html
+<a href="/auth/sso/redirect">Login dengan SSO Mahulu</a>
+```
+
+### 4. Protected Routes
+
+```javascript
+// Middleware auth check
+function requireAuth(req, res, next) {
+    if (!req.session.ssoUser) {
+        return res.redirect('/login');
+    }
+    next();
+}
+
+// Protected route + auto-refresh token
+app.get('/dashboard', requireAuth, sso.ensureTokenValid, (req, res) => {
+    const user = req.session.ssoUser;
+    res.json({ message: `Selamat datang, ${user.name}!`, user });
+});
+```
+
+### 5. Logout
+
+```html
+<form
+    method="POST"
+    action="/auth/sso/logout"
+>
+    <button type="submit">Logout</button>
+</form>
+```
+
+## Penggunaan Lanjutan
+
+### Custom onSuccess Handler
+
+Gunakan `onSuccess` untuk menyimpan user ke database:
+
+```javascript
+const sso = createExpressMiddleware({
+    // ... config
+    onSuccess: async (req, user, tokens) => {
+        // Simpan/update user di database
+        const dbUser = await User.findOneAndUpdate(
+            { nip: user.nip },
+            {
+                name: user.name,
+                email: user.email,
+                nip: user.nip,
+                ssoAccessToken: tokens.access_token,
+                ssoRefreshToken: tokens.refresh_token,
+                tokenExpiresAt: new Date(Date.now() + tokens.expires_in * 1000),
+            },
+            { upsert: true, new: true },
+        );
+
+        // Simpan di session
+        req.session.user = dbUser;
+        req.session.ssoTokens = {
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            expiresAt: new Date(Date.now() + tokens.expires_in * 1000).toISOString(),
+        };
+    },
+});
+```
+
+### Custom onError Handler
+
+```javascript
+const sso = createExpressMiddleware({
+    // ... config
+    onError: (req, res, error) => {
+        console.error('[SSO Error]', error.message);
+
+        // Render error page atau redirect
+        res.status(400).render('login', {
+            error: 'Login SSO gagal. Silakan coba lagi.',
+        });
+    },
+});
+```
+
+### Menggunakan SsoMahuluClient Langsung (Tanpa Express)
+
+Untuk framework lain (Fastify, Hapi, NestJS, dll):
+
+```javascript
+const { SsoMahuluClient } = require('@mahulu/sso-client');
+
+const sso = new SsoMahuluClient({
+    baseUrl: 'https://sso.mahulu.go.id',
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    redirectUri: 'http://localhost:3000/auth/sso/callback',
+});
+
+// 1. Generate state & redirect URL
+const state = sso.generateState();
+// Simpan state di session/store
+const authUrl = sso.getAuthorizationUrl(state);
+// Redirect user ke authUrl
+
+// 2. Di callback handler
+const tokens = await sso.exchangeCodeForToken(code);
+
+// 3. Get user info
+const user = await sso.getUserInfo(tokens.access_token);
+
+// 4. Refresh token jika expired
+if (sso.isTokenExpired(storedExpiresAt)) {
+    const newTokens = await sso.refreshToken(storedRefreshToken);
+}
+
+// 5. Logout URL
+const logoutUrl = sso.getLogoutUrl();
+```
+
+### Integrasi dengan NestJS
+
+```typescript
+// sso.module.ts
+import { Module } from '@nestjs/common';
+import { SsoMahuluClient } from '@mahulu/sso-client';
+
+@Module({
+    providers: [
+        {
+            provide: 'SSO_CLIENT',
+            useFactory: () =>
+                new SsoMahuluClient({
+                    baseUrl: process.env.SSO_MAHULU_BASE_URL,
+                    clientId: process.env.SSO_MAHULU_CLIENT_ID,
+                    clientSecret: process.env.SSO_MAHULU_CLIENT_SECRET,
+                    redirectUri: process.env.SSO_MAHULU_REDIRECT_URI,
+                }),
+        },
+    ],
+    exports: ['SSO_CLIENT'],
+})
+export class SsoModule {}
+
+// sso.controller.ts
+import { Controller, Get, Inject, Query, Req, Res, Session } from '@nestjs/common';
+import { SsoMahuluClient } from '@mahulu/sso-client';
+
+@Controller('auth/sso')
+export class SsoController {
+    constructor(@Inject('SSO_CLIENT') private sso: SsoMahuluClient) {}
+
+    @Get('redirect')
+    redirect(@Session() session: any, @Res() res: any) {
+        const state = this.sso.generateState();
+        session.ssoState = state;
+        res.redirect(this.sso.getAuthorizationUrl(state));
+    }
+
+    @Get('callback')
+    async callback(
+        @Query('code') code: string,
+        @Query('state') state: string,
+        @Session() session: any,
+        @Res() res: any,
+    ) {
+        if (state !== session.ssoState) {
+            return res.redirect('/login?error=invalid_state');
+        }
+
+        const tokens = await this.sso.exchangeCodeForToken(code);
+        const user = await this.sso.getUserInfo(tokens.access_token);
+
+        session.user = user;
+        session.tokens = tokens;
+
+        res.redirect('/dashboard');
+    }
+}
+```
+
+### Integrasi dengan Next.js (API Routes)
+
+```javascript
+// pages/api/auth/sso/redirect.js
+import { SsoMahuluClient } from '@mahulu/sso-client';
+
+const sso = new SsoMahuluClient({
+    baseUrl: process.env.SSO_MAHULU_BASE_URL,
+    clientId: process.env.SSO_MAHULU_CLIENT_ID,
+    clientSecret: process.env.SSO_MAHULU_CLIENT_SECRET,
+    redirectUri: process.env.SSO_MAHULU_REDIRECT_URI,
+});
+
+export default function handler(req, res) {
+    const state = sso.generateState();
+    // Simpan state di cookie
+    res.setHeader('Set-Cookie', `sso_state=${state}; Path=/; HttpOnly; SameSite=Lax`);
+    res.redirect(302, sso.getAuthorizationUrl(state));
+}
+
+// pages/api/auth/sso/callback.js
+export default async function handler(req, res) {
+    const { code, state } = req.query;
+    // Validasi state dari cookie...
+
+    const tokens = await sso.exchangeCodeForToken(code);
+    const user = await sso.getUserInfo(tokens.access_token);
+
+    // Set JWT atau session cookie
+    // ...
+
+    res.redirect(302, '/dashboard');
+}
+```
+
+## API Reference
+
+### `SsoMahuluClient`
+
+| Method                           | Parameter              | Return                   | Deskripsi                 |
+| -------------------------------- | ---------------------- | ------------------------ | ------------------------- |
+| `generateState(length?)`         | `number` (default: 32) | `string`                 | Generate random state     |
+| `getAuthorizationUrl(state)`     | `string`               | `string`                 | Build authorization URL   |
+| `exchangeCodeForToken(code)`     | `string`               | `Promise<TokenResponse>` | Exchange code untuk token |
+| `getUserInfo(accessToken)`       | `string`               | `Promise<SsoUser>`       | Get user info             |
+| `refreshToken(refreshToken)`     | `string`               | `Promise<TokenResponse>` | Refresh expired token     |
+| `getLogoutUrl()`                 | -                      | `string`                 | Build SSO logout URL      |
+| `isTokenExpired(expiresAt)`      | `Date\|string\|number` | `boolean`                | Check token expired       |
+| `calculateExpiryDate(expiresIn)` | `number` (seconds)     | `Date`                   | Calculate expiry date     |
+
+### `createExpressMiddleware(options)`
+
+Returns object with handlers:
+
+| Handler            | Tipe                     | Deskripsi                  |
+| ------------------ | ------------------------ | -------------------------- |
+| `redirect`         | `(req, res)`             | Redirect ke SSO login      |
+| `callback`         | `async (req, res)`       | Handle callback SSO        |
+| `logout`           | `(req, res)`             | Logout + redirect ke SSO   |
+| `ensureTokenValid` | `async (req, res, next)` | Middleware auto-refresh    |
+| `client`           | `SsoMahuluClient`        | Underlying client instance |
+
+### User Data dari SSO
+
+```typescript
+interface SsoUser {
+    id: number;
+    nip: string; // "199001012020121001"
+    name: string; // "Budi Santoso"
+    email: string; // "budi.santoso@mahulu.go.id"
+    username: string; // "199001012020121001"
+    is_active: boolean; // true
+    api_hub_data: {
+        // Data tambahan dari API Hub
+        jabatan?: string; // "Kepala Bidang Kepegawaian"
+        unit_kerja?: string; // "Badan Kepegawaian Daerah"
+        pangkat_golongan?: string;
+        eselon?: string;
+    } | null;
+    created_at: string;
+    updated_at: string;
+}
+```
+
+### Token Expiration
+
+| Token              | Durasi   |
+| ------------------ | -------- |
+| Access Token       | 60 menit |
+| Refresh Token      | 14 hari  |
+| Authorization Code | 10 menit |
+
+## Fitur
+
+- **Zero dependencies** - Hanya menggunakan built-in Node.js modules (`http`, `https`, `crypto`)
+- **TypeScript support** - Type definitions included
+- **Express middleware** - Plug-and-play untuk Express.js
+- **Framework agnostic** - `SsoMahuluClient` class bisa digunakan dengan framework apapun
+- **Auto token refresh** - Middleware `ensureTokenValid` otomatis refresh expired token
+- **CSRF protection** - State parameter validation built-in
+
+## Mendapatkan OAuth Client Credentials
+
+1. Hubungi admin SSO Mahulu di `admin-sso@mahulu.go.id`
+2. Sertakan: nama aplikasi, redirect URI, PIC
+3. Terima `CLIENT_ID` & `CLIENT_SECRET`
+
+**PENTING:** `CLIENT_SECRET` hanya ditampilkan SATU KALI. Simpan dengan aman.
+
+## Troubleshooting
+
+### "Invalid state parameter"
+
+- Session mungkin expired. Pastikan `express-session` dikonfigurasi dengan benar.
+- Pastikan `resave: false` dan `saveUninitialized: false`.
+
+### "SSO connection failed"
+
+- Pastikan `SSO_MAHULU_BASE_URL` benar dan server SSO bisa diakses.
+- Check firewall/network connectivity.
+
+### "Client authentication failed"
+
+- Verify `CLIENT_ID` dan `CLIENT_SECRET` sudah benar.
+- Check apakah client ter-revoke di admin panel SSO.
+
+### CORS Error (jika frontend SPA)
+
+- Pastikan domain aplikasi sudah ditambahkan di CORS config server SSO.
+- Token exchange harus dilakukan di backend, bukan di browser.
+
+## Struktur Package
+
+```
+sso-mahulu-node/
+├── package.json
+├── README.md
+├── .gitignore
+├── src/
+│   ├── index.js          # Main module (SsoMahuluClient + Express middleware)
+│   └── index.d.ts        # TypeScript type definitions
+└── examples/
+    └── express-example.js # Contoh lengkap Express.js
+```
+
+## Lisensi
+
+MIT License
+
+## Support
+
+- Email: support@mahulu.go.id
+- Admin SSO: admin-sso@mahulu.go.id

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mahulu/sso-client",
+  "version": "1.0.0",
+  "description": "Node.js SDK untuk integrasi OAuth 2.0 dengan SSO Mahulu",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "keywords": [
+    "sso",
+    "oauth2",
+    "mahulu",
+    "authentication",
+    "nodejs",
+    "express"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Tysoft",
+    "email": "support@mahulu.go.id"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0",
+    "express-session": ">=1.17.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "express-session": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/nocash/sso-mahulu-nodejs-package.git"
+  },
+  "homepage": "https://gitlab.com/nocash/sso-mahulu-nodejs-package",
+  "bugs": {
+    "url": "https://gitlab.com/nocash/sso-mahulu-nodejs-package/issues"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * TypeScript type definitions untuk @mahulu/sso-client
+ */
+
+import { NextFunction, Request, Response } from 'express';
+
+/** Konfigurasi SSO Mahulu Client */
+export interface SsoConfig {
+    /** URL server SSO Mahulu (contoh: https://sso.mahulu.go.id) */
+    baseUrl: string;
+    /** OAuth Client ID dari admin SSO */
+    clientId: string;
+    /** OAuth Client Secret dari admin SSO */
+    clientSecret: string;
+    /** Callback URL yang didaftarkan di admin SSO */
+    redirectUri: string;
+    /** OAuth scopes (opsional) */
+    scopes?: string;
+    /** HTTP timeout dalam milliseconds (default: 30000) */
+    timeout?: number;
+}
+
+/** Response dari token exchange */
+export interface TokenResponse {
+    token_type: 'Bearer';
+    expires_in: number;
+    access_token: string;
+    refresh_token: string;
+}
+
+/** Data user dari SSO */
+export interface SsoUser {
+    id: number;
+    nip: string;
+    name: string;
+    email: string;
+    username: string;
+    is_active: boolean;
+    api_hub_data: {
+        jabatan?: string;
+        unit_kerja?: string;
+        pangkat_golongan?: string;
+        eselon?: string;
+        [key: string]: any;
+    } | null;
+    last_sync_api?: string;
+    email_verified_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+
+/** Options tambahan untuk Express middleware */
+export interface ExpressMiddlewareOptions {
+    /** Callback setelah login berhasil (untuk simpan user ke DB/session) */
+    onSuccess?: (req: Request, user: SsoUser, tokens: TokenResponse) => void | Promise<void>;
+    /** Callback saat error terjadi */
+    onError?: (req: Request, res: Response, error: Error) => void;
+    /** Path redirect setelah login sukses (default: /dashboard) */
+    redirectAfterLogin?: string;
+    /** Path redirect saat error (default: /login) */
+    redirectOnError?: string;
+}
+
+/** SSO Mahulu Client class */
+export declare class SsoMahuluClient {
+    constructor(config: SsoConfig);
+
+    /** Generate random state string untuk CSRF protection */
+    generateState(length?: number): string;
+
+    /** Build authorization URL untuk redirect ke SSO login */
+    getAuthorizationUrl(state: string): string;
+
+    /** Exchange authorization code untuk access token */
+    exchangeCodeForToken(code: string): Promise<TokenResponse>;
+
+    /** Fetch user info dari SSO menggunakan access token */
+    getUserInfo(accessToken: string): Promise<SsoUser>;
+
+    /** Refresh expired access token */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+
+    /** Build logout URL SSO */
+    getLogoutUrl(): string;
+
+    /** Check apakah token sudah expired */
+    isTokenExpired(expiresAt: Date | string | number): boolean;
+
+    /** Calculate expiry date dari expires_in (seconds) */
+    calculateExpiryDate(expiresIn: number): Date;
+}
+
+/** Express middleware handlers */
+export interface SsoExpressHandlers {
+    /** Redirect ke SSO login page */
+    redirect: (req: Request, res: Response) => void;
+    /** Handle callback dari SSO */
+    callback: (req: Request, res: Response) => Promise<void>;
+    /** Logout dan redirect ke SSO logout */
+    logout: (req: Request, res: Response) => void;
+    /** Middleware: auto-refresh expired token */
+    ensureTokenValid: (req: Request, res: Response, next: NextFunction) => Promise<void>;
+    /** Underlying SSO client instance */
+    client: SsoMahuluClient;
+}
+
+/** Create Express middleware untuk SSO Mahulu */
+export declare function createExpressMiddleware(
+    options: SsoConfig & ExpressMiddlewareOptions,
+): SsoExpressHandlers;
+
+/** Session augmentation */
+declare module 'express-session' {
+    interface SessionData {
+        ssoState?: string;
+        ssoUser?: SsoUser;
+        ssoTokens?: {
+            accessToken: string;
+            refreshToken: string;
+            expiresAt: string;
+        };
+    }
+}

package/src/index.js

@@ -0,0 +1,397 @@
+const crypto = require("crypto");
+const https = require("https");
+const http = require("http");
+const { URL, URLSearchParams } = require("url");
+
+/**
+ * SSO Mahulu Client - OAuth 2.0 Authorization Code Flow
+ *
+ * @example
+ * const { SsoMahuluClient } = require('@mahulu/sso-client');
+ *
+ * const sso = new SsoMahuluClient({
+ *   baseUrl: 'https://sso.mahulu.go.id',
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'http://localhost:3000/auth/sso/callback',
+ * });
+ */
+class SsoMahuluClient {
+  /**
+   * @param {import('./index').SsoConfig} config
+   */
+  constructor(config) {
+    if (!config.baseUrl) throw new Error("[SSO Mahulu] baseUrl is required");
+    if (!config.clientId) throw new Error("[SSO Mahulu] clientId is required");
+    if (!config.clientSecret)
+      throw new Error("[SSO Mahulu] clientSecret is required");
+    if (!config.redirectUri)
+      throw new Error("[SSO Mahulu] redirectUri is required");
+
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.redirectUri = config.redirectUri;
+    this.scopes = config.scopes || "";
+    this.timeout = config.timeout || 30000;
+  }
+
+  /**
+   * Generate random state string untuk CSRF protection.
+   * @param {number} [length=32]
+   * @returns {string}
+   */
+  generateState(length = 32) {
+    return crypto.randomBytes(length).toString("hex").slice(0, length);
+  }
+
+  /**
+   * Build authorization URL untuk redirect ke SSO login.
+   * @param {string} state - Random string untuk CSRF protection
+   * @returns {string}
+   */
+  getAuthorizationUrl(state) {
+    const params = new URLSearchParams({
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      response_type: "code",
+      scope: this.scopes,
+      state: state,
+    });
+    return `${this.baseUrl}/oauth/authorize?${params.toString()}`;
+  }
+
+  /**
+   * Exchange authorization code untuk access token.
+   * @param {string} code - Authorization code dari callback
+   * @returns {Promise<import('./index').TokenResponse>}
+   */
+  async exchangeCodeForToken(code) {
+    const body = new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      redirect_uri: this.redirectUri,
+      code: code,
+    });
+
+    const response = await this._request(
+      "POST",
+      "/oauth/token",
+      body.toString(),
+      {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+    );
+
+    return response;
+  }
+
+  /**
+   * Fetch user info dari SSO menggunakan access token.
+   * @param {string} accessToken
+   * @returns {Promise<import('./index').SsoUser>}
+   */
+  async getUserInfo(accessToken) {
+    const response = await this._request("GET", "/api/oauth/user", null, {
+      Authorization: `Bearer ${accessToken}`,
+    });
+
+    return response;
+  }
+
+  /**
+   * Refresh expired access token.
+   * @param {string} refreshToken
+   * @returns {Promise<import('./index').TokenResponse>}
+   */
+  async refreshToken(refreshToken) {
+    const body = new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      refresh_token: refreshToken,
+    });
+
+    const response = await this._request(
+      "POST",
+      "/oauth/token",
+      body.toString(),
+      {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+    );
+
+    return response;
+  }
+
+  /**
+   * Build logout URL SSO.
+   * @returns {string}
+   */
+  getLogoutUrl() {
+    return `${this.baseUrl}/oauth/logout`;
+  }
+
+  /**
+   * Check apakah token sudah expired.
+   * @param {Date|string|number} expiresAt - Waktu expiry token
+   * @returns {boolean}
+   */
+  isTokenExpired(expiresAt) {
+    if (!expiresAt) return true;
+    const expiry = expiresAt instanceof Date ? expiresAt : new Date(expiresAt);
+    return Date.now() >= expiry.getTime();
+  }
+
+  /**
+   * Calculate expiry date dari expires_in (seconds).
+   * @param {number} expiresIn - Detik sampai expired
+   * @returns {Date}
+   */
+  calculateExpiryDate(expiresIn) {
+    return new Date(Date.now() + expiresIn * 1000);
+  }
+
+  /**
+   * Internal HTTP request helper (zero dependencies).
+   * @private
+   */
+  _request(method, path, body, headers) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, this.baseUrl);
+      const isHttps = url.protocol === "https:";
+      const transport = isHttps ? https : http;
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname + url.search,
+        method: method,
+        headers: {
+          Accept: "application/json",
+          "User-Agent": "SSO-Mahulu-Node-Client/1.0",
+          ...headers,
+        },
+        timeout: this.timeout,
+      };
+
+      if (body) {
+        options.headers["Content-Length"] = Buffer.byteLength(body);
+      }
+
+      const req = transport.request(options, (res) => {
+        let data = "";
+        res.on("data", (chunk) => {
+          data += chunk;
+        });
+        res.on("end", () => {
+          try {
+            const parsed = JSON.parse(data);
+
+            if (res.statusCode >= 400) {
+              const error = new Error(
+                parsed.error_description ||
+                  parsed.message ||
+                  `SSO request failed with status ${res.statusCode}`,
+              );
+              error.statusCode = res.statusCode;
+              error.response = parsed;
+              reject(error);
+              return;
+            }
+
+            resolve(parsed);
+          } catch (e) {
+            reject(
+              new Error(`Failed to parse SSO response: ${data.slice(0, 200)}`),
+            );
+          }
+        });
+      });
+
+      req.on("error", (err) => {
+        reject(new Error(`SSO connection failed: ${err.message}`));
+      });
+
+      req.on("timeout", () => {
+        req.destroy();
+        reject(new Error(`SSO request timed out after ${this.timeout}ms`));
+      });
+
+      if (body) {
+        req.write(body);
+      }
+
+      req.end();
+    });
+  }
+}
+
+/**
+ * Express middleware factory untuk SSO Mahulu.
+ *
+ * @param {import('./index').SsoConfig & import('./index').ExpressMiddlewareOptions} options
+ * @returns {{ redirect: Function, callback: Function, logout: Function, ensureTokenValid: Function }}
+ *
+ * @example
+ * const { createExpressMiddleware } = require('@mahulu/sso-client');
+ *
+ * const sso = createExpressMiddleware({
+ *   baseUrl: process.env.SSO_MAHULU_BASE_URL,
+ *   clientId: process.env.SSO_MAHULU_CLIENT_ID,
+ *   clientSecret: process.env.SSO_MAHULU_CLIENT_SECRET,
+ *   redirectUri: process.env.SSO_MAHULU_REDIRECT_URI,
+ *   onSuccess: async (req, user, tokens) => {
+ *     // Simpan user ke session atau database
+ *     req.session.user = user;
+ *     req.session.tokens = tokens;
+ *   },
+ * });
+ *
+ * app.get('/auth/sso/redirect', sso.redirect);
+ * app.get('/auth/sso/callback', sso.callback);
+ * app.post('/auth/sso/logout', sso.logout);
+ */
+function createExpressMiddleware(options) {
+  const client = new SsoMahuluClient(options);
+
+  const onSuccess =
+    options.onSuccess ||
+    ((req, user, tokens) => {
+      req.session.ssoUser = user;
+      req.session.ssoTokens = {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt: client.calculateExpiryDate(tokens.expires_in).toISOString(),
+      };
+    });
+
+  const onError =
+    options.onError ||
+    ((req, res, error) => {
+      console.error("[SSO Mahulu]", error.message);
+      res.redirect(options.redirectOnError || "/login?error=sso_failed");
+    });
+
+  const redirectAfterLogin = options.redirectAfterLogin || "/dashboard";
+  const redirectOnError = options.redirectOnError || "/login";
+
+  return {
+    /**
+     * Redirect ke SSO login page.
+     */
+    redirect(req, res) {
+      const state = client.generateState();
+      req.session.ssoState = state;
+      res.redirect(client.getAuthorizationUrl(state));
+    },
+
+    /**
+     * Handle callback dari SSO.
+     */
+    async callback(req, res) {
+      try {
+        // Validate state
+        const savedState = req.session.ssoState;
+        delete req.session.ssoState;
+
+        if (!savedState || savedState !== req.query.state) {
+          throw new Error(
+            "Invalid state parameter. Silakan coba login kembali.",
+          );
+        }
+
+        // Check for error from SSO in Query String
+        if (req.query.error) {
+          throw new Error(
+            req.query.error_description || "SSO authorization failed.",
+          );
+        }
+
+        // Check for authorization code in Query String
+        const code = req.query.code;
+        if (!code) {
+          throw new Error("Authorization code not found.");
+        }
+
+        // Exchange code for tokens
+        const tokens = await client.exchangeCodeForToken(code);
+
+        // Get user info
+        const user = await client.getUserInfo(tokens.access_token);
+
+        // Call onSuccess handler
+        await onSuccess(req, user, tokens);
+
+        // Save session then redirect
+        req.session.save((err) => {
+          if (err) console.error("[SSO Mahulu] Session save error:", err);
+          res.redirect(redirectAfterLogin);
+        });
+      } catch (error) {
+        onError(req, res, error);
+      }
+    },
+
+    /**
+     * Logout dan redirect ke SSO logout.
+     */
+    logout(req, res) {
+      // Clear SSO data from session
+      delete req.session.ssoUser;
+      delete req.session.ssoTokens;
+
+      req.session.destroy((err) => {
+        if (err) console.error("[SSO Mahulu] Session destroy error:", err);
+        res.redirect(client.getLogoutUrl());
+      });
+    },
+
+    /**
+     * Middleware: pastikan SSO token masih valid, auto-refresh jika expired.
+     */
+    async ensureTokenValid(req, res, next) {
+      if (!req.session || !req.session.ssoTokens) {
+        return next();
+      }
+
+      const { expiresAt, refreshToken } = req.session.ssoTokens;
+
+      if (client.isTokenExpired(expiresAt)) {
+        if (!refreshToken) {
+          delete req.session.ssoUser;
+          delete req.session.ssoTokens;
+          return res.redirect(redirectOnError + "?error=session_expired");
+        }
+
+        try {
+          const newTokens = await client.refreshToken(refreshToken);
+
+          req.session.ssoTokens = {
+            accessToken: newTokens.access_token,
+            refreshToken: newTokens.refresh_token,
+            expiresAt: client
+              .calculateExpiryDate(newTokens.expires_in)
+              .toISOString(),
+          };
+        } catch (error) {
+          console.error("[SSO Mahulu] Token refresh failed:", error.message);
+          delete req.session.ssoUser;
+          delete req.session.ssoTokens;
+          return res.redirect(redirectOnError + "?error=session_expired");
+        }
+      }
+
+      next();
+    },
+
+    /** Expose the underlying client for advanced usage */
+    client,
+  };
+}
+
+module.exports = {
+  SsoMahuluClient,
+  createExpressMiddleware,
+};