cloudstructs 0.12.8 → 0.12.10

package/node_modules/@slack/web-api/node_modules/@types/node/sqlite.d.ts

@@ -123,6 +123,14 @@ declare module "node:sqlite" {
          * @default false
          */
         allowUnknownNamedParameters?: boolean | undefined;
+        /**
+         * If `true`, enables the defensive flag. When the defensive flag is enabled,
+         * language features that allow ordinary SQL to deliberately corrupt the database file are disabled.
+         * The defensive flag can also be set using `enableDefensive()`.
+         * @since v25.1.0
+         * @default true
+         */
+        defensive?: boolean | undefined;
     }
     interface CreateSessionOptions {
         /**
@@ -225,6 +233,28 @@ declare module "node:sqlite" {
          */
         inverse?: ((accumulator: T, ...args: SQLOutputValue[]) => T) | undefined;
     }
+    interface PrepareOptions {
+        /**
+         * If `true`, integer fields are read as `BigInt`s.
+         * @since v25.5.0
+         */
+        readBigInts?: boolean | undefined;
+        /**
+         * If `true`, results are returned as arrays.
+         * @since v25.5.0
+         */
+        returnArrays?: boolean | undefined;
+        /**
+         * If `true`, allows binding named parameters without the prefix character.
+         * @since v25.5.0
+         */
+        allowBareNamedParameters?: boolean | undefined;
+        /**
+         * If `true`, unknown named parameters are ignored.
+         * @since v25.5.0
+         */
+        allowUnknownNamedParameters?: boolean | undefined;
+    }
     /**
      * This class represents a single [connection](https://www.sqlite.org/c3ref/sqlite3.html) to a SQLite database. All APIs
      * exposed by this class execute synchronously.
@@ -294,6 +324,14 @@ declare module "node:sqlite" {
          * @param allow Whether to allow loading extensions.
          */
         enableLoadExtension(allow: boolean): void;
+        /**
+         * Enables or disables the defensive flag. When the defensive flag is active,
+         * language features that allow ordinary SQL to deliberately corrupt the database file are disabled.
+         * See [`SQLITE_DBCONFIG_DEFENSIVE`](https://www.sqlite.org/c3ref/c_dbconfig_defensive.html#sqlitedbconfigdefensive) in the SQLite documentation for details.
+         * @since v25.1.0
+         * @param active Whether to set the defensive flag.
+         */
+        enableDefensive(active: boolean): void;
         /**
          * This method is a wrapper around [`sqlite3_db_filename()`](https://sqlite.org/c3ref/db_filename.html)
          * @since v24.0.0
@@ -409,19 +447,73 @@ declare module "node:sqlite" {
          * around [`sqlite3_prepare_v2()`](https://www.sqlite.org/c3ref/prepare.html).
          * @since v22.5.0
          * @param sql A SQL string to compile to a prepared statement.
+         * @param options Optional configuration for the prepared statement.
          * @return The prepared statement.
          */
-        prepare(sql: string): StatementSync;
+        prepare(sql: string, options?: PrepareOptions): StatementSync;
         /**
-         * Creates a new `SQLTagStore`, which is an LRU (Least Recently Used) cache for
-         * storing prepared statements. This allows for the efficient reuse of prepared
-         * statements by tagging them with a unique identifier.
+         * Creates a new {@link SQLTagStore}, which is a Least Recently Used (LRU) cache
+         * for storing prepared statements. This allows for the efficient reuse of
+         * prepared statements by tagging them with a unique identifier.
          *
          * When a tagged SQL literal is executed, the `SQLTagStore` checks if a prepared
-         * statement for that specific SQL string already exists in the cache. If it does,
-         * the cached statement is used. If not, a new prepared statement is created,
-         * executed, and then stored in the cache for future use. This mechanism helps to
-         * avoid the overhead of repeatedly parsing and preparing the same SQL statements.
+         * statement for the corresponding SQL query string already exists in the cache.
+         * If it does, the cached statement is used. If not, a new prepared statement is
+         * created, executed, and then stored in the cache for future use. This mechanism
+         * helps to avoid the overhead of repeatedly parsing and preparing the same SQL
+         * statements.
+         *
+         * Tagged statements bind the placeholder values from the template literal as
+         * parameters to the underlying prepared statement. For example:
+         *
+         * ```js
+         * sqlTagStore.get`SELECT ${value}`;
+         * ```
+         *
+         * is equivalent to:
+         *
+         * ```js
+         * db.prepare('SELECT ?').get(value);
+         * ```
+         *
+         * However, in the first example, the tag store will cache the underlying prepared
+         * statement for future use.
+         *
+         * > **Note:** The `${value}` syntax in tagged statements _binds_ a parameter to
+         * > the prepared statement. This differs from its behavior in _untagged_ template
+         * > literals, where it performs string interpolation.
+         * >
+         * > ```js
+         * > // This a safe example of binding a parameter to a tagged statement.
+         * > sqlTagStore.run`INSERT INTO t1 (id) VALUES (${id})`;
+         * >
+         * > // This is an *unsafe* example of an untagged template string.
+         * > // `id` is interpolated into the query text as a string.
+         * > // This can lead to SQL injection and data corruption.
+         * > db.run(`INSERT INTO t1 (id) VALUES (${id})`);
+         * > ```
+         *
+         * The tag store will match a statement from the cache if the query strings
+         * (including the positions of any bound placeholders) are identical.
+         *
+         * ```js
+         * // The following statements will match in the cache:
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = ${12345} AND active = 1`;
+         *
+         * // The following statements will not match, as the query strings
+         * // and bound placeholders differ:
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = 12345 AND active = 1`;
+         *
+         * // The following statements will not match, as matches are case-sensitive:
+         * sqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;
+         * sqlTagStore.get`select * from t1 where id = ${id} and active = 1`;
+         * ```
+         *
+         * The only way of binding parameters in tagged statements is with the `${value}`
+         * syntax. Do not add parameter binding placeholders (`?` etc.) to the SQL query
+         * string itself.
          *
          * ```js
          * import { DatabaseSync } from 'node:sqlite';
@@ -437,8 +529,8 @@ declare module "node:sqlite" {
          * sql.run`INSERT INTO users VALUES (2, 'Bob')`;
          *
          * // Using the 'get' method to retrieve a single row.
-         * const id = 1;
-         * const user = sql.get`SELECT * FROM users WHERE id = ${id}`;
+         * const name = 'Alice';
+         * const user = sql.get`SELECT * FROM users WHERE name = ${name}`;
          * console.log(user); // { id: 1, name: 'Alice' }
          *
          * // Using the 'all' method to retrieve all rows.
@@ -468,6 +560,8 @@ declare module "node:sqlite" {
          * [`sqlite3changeset_apply()`](https://www.sqlite.org/session/sqlite3changeset_apply.html).
          *
          * ```js
+         * import { DatabaseSync } from 'node:sqlite';
+         *
          * const sourceDb = new DatabaseSync(':memory:');
          * const targetDb = new DatabaseSync(':memory:');
          *
@@ -525,26 +619,39 @@ declare module "node:sqlite" {
          * [`sqlite3session_delete()`](https://www.sqlite.org/session/sqlite3session_delete.html).
          */
         close(): void;
+        /**
+         * Closes the session. If the session is already closed, does nothing.
+         * @since v24.9.0
+         */
+        [Symbol.dispose](): void;
     }
     /**
      * This class represents a single LRU (Least Recently Used) cache for storing
      * prepared statements.
      *
-     * Instances of this class are created via the database.createSQLTagStore() method,
-     * not by using a constructor. The store caches prepared statements based on the
-     * provided SQL query string. When the same query is seen again, the store
+     * Instances of this class are created via the `database.createTagStore()`
+     * method, not by using a constructor. The store caches prepared statements based
+     * on the provided SQL query string. When the same query is seen again, the store
      * retrieves the cached statement and safely applies the new values through
      * parameter binding, thereby preventing attacks like SQL injection.
      *
      * The cache has a maxSize that defaults to 1000 statements, but a custom size can
-     * be provided (e.g., database.createSQLTagStore(100)). All APIs exposed by this
+     * be provided (e.g., `database.createTagStore(100)`). All APIs exposed by this
      * class execute synchronously.
      * @since v24.9.0
      */
     interface SQLTagStore {
         /**
-         * Executes the given SQL query and returns all resulting rows as an array of objects.
+         * Executes the given SQL query and returns all resulting rows as an array of
+         * objects.
+         *
+         * This function is intended to be used as a template literal tag, not to be
+         * called directly.
          * @since v24.9.0
+         * @param stringElements Template literal elements containing the SQL
+         * query.
+         * @param boundParameters Parameter values to be bound to placeholders in the template string.
+         * @returns An array of objects representing the rows returned by the query.
          */
         all(
             stringElements: TemplateStringsArray,
@@ -552,7 +659,15 @@ declare module "node:sqlite" {
         ): Record<string, SQLOutputValue>[];
         /**
          * Executes the given SQL query and returns the first resulting row as an object.
+         *
+         * This function is intended to be used as a template literal tag, not to be
+         * called directly.
          * @since v24.9.0
+         * @param stringElements Template literal elements containing the SQL
+         * query.
+         * @param boundParameters Parameter values to be bound to placeholders in the template string.
+         * @returns An object representing the first row returned by
+         * the query, or `undefined` if no rows are returned.
          */
         get(
             stringElements: TemplateStringsArray,
@@ -560,7 +675,14 @@ declare module "node:sqlite" {
         ): Record<string, SQLOutputValue> | undefined;
         /**
          * Executes the given SQL query and returns an iterator over the resulting rows.
+         *
+         * This function is intended to be used as a template literal tag, not to be
+         * called directly.
          * @since v24.9.0
+         * @param stringElements Template literal elements containing the SQL
+         * query.
+         * @param boundParameters Parameter values to be bound to placeholders in the template string.
+         * @returns An iterator that yields objects representing the rows returned by the query.
          */
         iterate(
             stringElements: TemplateStringsArray,
@@ -568,15 +690,21 @@ declare module "node:sqlite" {
         ): NodeJS.Iterator<Record<string, SQLOutputValue>>;
         /**
          * Executes the given SQL query, which is expected to not return any rows (e.g., INSERT, UPDATE, DELETE).
+         *
+         * This function is intended to be used as a template literal tag, not to be
+         * called directly.
          * @since v24.9.0
+         * @param stringElements Template literal elements containing the SQL
+         * query.
+         * @param boundParameters Parameter values to be bound to placeholders in the template string.
+         * @returns An object containing information about the execution, including `changes` and `lastInsertRowid`.
          */
         run(stringElements: TemplateStringsArray, ...boundParameters: SQLInputValue[]): StatementResultingChanges;
         /**
          * A read-only property that returns the number of prepared statements currently in the cache.
          * @since v24.9.0
-         * @returns The maximum number of prepared statements the cache can hold.
          */
-        size(): number;
+        readonly size: number;
         /**
          * A read-only property that returns the maximum number of prepared statements the cache can hold.
          * @since v24.9.0

package/node_modules/@slack/web-api/node_modules/@types/node/stream.d.ts

@@ -81,6 +81,7 @@ declare module "node:stream" {
         interface ArrayOptions extends ReadableOperatorOptions {}
         interface ReadableToWebOptions {
             strategy?: web.QueuingStrategy | undefined;
+            type?: web.ReadableStreamType | undefined;
         }
         interface ReadableEventMap {
             "close": [];
@@ -485,13 +486,18 @@ declare module "node:stream" {
              *   }
              * }
              *
-             * const wordsStream = Readable.from(['this is', 'compose as operator']).compose(splitToWords);
+             * const wordsStream = Readable.from(['text passed through', 'composed stream']).compose(splitToWords);
              * const words = await wordsStream.toArray();
              *
-             * console.log(words); // prints ['this', 'is', 'compose', 'as', 'operator']
+             * console.log(words); // prints ['text', 'passed', 'through', 'composed', 'stream']
              * ```
              *
-             * See [`stream.compose`](https://nodejs.org/docs/latest-v25.x/api/stream.html#streamcomposestreams) for more information.
+             * `readable.compose(s)` is equivalent to `stream.compose(readable, s)`.
+             *
+             * This method also allows for an `AbortSignal` to be provided, which will destroy
+             * the composed stream when aborted.
+             *
+             * See [`stream.compose(...streams)`](https://nodejs.org/docs/latest-v25.x/api/stream.html#streamcomposestreams) for more information.
              * @since v19.1.0, v18.13.0
              * @returns a stream composed with the stream `stream`.
              */
@@ -1056,6 +1062,9 @@ declare module "node:stream" {
             writableHighWaterMark?: number | undefined;
             writableCorked?: number | undefined;
         }
+        interface DuplexToWebOptions {
+            type?: web.ReadableStreamType | undefined;
+        }
         interface DuplexEventMap extends ReadableEventMap, WritableEventMap {}
         /**
          * Duplex streams are streams that implement both the `Readable` and `Writable` interfaces.
@@ -1109,7 +1118,7 @@ declare module "node:stream" {
              * A utility method for creating a web `ReadableStream` and `WritableStream` from a `Duplex`.
              * @since v17.0.0
              */
-            static toWeb(streamDuplex: NodeJS.ReadWriteStream): web.ReadableWritablePair;
+            static toWeb(streamDuplex: NodeJS.ReadWriteStream, options?: DuplexToWebOptions): web.ReadableWritablePair;
             /**
              * A utility method for creating a `Duplex` from a web `ReadableStream` and `WritableStream`.
              * @since v17.0.0
@@ -1653,7 +1662,8 @@ declare module "node:stream" {
          * console.log(res); // prints 'HELLOWORLD'
          * ```
          *
-         * See [`readable.compose(stream)`](https://nodejs.org/docs/latest-v25.x/api/stream.html#readablecomposestream-options) for `stream.compose` as operator.
+         * For convenience, the `readable.compose(stream)` method is available on
+         * `Readable` and `Duplex` streams as a wrapper for this function.
          * @since v16.9.0
          * @experimental
          */

package/node_modules/@slack/web-api/node_modules/@types/node/test.d.ts

@@ -82,6 +82,7 @@ declare module "node:test" {
     import { AssertMethodNames } from "node:assert";
     import { Readable, ReadableEventMap } from "node:stream";
     import { TestEvent } from "node:test/reporters";
+    import { URL } from "node:url";
     import TestFn = test.TestFn;
     import TestOptions = test.TestOptions;
     /**
@@ -190,6 +191,11 @@ declare module "node:test" {
             function only(name?: string, fn?: SuiteFn): Promise<void>;
             function only(options?: TestOptions, fn?: SuiteFn): Promise<void>;
             function only(fn?: SuiteFn): Promise<void>;
+            // added in v25.5.0, undocumented
+            function expectFailure(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
+            function expectFailure(name?: string, fn?: SuiteFn): Promise<void>;
+            function expectFailure(options?: TestOptions, fn?: SuiteFn): Promise<void>;
+            function expectFailure(fn?: SuiteFn): Promise<void>;
         }
         /**
          * Shorthand for skipping a test. This is the same as calling {@link test} with `options.skip` set to `true`.
@@ -215,6 +221,11 @@ declare module "node:test" {
         function only(name?: string, fn?: TestFn): Promise<void>;
         function only(options?: TestOptions, fn?: TestFn): Promise<void>;
         function only(fn?: TestFn): Promise<void>;
+        // added in v25.5.0, undocumented
+        function expectFailure(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
+        function expectFailure(name?: string, fn?: TestFn): Promise<void>;
+        function expectFailure(options?: TestOptions, fn?: TestFn): Promise<void>;
+        function expectFailure(fn?: TestFn): Promise<void>;
         /**
          * The type of a function passed to {@link test}. The first argument to this function is a {@link TestContext} object.
          * If the test uses callbacks, the callback function is passed as the second argument.
@@ -236,7 +247,7 @@ declare module "node:test" {
         }
         interface RunOptions {
             /**
-             * If a number is provided, then that many test processes would run in parallel, where each process corresponds to one test file.
+             * If a number is provided, then that many tests would run asynchronously (they are still managed by the single-threaded event loop).
              * If `true`, it would run `os.availableParallelism() - 1` test files in parallel. If `false`, it would only run one test file at a time.
              * @default false
              */
@@ -479,7 +490,7 @@ declare module "node:test" {
         }
         namespace EventData {
             interface Error extends globalThis.Error {
-                cause: globalThis.Error;
+                cause: unknown;
             }
             interface LocationInfo {
                 /**
@@ -968,7 +979,6 @@ declare module "node:test" {
              * @since v22.2.0, v20.15.0
              */
             readonly assert: TestContextAssert;
-            readonly attempt: number;
             /**
              * This function is used to create a hook running before subtest of the current test.
              * @param fn The hook function. The first argument to this function is a `TestContext` object.
@@ -1031,6 +1041,21 @@ declare module "node:test" {
              * @since v18.8.0, v16.18.0
              */
             readonly name: string;
+            /**
+             * Indicated whether the test succeeded.
+             * @since v21.7.0, v20.12.0
+             */
+            readonly passed: boolean;
+            /**
+             * The failure reason for the test/case; wrapped and available via `context.error.cause`.
+             * @since v21.7.0, v20.12.0
+             */
+            readonly error: EventData.Error | null;
+            /**
+             * Number of times the test has been attempted.
+             * @since v21.7.0, v20.12.0
+             */
+            readonly attempt: number;
             /**
              * This function is used to set the number of assertions and subtests that are expected to run
              * within the test. If the number of assertions and subtests that run does not match the
@@ -1285,6 +1310,11 @@ declare module "node:test" {
              * @since v22.6.0
              */
             readonly filePath: string | undefined;
+            /**
+             * The name of the suite and each of its ancestors, separated by `>`.
+             * @since v22.3.0, v20.16.0
+             */
+            readonly fullName: string;
             /**
              * The name of the suite.
              * @since v18.8.0, v16.18.0
@@ -1344,6 +1374,8 @@ declare module "node:test" {
              * @since v22.2.0
              */
             plan?: number | undefined;
+            // added in v25.5.0, undocumented
+            expectFailure?: boolean | undefined;
         }
         /**
          * This function creates a hook that runs before executing a suite.
@@ -1352,7 +1384,7 @@ declare module "node:test" {
          * describe('tests', async () => {
          *   before(() => console.log('about to run some test'));
          *   it('is a subtest', () => {
-         *     assert.ok('some relevant assertion here');
+         *     // Some relevant assertion here
          *   });
          * });
          * ```
@@ -1368,7 +1400,7 @@ declare module "node:test" {
          * describe('tests', async () => {
          *   after(() => console.log('finished running tests'));
          *   it('is a subtest', () => {
-         *     assert.ok('some relevant assertion here');
+         *     // Some relevant assertion here
          *   });
          * });
          * ```
@@ -1384,7 +1416,7 @@ declare module "node:test" {
          * describe('tests', async () => {
          *   beforeEach(() => console.log('about to run a test'));
          *   it('is a subtest', () => {
-         *     assert.ok('some relevant assertion here');
+         *     // Some relevant assertion here
          *   });
          * });
          * ```
@@ -1401,7 +1433,7 @@ declare module "node:test" {
          * describe('tests', async () => {
          *   afterEach(() => console.log('finished running a test'));
          *   it('is a subtest', () => {
-         *     assert.ok('some relevant assertion here');
+         *     // Some relevant assertion here
          *   });
          * });
          * ```
@@ -1692,7 +1724,7 @@ declare module "node:test" {
              * @param specifier A string identifying the module to mock.
              * @param options Optional configuration options for the mock module.
              */
-            module(specifier: string, options?: MockModuleOptions): MockModuleContext;
+            module(specifier: string | URL, options?: MockModuleOptions): MockModuleContext;
             /**
              * Creates a mock for a property value on an object. This allows you to track and control access to a specific property,
              * including how many times it is read (getter) or written (setter), and to restore the original value after mocking.
@@ -2033,24 +2065,28 @@ declare module "node:test" {
              */
             enable(options?: MockTimersOptions): void;
             /**
-             * You can use the `.setTime()` method to manually move the mocked date to another time. This method only accepts a positive integer.
-             * Note: This method will execute any mocked timers that are in the past from the new time.
-             * In the below example we are setting a new time for the mocked date.
+             * Sets the current Unix timestamp that will be used as reference for any mocked
+             * `Date` objects.
+             *
              * ```js
              * import assert from 'node:assert';
              * import { test } from 'node:test';
-             * test('sets the time of a date object', (context) => {
-             *   // Optionally choose what to mock
-             *   context.mock.timers.enable({ apis: ['Date'], now: 100 });
-             *   assert.strictEqual(Date.now(), 100);
-             *   // Advance in time will also advance the date
-             *   context.mock.timers.setTime(1000);
-             *   context.mock.timers.tick(200);
-             *   assert.strictEqual(Date.now(), 1200);
+             *
+             * test('runAll functions following the given order', (context) => {
+             *   const now = Date.now();
+             *   const setTime = 1000;
+             *   // Date.now is not mocked
+             *   assert.deepStrictEqual(Date.now(), now);
+             *
+             *   context.mock.timers.enable({ apis: ['Date'] });
+             *   context.mock.timers.setTime(setTime);
+             *   // Date.now is now 1000
+             *   assert.strictEqual(Date.now(), setTime);
              * });
              * ```
+             * @since v21.2.0, v20.11.0
              */
-            setTime(time: number): void;
+            setTime(milliseconds: number): void;
             /**
              * This function restores the default behavior of all mocks that were previously
              * created by this `MockTimers` instance and disassociates the mocks

package/node_modules/@slack/web-api/node_modules/@types/node/tls.d.ts

@@ -15,31 +15,31 @@ declare module "node:tls" {
     import * as stream from "stream";
     const CLIENT_RENEG_LIMIT: number;
     const CLIENT_RENEG_WINDOW: number;
-    interface Certificate {
+    interface Certificate extends NodeJS.Dict<string | string[]> {
         /**
          * Country code.
          */
-        C: string;
+        C?: string | string[];
         /**
          * Street.
          */
-        ST: string;
+        ST?: string | string[];
         /**
          * Locality.
          */
-        L: string;
+        L?: string | string[];
         /**
          * Organization.
          */
-        O: string;
+        O?: string | string[];
         /**
          * Organizational unit.
          */
-        OU: string;
+        OU?: string | string[];
         /**
          * Common name.
          */
-        CN: string;
+        CN?: string | string[];
     }
     interface PeerCertificate {
         /**
@@ -210,6 +210,7 @@ declare module "node:tls" {
     interface TLSSocketEventMap extends net.SocketEventMap {
         "keylog": [line: NonSharedBuffer];
         "OCSPResponse": [response: NonSharedBuffer];
+        "secure": [];
         "secureConnect": [];
         "session": [session: NonSharedBuffer];
     }
@@ -551,8 +552,12 @@ declare module "node:tls" {
          */
         requestCert?: boolean | undefined;
         /**
-         * An array of strings or a Buffer naming possible ALPN protocols.
-         * (Protocols should be ordered by their priority.)
+         * An array of strings, or a single `Buffer`, `TypedArray`, or `DataView` containing the supported
+         * ALPN protocols. Buffers should have the format `[len][name][len][name]...`
+         * e.g. `'\x08http/1.1\x08http/1.0'`, where the `len` byte is the length of the
+         * next protocol name. Passing an array is usually much simpler, e.g.
+         * `['http/1.1', 'http/1.0']`. Protocols earlier in the list have higher
+         * preference than those later.
          */
         ALPNProtocols?: readonly string[] | NodeJS.ArrayBufferView | undefined;
         /**

package/node_modules/@slack/web-api/node_modules/@types/node/url.d.ts

@@ -334,6 +334,19 @@ declare module "node:url" {
      * new URL('file:///hello world').pathname;   // Incorrect: /hello%20world
      * fileURLToPath('file:///hello world');      // Correct:   /hello world (POSIX)
      * ```
+     *
+     * **Security Considerations:**
+     *
+     * This function decodes percent-encoded characters, including encoded dot-segments
+     * (`%2e` as `.` and `%2e%2e` as `..`), and then normalizes the resulting path.
+     * This means that encoded directory traversal sequences (such as `%2e%2e`) are
+     * decoded and processed as actual path traversal, even though encoded slashes
+     * (`%2F`, `%5C`) are correctly rejected.
+     *
+     * **Applications must not rely on `fileURLToPath()` alone to prevent directory
+     * traversal attacks.** Always perform explicit path validation and security checks
+     * on the returned path value to ensure it remains within expected boundaries
+     * before using it for file system operations.
      * @since v10.12.0
      * @param url The file URL string or URL object to convert to a path.
      * @return The fully-resolved platform-specific Node.js file path.
@@ -344,6 +357,15 @@ declare module "node:url" {
      * representation of the path, a `Buffer` is returned. This conversion is
      * helpful when the input URL contains percent-encoded segments that are
      * not valid UTF-8 / Unicode sequences.
+     *
+     * **Security Considerations:**
+     *
+     * This function has the same security considerations as `url.fileURLToPath()`.
+     * It decodes percent-encoded characters, including encoded dot-segments
+     * (`%2e` as `.` and `%2e%2e` as `..`), and normalizes the path. **Applications
+     * must not rely on this function alone to prevent directory traversal attacks.**
+     * Always perform explicit path validation on the returned buffer value before
+     * using it for file system operations.
      * @since v24.3.0
      * @param url The file URL string or URL object to convert to a path.
      * @returns The fully-resolved platform-specific Node.js file path