@checkstack/auth-ldap-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# @checkstack/auth-ldap-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/auth-backend@0.0.2
+  - @checkstack/auth-common@0.0.2
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+
+## 0.0.4
+
+### Patch Changes
+
+- a65e002: Add compile-time type safety for Lucide icon names
+
+  - Add `LucideIconName` type and `lucideIconSchema` Zod schema to `@checkstack/common`
+  - Update backend interfaces (`AuthStrategy`, `NotificationStrategy`, `IntegrationProvider`, `CommandDefinition`) to use `LucideIconName`
+  - Update RPC contracts to use `lucideIconSchema` for proper type inference across RPC boundaries
+  - Simplify `SocialProviderButton` to use `DynamicIcon` directly (removes 30+ lines of pascalCase conversion)
+  - Replace static `iconMap` in `SearchDialog` with `DynamicIcon` for dynamic icon rendering
+  - Add fallback handling in `DynamicIcon` when icon name isn't found
+  - Fix legacy kebab-case icon names to PascalCase: `mail`→`Mail`, `send`→`Send`, `github`→`Github`, `key-round`→`KeyRound`, `network`→`Network`, `AlertCircle`→`CircleAlert`
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/auth-common@0.2.1
+  - @checkstack/auth-backend@1.1.0
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [e26c08e]
+  - @checkstack/auth-common@0.2.0
+  - @checkstack/auth-backend@1.0.1
+
+## 0.0.2
+
+### Patch Changes
+
+- b354ab3: # Strategy Instructions Support & Telegram Notification Plugin
+
+  ## Strategy Instructions Interface
+
+  Added `adminInstructions` and `userInstructions` optional fields to the `NotificationStrategy` interface. These allow strategies to export markdown-formatted setup guides that are displayed in the configuration UI:
+
+  - **`adminInstructions`**: Shown when admins configure platform-wide strategy settings (e.g., how to create API keys)
+  - **`userInstructions`**: Shown when users configure their personal settings (e.g., how to link their account)
+
+  ### Updated Components
+
+  - `StrategyConfigCard` now accepts an `instructions` prop and renders it before config sections
+  - `StrategyCard` passes `adminInstructions` to `StrategyConfigCard`
+  - `UserChannelCard` renders `userInstructions` when users need to connect
+
+  ## New Telegram Notification Plugin
+
+  Added `@checkstack/notification-telegram-backend` plugin for sending notifications via Telegram:
+
+  - Uses [grammY](https://grammy.dev/) framework for Telegram Bot API integration
+  - Sends messages with MarkdownV2 formatting and inline keyboard buttons for actions
+  - Includes comprehensive admin instructions for bot setup via @BotFather
+  - Includes user instructions for account linking
+
+  ### Configuration
+
+  Admins need to configure a Telegram Bot Token obtained from @BotFather.
+
+  ### User Linking
+
+  The strategy uses `contactResolution: { type: "custom" }` for Telegram Login Widget integration. Full frontend integration for the Login Widget is pending future work.
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [32f2535]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [8e889b4]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/auth-backend@1.0.0
+  - @checkstack/auth-common@0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@checkstack/auth-ldap-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/auth-backend": "workspace:*",
+    "@checkstack/auth-common": "workspace:*",
+    "better-auth": "^1.4.9",
+    "drizzle-orm": "^0.45.1",
+    "ldapts": "^8.0.0",
+    "zod": "^4.0.0",
+    "@checkstack/common": "workspace:*"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/test-utils-backend": "workspace:*",
+    "typescript": "^5.7.2"
+  },
+  "plugin": {
+    "id": "auth-ldap-backend",
+    "name": "@checkstack/auth-ldap-backend",
+    "type": "backend",
+    "displayName": "LDAP Authentication (Backend)"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,272 @@
+import { describe, expect, it, beforeEach, mock } from "bun:test";
+import type { Client as LdapClient } from "ldapts";
+
+describe("LDAP Authentication Strategy", () => {
+  // Mock LDAP client
+  let mockLdapClient: {
+    bind: ReturnType<typeof mock>;
+    search: ReturnType<typeof mock>;
+    unbind: ReturnType<typeof mock>;
+  };
+
+  beforeEach(() => {
+    mockLdapClient = {
+      bind: mock(() => Promise.resolve()),
+      search: mock(() =>
+        Promise.resolve({
+          searchEntries: [
+            {
+              dn: "uid=testuser,ou=users,dc=example,dc=com",
+              uid: "testuser",
+              mail: "testuser@example.com",
+              displayName: "Test User",
+              givenName: "Test",
+              sn: "User",
+            },
+          ],
+        })
+      ),
+      unbind: mock(() => Promise.resolve()),
+    };
+  });
+
+  describe("LDAP Client Authentication", () => {
+    it("should successfully authenticate with valid credentials", async () => {
+      // Simulate successful bind
+      mockLdapClient.bind.mockResolvedValue(undefined);
+
+      await mockLdapClient.bind("cn=admin,dc=example,dc=com", "adminPassword");
+      expect(mockLdapClient.bind).toHaveBeenCalledWith(
+        "cn=admin,dc=example,dc=com",
+        "adminPassword"
+      );
+    });
+
+    it("should fail authentication with invalid credentials", async () => {
+      // Simulate failed bind
+      mockLdapClient.bind.mockRejectedValue(new Error("Invalid credentials"));
+
+      await expect(
+        mockLdapClient.bind("uid=testuser,ou=users,dc=example,dc=com", "wrong")
+      ).rejects.toThrow("Invalid credentials");
+    });
+
+    it("should search for user in LDAP directory", async () => {
+      const searchResult = await mockLdapClient.search();
+
+      expect(mockLdapClient.search).toHaveBeenCalled();
+      expect(searchResult.searchEntries).toHaveLength(1);
+      expect(searchResult.searchEntries[0].uid).toBe("testuser");
+      expect(searchResult.searchEntries[0].mail).toBe("testuser@example.com");
+    });
+
+    it("should return empty result when user not found", async () => {
+      mockLdapClient.search.mockResolvedValue({
+        searchEntries: [],
+      });
+
+      const searchResult = await mockLdapClient.search();
+      expect(searchResult.searchEntries).toHaveLength(0);
+    });
+
+    it("should extract user attributes from LDAP entry", async () => {
+      const searchResult = await mockLdapClient.search();
+      const userEntry = searchResult.searchEntries[0];
+
+      expect(userEntry.mail).toBe("testuser@example.com");
+      expect(userEntry.displayName).toBe("Test User");
+      expect(userEntry.givenName).toBe("Test");
+      expect(userEntry.sn).toBe("User");
+    });
+  });
+
+  describe("HTTP Login Endpoint", () => {
+    it("should return 400 when username is missing", async () => {
+      const request = new Request("http://localhost/api/auth-ldap/", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password: "test123" }),
+      });
+
+      // We'll test this with the actual handler in integration tests
+      const body = await request.json();
+      expect(body.password).toBe("test123");
+      expect(body.username).toBeUndefined();
+    });
+
+    it("should return 400 when password is missing", async () => {
+      const request = new Request("http://localhost/api/auth-ldap/", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ username: "testuser" }),
+      });
+
+      const body = await request.json();
+      expect(body.username).toBe("testuser");
+      expect(body.password).toBeUndefined();
+    });
+
+    it("should parse valid login request body", async () => {
+      const request = new Request("http://localhost/api/auth-ldap/", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          username: "testuser",
+          password: "test123",
+        }),
+      });
+
+      const body = await request.json();
+      expect(body.username).toBe("testuser");
+      expect(body.password).toBe("test123");
+    });
+  });
+
+  describe("User Attribute Mapping", () => {
+    it("should map email attribute correctly", () => {
+      const ldapAttributes = {
+        mail: "user@example.com",
+        userPrincipalName: "user@domain.com",
+      };
+
+      const emailMapping = "mail";
+      const email = ldapAttributes[emailMapping];
+      expect(email).toBe("user@example.com");
+    });
+
+    it("should map displayName attribute correctly", () => {
+      const ldapAttributes = {
+        displayName: "John Doe",
+        cn: "johndoe",
+      };
+
+      const nameMapping = "displayName";
+      const name = ldapAttributes[nameMapping];
+      expect(name).toBe("John Doe");
+    });
+
+    it("should build name from firstName and lastName", () => {
+      const ldapAttributes = {
+        givenName: "John",
+        sn: "Doe",
+      };
+
+      const firstName = ldapAttributes.givenName;
+      const lastName = ldapAttributes.sn;
+      const fullName = `${firstName} ${lastName}`;
+      expect(fullName).toBe("John Doe");
+    });
+
+    it("should handle missing optional attributes gracefully", () => {
+      const ldapAttributes: Record<string, string | undefined> = {
+        uid: "testuser",
+        mail: "test@example.com",
+        // displayName is missing
+      };
+
+      const displayName =
+        ldapAttributes["displayName"] || ldapAttributes["uid"];
+      expect(displayName).toBe("testuser");
+    });
+  });
+
+  describe("Search Filter Templates", () => {
+    it("should replace {0} placeholder with username", () => {
+      const searchFilter = "(uid={0})";
+      const username = "testuser";
+      const result = searchFilter.replace("{0}", username);
+      expect(result).toBe("(uid=testuser)");
+    });
+
+    it("should work with sAMAccountName filter for Active Directory", () => {
+      const searchFilter = "(sAMAccountName={0})";
+      const username = "jdoe";
+      const result = searchFilter.replace("{0}", username);
+      expect(result).toBe("(sAMAccountName=jdoe)");
+    });
+
+    it("should work with email filter", () => {
+      const searchFilter = "(mail={0})";
+      const email = "user@example.com";
+      const result = searchFilter.replace("{0}", email);
+      expect(result).toBe("(mail=user@example.com)");
+    });
+
+    it("should work with complex AND filter", () => {
+      const searchFilter = "(&(uid={0})(objectClass=person))";
+      const username = "testuser";
+      const result = searchFilter.replace("{0}", username);
+      expect(result).toBe("(&(uid=testuser)(objectClass=person))");
+    });
+  });
+
+  describe("Configuration Validation", () => {
+    it("should validate required URL field", () => {
+      const config = {
+        enabled: true,
+        url: "",
+        baseDN: "ou=users,dc=example,dc=com",
+      };
+
+      expect(config.url).toBe("");
+      // URL validation would happen in Zod schema
+    });
+
+    it("should validate baseDN format", () => {
+      const validBaseDN = "ou=users,dc=example,dc=com";
+      expect(validBaseDN).toContain("dc=");
+      expect(validBaseDN).toContain("ou=");
+    });
+
+    it("should have sensible default for timeout", () => {
+      const defaultTimeout = 5000;
+      expect(defaultTimeout).toBe(5000);
+      expect(defaultTimeout).toBeGreaterThan(0);
+    });
+
+    it("should default autoCreateUsers to true", () => {
+      const defaultAutoCreate = true;
+      expect(defaultAutoCreate).toBe(true);
+    });
+
+    it("should default autoUpdateUsers to true", () => {
+      const defaultAutoUpdate = true;
+      expect(defaultAutoUpdate).toBe(true);
+    });
+  });
+
+  describe("Array Attribute Handling", () => {
+    it("should take first value from array attributes", () => {
+      const ldapEntry = {
+        mail: ["primary@example.com", "secondary@example.com"],
+        cn: ["John Doe"],
+      };
+
+      // Simulate taking first value
+      const email = Array.isArray(ldapEntry.mail)
+        ? ldapEntry.mail[0]
+        : ldapEntry.mail;
+      const name = Array.isArray(ldapEntry.cn) ? ldapEntry.cn[0] : ldapEntry.cn;
+
+      expect(email).toBe("primary@example.com");
+      expect(name).toBe("John Doe");
+    });
+
+    it("should handle string attributes without modification", () => {
+      const ldapEntry = {
+        uid: "testuser",
+        mail: "test@example.com",
+      };
+
+      const uid = Array.isArray(ldapEntry.uid)
+        ? ldapEntry.uid[0]
+        : ldapEntry.uid;
+      const mail = Array.isArray(ldapEntry.mail)
+        ? ldapEntry.mail[0]
+        : ldapEntry.mail;
+
+      expect(uid).toBe("testuser");
+      expect(mail).toBe("test@example.com");
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,471 @@
+import {
+  createBackendPlugin,
+  type AuthStrategy,
+  configString,
+  coreServices,
+  configBoolean,
+  configNumber,
+} from "@checkstack/backend-api";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  betterAuthExtensionPoint,
+  redirectToAuthError,
+} from "@checkstack/auth-backend";
+import { AuthApi } from "@checkstack/auth-common";
+import { z } from "zod";
+import { Client as LdapClient } from "ldapts";
+import { hashPassword } from "better-auth/crypto";
+
+// LDAP Configuration Schema V1
+const _ldapConfigV1 = z.object({
+  enabled: configBoolean({})
+    .default(false)
+    .describe("Enable LDAP authentication"),
+  url: configString({})
+    .url()
+    .default("ldaps://ldap.example.com:636")
+    .describe("LDAP server URL (e.g., ldaps://ldap.example.com:636)"),
+  bindDN: configString({})
+    .optional()
+    .describe(
+      "Service account DN for searching (e.g., cn=admin,dc=example,dc=com)"
+    ),
+  bindPassword: configString({ "x-secret": true })
+    .describe("Service account password")
+    .optional(),
+  baseDN: configString({})
+    .default("ou=users,dc=example,dc=com")
+    .describe("Base DN for user searches (e.g., ou=users,dc=example,dc=com)"),
+  searchFilter: configString({})
+    .default("(uid={0})")
+    .describe("LDAP search filter, {0} will be replaced with username"),
+  usernameAttribute: configString({})
+    .default("uid")
+    .describe("LDAP attribute to match against login username"),
+  attributeMapping: z
+    .object({
+      email: configString({})
+        .default("mail")
+        .describe("LDAP attribute for email address"),
+      name: configString({})
+        .default("displayName")
+        .describe("LDAP attribute for display name"),
+      firstName: configString({})
+        .default("givenName")
+        .describe("LDAP attribute for first name")
+        .optional(),
+      lastName: configString({})
+        .default("sn")
+        .describe("LDAP attribute for last name")
+        .optional(),
+    })
+    .default({
+      email: "mail",
+      name: "displayName",
+    })
+    .describe("Map LDAP attributes to user fields"),
+  tlsOptions: z
+    .object({
+      rejectUnauthorized: configBoolean({})
+        .default(true)
+        .describe("Reject unauthorized SSL certificates"),
+      ca: configString({ "x-secret": true })
+        .describe("Custom CA certificate (PEM format)")
+        .optional(),
+    })
+    .default({ rejectUnauthorized: true })
+    .describe("TLS/SSL configuration"),
+  timeout: configNumber({})
+    .default(5000)
+    .describe("Connection timeout in milliseconds"),
+  autoCreateUsers: configBoolean({})
+    .default(true)
+    .describe("Automatically create users on first login"),
+  autoUpdateUsers: configBoolean({})
+    .default(true)
+    .describe("Update user attributes on each login"),
+});
+
+// LDAP Configuration Schema V1
+const ldapConfigV2 = z.object({
+  url: configString({})
+    .url()
+    .default("ldaps://ldap.example.com:636")
+    .describe("LDAP server URL (e.g., ldaps://ldap.example.com:636)"),
+  bindDN: configString({})
+    .optional()
+    .describe(
+      "Service account DN for searching (e.g., cn=admin,dc=example,dc=com)"
+    ),
+  bindPassword: configString({ "x-secret": true })
+    .describe("Service account password")
+    .optional(),
+  baseDN: configString({})
+    .default("ou=users,dc=example,dc=com")
+    .describe("Base DN for user searches (e.g., ou=users,dc=example,dc=com)"),
+  searchFilter: configString({})
+    .default("(uid={0})")
+    .describe("LDAP search filter, {0} will be replaced with username"),
+  usernameAttribute: configString({})
+    .default("uid")
+    .describe("LDAP attribute to match against login username"),
+  attributeMapping: z
+    .object({
+      email: configString({})
+        .default("mail")
+        .describe("LDAP attribute for email address"),
+      name: configString({})
+        .default("displayName")
+        .describe("LDAP attribute for display name"),
+      firstName: configString({})
+        .default("givenName")
+        .describe("LDAP attribute for first name")
+        .optional(),
+      lastName: configString({})
+        .default("sn")
+        .describe("LDAP attribute for last name")
+        .optional(),
+    })
+    .default({
+      email: "mail",
+      name: "displayName",
+    })
+    .describe("Map LDAP attributes to user fields"),
+  tlsOptions: z
+    .object({
+      rejectUnauthorized: configBoolean({})
+        .default(true)
+        .describe("Reject unauthorized SSL certificates"),
+      ca: configString({ "x-secret": true })
+        .describe("Custom CA certificate (PEM format)")
+        .optional(),
+    })
+    .default({ rejectUnauthorized: true })
+    .describe("TLS/SSL configuration"),
+  timeout: configNumber({})
+    .default(5000)
+    .describe("Connection timeout in milliseconds"),
+  autoCreateUsers: configBoolean({})
+    .default(true)
+    .describe("Automatically create users on first login"),
+  autoUpdateUsers: configBoolean({})
+    .default(true)
+    .describe("Update user attributes on each login"),
+});
+
+type LdapConfig = z.infer<typeof ldapConfigV2>;
+
+// LDAP Strategy Definition
+const ldapStrategy: AuthStrategy<LdapConfig> = {
+  id: "ldap",
+  displayName: "LDAP",
+  description: "Authenticate using LDAP directory",
+  icon: "Network",
+  configVersion: 2,
+  configSchema: ldapConfigV2,
+  requiresManualRegistration: false,
+  adminInstructions: `
+## LDAP Configuration
+
+Configure LDAP authentication to allow users from your directory to sign in:
+
+1. Enter your LDAP server **URL** (e.g., \`ldaps://ldap.example.com:636\`)
+2. If your server requires bind authentication, provide **Bind DN** and **password**
+3. Set the **Base DN** where user accounts are located
+4. Configure the **search filter** to match usernames (e.g., \`(uid={0})\` or \`(sAMAccountName={0})\`)
+5. Map **LDAP attributes** to user fields (email, name)
+
+> **Active Directory**: Use \`ldaps://\` with port 636, \`sAMAccountName\` for username, and \`userPrincipalName\` for email.
+`.trim(),
+  migrations: [
+    {
+      description: "Migrate LDAP configuration to version 2",
+      fromVersion: 1,
+      toVersion: 2,
+      migrate: (oldConfig: z.infer<typeof _ldapConfigV1>) => {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { enabled, ...rest } = oldConfig;
+        return rest;
+      },
+    },
+  ],
+};
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    // Register the LDAP strategy
+    const extensionPoint = env.getExtensionPoint(betterAuthExtensionPoint);
+    extensionPoint.addStrategy(ldapStrategy);
+
+    // Register init logic for custom login endpoint
+    env.registerInit({
+      deps: {
+        rpc: coreServices.rpc,
+        logger: coreServices.logger,
+        config: coreServices.config,
+        rpcClient: coreServices.rpcClient,
+      },
+      init: async ({ rpc, logger, config, rpcClient }) => {
+        logger.debug("[auth-ldap-backend] Initializing LDAP authentication...");
+
+        // Create auth client once for reuse
+        const authClient = rpcClient.forPlugin(AuthApi);
+
+        // Helper function to authenticate against LDAP
+        const authenticateLdap = async (
+          username: string,
+          password: string
+        ): Promise<{
+          success: boolean;
+          userAttributes?: Record<string, unknown>;
+          error?: string;
+        }> => {
+          try {
+            // Load LDAP configuration
+            const ldapConfig = await config.get("ldap", ldapConfigV2, 2);
+
+            if (!ldapConfig) {
+              return {
+                success: false,
+                error: "LDAP authentication is not enabled",
+              };
+            }
+
+            // Create LDAP client
+            const client = new LdapClient({
+              url: ldapConfig.url,
+              timeout: ldapConfig.timeout,
+              tlsOptions: ldapConfig.tlsOptions.ca
+                ? {
+                    rejectUnauthorized:
+                      ldapConfig.tlsOptions.rejectUnauthorized,
+                    ca: ldapConfig.tlsOptions.ca,
+                  }
+                : {
+                    rejectUnauthorized:
+                      ldapConfig.tlsOptions.rejectUnauthorized,
+                  },
+            });
+
+            try {
+              // Step 1: Bind with service account (if configured)
+              if (ldapConfig.bindDN && ldapConfig.bindPassword) {
+                await client.bind(ldapConfig.bindDN, ldapConfig.bindPassword);
+              }
+
+              // Step 2: Search for the user
+              const searchFilter = ldapConfig.searchFilter.replace(
+                "{0}",
+                username
+              );
+              const searchResult = await client.search(ldapConfig.baseDN, {
+                filter: searchFilter,
+                scope: "sub",
+              });
+
+              if (
+                !searchResult.searchEntries ||
+                searchResult.searchEntries.length === 0
+              ) {
+                return {
+                  success: false,
+                  error: "User not found in LDAP directory",
+                };
+              }
+
+              if (searchResult.searchEntries.length > 1) {
+                logger.warn(
+                  `Multiple LDAP entries found for username: ${username}`
+                );
+              }
+
+              const userEntry = searchResult.searchEntries[0];
+              const userDN = userEntry.dn;
+
+              // Step 3: Try to bind as the user to verify password
+              const userClient = new LdapClient({
+                url: ldapConfig.url,
+                timeout: ldapConfig.timeout,
+                tlsOptions: ldapConfig.tlsOptions.ca
+                  ? {
+                      rejectUnauthorized:
+                        ldapConfig.tlsOptions.rejectUnauthorized,
+                      ca: ldapConfig.tlsOptions.ca,
+                    }
+                  : {
+                      rejectUnauthorized:
+                        ldapConfig.tlsOptions.rejectUnauthorized,
+                    },
+              });
+
+              try {
+                await userClient.bind(userDN, password);
+              } catch (bindError) {
+                logger.debug(`LDAP bind failed for user ${userDN}:`, bindError);
+                return { success: false, error: "Invalid credentials" };
+              } finally {
+                await userClient.unbind();
+              }
+
+              // Step 4: Extract user attributes
+              const attributes: Record<string, unknown> = {};
+              for (const [key, value] of Object.entries(userEntry)) {
+                if (typeof value === "string" || typeof value === "number") {
+                  attributes[key] = value;
+                } else if (Array.isArray(value) && value.length > 0) {
+                  // Take first value for arrays
+                  attributes[key] = value[0];
+                }
+              }
+
+              return { success: true, userAttributes: attributes };
+            } finally {
+              await client.unbind();
+            }
+          } catch (error) {
+            logger.error("LDAP authentication error:", error);
+            return {
+              success: false,
+              error: error instanceof Error ? error.message : "Unknown error",
+            };
+          }
+        };
+
+        // Helper function to create or update user via RPC
+        const syncUser = async (
+          username: string,
+          ldapAttributes: Record<string, unknown>
+        ): Promise<{ userId: string; email: string; name: string }> => {
+          const ldapConfig = await config.get("ldap", ldapConfigV2, 2);
+          if (!ldapConfig) {
+            throw new Error("LDAP configuration not found");
+          }
+
+          // Extract user info from LDAP attributes
+          const mapping = ldapConfig.attributeMapping;
+          const email =
+            (ldapAttributes[mapping.email] as string | undefined) ||
+            `${username}@ldap.local`;
+
+          // Build name from available attributes
+          let name: string;
+          if (ldapAttributes[mapping.name]) {
+            name = ldapAttributes[mapping.name] as string;
+          } else if (
+            mapping.firstName &&
+            mapping.lastName &&
+            ldapAttributes[mapping.firstName] &&
+            ldapAttributes[mapping.lastName]
+          ) {
+            name = `${ldapAttributes[mapping.firstName]} ${
+              ldapAttributes[mapping.lastName]
+            }`;
+          } else {
+            name = username;
+          }
+
+          // Check if auto-creation is disabled and user doesn't exist
+          if (!ldapConfig.autoCreateUsers) {
+            const existingUser = await authClient.findUserByEmail({ email });
+            if (!existingUser) {
+              throw new Error(
+                "User does not exist and auto-creation is disabled"
+              );
+            }
+          }
+
+          // Use RPC to upsert user (handles registration check, user/account creation)
+          const hashedPassword = await hashPassword(crypto.randomUUID()); // Random password, won't be used
+
+          const { userId, created } = await authClient.upsertExternalUser({
+            email,
+            name,
+            providerId: "ldap",
+            accountId: username,
+            password: hashedPassword,
+            autoUpdateUser: ldapConfig.autoUpdateUsers,
+          });
+
+          if (created) {
+            logger.info(`Created new user from LDAP: ${email}`);
+          } else if (ldapConfig.autoUpdateUsers) {
+            logger.debug(`Updated LDAP user: ${email}`);
+          }
+
+          return { userId, email, name };
+        };
+
+        // Register custom HTTP handler for LDAP login
+        // Path /ldap/login will resolve to /api/auth-ldap/ldap/login
+        rpc.registerHttpHandler(async (req: Request) => {
+          try {
+            const body = await req.json();
+            const { username, password } = body;
+
+            if (!username || !password) {
+              return redirectToAuthError("Username and password are required");
+            }
+
+            // Authenticate with LDAP
+            const authResult = await authenticateLdap(username, password);
+
+            if (!authResult.success) {
+              return redirectToAuthError(
+                authResult.error || "Authentication failed"
+              );
+            }
+
+            // Sync user to database
+            const { userId, email, name } = await syncUser(
+              username,
+              authResult.userAttributes!
+            );
+
+            // Create session via RPC
+            const sessionToken = crypto.randomUUID();
+            const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days
+
+            await authClient.createSession({
+              userId,
+              token: sessionToken,
+              expiresAt,
+            });
+
+            logger.info(`Created session for LDAP user: ${email}`);
+
+            // Return session token in cookie format
+            return Response.json(
+              {
+                success: true,
+                user: {
+                  id: userId,
+                  email,
+                  name,
+                },
+              },
+              {
+                status: 200,
+                headers: {
+                  "Content-Type": "application/json",
+                  "Set-Cookie": `better-auth.session_token=${sessionToken}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${
+                    7 * 24 * 60 * 60
+                  }`,
+                },
+              }
+            );
+          } catch (error) {
+            logger.error("LDAP login error:", error);
+            const message =
+              error instanceof Error
+                ? error.message
+                : "Authentication failed. Please try again.";
+            return redirectToAuthError(message);
+          }
+        });
+
+        logger.debug("✅ LDAP authentication initialized");
+      },
+    });
+  },
+});

package/src/integration.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it, beforeEach, mock } from "bun:test";
+
+describe("LDAP Authentication Integration Tests", () => {
+  // Mock LDAP client responses
+  const mockLdapBind = mock(() => Promise.resolve());
+  const mockLdapSearch = mock(() =>
+    Promise.resolve({
+      searchEntries: [
+        {
+          dn: "uid=testuser,ou=users,dc=example,dc=com",
+          uid: ["testuser"],
+          mail: ["testuser@example.com"],
+          displayName: ["Test User"],
+          givenName: ["Test"],
+          sn: ["User"],
+        },
+      ],
+    })
+  );
+  const mockLdapUnbind = mock(() => Promise.resolve());
+
+  beforeEach(() => {
+    // Reset mocks
+    mockLdapBind.mockClear();
+    mockLdapSearch.mockClear();
+    mockLdapUnbind.mockClear();
+
+    // Setup default successful responses
+    mockLdapBind.mockResolvedValue(undefined);
+    mockLdapSearch.mockResolvedValue({
+      searchEntries: [
+        {
+          dn: "uid=testuser,ou=users,dc=example,dc=com",
+          uid: ["testuser"],
+          mail: ["testuser@example.com"],
+          displayName: ["Test User"],
+          givenName: ["Test"],
+          sn: ["User"],
+        },
+      ],
+    });
+  });
+
+  describe("Full LDAP Authentication Flow", () => {
+    it("should authenticate user via LDAP", async () => {
+      // Simulate authentication
+      const username = "testuser";
+      const password = "correct-password";
+
+      // 1. Search for user
+      const searchResult = await mockLdapSearch();
+      expect(searchResult.searchEntries).toHaveLength(1);
+      const userEntry = searchResult.searchEntries[0];
+
+      // 2. Bind as user
+      await mockLdapBind();
+
+      // 3. Extract attributes
+      const email = Array.isArray(userEntry.mail)
+        ? userEntry.mail[0]
+        : userEntry.mail;
+      const name = Array.isArray(userEntry.displayName)
+        ? userEntry.displayName[0]
+        : userEntry.displayName;
+
+      expect(email).toBe("testuser@example.com");
+      expect(name).toBe("Test User");
+    });
+
+    it("should fail authentication with invalid LDAP credentials", async () => {
+      // Mock LDAP bind failure
+      mockLdapBind.mockRejectedValueOnce(new Error("Invalid Credentials"));
+
+      await expect(mockLdapBind()).rejects.toThrow("Invalid Credentials");
+    });
+
+    it("should fail when user not found in LDAP directory", async () => {
+      // Mock empty search result
+      mockLdapSearch.mockResolvedValueOnce({
+        searchEntries: [],
+      });
+
+      const searchResult = await mockLdapSearch();
+      expect(searchResult.searchEntries).toHaveLength(0);
+    });
+
+    it("should handle LDAP connection errors gracefully", async () => {
+      // Mock connection error
+      mockLdapBind.mockRejectedValueOnce(new Error("Connection refused"));
+
+      await expect(mockLdapBind()).rejects.toThrow("Connection refused");
+    });
+  });
+
+  describe("HTTP Login Endpoint Integration", () => {
+    it("should return session cookie format on successful authentication", async () => {
+      // Simulate successful login
+      const searchResult = await mockLdapSearch();
+      await mockLdapBind();
+
+      const sessionToken = "mock-session-token-12345";
+      const maxAge = 7 * 24 * 60 * 60; // 7 days in seconds
+      const expectedCookie = `better-auth.session_token=${sessionToken}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}`;
+
+      expect(expectedCookie).toContain("better-auth.session_token");
+      expect(expectedCookie).toContain("HttpOnly");
+      expect(expectedCookie).toContain("SameSite=Lax");
+      expect(expectedCookie).toContain(`Max-Age=${maxAge}`);
+    });
+
+    it("should return 401 on authentication failure", async () => {
+      mockLdapBind.mockRejectedValueOnce(new Error("Invalid Credentials"));
+
+      try {
+        await mockLdapBind();
+        expect(true).toBe(false); // Should not reach here
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBe("Invalid Credentials");
+      }
+    });
+
+    it("should return user info structure on successful login", async () => {
+      const searchResult = await mockLdapSearch();
+      const userEntry = searchResult.searchEntries[0];
+
+      const email = Array.isArray(userEntry.mail)
+        ? userEntry.mail[0]
+        : userEntry.mail;
+      const name = Array.isArray(userEntry.displayName)
+        ? userEntry.displayName[0]
+        : userEntry.displayName;
+
+      const response = {
+        success: true,
+        user: {
+          id: "user-123",
+          email,
+          name,
+        },
+      };
+
+      expect(response.success).toBe(true);
+      expect(response.user.email).toBe("testuser@example.com");
+      expect(response.user.name).toBe("Test User");
+    });
+  });
+
+  describe("Attribute Mapping Configuration", () => {
+    it("should use custom email attribute mapping (userPrincipalName)", async () => {
+      // Mock LDAP entry with userPrincipalName instead of mail
+      type CustomLdapEntry = {
+        dn: string;
+        userPrincipalName: string[];
+        displayName: string[];
+      };
+
+      // @ts-expect-error - Mock data doesn't need to match full type
+      mockLdapSearch.mockResolvedValueOnce({
+        searchEntries: [
+          {
+            dn: "CN=Test User,OU=Users,DC=example,DC=com",
+            userPrincipalName: ["testuser@domain.com"],
+            displayName: ["Test User"],
+          } as unknown,
+        ],
+      } as unknown);
+
+      const searchResult = await mockLdapSearch();
+      const userEntry = searchResult.searchEntries[0] as Record<
+        string,
+        unknown
+      >;
+
+      // Simulate custom mapping
+      const emailMapping = "userPrincipalName";
+      const emailValue = userEntry[emailMapping] as string[] | string;
+      const email = Array.isArray(emailValue) ? emailValue[0] : emailValue;
+
+      expect(email).toBe("testuser@domain.com");
+    });
+
+    it("should use custom name attribute mapping (cn)", async () => {
+      type CustomLdapEntry = {
+        dn: string;
+        cn: string[];
+        mail: string[];
+      };
+
+      // @ts-expect-error - Mock data doesn't need to match full type
+      mockLdapSearch.mockResolvedValueOnce({
+        searchEntries: [
+          {
+            dn: "uid=testuser,ou=users,dc=example,dc=com",
+            cn: ["Test User CN"],
+            mail: ["test@example.com"],
+          } as unknown,
+        ],
+      } as unknown);
+
+      const searchResult = await mockLdapSearch();
+      const userEntry = searchResult.searchEntries[0] as Record<
+        string,
+        unknown
+      >;
+
+      // Simulate custom mapping to cn instead of displayName
+      const nameMapping = "cn";
+      const nameValue = userEntry[nameMapping] as string[] | string;
+      const name = Array.isArray(nameValue) ? nameValue[0] : nameValue;
+
+      expect(name).toBe("Test User CN");
+    });
+
+    it("should construct name from firstName and lastName attributes", async () => {
+      const searchResult = await mockLdapSearch();
+      const userEntry = searchResult.searchEntries[0];
+
+      const firstNameValue = userEntry.givenName;
+      const lastNameValue = userEntry.sn;
+
+      const firstName = Array.isArray(firstNameValue)
+        ? firstNameValue[0]
+        : firstNameValue;
+      const lastName = Array.isArray(lastNameValue)
+        ? lastNameValue[0]
+        : lastNameValue;
+      const fullName = `${firstName} ${lastName}`.trim();
+
+      expect(fullName).toBe("Test User");
+    });
+  });
+
+  describe("TLS/SSL Configuration", () => {
+    it("should connect with TLS when using ldaps:// URL", () => {
+      const url = "ldaps://ldap.example.com:636";
+      expect(url).toContain("ldaps://");
+      expect(url).toContain(":636");
+    });
+
+    it("should allow custom CA certificate", () => {
+      const caCertificate = "-----BEGIN CERTIFICATE-----\\nMIID...";
+      expect(caCertificate).toContain("BEGIN CERTIFICATE");
+    });
+
+    it("should respect rejectUnauthorized setting", () => {
+      const rejectUnauthorized = false;
+      expect(rejectUnauthorized).toBe(false);
+    });
+  });
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Auth LDAP backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "auth-ldap",
+});

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json"
+}