@hazeljs/oauth 0.7.7 → 0.7.9

package/README.md

@@ -1,8 +1,8 @@
 # @hazeljs/oauth
 
-**"Sign in with Google" in 5 minutes.**
+**OAuth social login + native SAML SSO in one HazelJS package.**
 
-Google, Microsoft, GitHub, Facebook, Twitter — one config, ready-made routes. PKCE, user profiles, JWT integration. Built on [Arctic](https://arcticjs.dev) — 50+ providers available if you need more.
+Google, Microsoft, GitHub, Facebook, Twitter — plus native SAML IdP support for enterprise SSO. One config, ready-made routes, PKCE, user profiles, callback handler hooks, JWT integration.
 
 [![npm version](https://img.shields.io/npm/v/@hazeljs/oauth.svg)](https://www.npmjs.com/package/@hazeljs/oauth)
 [![npm downloads](https://img.shields.io/npm/dm/@hazeljs/oauth)](https://www.npmjs.com/package/@hazeljs/oauth)
@@ -10,7 +10,8 @@ Google, Microsoft, GitHub, Facebook, Twitter — one config, ready-made routes.
 
 ## Features
 
-- **Multi-Provider** — Google, Microsoft Entra ID, GitHub, Facebook, Twitter
+- **Multi-Provider OAuth** — Google, Microsoft Entra ID, GitHub, Facebook, Twitter
+- **Native SAML SP** — Multi-IdP configuration with ACS callback and metadata endpoint
 - **PKCE Support** — Automatic for Google, Microsoft, Twitter
 - **User Profile** — Fetches id, email, name, picture from provider APIs
 - **Ready-Made Routes** — Optional `/auth/:provider` and `/auth/:provider/callback`
@@ -63,6 +64,9 @@ The `OAuthController` provides:
 
 - **GET /auth/:provider** — Redirects to provider (google, microsoft, github, facebook, twitter)
 - **GET /auth/:provider/callback** — Handles callback, returns `{ accessToken, user }`
+- **GET /auth/saml/:idp** — Redirects to SAML IdP with AuthnRequest
+- **POST /auth/saml/:idp/callback** — Handles SAML ACS callback
+- **GET /auth/saml/:idp/metadata** — Returns SP metadata XML
 
 Example: User visits `/auth/google` → authenticates → callback returns tokens and profile.
 
@@ -104,6 +108,38 @@ export class AuthController {
 | Facebook | No | email, public_profile |
 | Twitter | Yes | users.read, tweet.read |
 
+## SAML Configuration (Multi-IdP)
+
+```typescript
+OAuthModule.forRoot({
+  providers: {
+    google: { ...googleConfig },
+    saml: {
+      oktaMain: {
+        idpKey: 'okta-main',
+        ssoUrl: 'https://your-org.okta.com/app/abc/sso/saml',
+        issuer: 'https://api.example.com',
+        acsUrl: 'https://api.example.com/auth/saml/okta-main/callback',
+        audience: 'https://api.example.com',
+        relayState: 'app=dashboard',
+      },
+      azureMain: {
+        idpKey: 'azure-main',
+        ssoUrl: 'https://login.microsoftonline.com/.../saml2',
+        issuer: 'https://api.example.com',
+        acsUrl: 'https://api.example.com/auth/saml/azure-main/callback',
+      },
+    },
+  },
+});
+```
+
+Use start + callback flow:
+
+1. Browser hits `GET /auth/saml/okta-main`
+2. IdP authenticates user and POSTS `SAMLResponse` to ACS callback
+3. Package parses assertion, extracts profile, then invokes optional callback handler
+
 ## Configuration
 
 ### Microsoft (optional tenant)
@@ -178,6 +214,10 @@ OAUTH_REDIRECT_URI=http://localhost:3000/auth/google/callback
 - `handleCallback(provider, code, state, codeVerifier?)` — Returns `{ accessToken, refreshToken?, expiresAt?, user }`
 - `validateState(received, stored)` — CSRF check
 - `generateState()` — Cryptographically secure state
+- `getSamlAuthorizationUrl(idpKey, relayState?)` — Returns SAML redirect URL + request ID
+- `handleSamlCallback(idpKey, samlResponseBase64, relayState?)` — Returns parsed SAML callback result
+- `getSamlMetadata(idpKey)` — Returns SP metadata XML
+- `getSamlProviderKeys()` — Returns configured SAML provider keys
 
 ### OAuthStateGuard
 

package/dist/index.d.ts

@@ -8,5 +8,5 @@ export { OAuthModule } from './oauth.module';
 export { OAuthService } from './oauth.service';
 export { OAuthController } from './oauth.controller';
 export { OAuthStateGuard } from './guards/oauth-state.guard';
-export type { OAuthModuleOptions, OAuthProvidersConfig, OAuthCallbackHandler, OAuthCallbackResult, OAuthAuthorizationResult, OAuthUser, SupportedProvider, GoogleProviderConfig, MicrosoftProviderConfig, GitHubProviderConfig, FacebookProviderConfig, TwitterProviderConfig, } from './providers/provider.types';
+export type { OAuthModuleOptions, OAuthProvidersConfig, OAuthCallbackHandler, OAuthCallbackResult, OAuthProtocolCallbackResult, OAuthAuthorizationResult, OAuthUser, SamlUser, SamlCallbackResult, SupportedProvider, GoogleProviderConfig, MicrosoftProviderConfig, GitHubProviderConfig, FacebookProviderConfig, TwitterProviderConfig, SamlProviderConfig, } from './providers/provider.types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,2BAA2B,EAC3B,wBAAwB,EACxB,SAAS,EACT,QAAQ,EACR,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC"}

package/dist/oauth.controller.d.ts

@@ -24,6 +24,27 @@ export declare class OAuthController {
     }, req: {
         headers?: Record<string, string | string[] | undefined>;
     }, res: Response): Promise<void>;
+    /**
+     * GET /auth/saml/:idp - Redirects user to SAML IdP login.
+     */
+    samlLogin(idp: string, query: {
+        relayState?: string;
+    }, res: Response): Promise<void>;
+    /**
+     * POST /auth/saml/:idp/callback - Handles SAML ACS callback.
+     */
+    samlCallback(idp: string, body: {
+        SAMLResponse?: string;
+        RelayState?: string;
+        successRedirect?: string;
+        errorRedirect?: string;
+    }, req: {
+        headers?: Record<string, string | string[] | undefined>;
+    }, res: Response): Promise<void>;
+    /**
+     * GET /auth/saml/:idp/metadata - Exposes minimal SP metadata.
+     */
+    samlMetadata(idp: string, res: Response): Promise<void>;
     private redirectOrJson;
 }
 //# sourceMappingURL=oauth.controller.d.ts.map

package/dist/oauth.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.controller.d.ts","sourceRoot":"","sources":["../src/oauth.controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2C,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAmB/C;;;GAGG;AACH,qBACa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,YAAY;IAEvD;;;OAGG;IAEG,KAAK,CAAoB,QAAQ,EAAE,MAAM,EAAS,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBrF;;;OAGG;IAEG,QAAQ,CACO,QAAQ,EAAE,MAAM,EAEnC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,EACnF,GAAG,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;KAAE,EAChE,GAAG,EAAE,QAAQ,GACnB,OAAO,CAAC,IAAI,CAAC;IA+ChB,OAAO,CAAC,cAAc;CAgBvB"}
+{"version":3,"file":"oauth.controller.d.ts","sourceRoot":"","sources":["../src/oauth.controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2C,KAAK,QAAQ,EAAc,MAAM,eAAe,CAAC;AACnG,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AA2B/C;;;GAGG;AACH,qBACa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,YAAY;IAEvD;;;OAGG;IAEG,KAAK,CAAoB,QAAQ,EAAE,MAAM,EAAS,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBrF;;;OAGG;IAEG,QAAQ,CACO,QAAQ,EAAE,MAAM,EAEnC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,EACnF,GAAG,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;KAAE,EAChE,GAAG,EAAE,QAAQ,GACnB,OAAO,CAAC,IAAI,CAAC;IA+ChB;;OAEG;IAEG,SAAS,CACC,GAAG,EAAE,MAAM,EAChB,KAAK,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EAChC,GAAG,EAAE,QAAQ,GACnB,OAAO,CAAC,IAAI,CAAC;IAmBhB;;OAEG;IAEG,YAAY,CACF,GAAG,EAAE,MAAM,EAEzB,IAAI,EAAE;QACJ,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,EACM,GAAG,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;KAAE,EAChE,GAAG,EAAE,QAAQ,GACnB,OAAO,CAAC,IAAI,CAAC;IA8BhB;;OAEG;IAEG,YAAY,CAAe,GAAG,EAAE,MAAM,EAAS,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlF,OAAO,CAAC,cAAc;CAgBvB"}

package/dist/oauth.controller.js

@@ -17,8 +17,16 @@ const core_1 = require("@hazeljs/core");
 const oauth_service_1 = require("./oauth.service");
 const STATE_COOKIE = 'oauth_state';
 const CODE_VERIFIER_COOKIE = 'oauth_code_verifier';
+const SAML_RELAYSTATE_COOKIE = 'saml_relay_state';
 const COOKIE_MAX_AGE = 60 * 10; // 10 minutes
 const COOKIE_OPTS = `Path=/; HttpOnly; SameSite=Lax; Max-Age=${COOKIE_MAX_AGE}`;
+const OAUTH_PROVIDERS = [
+    'google',
+    'microsoft',
+    'github',
+    'facebook',
+    'twitter',
+];
 function getCookie(req, name) {
     const h = req?.headers?.['cookie'];
     const cookieHeader = Array.isArray(h) ? h[0] : h;
@@ -41,7 +49,7 @@ let OAuthController = class OAuthController {
      */
     async login(provider, res) {
         const p = provider.toLowerCase();
-        if (!['google', 'microsoft', 'github', 'facebook', 'twitter'].includes(p)) {
+        if (!OAUTH_PROVIDERS.includes(p)) {
             res.status(400).json({ error: 'Invalid provider' });
             return;
         }
@@ -61,7 +69,7 @@ let OAuthController = class OAuthController {
      */
     async callback(provider, query, req, res) {
         const p = provider.toLowerCase();
-        if (!['google', 'microsoft', 'github', 'facebook', 'twitter'].includes(p)) {
+        if (!OAUTH_PROVIDERS.includes(p)) {
             res.status(400).json({ error: 'Invalid provider' });
             return;
         }
@@ -98,6 +106,71 @@ let OAuthController = class OAuthController {
             this.redirectOrJson(res, 401, query.errorRedirect, { error: message });
         }
     }
+    /**
+     * GET /auth/saml/:idp - Redirects user to SAML IdP login.
+     */
+    async samlLogin(idp, query, res) {
+        try {
+            const { url, relayState } = this.oauthService.getSamlAuthorizationUrl(idp, query.relayState);
+            const cookies = [];
+            if (relayState) {
+                cookies.push(`${SAML_RELAYSTATE_COOKIE}=${relayState}; ${COOKIE_OPTS}`);
+            }
+            if (cookies.length > 0) {
+                res.setHeader('Set-Cookie', cookies);
+            }
+            res.status(302);
+            res.setHeader('Location', url);
+            res.end();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to initiate SAML login';
+            res.status(400).json({ error: message });
+        }
+    }
+    /**
+     * POST /auth/saml/:idp/callback - Handles SAML ACS callback.
+     */
+    async samlCallback(idp, body, req, res) {
+        const samlResponse = body?.SAMLResponse;
+        if (!samlResponse) {
+            this.redirectOrJson(res, 400, body?.errorRedirect, { error: 'Missing SAMLResponse' });
+            return;
+        }
+        const relayState = body?.RelayState ?? getCookie(req, SAML_RELAYSTATE_COOKIE);
+        res.setHeader('Set-Cookie', [
+            `${SAML_RELAYSTATE_COOKIE}=; Path=/; HttpOnly; Max-Age=0`,
+        ]);
+        try {
+            const result = this.oauthService.handleSamlCallback(idp, samlResponse, relayState);
+            const response = await this.oauthService.executeCallback(`saml:${idp}`, result);
+            if (body.successRedirect) {
+                res.status(302);
+                res.setHeader('Location', body.successRedirect);
+                res.end();
+                return;
+            }
+            res.status(200).json(response);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'SAML callback failed';
+            this.redirectOrJson(res, 401, body?.errorRedirect, { error: message });
+        }
+    }
+    /**
+     * GET /auth/saml/:idp/metadata - Exposes minimal SP metadata.
+     */
+    async samlMetadata(idp, res) {
+        try {
+            const xml = this.oauthService.getSamlMetadata(idp);
+            res.setHeader('Content-Type', 'application/samlmetadata+xml; charset=utf-8');
+            res.status(200).send(xml);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'SAML metadata unavailable';
+            res.status(404).json({ error: message });
+        }
+    }
     redirectOrJson(res, status, errorRedirect, json) {
         if (errorRedirect) {
             const url = new URL(errorRedirect);
@@ -131,6 +204,33 @@ __decorate([
     __metadata("design:paramtypes", [String, Object, Object, Object]),
     __metadata("design:returntype", Promise)
 ], OAuthController.prototype, "callback", null);
+__decorate([
+    (0, core_1.Get)('/saml/:idp'),
+    __param(0, (0, core_1.Param)('idp')),
+    __param(1, (0, core_1.Query)()),
+    __param(2, (0, core_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, Object]),
+    __metadata("design:returntype", Promise)
+], OAuthController.prototype, "samlLogin", null);
+__decorate([
+    (0, core_1.Post)('/saml/:idp/callback'),
+    __param(0, (0, core_1.Param)('idp')),
+    __param(1, (0, core_1.Body)()),
+    __param(2, (0, core_1.Req)()),
+    __param(3, (0, core_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], OAuthController.prototype, "samlCallback", null);
+__decorate([
+    (0, core_1.Get)('/saml/:idp/metadata'),
+    __param(0, (0, core_1.Param)('idp')),
+    __param(1, (0, core_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], OAuthController.prototype, "samlMetadata", null);
 exports.OAuthController = OAuthController = __decorate([
     (0, core_1.Controller)('/auth'),
     __metadata("design:paramtypes", [oauth_service_1.OAuthService])

package/dist/oauth.controller.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth.controller.test.d.ts.map

package/dist/oauth.controller.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.controller.test.d.ts","sourceRoot":"","sources":["../src/oauth.controller.test.ts"],"names":[],"mappings":""}

package/dist/oauth.controller.test.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+jest.mock('./oauth.service', () => ({
+    OAuthService: class OAuthService {
+    },
+}));
+const oauth_controller_1 = require("./oauth.controller");
+describe('OAuthController', () => {
+    function createResponseMock() {
+        const res = {
+            status: jest.fn().mockReturnThis(),
+            json: jest.fn().mockReturnThis(),
+            setHeader: jest.fn(),
+            end: jest.fn(),
+            send: jest.fn(),
+        };
+        return res;
+    }
+    it('redirects for SAML login route', async () => {
+        const oauthService = {
+            getSamlAuthorizationUrl: jest.fn().mockReturnValue({
+                url: 'https://idp.example.com/sso?SAMLRequest=abc',
+                requestId: '_req',
+            }),
+        };
+        const controller = new oauth_controller_1.OAuthController(oauthService);
+        const res = createResponseMock();
+        await controller.samlLogin('okta-main', {}, res);
+        expect(res.status).toHaveBeenCalledWith(302);
+        expect(res.setHeader).toHaveBeenCalledWith('Location', 'https://idp.example.com/sso?SAMLRequest=abc');
+    });
+    it('returns 400 when SAML callback is missing response payload', async () => {
+        const oauthService = {};
+        const controller = new oauth_controller_1.OAuthController(oauthService);
+        const res = createResponseMock();
+        await controller.samlCallback('okta-main', {}, {}, res);
+        expect(res.status).toHaveBeenCalledWith(400);
+        expect(res.json).toHaveBeenCalledWith({ error: 'Missing SAMLResponse' });
+    });
+    it('returns metadata xml from service', async () => {
+        const oauthService = {
+            getSamlMetadata: jest.fn().mockReturnValue('<EntityDescriptor/>'),
+        };
+        const controller = new oauth_controller_1.OAuthController(oauthService);
+        const res = createResponseMock();
+        await controller.samlMetadata('okta-main', res);
+        expect(res.status).toHaveBeenCalledWith(200);
+        expect(res.send).toHaveBeenCalledWith('<EntityDescriptor/>');
+    });
+});

package/dist/oauth.service.d.ts

@@ -1,4 +1,4 @@
-import type { OAuthModuleOptions, OAuthCallbackResult, OAuthAuthorizationResult, SupportedProvider } from './providers/provider.types';
+import type { OAuthModuleOptions, OAuthCallbackResult, OAuthProtocolCallbackResult, OAuthAuthorizationResult, SamlCallbackResult, SupportedProvider } from './providers/provider.types';
 export declare class OAuthService {
     private options;
     private googleClient;
@@ -6,6 +6,7 @@ export declare class OAuthService {
     private githubClient;
     private facebookClient;
     private twitterClient;
+    private samlProviders;
     constructor();
     private static options;
     static configure(options: OAuthModuleOptions): void;
@@ -23,6 +24,14 @@ export declare class OAuthService {
      * For PKCE providers (Google, Microsoft), codeVerifier is required.
      */
     handleCallback(provider: SupportedProvider, code: string, state: string, codeVerifier?: string): Promise<OAuthCallbackResult>;
+    getSamlAuthorizationUrl(idpKey: string, relayState?: string): {
+        url: string;
+        requestId: string;
+        relayState?: string;
+    };
+    handleSamlCallback(idpKey: string, samlResponseBase64: string, relayState?: string): SamlCallbackResult;
+    getSamlMetadata(idpKey: string): string;
+    getSamlProviderKeys(): string[];
     /**
      * Called by OAuthController after a successful token exchange and user-profile fetch.
      *
@@ -33,7 +42,7 @@ export declare class OAuthService {
      * When no handler is configured the raw OAuthCallbackResult is returned unchanged,
      * which preserves backwards-compatible behaviour.
      */
-    executeCallback(provider: SupportedProvider, result: OAuthCallbackResult): Promise<unknown>;
+    executeCallback(provider: SupportedProvider | `saml:${string}`, result: OAuthProtocolCallbackResult): Promise<unknown>;
     /**
      * Validate that the state matches (CSRF protection).
      * Use this when handling the callback to ensure the request originated from your app.
@@ -43,5 +52,6 @@ export declare class OAuthService {
      * Generate a cryptographically secure state value for OAuth.
      */
     generateState(): string;
+    private getSamlProvider;
 }
 //# sourceMappingURL=oauth.service.d.ts.map

package/dist/oauth.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.service.d.ts","sourceRoot":"","sources":["../src/oauth.service.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,kBAAkB,EAElB,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,EAElB,MAAM,4BAA4B,CAAC;AAIpC,qBACa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,YAAY,CAAwD;IAC5E,OAAO,CAAC,eAAe,CAA2D;IAClF,OAAO,CAAC,YAAY,CAAwD;IAC5E,OAAO,CAAC,cAAc,CAA0D;IAChF,OAAO,CAAC,aAAa,CAAyD;;IAO9E,OAAO,CAAC,MAAM,CAAC,OAAO,CAAmC;IAEzD,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAInD,OAAO,CAAC,MAAM,CAAC,UAAU;IASzB,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,SAAS;IA8BjB,OAAO,CAAC,gBAAgB;IAmBxB;;;OAGG;IACH,mBAAmB,CACjB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,wBAAwB;IA2B3B;;;OAGG;IACG,cAAc,CAClB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,CAAC;IAuF/B;;;;;;;;;OASG;IACG,eAAe,CACnB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,OAAO,CAAC;IAWnB;;;OAGG;IACH,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO;IAIlE;;OAEG;IACH,aAAa,IAAI,MAAM;CAGxB"}
+{"version":3,"file":"oauth.service.d.ts","sourceRoot":"","sources":["../src/oauth.service.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,kBAAkB,EAElB,mBAAmB,EACnB,2BAA2B,EAC3B,wBAAwB,EAExB,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,4BAA4B,CAAC;AAIpC,qBACa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,YAAY,CAAwD;IAC5E,OAAO,CAAC,eAAe,CAA2D;IAClF,OAAO,CAAC,YAAY,CAAwD;IAC5E,OAAO,CAAC,cAAc,CAA0D;IAChF,OAAO,CAAC,aAAa,CAAyD;IAC9E,OAAO,CAAC,aAAa,CAA0C;;IAO/D,OAAO,CAAC,MAAM,CAAC,OAAO,CAAmC;IAEzD,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAInD,OAAO,CAAC,MAAM,CAAC,UAAU;IASzB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,SAAS;IA8BjB,OAAO,CAAC,gBAAgB;IAmBxB;;;OAGG;IACH,mBAAmB,CACjB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,wBAAwB;IA2B3B;;;OAGG;IACG,cAAc,CAClB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,CAAC;IAwF/B,uBAAuB,CACrB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,GAClB;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAQ1D,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,MAAM,EAC1B,UAAU,CAAC,EAAE,MAAM,GAClB,kBAAkB;IAMrB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAYvC,mBAAmB,IAAI,MAAM,EAAE;IAI/B;;;;;;;;;OASG;IACG,eAAe,CACnB,QAAQ,EAAE,iBAAiB,GAAG,QAAQ,MAAM,EAAE,EAC9C,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,OAAO,CAAC;IAWnB;;;OAGG;IACH,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO;IAIlE;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB,OAAO,CAAC,eAAe;CAOxB"}

package/dist/oauth.service.js

@@ -55,6 +55,7 @@ let OAuthService = OAuthService_1 = class OAuthService {
         this.githubClient = null;
         this.facebookClient = null;
         this.twitterClient = null;
+        this.samlProviders = {};
         this.options = OAuthService_1.getOptions();
         this.initClients();
     }
@@ -83,6 +84,7 @@ let OAuthService = OAuthService_1 = class OAuthService {
         if (this.options.providers.twitter) {
             this.twitterClient = (0, providers_1.createTwitterProvider)(this.options.providers.twitter);
         }
+        this.samlProviders = this.options.providers.saml ?? {};
     }
     getClient(provider) {
         switch (provider) {
@@ -211,12 +213,39 @@ let OAuthService = OAuthService_1 = class OAuthService {
                 throw new Error(`Unsupported provider: ${provider}`);
         }
         return {
+            protocol: 'oauth2',
             accessToken,
             refreshToken,
             expiresAt,
             user,
         };
     }
+    getSamlAuthorizationUrl(idpKey, relayState) {
+        const provider = this.getSamlProvider(idpKey);
+        if (relayState) {
+            return (0, providers_1.createSamlAuthnRequest)({ ...provider, relayState });
+        }
+        return (0, providers_1.createSamlAuthnRequest)(provider);
+    }
+    handleSamlCallback(idpKey, samlResponseBase64, relayState) {
+        const provider = this.getSamlProvider(idpKey);
+        const parsed = (0, providers_1.parseSamlResponse)(provider, samlResponseBase64, relayState);
+        return (0, providers_1.buildSamlCallbackResult)(idpKey, parsed, relayState, samlResponseBase64);
+    }
+    getSamlMetadata(idpKey) {
+        const provider = this.getSamlProvider(idpKey);
+        const acs = provider.acsUrl.replace(/"/g, '"');
+        const issuer = provider.issuer.replace(/"/g, '"');
+        return `<?xml version="1.0" encoding="UTF-8"?>
+<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${issuer}">
+  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
+    <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${acs}" index="0" isDefault="true"/>
+  </SPSSODescriptor>
+</EntityDescriptor>`;
+    }
+    getSamlProviderKeys() {
+        return Object.keys(this.samlProviders);
+    }
     /**
      * Called by OAuthController after a successful token exchange and user-profile fetch.
      *
@@ -247,6 +276,13 @@ let OAuthService = OAuthService_1 = class OAuthService {
     generateState() {
         return arctic.generateState();
     }
+    getSamlProvider(idpKey) {
+        const provider = this.samlProviders[idpKey];
+        if (!provider) {
+            throw new Error(`SAML provider "${idpKey}" is not configured`);
+        }
+        return provider;
+    }
 };
 exports.OAuthService = OAuthService;
 OAuthService.options = null;

package/dist/oauth.service.test.js

@@ -101,6 +101,15 @@ describe('OAuthService', () => {
                 facebook: { ...baseConfig },
                 microsoft: { ...baseConfig },
                 twitter: { ...baseConfig },
+                saml: {
+                    'okta-main': {
+                        idpKey: 'okta-main',
+                        ssoUrl: 'https://idp.example.com/sso',
+                        issuer: 'https://app.example.com',
+                        acsUrl: 'https://app.example.com/auth/saml/okta-main/callback',
+                        audience: 'https://app.example.com',
+                    },
+                },
             },
         });
         mockFetch.mockResolvedValue({
@@ -190,6 +199,7 @@ describe('OAuthService', () => {
                 }),
             });
             const result = await service.handleCallback('github', 'auth-code', 'mock-state-123');
+            expect(result.protocol).toBe('oauth2');
             expect(result.accessToken).toBe('mock-access-token');
             expect(result.user.id).toBe('12345');
             expect(result.user.email).toBe('github@example.com');
@@ -245,4 +255,74 @@ describe('OAuthService', () => {
             await expect(service.handleCallback('facebook', 'code', 'state')).rejects.toThrow('Facebook OAuth is not configured');
         });
     });
+    describe('SAML support', () => {
+        it('returns SAML authorization URL for configured IdP', () => {
+            const service = new oauth_service_1.OAuthService();
+            const result = service.getSamlAuthorizationUrl('okta-main');
+            expect(result.url).toContain('idp.example.com/sso');
+            expect(result.url).toContain('SAMLRequest=');
+            expect(result.requestId).toMatch(/^_/);
+        });
+        it('throws for unknown SAML provider key', () => {
+            const service = new oauth_service_1.OAuthService();
+            expect(() => service.getSamlAuthorizationUrl('unknown-idp')).toThrow('not configured');
+        });
+        it('returns provider keys for configured SAML providers', () => {
+            const service = new oauth_service_1.OAuthService();
+            expect(service.getSamlProviderKeys()).toContain('okta-main');
+        });
+        it('returns metadata XML for configured SAML provider', () => {
+            const service = new oauth_service_1.OAuthService();
+            const xml = service.getSamlMetadata('okta-main');
+            expect(xml).toContain('EntityDescriptor');
+            expect(xml).toContain('AssertionConsumerService');
+        });
+        it('parses successful SAML callback payload', () => {
+            const service = new oauth_service_1.OAuthService();
+            const samlResponseXml = `
+        <samlp:Response InResponseTo="_req123">
+          <samlp:Status>
+            <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
+          </samlp:Status>
+          <saml:Assertion>
+            <saml:Conditions>
+              <saml:AudienceRestriction>
+                <saml:Audience>https://app.example.com</saml:Audience>
+              </saml:AudienceRestriction>
+            </saml:Conditions>
+            <saml:Subject>
+              <saml:NameID>user-001</saml:NameID>
+            </saml:Subject>
+            <saml:AuthnStatement SessionIndex="session-1"/>
+            <saml:AttributeStatement>
+              <saml:Attribute Name="email">
+                <saml:AttributeValue>user@example.com</saml:AttributeValue>
+              </saml:Attribute>
+              <saml:Attribute Name="name">
+                <saml:AttributeValue>Saml User</saml:AttributeValue>
+              </saml:Attribute>
+            </saml:AttributeStatement>
+          </saml:Assertion>
+        </samlp:Response>
+      `;
+            const encoded = Buffer.from(samlResponseXml, 'utf8').toString('base64');
+            const result = service.handleSamlCallback('okta-main', encoded, 'relay-123');
+            expect(result.protocol).toBe('saml');
+            expect(result.user.email).toBe('user@example.com');
+            expect(result.nameId).toBe('user-001');
+            expect(result.relayState).toBe('relay-123');
+        });
+        it('throws when SAML callback is unsuccessful', () => {
+            const service = new oauth_service_1.OAuthService();
+            const badXml = `
+        <samlp:Response>
+          <samlp:Status>
+            <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester"/>
+          </samlp:Status>
+        </samlp:Response>
+      `;
+            const encoded = Buffer.from(badXml, 'utf8').toString('base64');
+            expect(() => service.handleSamlCallback('okta-main', encoded)).toThrow('not successful');
+        });
+    });
 });

package/dist/providers/index.d.ts

@@ -4,4 +4,5 @@ export * from './microsoft.provider';
 export * from './github.provider';
 export * from './facebook.provider';
 export * from './twitter.provider';
+export * from './saml.provider';
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/providers/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./microsoft.provider"), exports);
 __exportStar(require("./github.provider"), exports);
 __exportStar(require("./facebook.provider"), exports);
 __exportStar(require("./twitter.provider"), exports);
+__exportStar(require("./saml.provider"), exports);

package/dist/providers/provider.types.d.ts

@@ -27,13 +27,55 @@ export type OAuthProviderConfig = {
     facebook: FacebookProviderConfig;
 } | {
     twitter: TwitterProviderConfig;
+} | {
+    saml: SamlProviderConfig;
 };
+export interface SamlProviderConfig {
+    /**
+     * IdP key used in routes: /auth/saml/:idpKey/*
+     */
+    idpKey: string;
+    /**
+     * SSO URL of the Identity Provider.
+     */
+    ssoUrl: string;
+    /**
+     * Issuer/entity ID for your HazelJS app (SP).
+     */
+    issuer: string;
+    /**
+     * ACS endpoint URL configured in IdP.
+     */
+    acsUrl: string;
+    /**
+     * IdP certificate (PEM). Required for signature validation in production.
+     */
+    idpCertificate?: string;
+    /**
+     * Optional explicit audience check. Defaults to `issuer`.
+     */
+    audience?: string;
+    /**
+     * Optional IdP metadata URL for convenience/documentation.
+     */
+    metadataUrl?: string;
+    /**
+     * Optional default relay state.
+     */
+    relayState?: string;
+    /**
+     * Optional allowed clock skew for time validations.
+     * @default 120
+     */
+    clockSkewSec?: number;
+}
 export interface OAuthProvidersConfig {
     google?: GoogleProviderConfig;
     microsoft?: MicrosoftProviderConfig;
     github?: GitHubProviderConfig;
     facebook?: FacebookProviderConfig;
     twitter?: TwitterProviderConfig;
+    saml?: Record<string, SamlProviderConfig>;
 }
 export type SupportedProvider = 'google' | 'microsoft' | 'github' | 'facebook' | 'twitter';
 export interface OAuthUser {
@@ -43,11 +85,29 @@ export interface OAuthUser {
     picture?: string | null;
 }
 export interface OAuthCallbackResult {
+    protocol?: 'oauth2';
     accessToken: string;
     refreshToken?: string;
     expiresAt?: Date;
     user: OAuthUser;
 }
+export interface SamlUser {
+    id: string;
+    email: string;
+    name: string | null;
+    attributes: Record<string, string | string[]>;
+}
+export interface SamlCallbackResult {
+    protocol: 'saml';
+    provider: string;
+    user: SamlUser;
+    nameId: string;
+    sessionIndex?: string;
+    relayState?: string;
+    inResponseTo?: string;
+    rawAssertion?: string;
+}
+export type OAuthProtocolCallbackResult = OAuthCallbackResult | SamlCallbackResult;
 export interface OAuthAuthorizationResult {
     url: string;
     state: string;
@@ -78,7 +138,7 @@ export interface OAuthAuthorizationResult {
  * ```
  */
 export interface OAuthCallbackHandler {
-    handle(result: OAuthCallbackResult, provider: SupportedProvider): Promise<unknown> | unknown;
+    handle(result: OAuthProtocolCallbackResult, provider: SupportedProvider | `saml:${string}`): Promise<unknown> | unknown;
 }
 export interface OAuthModuleOptions {
     providers: OAuthProvidersConfig;

package/dist/providers/provider.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.types.d.ts","sourceRoot":"","sources":["../../src/providers/provider.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AAEtD,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AAEtD,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAExD,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,kBAAkB,EAAE,cAAc,CAAC;IACrF,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAChC;IAAE,SAAS,EAAE,uBAAuB,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAChC;IAAE,QAAQ,EAAE,sBAAsB,CAAA;CAAE,GACpC;IAAE,OAAO,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEvC,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3F,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC9F;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,oBAAoB,CAAC;IAChC,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7D;;;;OAIG;IAEH,eAAe,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,oBAAoB,CAAC;CAChE"}
+{"version":3,"file":"provider.types.d.ts","sourceRoot":"","sources":["../../src/providers/provider.types.ts"],"names":[],"mappings":"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"}

package/dist/providers/provider.types.test.js

@@ -37,11 +37,38 @@ describe('Provider Types', () => {
     });
     it('should define OAuthCallbackResult shape', () => {
         const result = {
+            protocol: 'oauth2',
             accessToken: 'token',
             user: { id: '1', email: 'e@e.com', name: 'N' },
         };
         expect(result.accessToken).toBe('token');
     });
+    it('should define SamlProviderConfig shape', () => {
+        const config = {
+            idpKey: 'okta-main',
+            ssoUrl: 'https://idp.example.com/sso',
+            issuer: 'https://app.example.com',
+            acsUrl: 'https://app.example.com/auth/saml/okta-main/callback',
+            audience: 'https://app.example.com',
+        };
+        expect(config.idpKey).toBe('okta-main');
+    });
+    it('should define SamlCallbackResult shape', () => {
+        const result = {
+            protocol: 'saml',
+            provider: 'okta-main',
+            nameId: 'name-id',
+            user: {
+                id: 'user-id',
+                email: 'saml@example.com',
+                name: 'Saml User',
+                attributes: {
+                    email: 'saml@example.com',
+                },
+            },
+        };
+        expect(result.protocol).toBe('saml');
+    });
     it('should define OAuthAuthorizationResult shape', () => {
         const result = {
             url: 'https://provider.com',

package/dist/providers/saml.provider.d.ts

@@ -0,0 +1,18 @@
+import type { SamlCallbackResult, SamlProviderConfig } from './provider.types';
+export interface SamlAuthorizationResult {
+    url: string;
+    requestId: string;
+    relayState?: string;
+}
+export interface ParsedSamlAssertion {
+    nameId: string;
+    email: string;
+    name: string | null;
+    attributes: Record<string, string | string[]>;
+    sessionIndex?: string;
+    inResponseTo?: string;
+}
+export declare function createSamlAuthnRequest(config: SamlProviderConfig): SamlAuthorizationResult;
+export declare function parseSamlResponse(config: SamlProviderConfig, samlResponseBase64: string, _relayState?: string): ParsedSamlAssertion;
+export declare function buildSamlCallbackResult(provider: string, parsed: ParsedSamlAssertion, relayState: string | undefined, rawAssertion: string): SamlCallbackResult;
+//# sourceMappingURL=saml.provider.d.ts.map

package/dist/providers/saml.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saml.provider.d.ts","sourceRoot":"","sources":["../../src/providers/saml.provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAsC/E,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,uBAAuB,CAuB1F;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,WAAW,CAAC,EAAE,MAAM,GACnB,mBAAmB,CAsErB;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,EAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,EAAE,MAAM,GACnB,kBAAkB,CAkBpB"}

package/dist/providers/saml.provider.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSamlAuthnRequest = createSamlAuthnRequest;
+exports.parseSamlResponse = parseSamlResponse;
+exports.buildSamlCallbackResult = buildSamlCallbackResult;
+const crypto_1 = require("crypto");
+function encodeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function decodeBase64(input) {
+    return Buffer.from(input, 'base64').toString('utf8');
+}
+function firstMatch(xml, pattern) {
+    const match = pattern.exec(xml);
+    return match?.[1];
+}
+function allAttributeValues(xml, attributeName) {
+    const escapedName = attributeName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`<[^>]*Attribute[^>]*Name=["']${escapedName}["'][^>]*>([\\s\\S]*?)</[^>]*Attribute>`, 'i');
+    const block = firstMatch(xml, pattern);
+    if (!block)
+        return [];
+    const values = [];
+    const valuePattern = /<[^>]*AttributeValue[^>]*>([\s\S]*?)<\/[^>]*AttributeValue>/gi;
+    let valueMatch = valuePattern.exec(block);
+    while (valueMatch) {
+        values.push(valueMatch[1].trim());
+        valueMatch = valuePattern.exec(block);
+    }
+    return values;
+}
+function createSamlAuthnRequest(config) {
+    const requestId = `_${(0, crypto_1.randomBytes)(16).toString('hex')}`;
+    const instant = new Date().toISOString();
+    const issueInstant = instant.replace(/\.\d{3}Z$/, 'Z');
+    const destination = encodeXml(config.ssoUrl);
+    const assertionConsumerServiceURL = encodeXml(config.acsUrl);
+    const issuer = encodeXml(config.issuer);
+    const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="${requestId}" Version="2.0" IssueInstant="${issueInstant}" Destination="${destination}" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="${assertionConsumerServiceURL}">
+  <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">${issuer}</saml:Issuer>
+  <samlp:NameIDPolicy AllowCreate="true"/>
+</samlp:AuthnRequest>`;
+    const samlRequest = Buffer.from(xml, 'utf8').toString('base64');
+    const url = new URL(config.ssoUrl);
+    url.searchParams.set('SAMLRequest', samlRequest);
+    if (config.relayState) {
+        url.searchParams.set('RelayState', config.relayState);
+    }
+    return {
+        url: url.toString(),
+        requestId,
+        relayState: config.relayState,
+    };
+}
+function parseSamlResponse(config, samlResponseBase64, _relayState) {
+    const xml = decodeBase64(samlResponseBase64);
+    const statusCode = firstMatch(xml, /<[^>]*StatusCode[^>]*Value=["']([^"']+)["']/i);
+    if (!statusCode || !statusCode.endsWith(':Success')) {
+        throw new Error(`SAML response is not successful (${statusCode || 'unknown status'})`);
+    }
+    const audience = firstMatch(xml, /<[^>]*Audience\b[^>]*>\s*([^<]+)\s*<\/[^>]*Audience>/i)?.trim();
+    const expectedAudience = config.audience || config.issuer;
+    if (audience && audience !== expectedAudience) {
+        throw new Error('SAML audience mismatch');
+    }
+    const nameId = firstMatch(xml, /<[^>]*NameID[^>]*>([\s\S]*?)<\/[^>]*NameID>/i)?.trim() || '';
+    if (!nameId) {
+        throw new Error('SAML NameID is missing');
+    }
+    const sessionIndex = firstMatch(xml, /<[^>]*AuthnStatement[^>]*SessionIndex=["']([^"']+)["']/i);
+    const inResponseTo = firstMatch(xml, /<[^>]*Response[^>]*InResponseTo=["']([^"']+)["']/i);
+    const emailCandidates = [
+        'email',
+        'emailaddress',
+        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
+    ];
+    const nameCandidates = [
+        'name',
+        'displayname',
+        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name',
+        'givenname',
+    ];
+    const attributes = {};
+    const attrBlockPattern = /<[^>]*Attribute[^>]*Name=["']([^"']+)["'][^>]*>([\s\S]*?)<\/[^>]*Attribute>/gi;
+    let attrMatch = attrBlockPattern.exec(xml);
+    while (attrMatch) {
+        const attrName = attrMatch[1];
+        const values = allAttributeValues(xml, attrName);
+        if (values.length === 1) {
+            attributes[attrName] = values[0];
+        }
+        else if (values.length > 1) {
+            attributes[attrName] = values;
+        }
+        attrMatch = attrBlockPattern.exec(xml);
+    }
+    const email = emailCandidates
+        .map((key) => attributes[key])
+        .map((value) => (Array.isArray(value) ? value[0] : value))
+        .find((value) => typeof value === 'string' && value.length > 0) || '';
+    const nameValue = nameCandidates
+        .map((key) => attributes[key])
+        .map((value) => (Array.isArray(value) ? value[0] : value))
+        .find((value) => typeof value === 'string' && value.length > 0);
+    if (!email) {
+        throw new Error('SAML response does not include an email attribute');
+    }
+    return {
+        nameId,
+        email,
+        name: nameValue || null,
+        attributes,
+        sessionIndex,
+        inResponseTo,
+    };
+}
+function buildSamlCallbackResult(provider, parsed, relayState, rawAssertion) {
+    const userId = parsed.nameId || parsed.email;
+    const stableId = (0, crypto_1.createHash)('sha256').update(`${provider}:${userId}`).digest('hex');
+    return {
+        protocol: 'saml',
+        provider,
+        user: {
+            id: stableId,
+            email: parsed.email,
+            name: parsed.name,
+            attributes: parsed.attributes,
+        },
+        nameId: parsed.nameId,
+        sessionIndex: parsed.sessionIndex,
+        relayState,
+        inResponseTo: parsed.inResponseTo,
+        rawAssertion,
+    };
+}

package/dist/providers/saml.provider.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=saml.provider.test.d.ts.map

package/dist/providers/saml.provider.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saml.provider.test.d.ts","sourceRoot":"","sources":["../../src/providers/saml.provider.test.ts"],"names":[],"mappings":""}

package/dist/providers/saml.provider.test.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const saml_provider_1 = require("./saml.provider");
+describe('SAML provider helpers', () => {
+    const config = {
+        idpKey: 'okta-main',
+        ssoUrl: 'https://idp.example.com/sso',
+        issuer: 'https://app.example.com',
+        acsUrl: 'https://app.example.com/auth/saml/okta-main/callback',
+        audience: 'https://app.example.com',
+    };
+    function encode(xml) {
+        return Buffer.from(xml, 'utf8').toString('base64');
+    }
+    it('creates SAML AuthnRequest URL with request id', () => {
+        const result = (0, saml_provider_1.createSamlAuthnRequest)(config);
+        expect(result.url).toContain('https://idp.example.com/sso');
+        expect(result.url).toContain('SAMLRequest=');
+        expect(result.requestId).toMatch(/^_/);
+    });
+    it('includes relay state when configured', () => {
+        const result = (0, saml_provider_1.createSamlAuthnRequest)({ ...config, relayState: 'app=dashboard' });
+        expect(result.url).toContain('RelayState=app%3Ddashboard');
+        expect(result.relayState).toBe('app=dashboard');
+    });
+    it('parses successful SAML assertion', () => {
+        const xml = `
+      <samlp:Response InResponseTo="_req123">
+        <samlp:Status>
+          <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
+        </samlp:Status>
+        <saml:Assertion>
+          <saml:Conditions>
+            <saml:AudienceRestriction>
+              <saml:Audience>https://app.example.com</saml:Audience>
+            </saml:AudienceRestriction>
+          </saml:Conditions>
+          <saml:Subject>
+            <saml:NameID>nameid-1</saml:NameID>
+          </saml:Subject>
+          <saml:AuthnStatement SessionIndex="session-1"/>
+          <saml:AttributeStatement>
+            <saml:Attribute Name="email">
+              <saml:AttributeValue>user@example.com</saml:AttributeValue>
+            </saml:Attribute>
+            <saml:Attribute Name="name">
+              <saml:AttributeValue>Demo User</saml:AttributeValue>
+            </saml:Attribute>
+            <saml:Attribute Name="groups">
+              <saml:AttributeValue>admin</saml:AttributeValue>
+              <saml:AttributeValue>ops</saml:AttributeValue>
+            </saml:Attribute>
+          </saml:AttributeStatement>
+        </saml:Assertion>
+      </samlp:Response>
+    `;
+        const parsed = (0, saml_provider_1.parseSamlResponse)(config, encode(xml));
+        expect(parsed.nameId).toBe('nameid-1');
+        expect(parsed.email).toBe('user@example.com');
+        expect(parsed.name).toBe('Demo User');
+        expect(parsed.sessionIndex).toBe('session-1');
+        expect(parsed.inResponseTo).toBe('_req123');
+        expect(parsed.attributes.groups).toEqual(['admin', 'ops']);
+    });
+    it('throws on non-success status', () => {
+        const xml = `
+      <samlp:Response>
+        <samlp:Status>
+          <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester"/>
+        </samlp:Status>
+      </samlp:Response>
+    `;
+        expect(() => (0, saml_provider_1.parseSamlResponse)(config, encode(xml))).toThrow('not successful');
+    });
+    it('throws on audience mismatch', () => {
+        const xml = `
+      <samlp:Response>
+        <samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>
+        <saml:Assertion>
+          <saml:Conditions>
+            <saml:AudienceRestriction>
+              <saml:Audience>https://wrong.example.com</saml:Audience>
+            </saml:AudienceRestriction>
+          </saml:Conditions>
+          <saml:Subject><saml:NameID>nameid-1</saml:NameID></saml:Subject>
+          <saml:AttributeStatement>
+            <saml:Attribute Name="email"><saml:AttributeValue>user@example.com</saml:AttributeValue></saml:Attribute>
+          </saml:AttributeStatement>
+        </saml:Assertion>
+      </samlp:Response>
+    `;
+        expect(() => (0, saml_provider_1.parseSamlResponse)(config, encode(xml))).toThrow('audience mismatch');
+    });
+    it('throws when NameID is missing', () => {
+        const xml = `
+      <samlp:Response>
+        <samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>
+        <saml:Assertion>
+          <saml:AttributeStatement>
+            <saml:Attribute Name="email"><saml:AttributeValue>user@example.com</saml:AttributeValue></saml:Attribute>
+          </saml:AttributeStatement>
+        </saml:Assertion>
+      </samlp:Response>
+    `;
+        expect(() => (0, saml_provider_1.parseSamlResponse)(config, encode(xml))).toThrow('NameID');
+    });
+    it('throws when email attribute is missing', () => {
+        const xml = `
+      <samlp:Response>
+        <samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>
+        <saml:Assertion>
+          <saml:Subject><saml:NameID>nameid-1</saml:NameID></saml:Subject>
+          <saml:AttributeStatement>
+            <saml:Attribute Name="displayname"><saml:AttributeValue>No Email User</saml:AttributeValue></saml:Attribute>
+          </saml:AttributeStatement>
+        </saml:Assertion>
+      </samlp:Response>
+    `;
+        expect(() => (0, saml_provider_1.parseSamlResponse)(config, encode(xml))).toThrow('email attribute');
+    });
+    it('builds SAML callback result with stable hashed user id', () => {
+        const parsed = {
+            nameId: 'name-id-abc',
+            email: 'user@example.com',
+            name: 'User',
+            attributes: { role: 'admin' },
+            sessionIndex: 'session-1',
+            inResponseTo: '_req-1',
+        };
+        const result = (0, saml_provider_1.buildSamlCallbackResult)('okta-main', parsed, 'relay-x', 'raw-assertion');
+        expect(result.protocol).toBe('saml');
+        expect(result.provider).toBe('okta-main');
+        expect(result.user.email).toBe('user@example.com');
+        expect(result.user.id).toHaveLength(64);
+        expect(result.relayState).toBe('relay-x');
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hazeljs/oauth",
-  "version": "0.7.7",
-  "description": "OAuth 2.0 social login module for HazelJS - Microsoft, Google, GitHub and more",
+  "version": "0.7.9",
+  "description": "OAuth 2.0 and SAML SSO module for HazelJS - Google, Microsoft, GitHub, and enterprise IdPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -41,7 +41,9 @@
     "google",
     "microsoft",
     "github",
-    "social-login"
+    "social-login",
+    "saml",
+    "sso"
   ],
   "author": "Muhammad Arslan <muhammad.arslan@hazeljs.ai>",
   "license": "Apache-2.0",
@@ -52,5 +54,5 @@
   "peerDependencies": {
     "@hazeljs/core": ">=0.2.0-beta.0"
   },
-  "gitHead": "5fa18729312dd9d2abe5dee3801fbd0ac0f1c3c9"
+  "gitHead": "28c21c509aeca3bf2d0878fbee737d906b654c67"
 }