ldap-authentication 4.3.0 → 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

@@ -29,8 +29,13 @@ The specs are integration tests against a seeded OpenLDAP container:
 
 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` and `cn=einstein` in `ou=users` (both with password `password`); group
+`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
@@ -77,16 +82,13 @@ with a single descriptive message, e.g.
    `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. The legacy `publish.yml` workflow also triggers on release and
-   its `npm publish` step fails with E404 because it duplicates the other
-   workflow - that failure is expected/harmless; `publish.yml` is a candidate
-   for deletion.
+   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 additionally trigger the publish workflows.
+Node 22.x/24.x matrix. Release events trigger `npm-publish.yml` (OIDC publish).
 
 ## When adding a new option
 

package/README.md

@@ -281,6 +281,13 @@ 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.
 
 

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/index.d.ts

@@ -84,10 +84,16 @@ declare module 'ldap-authentication' {
   /**
    * 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.
+   * {@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}. */
+  /**
+   * 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>
 
   /**
@@ -99,8 +105,17 @@ declare module 'ldap-authentication' {
    */
   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
   }
 }