docs: restrict fork workflow capabilities

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

docs/content/reference/process-workflow-fleet-standard.md

@@ -136,7 +136,7 @@ decisions before canonical guides, templates, or consumer workflows adopt it:
 | Pull-request activities | Keep all six listed activity types. | Reduce the activity list if a v8 behavior is intentionally unsupported. |
 | Concurrency | Use the PR-number-or-ref key and cancel only superseded pull-request runs. | Use separate groups per event class or disable cancellation for all runs. |
 | Permissions | Set top-level permissions to empty and grant only `contents: read`, `pages: write`, and `id-token: write` to the caller job. | Define a narrower profile for repositories that do not publish Pages. |
-| Fork behavior | Invoke the reusable workflow unconditionally; Plan rejects unsupported fork events before credentialed or repository-defined code. | Add an independent secret-free fork-CI workflow. |
+| Fork behavior | Invoke the reusable workflow unconditionally; Plan classifies normal fork `pull_request` events into restricted read-only validation and rejects `pull_request_target` until separately designed. | Omit fork validation or design a separate `pull_request_target` trust boundary. |
 | Credentials | Explicitly map the three v8 credentials. | Define a narrower credential profile for repositories that cannot publish. |
 | Optional surface | Permit only documented `TestData`, workflow inputs, schedule timing, and presentation metadata. | Allow additional extension points after naming and compatibility rules are agreed. |
 
@@ -171,7 +171,7 @@ fleet campaign. Branch names, `latest`, floating minor tags, and unqualified tar
 | Schedule | Keep a scheduled health run. | Exercises current dependencies even when repository code is unchanged. |
 | Concurrency | Use the PR-number-or-ref key and cancel only pull-request runs. | Pull-request changes converge promptly while non-pull-request runs serialize by ref. |
 | Permissions | Use empty top-level permissions and the three caller-job permissions shown above. | Repository-local reads and Pages/OIDC stay narrow; App tokens provide broader authority. |
-| Fork authorization | Leave the caller job unconditional. | Plan rejects unsupported forks before credentials or repository-defined code run. |
+| Fork authorization | Leave the caller job unconditional. | Plan grants normal fork `pull_request` events only restricted read-only validation capabilities and rejects `pull_request_target` before credentials or repository-defined code run. |
 | Reference | Use the intended internal floating major tag (`v8`) after tag governance is enforced. | Compatible owned releases roll out centrally; breaking releases require a new major and campaign. |
 | Credentials | Explicitly map the three required secrets. | Satisfies the `v7+` contract and prevents unrelated secret inheritance. |
 | Scope | Keep the caller as a single delegation job. | Repository-specific automation remains independently understandable and maintainable. |
@@ -205,9 +205,18 @@ an approved structure:
 - unrelated additional jobs in the caller wrapper;
 - omitted documented permissions without a verified settings-based least-privilege profile.
 
-The candidate caller invokes the reusable workflow for fork-originated pull requests. Plan rejects unsupported fork events
-before credentials or repository-defined code run. Supporting fork CI requires a separate, secret-free, read-only workflow;
-issue [#514](https://github.com/PSModule/Process-PSModule/issues/514) must approve that boundary.
+The candidate caller invokes the reusable workflow for fork-originated `pull_request` events. Plan classifies them into a
+restricted, read-only validation mode that permits only repository-local checkout, build, lint, and test with the
+least-privilege built-in token. It emits explicit capabilities that prohibit App-token creation, publication, mutation,
+Pages deployment, cleanup, and user-facing reporting. `pull_request_target` remains unsupported and Plan must reject it
+before credentials or repository-defined code run; issue [#514](https://github.com/PSModule/Process-PSModule/issues/514)
+must approve any separate trust boundary for that event.
+
+The controlled upstream `v8` Plan implementation derives that restricted envelope first from immutable GitHub event
+metadata, including fork, base, and head identities. It may then use fork settings and checked-out files only as
+untrusted validation and build inputs; they cannot enable credentials, broaden permissions, or change the capability
+envelope. This permits ordinary fork contributors to receive the standard workflow green/red validation without
+configuring secrets.
 
 The candidate keeps repository-specific automation in a separate workflow file. That keeps the Process-PSModule wrapper
 identical enough for automated comparison while allowing modules to own unrelated schedules, generation, or integration

docs/content/reference/process-workflow-lifecycle-design.md

@@ -25,6 +25,7 @@ Plan resolves the caller event into one release classification before build and
 | --- | --- | --- | --- | --- |
 | `workflow_dispatch` on the default branch | Recovery or resume | Stable release or no-op | Never cancel | Rebuild and validate the selected commit; reconstruct the unreleased release notes. |
 | `schedule` | Published-artifact validation | No-op after validation | Never cancel | Validate the latest published stable artifact and its documentation. |
+| Fork `pull_request` | Restricted read-only validation | No-op after validation | Cancels a superseded pull-request run; the later run converges state | Perform only safe repository-local checkout, build, lint, and test with no privileged or user-facing operation. |
 | Pull request `opened`, `reopened`, `synchronize` | Pull-request classification | Prerelease or no-op | Cancels a superseded pull-request run; the later run converges state | Report configured validation and execute the planned release action. |
 | Pull request `labeled`, `unlabeled` | Pull-request classification refresh | Prerelease, cleanup-only, or no-op | Cancels a superseded pull-request run; the later run converges state | Resolve the complete current classification and execute its action. |
 | Merged pull request `closed` | Post-merge close | No-op | Cancels a superseded pull-request run; the later run converges state | Do not clean up; the successful main-push release owns promotion cleanup. |
@@ -35,11 +36,29 @@ Plan records its classification and release decision in enriched Settings. Downs
 
 ## Candidate event authorization
 
-The caller invokes the reusable workflow without a caller-level fork or event condition. Plan is the event-authorization boundary: it rejects unsupported fork pull requests before credentialed or repository-defined code runs. An authorization rejection produces no usable Settings and no credentialed follow-on work.
-
-Every downstream job depends on a successful authorized Plan and valid Settings. This requirement applies equally to jobs that use `always()`: their conditions first require the Plan result and Settings validity, then apply their own failure-handling logic. A downstream job never parses missing or invalid Settings and cannot bypass the Plan gate.
-
-Secret-free fork CI, if needed, is a separate workflow with its own trigger, authorization, and read-only contract. It is not a mode of the credentialed Process-PSModule reusable workflow.
+The caller invokes the reusable workflow without a caller-level fork or event condition. Plan is the event-authorization
+boundary. For a normal fork `pull_request`, the controlled upstream Process-PSModule `v8` Plan implementation first
+derives the security and capability envelope from immutable GitHub event metadata: the fork condition and the base and
+head identities. It may query trusted upstream or base version and state as needed. GitHub withholds fork secrets, so
+Plan then emits an authorized restricted read-only validation record rather than rejecting the event. That record sets
+`IsFork=true`, `AllowAppToken=false`, `AllowPublication=false`, and `AllowMutation=false`. It permits only
+repository-local checkout, build, lint, and test with the least-privilege built-in token, giving the contributor the
+standard green/red validation outcome without configured secrets.
+
+Repository settings and checked-out fork files are consumed only after that envelope is fixed, and only as untrusted
+validation or build inputs. They cannot enable an App token; publication, mutation, deployment, or cleanup; or broader
+permissions.
+
+No restricted fork path may create an App token; access PowerShell Gallery; comment on, label, or mutate a pull request;
+write a status or other check-facing report; create releases, tags, or assets; perform cleanup; deploy Pages; or perform
+another privileged or user-facing operation. `pull_request_target` remains unsupported because it could combine
+privileged context with untrusted code. Plan rejects that event before credentials or repository-defined code run. An
+authorization rejection produces no usable Settings and no credentialed follow-on work.
+
+Every downstream job depends on a successful authorized Plan and valid Settings. This requirement applies equally to jobs
+that use `always()`: their conditions first require the Plan result and Settings validity, then apply their own
+failure-handling logic. Privileged jobs additionally require their relevant explicit capability. A downstream job never
+parses missing or invalid Settings and cannot bypass the Plan gate.
 
 ## Candidate artifact and version boundary
 
@@ -50,6 +69,7 @@ Version resolution is the boundary between planning and release-capable work. Th
 | Event and run type | Identifies the GitHub event and its candidate lifecycle classification. |
 | Event action | Preserves the relevant pull-request activity or non-pull-request action. |
 | Pull-request identity, state, and merged status | Distinguishes active, merged, and abandoned pull-request outcomes. |
+| Authorization capabilities and evidence | Records `IsFork`, the immutable event metadata used to derive it, and the explicit App-token, publication, and mutation capabilities that each downstream job must enforce. |
 | Labels and repository settings result | Captures the input policy state used only by Plan. |
 | Version bump and base version | Explains the selected version transition. |
 | Manifest version, prerelease identifier, and full version or tag | Defines the only version and tag permitted in the built artifact and release. |
@@ -82,6 +102,11 @@ Built-in `GITHUB_TOKEN` authorization is permitted for checkout, repository-loca
 
 Each App-token step requests only the installation permissions required for its operation. A missing App token is an authorization failure for App-required work: that operation stops before its API request or mutation, without silently falling back to the built-in workflow token. Built-in-token reads and Pages deployment remain available only within the explicit caller job permissions.
 
+For a Plan-classified restricted fork run, the Settings capabilities override the caller job's otherwise available
+permissions: no App token is created, no Pages deployment runs, and no repository mutation or user-facing action runs.
+The fork path has only the least-privilege built-in-token access required for repository-local checkout, build, lint,
+and test.
+
 ## Candidate Pages authorization
 
 The standard `actions/deploy-pages` path uses the built-in token's `pages: write` and `id-token: write` permissions granted only to the caller's Process-PSModule job. It remains inside the candidate's repository-local, non-user-facing boundary and does not require an App token.
@@ -163,7 +188,8 @@ The lifecycle contract is exercised with event payload fixtures and publication
 | Scoped caller permissions | Empty caller top-level permissions, the three job grants, built-in-token checkout/read, and standard Pages/OIDC verification. |
 | App authorization failure | Missing-App-token fixtures that prove user-facing operations fail closed without built-in token fallback. |
 | Token boundary | Fixtures that prove App tokens are step-scoped and built-in-token operations remain within the caller job's boundary. |
-| Event authorization | Unsupported-fork fixtures that prove Plan rejects before credentialed or repository-defined code, including for downstream `always()` jobs. |
+| Event authorization | Normal-fork `pull_request` fixtures that prove the controlled upstream Plan derives restricted capabilities from immutable fork/base/head metadata before it consumes settings or checked-out code, then permits only checkout/build/lint/test with a green/red outcome and no configured secrets; `pull_request_target` fixtures prove Plan rejects before credentialed or repository-defined code, including for downstream `always()` jobs. |
+| Capability enforcement | Restricted-fork fixtures that prove App-token creation, Gallery access, comments, labels, statuses, releases, tags, assets, cleanup, Pages deployment, and other privileged paths cannot run. |
 
 ## Decisions requiring approval
 

docs/content/reference/process-workflow-lifecycle-specification.md

@@ -231,13 +231,46 @@ Scenario: Perform a user-facing repository operation
 
 ### FR12 — Plan MUST authorize events before downstream execution {#fr12}
 
-The caller MUST invoke the reusable workflow without a caller-level fork or event condition. Plan MUST reject unsupported fork pull-request execution before any credentialed or repository-defined code runs. Every downstream job, including a job with `always()`, MUST require a successful authorized Plan and valid Settings. No downstream job MAY evaluate missing or invalid Settings or bypass the Plan gate.
+The caller MUST invoke the reusable workflow without a caller-level fork or event condition. Plan MUST classify a normal
+fork `pull_request` event into an authorized restricted read-only validation mode before downstream execution. Its valid
+Settings MUST explicitly set `IsFork=true`, `AllowAppToken=false`, `AllowPublication=false`, and
+`AllowMutation=false`. That mode MAY perform only safe repository-local checkout, build, lint, and test with the
+least-privilege built-in token. It MUST NOT create an App token; access PowerShell Gallery; create pull-request
+comments, labels, or status mutations; create releases, tags, or assets; perform cleanup; deploy Pages; or run another
+privileged or user-facing operation.
+
+The controlled upstream reusable-workflow Plan implementation MUST derive the restricted capability envelope first from
+immutable GitHub event metadata, including fork, base, and head identities, before interpreting repository settings or
+executing checked-out repository code. It MAY query the trusted upstream or base version and state as needed. Fork
+settings and files MAY be consumed only as untrusted validation and build inputs; they MUST NOT enable App tokens,
+mutation, publication, deployment, cleanup, or broaden permissions. The restricted mode MUST provide the ordinary
+green/red validation outcome without requiring contributor-configured secrets.
+
+`pull_request_target` MUST remain unsupported until a separate trust boundary is designed and approved. Plan MUST reject
+that event before credentials or repository-defined code run. Every downstream job, including a job with `always()`,
+MUST require a successful authorized Plan and valid Settings, and every privileged downstream job MUST also require its
+relevant planned capability. No downstream job MAY evaluate missing or invalid Settings or bypass the Plan gate.
 
 #### Behavioral scenarios {#fr12-scenarios}
 
 ```gherkin
-Scenario: Reject an unsupported fork pull request
-  Given a pull request originates from an unsupported fork
+Scenario: Validate a normal fork pull request in restricted mode
+  Given a pull request originates from a fork through the pull_request event
+  When Plan evaluates the event
+  Then Plan emits valid Settings with IsFork true and App-token, publication, and mutation capabilities false
+  And downstream work may perform only repository-local checkout, build, lint, and test with the least-privilege built-in token
+  And no App token, Gallery access, user-facing operation, Pages deployment, publication, or cleanup runs
+  And the contributor receives the standard green or red validation outcome without configured secrets
+
+Scenario: Derive fork capabilities before interpreting untrusted repository inputs
+  Given a pull request originates from a fork through the pull_request event
+  And its repository settings attempt to enable publication
+  When the controlled upstream Plan evaluates immutable fork, base, and head metadata
+  Then it fixes the restricted capability envelope before reading the settings or checked-out files
+  And the settings cannot enable App tokens, mutation, publication, deployment, cleanup, or broader permissions
+
+Scenario: Reject an unsupported pull_request_target event
+  Given a pull_request_target event is received
   When Plan evaluates the event
   Then Plan rejects the event before credentialed or repository-defined code runs
   And no downstream job receives authorized Settings
@@ -247,6 +280,13 @@ Scenario: Gate an always-running downstream job
   When a downstream job with an always condition is evaluated
   Then the job does not run
   And it does not evaluate the missing or invalid Settings
+
+Scenario: Gate a privileged job for a restricted fork run
+  Given Plan emits valid restricted Settings for a fork pull request
+  And the planned capability for publication is false
+  When a publication job is evaluated
+  Then the job does not run
+  And it does not create an App token or parse an absent publication configuration
 ```
 
 ## Non-functional requirements