doc: deprecate process.umask() with no arguments

This commit introduces a documentation deprecation for calling
process.umask() with no arguments.

PR-URL: #32499
Fixes: #32321
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: cjihrig

doc/api/deprecations.md

@@ -2635,6 +2635,22 @@ modules is unsupported.
 It is deprecated in favor of [`require.main`][], because it serves the same
 purpose and is only available on CommonJS environment.
 
+<a id="DEP0XXX"></a>
+### DEP0XXX: `process.umask()` with no arguments
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/32499
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+Calling `process.umask()` with no arguments causes the process-wide umask to be
+written twice. This introduces a race condition between threads, and is a
+potential security vulnerability. There is no safe, cross-platform alternative
+API.
+
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
 [`--throw-deprecation`]: cli.html#cli_throw_deprecation
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size

doc/api/process.md

@@ -2426,8 +2426,16 @@ flag's behavior.
 ## `process.umask([mask])`
 <!-- YAML
 added: v0.1.19
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/32499
+    description: Calling `process.umask()` with no arguments is deprecated.
+
 -->
 
+> Stability: 0 - Deprecated. Calling `process.umask()` with no arguments is
+> deprecated. No alternative is provided.
+
 * `mask` {string|integer}
 
 The `process.umask()` method sets or returns the Node.js process's file mode