ldap-authentication 4.2.1 → 4.4.0

package/.github/workflows/codeql-analysis.yml

@@ -31,15 +31,20 @@ jobs:
         language: [ 'javascript' ]
         # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
         # Learn more:
-        # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
+        # https://docs.github.com/en/code-security/code-scanning/defining-your-code-scanning-policy/configuring-code-scanning-for-your-personal-account-and-repositories/changing-your-code-scanning-configuration#changing-the-languages-that-are-analyzed
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
+
+    - name: Use Node.js 24.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: 24.x
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -47,13 +52,10 @@ jobs:
         # Prefix the list here with "+" to use these queries and those in the config file.
         # queries: ./path/to/local/query, your-org/your-repo/queries@main
 
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
+    # Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below).
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
-
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 https://git.io/JvXDl
+      uses: github/codeql-action/autobuild@v4
 
     # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
     #    and modify them (or add more) to build your code if your project
@@ -64,4 +66,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v4

package/AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS.md - guidance for AI coding agents working in this repo
+
+## What this repo is
+
+`ldap-authentication` - a small Node.js library that authenticates users against an
+LDAP/AD server. It is a thin wrapper around `ldapts` (its only runtime dependency).
+
+There is **no build step**. The package is published as-is:
+
+- `index.js` - CJS implementation (all runtime logic lives here)
+- `index.mjs` - ESM re-export entry point
+- `index.d.ts` - hand-written TypeScript types (keep in sync with `index.js` and the README)
+- `test/` - jasmine integration specs (require a running LDAP server)
+- `example/` - runnable usage examples (require a running LDAP server)
+- `docker/` + `docker-compose.yml` - the seeded OpenLDAP test server
+- `dist/` - **stale legacy build (gitignored, not referenced by package.json, not
+  published). Ignore it; do not edit or "fix" it.**
+
+## Running the tests
+
+The specs are integration tests against a seeded OpenLDAP container:
+
+1. `docker compose -f docker-compose.yml up -d` - LDAP on `ldap://localhost:1389`,
+   LDAPS on `ldaps://localhost:1636`
+2. Wait until an admin bind succeeds (server is ready when this works)
+3. `INGITHUB=true npm test` - the `INGITHUB` env var switches the specs from the
+   docker-internal URL (`ldap://ldap:1389`) to `ldap://localhost:1389`
+4. `docker compose -f docker-compose.yml down`
+
+Or all of the above in one shot: `npm run test:local` (`scripts/test-local.sh`).
+
+After changing the seed ldifs, rebuild the container first (`docker compose -f
+docker-compose.yml build`) - `up -d` reuses the existing image and the seed
+data is baked into it at build time.
+
+Seeded data (see `docker/ldap/*.ldif`): domain `dc=example,dc=com`; users
+`cn=gauss`, `cn=einstein` and `cn=Doe, John` (uid `doe`, used to test DNs with a
+comma in the CN) in `ou=users` (all with password `password`); group
+`cn=科学A部` in `ou=groups` containing gauss; admin
+`cn=read-only-admin,dc=example,dc=com` (password `password`).
+`test/binary.spec.js` MUTATES the directory (adds `jpegPhoto` to gauss), so spec
+order matters - keep the deterministic order: in jasmine 7 the env options
+(`random`, `seed`, `stopSpecOnExpectationFailure`) must be nested under the `env`
+key in `loadConfig` (see `test/jasmine.js`).
+
+## Code style
+
+Prettier (`.prettierrc`): no semicolons, single quotes, 2-space indent, trailing
+commas in `es5`. Match the existing style when editing `index.js`.
+
+## Version control - IMPORTANT: this is a Jujutsu (jj) repo
+
+This repo is managed with **jj** (see `.jj/`). Do NOT use `git commit` for commits;
+use jj:
+
+1. `jj describe -m "<message>"` - commits the current working-copy changes
+   (after `jj describe`, jj may warn that the commit became immutable and create an
+   empty working-copy commit on top - that is normal and harmless)
+2. `jj bookmark move master` - move the local `master` bookmark to the new commit
+   (defaults to the working copy, `@`)
+3. `jj git push --bookmark master` - push to `origin`
+   (`git@github.com:shaozi/ldap-authentication.git`). The remote prints a
+   "Bypassed rule violations ... Changes must be made through a pull request"
+   notice on master - that is expected (maintainer bypass) and not an error.
+
+The maintainer works detached (no branch); commits go on the `master` bookmark
+with a single descriptive message, e.g.
+`"Add fetchUsers() to search all users via paged admin-bound lookup (#3); bump to 4.1.0"`.
+
+## Releases
+
+1. Bump `version` in **both** `package.json` and `package-lock.json` (the lockfile
+   has it twice: top-level and under `packages."").version`). Follow semver
+   (new feature = e.g. 4.1.0, docs/deps-only = patch).
+2. Commit + push as above.
+3. `jj tag set vN.N.N -r @-` (tag the just-pushed master commit), then
+   `git push origin vN.N.N` (jj has no tag push in this version).
+4. `gh release create vN.N.N --title "vN.N.N" --notes "..."` - creating the
+   release triggers `.github/workflows/npm-publish.yml` (OIDC), which runs
+   `npm ci && npm publish`.
+5. Verify: `gh run list` (the `Publish Package` run should succeed) and
+   `npm view ldap-authentication@N.N.N`. Note that the npm registry's packument
+   can lag the publish by a couple of minutes - check the
+   `https://registry.npmjs.org/ldap-authentication` `time`/`versions` before
+   re-publishing.
+
+## CI
+
+`integration-test.yml` runs on push/PR to `master`: builds the LDAP container from
+`docker-compose.yml`, runs `npm ci` + `npm run test` with `INGITHUB=true` on a
+Node 22.x/24.x matrix. Release events trigger `npm-publish.yml` (OIDC publish).
+
+## When adding a new option
+
+Update all of: the validation in `index.js` (`authenticateResult` /
+`fetchUsers`), the JSDoc in `index.js`, `index.d.ts` (`AuthenticationOptions` and
+/ or `FetchUsersOptions`), and the README (Parameters list, the
+options-by-mode table, and an example if the option changes behavior). Add or
+extend the specs in `test/` (integration specs run against the seeded container).

package/README.md

@@ -212,6 +212,18 @@ auth()
 - For `ldaps://` URLs, omit `starttls` and the connection will use TLS from the start
 - TLS options like `rejectUnauthorized`, `minVersion`, and `servername` can be specified in `ldapOpts.tlsOptions`
 
+#### Runnable examples
+
+The [example/](example/) directory contains complete, runnable scripts: admin auth, self auth, group lookup,
+`fetchUsers`, `verifyUserExists`, and StartTLS. They run against the bundled seeded test server
+(start it via `docker compose up -d`, or point `LDAP_URL` at your own server):
+
+```sh
+docker compose up -d               # seeded OpenLDAP on localhost:1389 / 1636
+node example/fetch-users.mjs       # or any other script in example/
+docker compose down
+```
+
 ## Parameters
 
 - `ldapOpts`: This is passed to `ldapts` client directly
@@ -254,12 +266,28 @@ auth()
 - `groupMemberAttribute`: if specified with groupClass and groupsSearchBase, will be used as member name (if not specified this defaults to `member`) in search filter for authenticated user groups
 - `groupMemberUserAttribute`: if specified with groupClass and groupsSearchBase, will be used as the attribute on the user object (if not specified this defaults to `dn`) in search filter for authenticated user groups
 
+### Which options for which mode?
+
+| Mode (call) | Required | Commonly used in addition |
+|---|---|---|
+| Admin authenticate (`authenticate`) | `ldapOpts`, `adminDn`, `adminPassword`, `userPassword`, `userSearchBase`, `usernameAttribute` or `usernameFilter`, `username` | `attributes`, `groupsSearchBase`, `groupClass`, `starttls` |
+| Self authenticate (`authenticate`) | `ldapOpts`, `userDn`, `userPassword` | `userSearchBase`, `usernameAttribute`, `attributes`, `groupsSearchBase`, `starttls` |
+| Verify user exists (`authenticate` with `verifyUserExists: true`) | `ldapOpts`, `adminDn`, `adminPassword`, `userSearchBase`, `usernameAttribute` or `usernameFilter`, `username` | `attributes`, `groupsSearchBase`, `starttls` |
+| Fetch all users (`fetchUsers`) | `ldapOpts`, `adminDn`, `adminPassword`, `userSearchBase` | `userFilter`, `attributes`, `pageSize`, `starttls` |
+
 ## Returns
 
 The user object if `authenticate()` is success.
 
 In version 4, a new function is added: `authenticateResult()`. It has the same call signature as `authenticate()` but returns an object `AuthenticationResult` with more details.
 
+`authenticate()` and `fetchUsers()` throw a `LdapAuthenticationError` on failure:
+- `authenticate()`: when the failure corresponds to a known outcome, the
+  error's `code` property holds the matching AUTH_RESULT_* constant (the same
+  value `authenticateResult()` reports).
+- Missing required options throw a `LdapAuthenticationError` too, with all
+  missing fields listed in the message in a single error.
+
 `fetchUsers()` returns an array of user objects, one per matched LDAP entry (each with its `dn` and the returned attributes), or an empty array if no user matches the filter.
 
 
@@ -279,6 +307,30 @@ AuthenticationResult object has the following fields:
 - `message`: authentication message array, which contains server messages
 - `client`: ldapClient instance
 
+## Active Directory notes
+
+- A typical admin bind DN is a service or admin account, e.g. `cn=Administrator,cn=users,dc=example,dc=com`,
+  or a dedicated LDAP sync account.
+- Username attributes: `sAMAccountName` for logins like `jdoe`, `userPrincipalName` for `jdoe@example.com`.
+  To look a user up by either at once, use
+  `usernameFilter: '(|(sAMAccountName={{username}})(userPrincipalName={{username}}))'`.
+- Set `userSearchBase` to the OU containing the users (e.g. `ou=users,dc=example,dc=com`):
+  the search is faster and avoids `AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS`.
+- `fetchUsers()` uses LDAP paged results, so Active Directory's usual 1000-entry limit per search
+  is not an issue (adjust the page size with `pageSize` if needed).
+- Binary attributes such as `thumbnailPhoto` should be requested as `thumbnailPhoto;binary`;
+  they are returned as base64-encoded strings.
+
+## Troubleshooting
+
+| Symptom | Likely cause / fix |
+|---|---|
+| `ECONNREFUSED`, `ETIMEDOUT`, or other connect errors | `ldapOpts.url` is wrong or the server is unreachable. Check the URL, the network/firewall, and `connectTimeout`. |
+| `LdapAuthenticationError` with `admin bind failed` / `user bind failed` | Wrong `adminDn`/`adminPassword`, or `userDn`/`userPassword` in self mode. Verify the bind manually, e.g. `ldapsearch -b dc=example,dc=com -D <dn> -w <password> dn`. |
+| `identity not found` (`AUTH_RESULT_FAILURE_IDENTITY_NOT_FOUND`) | The user does not exist under `userSearchBase`, or `usernameAttribute`/`username`/`usernameFilter` does not match the attribute(s) stored on the server. |
+| `identity ambiguous` (`AUTH_RESULT_FAILURE_IDENTITY_AMBIGUOUS`) | The search matched multiple entries - narrow `userSearchBase` or make the filter more specific. |
+| `Invalid credentials` (`AUTH_RESULT_FAILURE_CREDENTIAL_INVALID`) | The user was found but the password is wrong. |
+| TLS certificate errors | For self-signed certificates use `tlsOptions: { rejectUnauthorized: false }`; add `servername` for SNI. Use `ldaps://` (without `starttls`) or `ldap://` with `starttls: true`. |
 
 ## Old Stuff
 

package/docker/ldap/10-ldap-test-data.ldif

@@ -30,6 +30,20 @@ gidNumber: 1000
 homeDirectory: /home/gauss
 userPassword: {SSHA}u/l8yXCyiWhP3iXpt0UWMyM9ch5sZGFwLXRlc3QtMjAyNg==
 
+# Note: the DN line needs the comma in the RDN value escaped (\,), the
+# attribute value line does not - LDIF values are raw strings, but `dn:` is
+# parsed as LDAP DN syntax (RFC 4514)
+dn: cn=Doe\, John,ou=users,dc=example,dc=com
+objectClass: inetOrgPerson
+objectClass: posixAccount
+cn: Doe, John
+sn: Doe
+uid: doe
+uidNumber: 1002
+gidNumber: 1002
+homeDirectory: /home/doe
+userPassword: {SSHA}u/l8yXCyiWhP3iXpt0UWMyM9ch5sZGFwLXRlc3QtMjAyNg==
+
 dn: cn=einstein,ou=users,dc=example,dc=com
 objectClass: inetOrgPerson
 objectClass: posixAccount

package/example/fetch-users.mjs

@@ -0,0 +1,36 @@
+// Fetch all users with the admin account - the search is paged, so more
+// than 1000 entries can be returned.
+// Requires the bundled seeded test server: `docker compose up -d`
+// (or set LDAP_URL to point at your own server).
+
+import { fetchUsers } from '../index.mjs'
+
+const ldapOpts = {
+  url: process.env.LDAP_URL || 'ldap://localhost:1389',
+}
+
+const baseOptions = {
+  ldapOpts,
+  adminDn: 'cn=read-only-admin,dc=example,dc=com',
+  adminPassword: 'password',
+  userSearchBase: 'dc=example,dc=com',
+}
+
+// 1. All users (default filter: entries with a uid or sAMAccountName), all attributes
+let users = await fetchUsers(baseOptions)
+console.log('all users ->', users.map((user) => user.uid ?? user.cn))
+
+// 2. Custom filter + attribute selection
+users = await fetchUsers({
+  ...baseOptions,
+  userFilter: '(uid=gauss)',
+  attributes: ['uid', 'sn'],
+})
+console.log('filtered  ->', users)
+
+// 3. Small page size (paged results are always on)
+users = await fetchUsers({
+  ...baseOptions,
+  pageSize: 1,
+})
+console.log('paged     ->', users.length, 'entries with pageSize 1')

package/example/index.js

@@ -1,58 +1,56 @@
+// Admin and self authentication, with group lookup.
+// Requires the bundled seeded test server: `docker compose up -d`
+// (or set LDAP_URL to point at your own server).
+
 const { authenticate } = require('../index')
 
+const url = process.env.LDAP_URL || 'ldap://localhost:1389'
+
 async function auth() {
-  // auth with admin
-  let options = {
-    ldapOpts: {
-      url: 'ldap://localhost:1389',
-      // tlsOptions: { rejectUnauthorized: false }
-    },
+  // 1. Admin mode: bind as admin, find the user, then bind as the user.
+  // Restrict `attributes` so the server does not return everything (including
+  // userPassword).
+  let user = await authenticate({
+    ldapOpts: { url },
     adminDn: 'cn=read-only-admin,dc=example,dc=com',
     adminPassword: 'password',
     userPassword: 'password',
     userSearchBase: 'dc=example,dc=com',
     usernameAttribute: 'uid',
     username: 'gauss',
-    // starttls: false
-  }
+    attributes: ['uid', 'sn', 'cn'],
+  })
+  console.log('admin mode     ->', JSON.stringify(user, null, 2))
 
-  let user = await authenticate(options)
-  console.log(`user = ${JSON.stringify(user, null, 2)}`)
-
-  // auth with regular user
-  options = {
-    ldapOpts: {
-      url: 'ldap://ldap.forumsys.com',
-      // tlsOptions: { rejectUnauthorized: false }
-    },
-    userDn: 'uid=einstein,dc=example,dc=com',
+  // 2. Self mode: the user binds with its own DN and gets its details
+  user = await authenticate({
+    ldapOpts: { url },
+    userDn: 'cn=einstein,ou=users,dc=example,dc=com',
     userPassword: 'password',
     userSearchBase: 'dc=example,dc=com',
     usernameAttribute: 'uid',
     username: 'einstein',
-    // starttls: false
-  }
-
-  user = await authenticate(options)
-  console.log(`user = ${JSON.stringify(user, null, 2)}`)
+    attributes: ['uid', 'sn'],
+  })
+  console.log('self mode      ->', { uid: user.uid, sn: user.sn })
 
-  // Getting user group info
-  options = {
-    ldapOpts: {
-      url: 'ldap://ldap.forumsys.com',
-    },
-    userDn: 'uid=gauss,dc=example,dc=com',
+  // 3. Admin mode with group lookup
+  user = await authenticate({
+    ldapOpts: { url },
+    adminDn: 'cn=read-only-admin,dc=example,dc=com',
+    adminPassword: 'password',
     userPassword: 'password',
     userSearchBase: 'dc=example,dc=com',
     usernameAttribute: 'uid',
     username: 'gauss',
     groupsSearchBase: 'dc=example,dc=com',
-    groupClass: 'groupOfUniqueNames',
-    groupMemberAttribute: 'uniqueMember',
-  }
-
-  user = await authenticate(options)
-  console.log(`user = ${JSON.stringify(user, null, 2)}`)
+    groupClass: 'groupOfNames',
+    groupMemberAttribute: 'member',
+  })
+  console.log('with groups    ->', user.groups.map((group) => group.cn))
 }
 
-auth().then()
+auth().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/example/starttls.mjs

@@ -0,0 +1,40 @@
+// Authenticate over STARTTLS (ldap:// URL upgraded to TLS).
+// Requires an LDAP server that supports TLS certificates.
+// (The bundled test container generates TLS config but does not enable it,
+// so this script prints a notice instead of failing in that case.)
+
+import { authenticate } from '../index.mjs'
+
+const isTlsNotSupported = (error) =>
+  error instanceof Error &&
+  /secure TLS connection was established/i.test(error.message)
+
+// The bundled container uses a self-signed certificate, so the test
+// disables certificate verification. Do NOT do this in production;
+// provide your CA in tlsOptions.ca instead.
+try {
+  const user = await authenticate({
+    ldapOpts: {
+      url: process.env.LDAP_URL || 'ldap://localhost:1389',
+      tlsOptions: {
+        rejectUnauthorized: false, // self-signed certificate (test only)
+      },
+    },
+    starttls: true, // upgrade the ldap:// connection to TLS
+    adminDn: 'cn=read-only-admin,dc=example,dc=com',
+    adminPassword: 'password',
+    userPassword: 'password',
+    userSearchBase: 'dc=example,dc=com',
+    usernameAttribute: 'uid',
+    username: 'gauss',
+  })
+  console.log('starttls auth ->', user.uid)
+} catch (error) {
+  if (isTlsNotSupported(error)) {
+    console.log('This LDAP server does not support TLS - STARTTLS could not be established.')
+    console.log('Run this example against a server with TLS enabled (or use an ldaps:// URL).')
+  } else {
+    console.error(error)
+    process.exit(1)
+  }
+}

package/example/verify-user-exists.js

@@ -0,0 +1,45 @@
+// Verify that a user exists (without checking the password).
+// Requires the bundled seeded test server: `docker compose up -d`
+// (or set LDAP_URL to point at your own server).
+
+const { authenticate, LdapAuthenticationError } = require('../index')
+
+const url = process.env.LDAP_URL || 'ldap://localhost:1389'
+
+async function verify() {
+  // Existing user
+  let user = await authenticate({
+    ldapOpts: { url },
+    adminDn: 'cn=read-only-admin,dc=example,dc=com',
+    adminPassword: 'password',
+    verifyUserExists: true,
+    userSearchBase: 'dc=example,dc=com',
+    usernameAttribute: 'uid',
+    username: 'gauss',
+  })
+  console.log('gauss exists ->', user.uid)
+
+  // Non-existing user throws LdapAuthenticationError
+  try {
+    await authenticate({
+      ldapOpts: { url },
+      adminDn: 'cn=read-only-admin,dc=example,dc=com',
+      adminPassword: 'password',
+      verifyUserExists: true,
+      userSearchBase: 'dc=example,dc=com',
+      usernameAttribute: 'uid',
+      username: 'does-not-exist',
+    })
+  } catch (error) {
+    if (error instanceof LdapAuthenticationError) {
+      console.log('does-not-exist ->', error.message)
+    } else {
+      throw error
+    }
+  }
+}
+
+verify().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/index.d.ts

@@ -37,6 +37,29 @@ declare module 'ldap-authentication' {
     readonly client: any
   }
 
+  /**
+   * A single group entry returned on `user.groups` when group lookup is
+   * enabled (`groupsSearchBase` + `groupClass`). `objectName` mirrors `dn`
+   * for backward compatibility with the old ldapjs-based API.
+   */
+  export interface LdapGroupEntry {
+    dn: string
+    objectName?: string
+    [attr: string]: any
+  }
+
+  /**
+   * A single user object returned by `authenticate()` / `fetchUsers()`.
+   * Always contains the entry's `dn`; other attribute values are
+   * `string`/`string[]` (or a base64 string for `;binary` attributes), and
+   * `groups` is present when group lookup is enabled.
+   */
+  export interface LdapUserEntry {
+    dn: string
+    groups?: LdapGroupEntry[]
+    [attr: string]: any
+  }
+
   export interface FetchUsersOptions {
     ldapOpts: ClientOptions
     adminDn: string
@@ -58,18 +81,41 @@ declare module 'ldap-authentication' {
     starttls?: boolean
   }
 
+  /**
+   * Authenticate a user against the LDAP server. Kept as `Promise<any>` for
+   * backward compatibility; the resolved value has the shape of
+   * {@link LdapUserEntry}. Throws {@link LdapAuthenticationError} on failure
+   * (the error's `code` then holds the corresponding AUTH_RESULT_* constant)
+   * or when required options are missing.
+   */
   export function authenticate(options: AuthenticationOptions): Promise<any>
+  /**
+   * Same options as {@link authenticate} but never throws on failure; returns an
+   * {@link AuthenticationResult}. Throws {@link LdapAuthenticationError} when
+   * required options are missing.
+   */
   export function authenticateResult(options: AuthenticationOptions): Promise<AuthenticationResult>
 
   /**
    * Bind with the admin account and search all users under `userSearchBase`.
    * The search always uses paged results, so results are not limited by the
    * common server-side limit of 1000 entries.
+   *
+   * Returns an empty array if no user matches the filter.
    */
-  export function fetchUsers(options: FetchUsersOptions): Promise<any[]>
+  export function fetchUsers(options: FetchUsersOptions): Promise<LdapUserEntry[]>
 
+  /**
+   * Thrown by authenticate()/authenticateResult()/fetchUsers() on failure.
+   * `message` describes the failure. When the failure corresponds to a known
+   * authentication outcome, `code` holds the matching AUTH_RESULT_* constant
+   * (the same value authenticateResult() reports in `AuthenticationResult.code`).
+   * Missing required options also throw this error, with all missing fields
+   * listed in `message`.
+   */
   export class LdapAuthenticationError extends Error {
-    constructor(message: any)
+    constructor(message: any, code?: number)
     name: string
+    code?: number
   }
 }