feat(lsphp): emergency build path compiling lsphp from php.net source

For when a PHP security release is out and the LiteSpeed apt repo lags
(2026-10-21: php2shell CVE-2026-109618/-109619 fixed in 8.2.35/8.3.36/
8.4.27/8.5.12, LiteSpeed still on 8.2.34/8.3.35/8.4.26/8.5.11).

Dockerfile.lsphp / Dockerfile.litespeed gain an `lsphp-src` stage that is
idle unless PHP_SRC_VERSION is set; normal builds are unchanged (measured:
module list, file manifest, ldd, ini and dpkg identical to the published
images).

When set (lsphp-src-build.sh):
- tarball sha256 (php.net releases JSON) + OpenPGP signature against the
  committed php.net keyring, signer pinned per branch
- configure flags replayed from the packaged lsphp's own Configure Command
- LiteSpeed's php-litespeed-8.3 SAPI (what the packages actually compile,
  measured) instead of php-src's sapi/litespeed; sha256-pinned and checked
  against the packaged binary's LSAPI_* names
- packaged compiled-in ini defaults reproduced (session.save_path on 8.2/
  8.3) and gated (`php -n` diff)
- ABI gate (lsphp-abi-gate.sh, pahole) before reusing LiteSpeed's packaged
  PECL .so files; regression-tested in Shell-Checks

lsphp-src-overlay.sh swaps only php-src-owned files (decided by dpkg) and
fails the build unless extensions, versions, effective ini and feature
lines match the packaged lsphp under both CLI and litespeed SAPIs.

CI: lsphp-source-emergency.yaml (workflow_dispatch only). build-push.yaml
refuses to overwrite a newer php.net image with an older packaged one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Dockerfile.lsphp

@@ -22,6 +22,29 @@
 ARG OLS_VERSION=1.8.4
 ARG PHPVER=83
 
+## ---- stage 0 (EMERGENCY ONLY): lsphp compiled from php.net source -----------
+## Idle unless PHP_SRC_VERSION is set: lsphp-src-build.sh then exits at once and
+## /lsphp-src-out stays empty, so every normal build is unchanged (the overlay
+## steps below are no-ops). Set PHP_SRC_VERSION + PHP_SRC_SHA256 + LSPHP_SOURCE=php.net
+## ONLY when a PHP security release is out and the LiteSpeed apt repo still lags
+## — CI: .gitea/workflows/lsphp-source-emergency.yaml; runbook:
+## docs/lsphp-source-emergency.md. The tarball is sha256- AND OpenPGP-verified
+## against keys/php-src/; configure flags are replayed from the packaged lsphp.
+FROM litespeedtech/openlitespeed:${OLS_VERSION}-lsphp${PHPVER} AS lsphp-src
+ARG PHPVER=83
+ARG CACHE_BUST=
+ARG EXPECT_LSPHP_PKG=
+ARG EXPECT_PHP_VERSION=
+ARG PHP_SRC_VERSION=
+ARG PHP_SRC_SHA256=
+RUN --mount=type=bind,source=scripts,target=/mnt/scripts \
+    --mount=type=bind,source=keys/php-src,target=/usr/local/share/php-src-keys \
+    set -e; \
+    if [ -n "$PHP_SRC_VERSION" ]; then \
+        install -m 0755 /mnt/scripts/lsphp-apt-upgrade.sh /usr/local/sbin/lsphp-apt-upgrade.sh; \
+    fi; \
+    PHPVER="${PHPVER}" bash /mnt/scripts/lsphp-src-build.sh
+
 ## ---- stage 1: build the cac_path_parity extension --------------------------
 ## $_SERVER['DOCUMENT_ROOT']/['SCRIPT_FILENAME'] parity with cac-fpm, enforced
 ## from RINIT so a customer's .user.ini cannot displace it — see
@@ -101,6 +124,17 @@ RUN set -e; \
 ##  - a run that executes ZERO tests also exits 0, so assert the summary shows
 ##    every .phpt in the directory both ran and passed. Same reasoning as the
 ##    `lsphp -i` probe below: an assertion that cannot fail is worse than none.
+## EMERGENCY PATH: swap the packaged lsphp + its -dev files for the php.net build
+## (no-op when stage 0 was idle), so cac_path_parity below compiles against, and
+## its .phpt suite runs on, the PHP this image will actually ship.
+ARG PHP_SRC_VERSION=
+ARG LSPHP_SOURCE=litespeed-apt
+RUN --mount=type=bind,from=lsphp-src,source=/lsphp-src-out,target=/lsphp-src-out,rw \
+    --mount=type=bind,source=scripts,target=/mnt/scripts \
+    install -m 0644 /mnt/scripts/lsphp-src-probe.php /usr/local/share/lsphp-src-probe.php && \
+    bash /mnt/scripts/lsphp-src-overlay.sh dev "${PHPVER}" && \
+    rm -f /usr/local/share/lsphp-src-probe.php
+
 COPY ./ext/cac-path-parity /usr/src/cac-path-parity
 RUN set -e; \
     cd /usr/src/cac-path-parity; \
@@ -189,6 +223,18 @@ RUN set -e; \
     fi; \
     echo "runtime lsphp${PHPVER} pinned to $V (the version cac_path_parity was built against)"
 
+## EMERGENCY PATH: overlay the php.net lsphp (no-op on normal builds) and prove
+## it has the same extension/feature surface as the packaged one just installed
+## — see scripts/lsphp-src-overlay.sh. Bind mounts, so neither the staged build
+## nor the scripts add a layer to the image.
+ARG PHP_SRC_VERSION=
+ARG LSPHP_SOURCE=litespeed-apt
+RUN --mount=type=bind,from=lsphp-src,source=/lsphp-src-out,target=/lsphp-src-out,rw \
+    --mount=type=bind,source=scripts,target=/mnt/scripts \
+    install -m 0644 /mnt/scripts/lsphp-src-probe.php /usr/local/share/lsphp-src-probe.php && \
+    bash /mnt/scripts/lsphp-src-overlay.sh runtime "${PHPVER}" && \
+    rm -f /usr/local/share/lsphp-src-probe.php
+
 ## Scripts + the SHARED production lsphp ini (reused verbatim from the litespeed
 ## image — same runtime, same tuning). Scripts layer last (they change most).
 COPY ./scripts/entrypoint-lsphp.sh \
@@ -250,8 +296,14 @@ ENV LSPHP_ENABLE_USER_INI=on
 ##   docker buildx imagetools inspect <ref> --format '{{json .Image.Config.Labels}}'
 ## Values come from CI's repo-index lookup and were asserted against the
 ## installed packages by lsphp-apt-upgrade.sh above ("unverified" = local build).
-LABEL org.whp.php-version="${EXPECT_PHP_VERSION:-unverified}" \
+## Emergency (php.net) builds: org.whp.php-version is the php.net version the
+## overlay step asserted; org.whp.lsphp-package-version still names the LiteSpeed
+## packages underneath (their ini/PECL files are what the image keeps);
+## org.whp.lsphp-source says which one is running. /etc/cac-lsphp-source has the
+## tarball sha256 + signer.
+LABEL org.whp.php-version="${PHP_SRC_VERSION:-${EXPECT_PHP_VERSION:-unverified}}" \
       org.whp.lsphp-package-version="${EXPECT_LSPHP_PKG:-unverified}" \
+      org.whp.lsphp-source="${LSPHP_SOURCE}" \
       org.whp.php-flavour="lsphp${PHPVER}"
 
 EXPOSE 9000