feat: Add async support for password policy validator callback

[dalyaidan1]

Pull Request

• Report security issues confidentially.
• Any contribution is under this license.

Issue

closes #10471
closes #10472

Approach

Note

I decided to bundle the typing fix and async support feature into one, as I felt they sufficiently overlapped. If this is incorrect I can make separate PRs. I have separated them here by conventional commits.

This adds type support so that the validator callback can:

1. take in a string argument (of the password)
2. return a boolean (error throw is still handled by the existing validationError policy config)
3. optionally become an async function

The only place I could find the validator callback being called was RestWrite, and so I updated it there.

Tasks

• Add tests
• Add changes to documentation (guides, repository pages, code comments)

Summary by CodeRabbit

Release Notes

• New Features

  • Password policy validatorCallback now supports asynchronous validation returning Promise<boolean> and receives the password as a parameter.

• Tests

  • Extended test coverage for async validator callbacks, including success and failure scenarios.

• Documentation

  • Updated documentation to reflect async callback support and behavior when combined with pattern validation.

[parse-github-assistant]

I will reformat the title to use the proper commit message syntax.

[parse-github-assistant]

🚀 Thanks for opening this pull request! We appreciate your effort in improving the project. Please let us know once your pull request is ready for review.

Tip

• Keep pull requests small. Large PRs will be rejected. Break complex features into smaller, incremental PRs.
• Use Test Driven Development. Write failing tests before implementing functionality. Ensure tests pass.
• Group code into logical blocks. Add a short comment before each block to explain its purpose.
• We offer conceptual guidance. Coding is up to you. PRs must be merge-ready for human review.
• Our review focuses on concept, not quality. PRs with code issues will be rejected. Use an AI agent.
• Human review time is precious. Avoid review ping-pong. Inspect and test your AI-generated code.

Note

Please respond to review comments from AI agents just like you would to comments from a human reviewer. Let the reviewer resolve their own comments, unless they have reviewed and accepted your commit, or agreed with your explanation for why the feedback was incorrect.

Caution

Pull requests must be written using an AI agent with human supervision. Pull requests written entirely by a human will likely be rejected, because of lower code quality, higher review effort and the higher risk of introducing bugs. Please note that AI review comments on this pull request alone do not satisfy this requirement. Our CI and AI review are safeguards, not development tools. If many issues are flagged, rethink your development approach. Invest more effort in planning and design rather than using review cycles to fix low-quality code.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 046895d2-840e-4759-8bc4-02884dc53824

📥 Commits

Reviewing files that changed from the base of the PR and between 828d0e0 and bd6230e.

📒 Files selected for processing (6)

• spec/PasswordPolicy.spec.js
• src/Options/Definitions.js
• src/Options/docs.js
• src/Options/index.js
• src/RestWrite.js
• types/Options/index.d.ts

---

📝 Walkthrough

Walkthrough

The PR enables asynchronous password validation by updating passwordPolicy.validatorCallback to accept a password parameter and return boolean | Promise<boolean>, fixing the type signature inconsistency and adding async support throughout the validation pipeline.

Changes

Password Policy Async Validator

Layer / File(s)	Summary
Type and Contract Definitions types/Options/index.d.ts, src/Options/index.js	TypeScript and Flow definitions for validatorCallback updated from () => void to accept a password string and return boolean | Promise<boolean>.
Async Validation Implementation src/RestWrite.js	_validatePasswordPolicy converted to async method; _validatePasswordRequirements refactored to extract patternValidator for immediate check and await validatorCallback via Promise.resolve() before rejecting invalid passwords.
Documentation Updates src/Options/Definitions.js, src/Options/docs.js	Help text and JSDoc expanded to document Promise<boolean> return type and clarify that password must satisfy both validatorCallback and validatorPattern when combined.
Async Validator Test Coverage spec/PasswordPolicy.spec.js	Added three test cases: async callback returning false rejects signup; async callback returning true permits signup and login; async callback returning false with validatorPattern match also rejects signup.

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Security Check	⚠️ Warning	Missing timeout protection on async validatorCallback could enable DoS via indefinitely hanging async operations blocking password validation.	Implement Promise.race with timeout for validatorCallback to prevent hung requests from blocking indefinitely and exhausting server resources.
Engage In Review Feedback	❓ Inconclusive	No review comments visible in repository state; cannot verify engagement with feedback without access to live GitHub PR page.	Check the actual GitHub PR #10477 to review whether review comments exist and if properly addressed.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title begins with 'feat:' prefix and clearly describes the main feature being added: async support for password policy validator callback.
Description check	✅ Passed	The pull request description follows the template structure with Issue, Approach, and completed Tasks sections. It references the related issues and explains the changes made.
Linked Issues check	✅ Passed	The PR fulfills all coding requirements from linked issues: updates typing to (password: string) => boolean | Promise, implements async support in RestWrite with await Promise.resolve(), adds comprehensive tests for async validators, and updates documentation.
Out of Scope Changes check	✅ Passed	All changes are directly related to the linked issues: type signature updates, RestWrite async implementation, test coverage, and documentation updates for password policy validator callback support.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 OpenGrep (1.21.0)

OpenGrep fatal error (exit code 2): [00.27][ERROR]: Error: exception Unix_error: No such file or directory stat src/RestWrite.js
Raised by primitive operation at UTmp.replace_named_pipe_by_regular_file_if_needed in file "libs/commons/UTmp.ml", line 145, characters 8-27
Called from Scan_CLI.replace_target_roots_by_regular_files_where_needed.(fun) in file "src/osemgrep/cli_scan/Scan_CLI.ml", lines 1086-1087, characters 19-65
Called from List_.fast_map in file "libs/commons/List_.ml", line 81, characters 17-20
Called from Scan_CLI.re

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}