[PATCH] GltfLoader.resolveUri callback JSDoc does not document the async/Promise requirement

[ormidales]

Category: documentation
Severity: patch
File(s): src/core/GltfLoader.ts (GltfLoaderOptions.resolveUri)

Description

The JSDoc for resolveUri describes what the callback receives and what it must return, and correctly warns against re-encoding URIs. However, it does not explicitly state that the callback must be asynchronous (i.e. return a Promise<ArrayBuffer>), nor does it document error handling expectations — specifically, whether the loader catches rejections or lets them propagate.

Problematic code example

/**
 * Do not perform additional URI resolution or decoding inside this
 * callback — doing so may re-introduce path-traversal or SSRF vulnerabilities…
 */
resolveUri?: (uri: string) => Promise<ArrayBuffer>;

Suggested fix

/**
 * Optional async callback invoked by the loader to fetch external buffer URIs
 * (non-`data:` references found in `buffers[].uri`).
 *
 * The callback **must** return a `Promise` that resolves to the raw bytes of
 * the referenced buffer. Rejections propagate directly from `loadGltf`.
 *
 * @param uri The raw URI string extracted from the glTF JSON, already validated
 *   against the loader's URI whitelist. Do **not** perform additional URI
 *   resolution or decoding — doing so may re-introduce path-traversal or SSRF
 *   vulnerabilities that the loader's validation was designed to prevent.
 * @returns A `Promise` resolving to the buffer's raw bytes as an `ArrayBuffer`.
 */
resolveUri?: (uri: string) => Promise<ArrayBuffer>;

Acceptance criteria

• The JSDoc explicitly states the callback must return a Promise
• Rejection propagation behavior is documented
• The @param uri and @returns tags are present