security: harden one-shot site URL recovery

[soulteary]

Summary

This follow-up hardens the emergency /tool-update-site-url.php endpoint and completes its operator/developer documentation.

Security

• raise WORDPRESS_SITE_URL_UPDATE_PASSWORD minimum length from 16 to 24 characters
• globally count failures across PHP workers; the fifth invalid credential in a 15-minute window starts a 15-minute lockout and returns 429 with Retry-After
• reserve a correct credential for one operation for five minutes, preventing concurrent reuse
• consume the one-shot authorization immediately before the SQLite write
• set WORDPRESS_SITE_URL_UPDATE_TOOL_ENABLED=false and remove credentials in the current PHP worker after consumption
• persist the used state in wp-content/database/.ht.site-url-update-tool-state, so other workers and container restarts still return 404
• clear the used state only during a deliberate container start where the enable switch is not exactly true
• reject symbolic-link, oversized, malformed, or insecurely permissioned state files and coordinate state changes with flock
• ignore local .env and secrets/ credentials

The persistent latch is necessary because an application process cannot rewrite Docker Compose's configured environment. A failed database write also leaves the authorization consumed, requiring an explicit disabled-start rearm.

Documentation

• add complete TOKEN_FILE and PASSWORD Compose examples
• add safe disabled PASSWORD defaults and commented TOKEN_FILE alternatives to docker-compose.yml
• document the exact environment-variable names, credential minimums, mutual exclusion, global throttle, one-shot shutdown, and deliberate rearm sequence
• centralize accepted URL rules and add an HTTP troubleshooting table
• correct the Volume / Upgrade heading hierarchy
• update stale token-only wording in SECURITY and the Dockerfile
• cover the recovery tests and release checklist in CONTRIBUTING and RELEASING
• clarify that the feature landed after immutable release 7.1.0 and must be built from main until the next release

Tests

• extend unit coverage for password length, rolling failure window, 429 lockout, correct-credential behavior during lockout, concurrency reservation, cancellation, one-shot consumption, PHP environment shutdown, cross-worker persistence, state permissions/corruption, and symlink rejection
• verify entrypoint state clearing on a disabled start and persistence on an enabled restart
• add a built-image smoke test that exercises five invalid requests, a real atomic two-option SQLite update, and a simulated fresh PHP worker returning 404 after use
• make changes to the image-smoke fixture trigger the image build

Local validation

• all shell and PHP repository tests
• PHP lint for every PHP file
• ShellCheck 0.11.0
• actionlint 1.7.12
• ./scripts/validate-release.sh 7.1.0
• git diff --check

Follow-up to the unresolved brute-force review on #17.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-29T18:58:04.173979Z	e7e2dea	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 76a553e059

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[soulteary]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: e7e2dea44a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".