[Security] Native libraries loaded by soname are subject to search-path hijacking

[s2x]

Context / Problem

The native libraries are loaded by bare soname:

src/NativeClient.php:179-181 — FFI::cdef(..., 'libfdb_c.so'), 'libpthread.so.0', 'libdl.so.2'
src/NativeClient.php:220 — dlopen('libfdb_c.so', RTLD_LAZY)

Loading depends on the linker search path (LD_LIBRARY_PATH/RUNPATH/cwd in some configurations). A malicious libfdb_c.so earlier on the path would execute arbitrary code inside the PHP process. This is primarily a deployment risk, but the library can reduce the attack surface.

Affected files / locations

• src/NativeClient.php:177-182,220

Proposed approach

Allow configuring an absolute path to the FoundationDB client library (constructor argument / environment variable) and load from that pinned path when provided; document the recommendation to pin the path in production.

Acceptance Criteria

• Documentation updated/added (security note + configuration)
• Unit test(s) added covering path resolution/selection logic
• Functional test(s) added: loading from an explicit absolute path works
• Changelog entry added
• Post-implementation comment posted on this issue describing what was changed

Severity

Low

[s2x]

Implemented in PR #108 (branch feat/49-pin-fdb-library-path).

What changed

• NativeClient now resolves the FoundationDB client library through a new NativeClient::resolveLibraryPath() method with the precedence: explicit constructor argument > FDB_LIBRARY_PATH environment variable > bare soname (libfdb_c.so). The resolved value is used consistently for both FFI::cdef() in the constructor and dlopen() in ensureNetwork().
• Configured paths must be absolute — relative paths throw InvalidArgumentException, since they would still traverse attacker-influenced directories and defeat the purpose of pinning.
• Empty/unset configuration keeps the previous bare-soname behavior, so existing deployments are unaffected.

Documentation

• README.md: new "Pinning the client library path (recommended in production)" section with a security note and usage example.
• docs/getting-started.md: security note pointing at FDB_LIBRARY_PATH.

Tests

• tests/Unit/NativeClientLibraryPathTest.php covers: default soname fallback, env-var override, explicit-argument precedence, empty-value fallbacks, rejection of relative paths (both env and argument), and a functional test that the pinned absolute path loads via FFI::cdef() with the real header (auto-skipped when libfdb_c is not installed).
• tests/Unit/NativeClientPartialInitTest.php updated for the new private property.

Changelog

• Security entry [Security] Native libraries loaded by soname are subject to search-path hijacking #49 added to CHANGELOG.md.

composer lint and composer test:unit pass.