@synth-deploy/server 0.1.0

package/src/auth/idp/ldap.ts

@@ -0,0 +1,340 @@
+import ldap from "ldapjs";
+import type { IdpUser } from "@synth-deploy/core";
+import type { IdpAdapter } from "./types.js";
+
+export interface LdapConfig {
+  url: string;              // e.g. ldaps://dc.corp.example.com:636
+  bindDn: string;           // service account DN
+  bindCredential: string;   // service account password (encrypted at rest)
+  searchBase: string;       // e.g. ou=Users,dc=corp,dc=example,dc=com
+  searchFilter: string;     // e.g. (sAMAccountName={{username}})
+  groupSearchBase: string;  // e.g. ou=Groups,dc=corp,dc=example,dc=com
+  groupSearchFilter: string; // e.g. (member={{dn}})
+  useTls: boolean;
+  tlsCaPath?: string;
+}
+
+export interface LdapAuthenticateParams {
+  username: string;
+  password: string;
+  config: LdapConfig;
+}
+
+interface LdapSearchEntry {
+  dn: string;
+  attributes: Array<{ type: string; values: string[] }>;
+}
+
+/**
+ * Creates an ldapjs client with optional TLS settings.
+ */
+function createClient(config: LdapConfig): ldap.Client {
+  const clientOpts: ldap.ClientOptions = {
+    url: config.url,
+    connectTimeout: 10_000,
+    timeout: 10_000,
+  };
+
+  if (config.useTls && config.tlsCaPath) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const fs = require("node:fs");
+    clientOpts.tlsOptions = {
+      ca: [fs.readFileSync(config.tlsCaPath)],
+      rejectUnauthorized: true,
+    };
+  }
+
+  return ldap.createClient(clientOpts);
+}
+
+/**
+ * Promisified bind operation.
+ */
+function bindAsync(client: ldap.Client, dn: string, password: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    client.bind(dn, password, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+/**
+ * Promisified unbind operation.
+ */
+function unbindAsync(client: ldap.Client): Promise<void> {
+  return new Promise((resolve) => {
+    client.unbind((err) => {
+      // Ignore unbind errors — best-effort cleanup
+      resolve();
+    });
+  });
+}
+
+/**
+ * Promisified search operation. Returns an array of entry objects.
+ */
+function searchAsync(
+  client: ldap.Client,
+  base: string,
+  opts: ldap.SearchOptions,
+): Promise<LdapSearchEntry[]> {
+  return new Promise((resolve, reject) => {
+    client.search(base, opts, (err, res) => {
+      if (err) return reject(err);
+
+      const entries: LdapSearchEntry[] = [];
+      res.on("searchEntry", (entry) => {
+        const obj = entry.pojo;
+        entries.push({
+          dn: obj.objectName,
+          attributes: obj.attributes.map((a) => ({
+            type: a.type,
+            values: a.values,
+          })),
+        });
+      });
+      res.on("error", (searchErr) => reject(searchErr));
+      res.on("end", () => resolve(entries));
+    });
+  });
+}
+
+/**
+ * Extracts a named attribute value from an LDAP entry.
+ */
+function getAttr(entry: LdapSearchEntry, name: string): string {
+  const attr = entry.attributes.find(
+    (a) => a.type.toLowerCase() === name.toLowerCase(),
+  );
+  return attr?.values[0] ?? "";
+}
+
+/**
+ * LDAP/Active Directory adapter -- implements IdpAdapter for LDAP-based identity providers.
+ *
+ * Authentication flow:
+ * 1. Bind with service account credentials
+ * 2. Search for the user by username
+ * 3. Bind with the user's DN + provided password
+ * 4. Query group memberships (supports AD nested groups via matching rule OID)
+ * 5. Return IdpUser
+ */
+export class LdapAdapter implements IdpAdapter {
+  type = "ldap";
+
+  async authenticate(params: unknown): Promise<IdpUser> {
+    const { username, password, config } = params as LdapAuthenticateParams;
+
+    if (!username || !password) {
+      throw new Error("Username and password are required");
+    }
+
+    const client = createClient(config);
+
+    try {
+      // Step 1: Bind with service account
+      await bindAsync(client, config.bindDn, config.bindCredential);
+
+      // Step 2: Search for user by username
+      const filter = config.searchFilter.replace(/\{\{username\}\}/g, escapeFilterValue(username));
+
+      const userEntries = await searchAsync(client, config.searchBase, {
+        filter,
+        scope: "sub",
+        attributes: ["dn", "mail", "email", "displayName", "cn", "sAMAccountName", "userPrincipalName", "uid"],
+      });
+
+      if (userEntries.length === 0) {
+        throw new Error(`User not found: ${username}`);
+      }
+
+      const userEntry = userEntries[0];
+      const userDn = userEntry.dn;
+
+      // Step 3: Bind as the user to verify their password
+      const userClient = createClient(config);
+      try {
+        await bindAsync(userClient, userDn, password);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        throw new Error(`Invalid credentials for user ${username}: ${message}`);
+      } finally {
+        await unbindAsync(userClient);
+      }
+
+      // Step 4: Query group memberships (re-bind as service account)
+      // Use AD's LDAP_MATCHING_RULE_IN_CHAIN (1.2.840.113556.1.4.1941)
+      // for nested group resolution when the filter contains {{dn}}
+      let groupFilter = config.groupSearchFilter.replace(/\{\{dn\}\}/g, escapeFilterValue(userDn));
+
+      // If the server is Active Directory (URL contains ldaps/ldap and filter uses member),
+      // enhance with the transitive membership matching rule for nested groups
+      const useNestedGroups = config.groupSearchFilter.includes("member={{dn}}");
+      if (useNestedGroups) {
+        groupFilter = config.groupSearchFilter.replace(
+          "member={{dn}}",
+          `member:1.2.840.113556.1.4.1941:=${escapeFilterValue(userDn)}`,
+        );
+      }
+
+      let groups: string[] = [];
+      try {
+        const groupEntries = await searchAsync(client, config.groupSearchBase, {
+          filter: groupFilter,
+          scope: "sub",
+          attributes: ["cn", "dn"],
+        });
+        groups = groupEntries.map((entry) => getAttr(entry, "cn") || entry.dn);
+      } catch {
+        // Group search may fail if groupSearchBase is misconfigured — return empty groups
+        groups = [];
+      }
+
+      // Step 5: Build IdpUser
+      const email =
+        getAttr(userEntry, "mail") ||
+        getAttr(userEntry, "email") ||
+        getAttr(userEntry, "userPrincipalName") ||
+        "";
+
+      const displayName =
+        getAttr(userEntry, "displayName") ||
+        getAttr(userEntry, "cn") ||
+        username;
+
+      return {
+        externalId: userDn,
+        email,
+        displayName,
+        groups,
+        provider: "ldap",
+      };
+    } finally {
+      await unbindAsync(client);
+    }
+  }
+
+  async validateConfig(config: unknown): Promise<{ valid: boolean; error?: string }> {
+    const c = config as Record<string, unknown>;
+
+    // Required fields
+    if (!c.url || typeof c.url !== "string") {
+      return { valid: false, error: "url is required and must be a string" };
+    }
+    if (!c.bindDn || typeof c.bindDn !== "string") {
+      return { valid: false, error: "bindDn is required and must be a string" };
+    }
+    if (!c.bindCredential || typeof c.bindCredential !== "string") {
+      return { valid: false, error: "bindCredential is required and must be a string" };
+    }
+    if (!c.searchBase || typeof c.searchBase !== "string") {
+      return { valid: false, error: "searchBase is required and must be a string" };
+    }
+    if (!c.searchFilter || typeof c.searchFilter !== "string") {
+      return { valid: false, error: "searchFilter is required and must be a string" };
+    }
+    if (!c.groupSearchBase || typeof c.groupSearchBase !== "string") {
+      return { valid: false, error: "groupSearchBase is required and must be a string" };
+    }
+    if (!c.groupSearchFilter || typeof c.groupSearchFilter !== "string") {
+      return { valid: false, error: "groupSearchFilter is required and must be a string" };
+    }
+
+    // Validate URL format (must be ldap:// or ldaps://)
+    try {
+      const url = new URL(c.url);
+      if (!["ldap:", "ldaps:"].includes(url.protocol)) {
+        return { valid: false, error: "url must use ldap:// or ldaps:// protocol" };
+      }
+    } catch {
+      return { valid: false, error: "url must be a valid URL (e.g. ldaps://dc.corp.example.com:636)" };
+    }
+
+    // Validate that searchFilter contains {{username}} placeholder
+    if (!(c.searchFilter as string).includes("{{username}}")) {
+      return { valid: false, error: "searchFilter must contain {{username}} placeholder" };
+    }
+
+    // Validate that groupSearchFilter contains {{dn}} placeholder
+    if (!(c.groupSearchFilter as string).includes("{{dn}}")) {
+      return { valid: false, error: "groupSearchFilter must contain {{dn}} placeholder" };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Tests the LDAP connection by attempting a service account bind.
+   * Returns success/error without authenticating any user.
+   */
+  async testConnection(config: LdapConfig): Promise<{ success: boolean; error?: string }> {
+    const validation = await this.validateConfig(config);
+    if (!validation.valid) {
+      return { success: false, error: validation.error };
+    }
+
+    const client = createClient(config);
+    try {
+      await bindAsync(client, config.bindDn, config.bindCredential);
+      return { success: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return { success: false, error: `Service account bind failed: ${message}` };
+    } finally {
+      await unbindAsync(client);
+    }
+  }
+
+  /**
+   * Tests whether a specific user can be found in the LDAP directory.
+   * Uses the service account to search — does not authenticate the user.
+   */
+  async testUser(
+    config: LdapConfig,
+    username: string,
+  ): Promise<{ found: boolean; userDn?: string; email?: string; displayName?: string; error?: string }> {
+    const validation = await this.validateConfig(config);
+    if (!validation.valid) {
+      return { found: false, error: validation.error };
+    }
+
+    const client = createClient(config);
+    try {
+      await bindAsync(client, config.bindDn, config.bindCredential);
+
+      const filter = config.searchFilter.replace(/\{\{username\}\}/g, escapeFilterValue(username));
+      const entries = await searchAsync(client, config.searchBase, {
+        filter,
+        scope: "sub",
+        attributes: ["dn", "mail", "email", "displayName", "cn", "sAMAccountName", "userPrincipalName"],
+      });
+
+      if (entries.length === 0) {
+        return { found: false, error: `No user found matching: ${username}` };
+      }
+
+      const entry = entries[0];
+      return {
+        found: true,
+        userDn: entry.dn,
+        email: getAttr(entry, "mail") || getAttr(entry, "email") || getAttr(entry, "userPrincipalName") || undefined,
+        displayName: getAttr(entry, "displayName") || getAttr(entry, "cn") || undefined,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return { found: false, error: `LDAP search failed: ${message}` };
+    } finally {
+      await unbindAsync(client);
+    }
+  }
+}
+
+/**
+ * Escapes special characters in an LDAP filter value per RFC 4515.
+ */
+function escapeFilterValue(value: string): string {
+  return value.replace(/[\\*()\/\x00]/g, (ch) => {
+    return "\\" + ch.charCodeAt(0).toString(16).padStart(2, "0");
+  });
+}

package/src/auth/idp/oidc.ts

@@ -0,0 +1,117 @@
+import * as client from "openid-client";
+import type { IdpUser, OidcConfig } from "@synth-deploy/core";
+import type { IdpAdapter } from "./types.js";
+
+export interface OidcAuthenticateParams {
+  code: string;
+  redirectUri: string;
+  config: OidcConfig;
+}
+
+/**
+ * OIDC adapter — implements IdpAdapter for OpenID Connect providers.
+ *
+ * Uses the openid-client library for OIDC discovery and code exchange.
+ * Stateless: each authenticate call performs discovery fresh (the library
+ * caches internally).
+ */
+export class OidcAdapter implements IdpAdapter {
+  type = "oidc";
+
+  async authenticate(params: unknown): Promise<IdpUser> {
+    const { code, redirectUri, config } = params as OidcAuthenticateParams;
+
+    // Discover the OIDC provider configuration
+    const issuer = new URL(config.issuerUrl);
+    const oidcConfig = await client.discovery(issuer, config.clientId, config.clientSecret);
+
+    // Exchange authorization code for tokens
+    const tokens = await client.authorizationCodeGrant(oidcConfig, new URL(`${redirectUri}?code=${code}`), {
+      expectedState: undefined,
+    });
+
+    // Extract user info claims from the ID token or userinfo endpoint
+    const claims = tokens.claims();
+    let userInfo: Record<string, unknown> = {};
+    if (claims) {
+      userInfo = claims as unknown as Record<string, unknown>;
+    }
+
+    // If we need more claims, fetch from userinfo endpoint
+    try {
+      const fetchedInfo = await client.fetchUserInfo(oidcConfig, tokens.access_token!, claims?.sub as string);
+      userInfo = { ...userInfo, ...fetchedInfo };
+    } catch {
+      // UserInfo endpoint may not be available; rely on ID token claims
+    }
+
+    // Extract groups from the configured claim
+    const groupsClaim = config.groupsClaim || "groups";
+    const groups: string[] = Array.isArray(userInfo[groupsClaim])
+      ? (userInfo[groupsClaim] as string[])
+      : [];
+
+    return {
+      externalId: (userInfo.sub as string) ?? "",
+      email: (userInfo.email as string) ?? "",
+      displayName: (userInfo.name as string) ?? (userInfo.preferred_username as string) ?? "",
+      groups,
+      provider: "oidc",
+    };
+  }
+
+  async validateConfig(config: unknown): Promise<{ valid: boolean; error?: string }> {
+    const c = config as Record<string, unknown>;
+
+    if (!c.issuerUrl || typeof c.issuerUrl !== "string") {
+      return { valid: false, error: "issuerUrl is required and must be a string" };
+    }
+    if (!c.clientId || typeof c.clientId !== "string") {
+      return { valid: false, error: "clientId is required and must be a string" };
+    }
+    if (!c.clientSecret || typeof c.clientSecret !== "string") {
+      return { valid: false, error: "clientSecret is required and must be a string" };
+    }
+
+    // Validate URL format
+    try {
+      new URL(c.issuerUrl);
+    } catch {
+      return { valid: false, error: "issuerUrl must be a valid URL" };
+    }
+
+    // Attempt OIDC discovery to verify the issuer is reachable
+    try {
+      const issuer = new URL(c.issuerUrl);
+      await client.discovery(issuer, c.clientId, c.clientSecret);
+      return { valid: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return { valid: false, error: `OIDC discovery failed: ${message}` };
+    }
+  }
+
+  /**
+   * Builds the authorization URL to redirect the user to the IdP.
+   */
+  async getAuthorizationUrl(config: OidcConfig, redirectUri: string, state: string): Promise<string> {
+    const issuer = new URL(config.issuerUrl);
+    const oidcConfig = await client.discovery(issuer, config.clientId, config.clientSecret);
+
+    const authEndpoint = oidcConfig.serverMetadata().authorization_endpoint;
+    if (!authEndpoint) {
+      throw new Error("OIDC provider does not expose an authorization_endpoint");
+    }
+
+    const scopes = config.scopes?.length > 0 ? config.scopes.join(" ") : "openid profile email";
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: config.clientId,
+      redirect_uri: redirectUri,
+      scope: scopes,
+      state,
+    });
+
+    return `${authEndpoint}?${params.toString()}`;
+  }
+}

package/src/auth/idp/role-mapping.ts

@@ -0,0 +1,22 @@
+import type { IdpUser, RoleMappingRule } from "@synth-deploy/core";
+
+/**
+ * Applies role mapping rules to an IdP user's groups.
+ * Returns the set of Synth role names that should be assigned.
+ *
+ * If no mapping rules match any of the user's groups, returns an empty array.
+ */
+export function applyRoleMappings(
+  idpUser: IdpUser,
+  rules: RoleMappingRule[],
+): string[] {
+  const matchedRoles = new Set<string>();
+
+  for (const rule of rules) {
+    if (idpUser.groups.includes(rule.idpGroup)) {
+      matchedRoles.add(rule.synthRole);
+    }
+  }
+
+  return [...matchedRoles];
+}

package/src/auth/idp/saml.ts

@@ -0,0 +1,148 @@
+import { SAML } from "@node-saml/node-saml";
+import type { IdpUser } from "@synth-deploy/core";
+import type { IdpAdapter } from "./types.js";
+
+export interface SamlConfig {
+  entryPoint: string;       // IdP SSO URL
+  issuer: string;           // SP entity ID
+  cert: string;             // IdP signing certificate (PEM)
+  callbackUrl: string;      // ACS URL
+  signatureAlgorithm: "sha256" | "sha512";
+  groupsAttribute: string;  // default: "memberOf"
+}
+
+export interface SamlAuthenticateParams {
+  samlResponse: string;
+  config: SamlConfig;
+}
+
+/**
+ * SAML 2.0 adapter — implements IdpAdapter for SAML identity providers.
+ *
+ * Uses @node-saml/node-saml for AuthnRequest generation, SAML Response
+ * validation, and assertion parsing. Stateless: each call constructs a
+ * fresh SAML instance from config.
+ */
+export class SamlAdapter implements IdpAdapter {
+  type = "saml";
+
+  private buildSaml(config: SamlConfig): SAML {
+    return new SAML({
+      entryPoint: config.entryPoint,
+      issuer: config.issuer,
+      idpCert: config.cert,
+      callbackUrl: config.callbackUrl,
+      signatureAlgorithm: config.signatureAlgorithm === "sha512" ? "sha512" : "sha256",
+      wantAuthnResponseSigned: true,
+      wantAssertionsSigned: false,
+    });
+  }
+
+  async authenticate(params: unknown): Promise<IdpUser> {
+    const { samlResponse, config } = params as SamlAuthenticateParams;
+
+    const saml = this.buildSaml(config);
+
+    // Validate and parse the SAML Response
+    const { profile } = await saml.validatePostResponseAsync({
+      SAMLResponse: samlResponse,
+    });
+
+    if (!profile) {
+      throw new Error("SAML response did not contain a valid profile");
+    }
+
+    // Extract user attributes
+    const email = profile.nameID
+      || (profile as Record<string, unknown>)["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"] as string
+      || (profile as Record<string, unknown>).email as string
+      || "";
+
+    const displayName =
+      (profile as Record<string, unknown>)["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"] as string
+      || (profile as Record<string, unknown>).displayName as string
+      || (profile as Record<string, unknown>)["http://schemas.microsoft.com/identity/claims/displayname"] as string
+      || email;
+
+    // Extract groups from the configured attribute
+    const groupsAttribute = config.groupsAttribute || "memberOf";
+    const rawGroups = (profile as Record<string, unknown>)[groupsAttribute];
+    let groups: string[] = [];
+    if (Array.isArray(rawGroups)) {
+      groups = rawGroups.map(String);
+    } else if (typeof rawGroups === "string") {
+      groups = [rawGroups];
+    }
+
+    return {
+      externalId: profile.nameID || "",
+      email,
+      displayName,
+      groups,
+      provider: "saml",
+    };
+  }
+
+  async validateConfig(config: unknown): Promise<{ valid: boolean; error?: string }> {
+    const c = config as Record<string, unknown>;
+
+    if (!c.entryPoint || typeof c.entryPoint !== "string") {
+      return { valid: false, error: "entryPoint is required and must be a string" };
+    }
+    if (!c.issuer || typeof c.issuer !== "string") {
+      return { valid: false, error: "issuer is required and must be a string" };
+    }
+    if (!c.cert || typeof c.cert !== "string") {
+      return { valid: false, error: "cert is required and must be a string" };
+    }
+    if (!c.callbackUrl || typeof c.callbackUrl !== "string") {
+      return { valid: false, error: "callbackUrl is required and must be a string" };
+    }
+
+    // Validate URL formats
+    try {
+      new URL(c.entryPoint);
+    } catch {
+      return { valid: false, error: "entryPoint must be a valid URL" };
+    }
+    try {
+      new URL(c.callbackUrl);
+    } catch {
+      return { valid: false, error: "callbackUrl must be a valid URL" };
+    }
+
+    // Validate signatureAlgorithm if provided
+    if (c.signatureAlgorithm && !["sha256", "sha512"].includes(c.signatureAlgorithm as string)) {
+      return { valid: false, error: "signatureAlgorithm must be 'sha256' or 'sha512'" };
+    }
+
+    // Validate PEM certificate format (basic check)
+    const cert = c.cert as string;
+    const pemPattern = /-----BEGIN CERTIFICATE-----[\s\S]+-----END CERTIFICATE-----/;
+    const isBase64Block = /^[A-Za-z0-9+/\s=]+$/.test(cert.trim());
+    if (!pemPattern.test(cert) && !isBase64Block) {
+      return { valid: false, error: "cert must be a valid PEM-encoded certificate or base64 certificate body" };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Generates the AuthnRequest URL to redirect the user to the SAML IdP.
+   */
+  async getAuthorizationUrl(config: SamlConfig, relayState?: string): Promise<string> {
+    const saml = this.buildSaml(config);
+    const url = await saml.getAuthorizeUrlAsync(relayState ?? "", undefined, {});
+    return url;
+  }
+
+  /**
+   * Generates SP metadata XML for the configured SAML service provider.
+   * This metadata can be provided to the IdP administrator for trust configuration.
+   */
+  generateMetadata(config: SamlConfig): string {
+    const saml = this.buildSaml(config);
+    const metadata = saml.generateServiceProviderMetadata(null, null);
+    return metadata;
+  }
+}

package/src/auth/idp/types.ts

@@ -0,0 +1,22 @@
+import type { IdpUser } from "@synth-deploy/core";
+
+/**
+ * Adapter interface for Identity Provider integrations.
+ * Each IdP type (OIDC, SAML, LDAP) implements this interface.
+ */
+export interface IdpAdapter {
+  /** The IdP type this adapter handles */
+  type: string;
+
+  /**
+   * Authenticates a user via IdP-specific mechanism.
+   * For OIDC: exchanges an authorization code for tokens and extracts user info.
+   */
+  authenticate(params: unknown): Promise<IdpUser>;
+
+  /**
+   * Validates that a given config object is well-formed for this IdP type.
+   * Used when creating or updating an IdP provider configuration.
+   */
+  validateConfig(config: unknown): Promise<{ valid: boolean; error?: string }>;
+}