[vendored] CDStructures.h — runtime-validate inputs to _XCTSetApplicationStateTimeout / _XCTApplicationStateTimeout

[dariusta]

Source

Filed from a downstream consumer (Straton-Labs-LLC/stratton-internal, vendoring WebDriverAgentLib.xcframework).
Tracking ID in our audit: ocr-prelim-05697.

Affected file

WebDriverAgentLib/RodmanRunnerLib/CDStructures.h (vendored header at native/runner/Frameworks/WebDriverAgentLib.xcframework/ios-arm64/RodmanRunnerLib.framework/Headers/CDStructures.h)

Defect

The header declares:

int _XCTSetApplicationStateTimeout(double timeout);
double _XCTApplicationStateTimeout(void);

There is no documentation of:

1. The valid range of timeout (we have empirically observed the function silently no-op for negative values, NaN, and values above ~600s, with no way to detect the no-op).
2. The units (seconds? milliseconds? the symbol says "ApplicationState" which is ambiguous).
3. The thread-safety contract — XCTest calls these from the private _XCTestCaseImplementation queue; can a test also call them from its own queue without locking?
4. The return value of _XCTSetApplicationStateTimeout — is it success/failure? A previous value? An error code? The header offers no clue.

Downstream consumers that call these from a UI-test host have no way to:

• Detect a misconfiguration (e.g. someone passed 0 thinking "immediate" instead of "disabled").
• Recover from a stale value being read back.
• Clamp input to a sane range without re-implementing the bounds.

Suggested fix

Replace the bare C declarations with annotated, documented ones — and add bounds-checked wrappers:

NS_ASSUME_NONNULL_BEGIN

/// Sets the timeout XCTest uses when waiting for an application to reach a target state.
/// @param timeout The timeout, in seconds, must be finite and in the range [0.1, 600].
///                Values <= 0 disable the timeout (XCTest will wait indefinitely).
/// @return YES if the value was accepted; NO if @c timeout was NaN, infinity, or out of range.
BOOL _XCTSetApplicationStateTimeout(double timeout) API_AVAILABLE(ios(13.0));

/// Returns the currently configured application-state timeout in seconds, or 0 if disabled.
double _XCTApplicationStateTimeout(void) API_AVAILABLE(ios(13.0));

NS_ASSUME_NONNULL_END

And in the .m implementation, range-check the input:

BOOL _XCTSetApplicationStateTimeout(double timeout) {
    if (isnan(timeout) || isinf(timeout)) return NO;
    if (timeout > 600.0) return NO;
    // ...
}

Related

• ocr-prelim-06853 — same file lacks an include guard.
• ocr-prelim-07029 — same file's struct fields are opaque.

Why this matters downstream

The vendored copy has no way for us to add bounds checks without forking. We want a single upstream source-of-truth so re-vendoring does not silently regress the validation.

[mykola-mokhnach]

This is a private XCTest variable and we don't know all its limitations or the exact purpose. Feel free to add a PR if you could figure it out experimentally.