Release v1.0.20 — hkm module command, http package dependency, Pageflow stage consolidation, OSS/CI hardening

[hakeemRash]

Summary

Closes #

Type of change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that changes existing behavior)
• 📝 Documentation only
• 🧹 Refactor / chore (no functional change)
• 🚀 Release PR (master → main, includes a CHANGELOG version bump)

Target branch

• This PR targets master (development), or
• This is a master → main release PR and adds a ## [x.y.z] - YYYY-MM-DD section to CHANGELOG.md.

How has this been tested?

vendor/bin/phpunit

Checklist

• My code follows the Gated Demand Architecture rules (no Laravel/Symfony/Slim patterns).
• Every PHP file has declare(strict_types=1);.
• The five access rules are respected (Controller → Service → Repository/Gateway → Port/SDK; Domain imports nothing external).
• Routes are declared in module.json / proj.json, not in PHP.
• Every env var read is declared in the relevant config[].
• Vendor exceptions are translated at their layer (no \PDOException/SDK exceptions escape).
• I added or updated tests and they pass locally.
• I updated documentation where relevant.
• For shippable changes, I added a ## [Unreleased] entry to CHANGELOG.md.
• CI is green.

Screenshots / notes (optional)

Summary by CodeRabbit

• New Features

  • Added comprehensive environment configuration guidance covering application, database, caching, authentication, security, mail, storage, and frontend settings.
  • Added unified Pageflow handling for stale assets, validation responses, shared properties, and precognition requests.
  • Added consolidated security response headers and CORS handling.
  • Added configurable tenancy-exempt paths, including health-check endpoints.

• Documentation & Chores

  • Updated project metadata, supported PHP extensions, licensing, ownership rules, and required CI checks.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds a complete environment template, updates package and repository policies, consolidates Pageflow and security HTTP stages, and adds configurable tenancy path exemptions.

Changes

Project configuration

Layer / File(s)	Summary
Package metadata and runtime configuration .env.example, composer.json	Runtime, service, security, storage, tenancy, frontend, and SEO variables are documented; Composer metadata, PHP requirements, and extension requirements are expanded.
License and repository governance LICENSE, .github/CODEOWNERS	The license changes to MIT, and main-branch code-owner requirements are updated.
Required CI status checks tools/ci/protect-main.sh	PHPStan and composer audit are added to required branch protection checks.

Pageflow pipeline

Layer / File(s)	Summary
Unified Pageflow request stage plugins/Pageflow/Http/PageflowStage.php	Version checks, precognition attributes, shared props, validation responses, URL normalization, and error flattening are implemented in one stage.
Pageflow pipeline registration plugins/Pageflow/Provider.php	The former multi-stage registration is replaced with one PageflowStage hook and the shared error flash key is updated.
Pageflow binding references plugins/Pageflow/API/Contracts/PageflowSharerContract.php, plugins/Pageflow/Http/CompositePageflowSharer.php, plugins/Pageflow/Support/helpers.php	Documentation references are updated for the consolidated stage.

Security response pipeline

Layer / File(s)	Summary
Combined CORS and security headers plugins/SecurityFilters/Infrastructure/Http/Stages/SecurityHeadersStage.php	CORS preflights, cross-origin response headers, and configured security headers are handled together.
Global security stage registration plugins/SecurityFilters/Provider.php	Separate CORS and secure-header hooks are replaced with the combined stage.

Tenancy request exemptions

Layer / File(s)	Summary
Exempt tenant paths plugins/Tenancy/Infrastructure/Http/Stages/TenantContextStage.php	Configured exempt paths bypass tenant identification and database rebinding.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Request
  participant PageflowStage
  participant PageflowResponder
  participant SessionPort
  Request->>PageflowStage: Submit Pageflow request
  PageflowStage->>PageflowResponder: Share responder props
  PageflowStage->>SessionPort: Flash validation errors when available
  PageflowStage-->>Request: Return Pageflow response

Loading

sequenceDiagram
  participant Client
  participant SecurityHeadersStage
  participant HTTPPipeline
  Client->>SecurityHeadersStage: Send request with Origin
  SecurityHeadersStage->>HTTPPipeline: Continue non-preflight request
  HTTPPipeline-->>SecurityHeadersStage: Return response
  SecurityHeadersStage-->>Client: Add CORS and security headers

Loading

Suggested reviewers: alshatri

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is specific and clearly reflects the release, dependency, Pageflow, and CI/security changes in the PR.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch master

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 7

🧹 Nitpick comments (1)

plugins/Pageflow/Http/PageflowStage.php (1)

68-79: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Doc comment claims route-scoping that the code doesn't implement.

The class doc says shared props run "when the route has it in scope" (lines 31-32), but the guard only checks $container->has(PageflowResponder::class) and $container->has(PageflowSharerContract::class) — both bound unconditionally in Provider::register(). Since this stage is hooked globally at after.load (see Provider.php line 112), $sharer->share() (and every pageflow_share() callback, e.g. PageflowAuth::resolve()) runs on every request through the pipeline, not just Pageflow-tagged page loads. Either the comment is inaccurate or an actual scope check (e.g. $this->isPageflow($request)) is missing.

♻️ Option: gate by Pageflow request

-        $container = $request->container();
-        if ($container !== null
+        $container = $request->container();
+        if ($this->isPageflow($request)
+            && $container !== null
             && $container->has(PageflowResponder::class)
             && $container->has(PageflowSharerContract::class)
         ) {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@plugins/Pageflow/Http/PageflowStage.php` around lines 68 - 79, Update the
shared-props block in PageflowStage so it only executes for Pageflow requests by
applying the existing isPageflow($request) check alongside the container
bindings. Keep resolving PageflowResponder and PageflowSharerContract and
calling share() unchanged for matching requests, while skipping the entire
sharing flow for non-Pageflow requests.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.env.example:
- Line 60: Update AUTH_SESSION_TTL in the environment template and its auth.php
consumer to use consistent units; preserve the intended 14-day remember-me
duration by setting the value to 14 when consumed as ttl_days, or convert both
configuration and consumption to seconds.

In @.github/CODEOWNERS:
- Line 5: Update the CODEOWNERS generation logic in protect-main.sh so it no
longer overwrites the tracked owner list with only the login and optional
collaborator; either stop generating .github/CODEOWNERS or preserve and validate
all required owners, including `@hakeemRash`, `@Alshatri`, and `@craftdevscommunity`.

In `@plugins/Pageflow/Http/PageflowStage.php`:
- Around line 99-105: Normalize the flashed errors in the session handling of
PageflowStage so the value consumed by Provider.php’s errors shared prop has one
predictable shape whether X-Pageflow-Error-Bag is present or absent. Update the
ERROR_FLASH_KEY payload construction while preserving field-to-message mappings
and ensuring useForm receives the expected flat error map.
- Around line 60-66: Update the rollback assignment in PageflowStage’s
precognition handling to parse PAGEFLOW_PRECOGNITION_ROLLBACK using a
boolean-aware parser, so string values such as “false” evaluate to false while
preserving the existing default when unset.

In `@plugins/SecurityFilters/Infrastructure/Http/Stages/SecurityHeadersStage.php`:
- Around line 121-140: Update resolveAllowedOrigin() so a wildcard
CORS_ALLOWED_ORIGINS configuration never reflects the request origin when
allowsCredentials() is enabled. Fail closed by returning no allowed origin for
that combination, or otherwise ensure corsHeaders() omits credentialed access;
preserve the existing wildcard response for non-credentialed requests and
explicit allow-list matching.
- Around line 76-88: Update SecurityHeadersStage so CORS responses add Origin to
Vary whenever the request includes an Origin header, not only when allowOrigin
is non-null. Before withHeaders(), merge this value with the response’s existing
Vary entries, preserving upstream values such as Accept-Encoding and avoiding
duplicates.

In `@plugins/Tenancy/Infrastructure/Http/Stages/TenantContextStage.php`:
- Around line 76-79: Reject bare "*" entries while parsing the tenancy exemption
configuration so empty wildcard prefixes are never accepted; update the relevant
parser near the path-matching logic and add a regression test proving this
configuration fails closed without bypassing tenant identification or database
rebinding.

---

Nitpick comments:
In `@plugins/Pageflow/Http/PageflowStage.php`:
- Around line 68-79: Update the shared-props block in PageflowStage so it only
executes for Pageflow requests by applying the existing isPageflow($request)
check alongside the container bindings. Keep resolving PageflowResponder and
PageflowSharerContract and calling share() unchanged for matching requests,
while skipping the entire sharing flow for non-Pageflow requests.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a5f14c57-93ab-4d66-950e-4e7207c5a2c5

📥 Commits

Reviewing files that changed from the base of the PR and between a9a06a3 and 1da40e9.

⛔ Files ignored due to path filters (1)

• composer.lock is excluded by !**/*.lock

📒 Files selected for processing (19)

• .env.example
• .github/CODEOWNERS
• LICENSE
• composer.json
• plugins/Pageflow/API/Contracts/PageflowSharerContract.php
• plugins/Pageflow/Http/CompositePageflowSharer.php
• plugins/Pageflow/Http/PageflowPrecognitionStage.php
• plugins/Pageflow/Http/PageflowShareStage.php
• plugins/Pageflow/Http/PageflowStage.php
• plugins/Pageflow/Http/PageflowValidationStage.php
• plugins/Pageflow/Http/PageflowVersionStage.php
• plugins/Pageflow/Provider.php
• plugins/Pageflow/Support/helpers.php
• plugins/SecurityFilters/Infrastructure/Http/Stages/CorsStage.php
• plugins/SecurityFilters/Infrastructure/Http/Stages/SecureHeadersStage.php
• plugins/SecurityFilters/Infrastructure/Http/Stages/SecurityHeadersStage.php
• plugins/SecurityFilters/Provider.php
• plugins/Tenancy/Infrastructure/Http/Stages/TenantContextStage.php
• tools/ci/protect-main.sh

💤 Files with no reviewable changes (6)

• plugins/SecurityFilters/Infrastructure/Http/Stages/CorsStage.php
• plugins/Pageflow/Http/PageflowPrecognitionStage.php
• plugins/Pageflow/Http/PageflowShareStage.php
• plugins/SecurityFilters/Infrastructure/Http/Stages/SecureHeadersStage.php
• plugins/Pageflow/Http/PageflowVersionStage.php
• plugins/Pageflow/Http/PageflowValidationStage.php

[Alshatri]

good

[Alshatri]

done reviewing