bootstrap module

Author: neSpecc

src/sso/index.ts

@@ -0,0 +1,15 @@
+import express from 'express';
+import { createSamlRouter } from './saml';
+import { ContextFactories } from '../types/graphql';
+
+/**
+ * Append SSO routes to Express app
+ *
+ * @param app - Express application instance
+ * @param factories - context factories for database access
+ */
+export function appendSsoRoutes(app: express.Application, factories: ContextFactories): void {
+  const samlRouter = createSamlRouter(factories);
+  app.use('/auth/sso/saml', samlRouter);
+}
+

src/sso/saml/controller.ts

@@ -0,0 +1,56 @@
+import express from 'express';
+import SamlService from './service';
+import samlStore from './store';
+import { ContextFactories } from '../../types/graphql';
+
+/**
+ * Controller for SAML SSO endpoints
+ */
+export default class SamlController {
+  /**
+   * SAML service instance
+   */
+  private samlService: SamlService;
+
+  /**
+   * Context factories for database access
+   */
+  private factories: ContextFactories;
+
+  constructor(factories: ContextFactories) {
+    this.samlService = new SamlService();
+    this.factories = factories;
+  }
+
+  /**
+   * Compose Assertion Consumer Service URL for workspace
+   *
+   * @param workspaceId - workspace ID
+   * @returns ACS URL
+   */
+  private getAcsUrl(workspaceId: string): string {
+    const apiUrl = process.env.API_URL || 'https://api.hawk.so';
+    return `${apiUrl}/auth/sso/saml/${workspaceId}/acs`;
+  }
+
+  /**
+   * Initiate SSO login (GET /auth/sso/saml/:workspaceId)
+   */
+  public async initiateLogin(req: express.Request, res: express.Response): Promise<void> {
+    /**
+     * TODO: Implement according to specification
+     */
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Handle ACS callback (POST /auth/sso/saml/:workspaceId/acs)
+   */
+  public async handleAcs(req: express.Request, res: express.Response): Promise<void> {
+    /**
+     * TODO: Implement according to specification
+     */
+    throw new Error('Not implemented');
+  }
+}
+

src/sso/saml/index.ts

@@ -0,0 +1,41 @@
+import express from 'express';
+import SamlController from './controller';
+import { ContextFactories } from '../../types/graphql';
+
+/**
+ * Create SAML router
+ *
+ * @param factories - context factories for database access
+ * @returns Express router with SAML endpoints
+ */
+export function createSamlRouter(factories: ContextFactories): express.Router {
+  const router = express.Router();
+  const controller = new SamlController(factories);
+
+  /**
+   * SSO login initiation
+   * GET /auth/sso/saml/:workspaceId
+   */
+  router.get('/:workspaceId', async (req, res, next) => {
+    try {
+      await controller.initiateLogin(req, res);
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  /**
+   * ACS callback
+   * POST /auth/sso/saml/:workspaceId/acs
+   */
+  router.post('/:workspaceId/acs', async (req, res, next) => {
+    try {
+      await controller.handleAcs(req, res);
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  return router;
+}
+

src/sso/saml/service.ts

@@ -0,0 +1,115 @@
+import { SamlConfig, SamlResponseData } from '../types';
+import { SamlValidationError, SamlValidationErrorType } from './types';
+
+/**
+ * Service for SAML SSO operations
+ */
+export default class SamlService {
+  /**
+   * Generate SAML AuthnRequest
+   *
+   * @param workspaceId - workspace ID
+   * @param acsUrl - Assertion Consumer Service URL
+   * @param relayState - relay state to pass through
+   * @param samlConfig - SAML configuration
+   * @returns AuthnRequest ID and encoded SAML request
+   */
+  public async generateAuthnRequest(
+    workspaceId: string,
+    acsUrl: string,
+    relayState: string,
+    samlConfig: SamlConfig
+  ): Promise<{ requestId: string; encodedRequest: string }> {
+    /**
+     * @todo Implement using @node-saml/node-saml
+     *
+     * This method should:
+     * 1. Generate unique AuthnRequest ID
+     * 2. Create SAML AuthnRequest XML
+     * 3. Encode it as base64
+     * 4. Return both requestId and encoded request
+     */
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Validate and parse SAML Response
+   *
+   * @param samlResponse - base64-encoded SAML Response
+   * @param workspaceId - workspace ID
+   * @param acsUrl - expected Assertion Consumer Service URL
+   * @param samlConfig - SAML configuration
+   * @returns parsed SAML response data
+   */
+  public async validateAndParseResponse(
+    samlResponse: string,
+    workspaceId: string,
+    acsUrl: string,
+    samlConfig: SamlConfig
+  ): Promise<SamlResponseData> {
+    /**
+     * @todo Implement using @node-saml/node-saml
+     *
+     * This method should:
+     * 1. Decode base64 SAML Response
+     * 2. Validate XML signature using x509Cert
+     * 3. Validate Audience (should match SSO_SP_ENTITY_ID)
+     * 4. Validate Recipient (should match acsUrl)
+     * 5. Validate InResponseTo (should match saved AuthnRequest ID)
+     * 6. Validate time conditions (NotBefore, NotOnOrAfter)
+     * 7. Extract NameID
+     * 8. Extract email using attributeMapping
+     * 9. Extract name using attributeMapping (if available)
+     * 10. Return parsed data
+     */
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Validate Audience value
+   *
+   * @param audience - audience value from SAML Assertion
+   * @returns true if audience matches SSO_SP_ENTITY_ID
+   */
+  public validateAudience(audience: string): boolean {
+    const spEntityId = process.env.SSO_SP_ENTITY_ID;
+
+    if (!spEntityId) {
+      throw new Error('SSO_SP_ENTITY_ID environment variable is not set');
+    }
+
+    return audience === spEntityId;
+  }
+
+  /**
+   * Validate Recipient value
+   *
+   * @param recipient - recipient URL from SAML Assertion
+   * @param expectedAcsUrl - expected ACS URL
+   * @returns true if recipient matches expected ACS URL
+   */
+  public validateRecipient(recipient: string, expectedAcsUrl: string): boolean {
+    return recipient === expectedAcsUrl;
+  }
+
+  /**
+   * Validate time conditions (NotBefore and NotOnOrAfter)
+   *
+   * @param notBefore - NotBefore timestamp
+   * @param notOnOrAfter - NotOnOrAfter timestamp
+   * @param clockSkew - allowed clock skew in milliseconds (default: 2 minutes)
+   * @returns true if assertion is valid at current time
+   */
+  public validateTimeConditions(
+    notBefore: Date,
+    notOnOrAfter: Date,
+    clockSkew: number = 2 * 60 * 1000
+  ): boolean {
+    const now = Date.now();
+    const notBeforeTime = notBefore.getTime() - clockSkew;
+    const notOnOrAfterTime = notOnOrAfter.getTime() + clockSkew;
+
+    return now >= notBeforeTime && now < notOnOrAfterTime;
+  }
+}
+

src/sso/saml/store.ts

@@ -0,0 +1,117 @@
+import { RelayStateData, AuthnRequestState } from './types';
+
+/**
+ * In-memory store for SAML state
+ * @todo Replace with Redis for production
+ */
+class SamlStateStore {
+  /**
+   * Map of relay state IDs to relay state data
+   */
+  private relayStates: Map<string, RelayStateData> = new Map();
+
+  /**
+   * Map of AuthnRequest IDs to AuthnRequest state
+   */
+  private authnRequests: Map<string, AuthnRequestState> = new Map();
+
+  /**
+   * Time-to-live for stored state (5 minutes)
+   */
+  private readonly TTL = 5 * 60 * 1000;
+
+  /**
+   * Save relay state
+   */
+  public saveRelayState(stateId: string, data: { returnUrl: string; workspaceId: string }): void {
+    this.relayStates.set(stateId, {
+      ...data,
+      expiresAt: Date.now() + this.TTL,
+    });
+  }
+
+  /**
+   * Get relay state by ID
+   */
+  public getRelayState(stateId: string): { returnUrl: string; workspaceId: string } | null {
+    const state = this.relayStates.get(stateId);
+
+    if (!state) {
+      return null;
+    }
+
+    if (Date.now() > state.expiresAt) {
+      this.relayStates.delete(stateId);
+      return null;
+    }
+
+    return { returnUrl: state.returnUrl, workspaceId: state.workspaceId };
+  }
+
+  /**
+   * Save AuthnRequest state
+   */
+  public saveAuthnRequest(requestId: string, workspaceId: string): void {
+    this.authnRequests.set(requestId, {
+      workspaceId,
+      expiresAt: Date.now() + this.TTL,
+    });
+  }
+
+  /**
+   * Validate and consume AuthnRequest
+   * Returns true if request is valid and not expired, false otherwise
+   * Removes the request from storage after validation
+   */
+  public validateAndConsumeAuthnRequest(requestId: string, workspaceId: string): boolean {
+    const state = this.authnRequests.get(requestId);
+
+    if (!state) {
+      return false;
+    }
+
+    if (Date.now() > state.expiresAt) {
+      this.authnRequests.delete(requestId);
+      return false;
+    }
+
+    if (state.workspaceId !== workspaceId) {
+      this.authnRequests.delete(requestId);
+      return false;
+    }
+
+    /**
+     * Remove request after successful validation (prevent replay attacks)
+     */
+    this.authnRequests.delete(requestId);
+    return true;
+  }
+
+  /**
+   * Clean up expired entries (can be called periodically)
+   */
+  public cleanup(): void {
+    const now = Date.now();
+
+    /**
+     * Clean up expired relay states
+     */
+    for (const [id, state] of this.relayStates.entries()) {
+      if (now > state.expiresAt) {
+        this.relayStates.delete(id);
+      }
+    }
+
+    /**
+     * Clean up expired AuthnRequests
+     */
+    for (const [id, state] of this.authnRequests.entries()) {
+      if (now > state.expiresAt) {
+        this.authnRequests.delete(id);
+      }
+    }
+  }
+}
+
+export default new SamlStateStore();
+