fix(security): verify project module commands

CHANGELOG.md

@@ -10,6 +10,17 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.55.5] - 2026-09-07
+
+### Security
+
+- **Project module command trust:** require cryptographic integrity and signature
+  verification before repository-local modules register executable commands,
+  unless unsigned loading is explicitly enabled for local development, and bind
+  official category bundles to their canonical `nold-ai` module identities.
+
+---
+
 ## [0.55.4] - 2026-09-02
 
 ### Security

docs/reference/module-security.md

@@ -18,11 +18,13 @@ Module packages carry **publisher** and **integrity** metadata so installation,
 - **Signature verification**: If `integrity.signature` is present and a public key is configured, signature validation proves provenance over the same full payload.
 - **Publisher trust gate**: Non-official publishers require one-time explicit trust (interactive confirmation or `--trust-non-official` / `SPECFACT_TRUST_NON_OFFICIAL`).
 - **Denylist gate**: Modules listed in denylist are blocked before install/bootstrap regardless of source.
+- **Project execution gate**: Repository-local modules discovered under `.specfact/modules` must have valid integrity metadata and a signature verified by trusted key material before their commands are registered. `SPECFACT_ALLOW_UNSIGNED=1` is an explicit local-development override; do not enable it for untrusted repositories or pull-request CI.
+- **Official bundle identity**: A manifest cannot become an official category command by copying a `bundle` value. Recognized bundles are mounted only for the matching canonical `nold-ai/<bundle>` module identity.
 
 ## Integrity flow
 
 1. Discovery reads `module-package.yaml` and parses `integrity.checksum`.
-2. At install/bootstrap/verification time, the tool hashes the full module payload and compares it to `integrity.checksum`.
+2. At install/bootstrap/verification time, the tool hashes the full module payload and compares it to `integrity.checksum`. Project-scoped command registration additionally requires a valid signature unless unsigned loading was explicitly enabled.
 3. On mismatch, the module is skipped and a security warning is logged.
 4. Other modules continue to register; one failing trust does not block the rest.
 

openspec/changes/fix-project-module-command-trust/TDD_EVIDENCE.md

@@ -0,0 +1,32 @@
+# TDD Evidence
+
+## Failing before
+
+- **Timestamp**: 2026-09-07T01:11Z
+- **Command**: `hatch run pytest tests/unit/specfact_cli/registry/test_module_packages.py -q -k 'spoofed_official_bundle_identity or unsigned_project_module_requires_integrity_and_signature or explicit_unsigned_override_preserves_project_module_development'`
+- **Result**: expected red; 2 failed and 1 passed. The spoofed manifest was accepted as `specfact-requirements`, and project registration called artifact verification without requiring integrity or a signature.
+
+## Passing after
+
+- **Timestamp**: 2026-09-07T01:12Z
+- **Command**: `hatch run pytest tests/unit/specfact_cli/registry/test_module_packages.py -q -k 'spoofed_official_bundle_identity or unsigned_project_module_requires_integrity_and_signature or explicit_unsigned_override_preserves_project_module_development or requirements_bundle_mounts_native'`
+- **Result**: 4 passed.
+- **Timestamp**: 2026-09-07T01:13Z
+- **Command**: `hatch run pytest tests/unit/specfact_cli/registry/test_module_packages.py tests/unit/cli/test_lean_help_output.py -q`
+- **Result**: 67 passed and 1 pre-existing migration skip.
+- **Timestamp**: 2026-09-07T01:14Z
+- **Commands**: `hatch run format`, `hatch run type-check`, `hatch run lint`, `openspec validate fix-project-module-command-trust --strict`, and `hatch run check-version-sources`.
+- **Result**: passed; BasedPyright reported 0 errors with repository-existing warnings.
+- **Timestamp**: 2026-09-07T01:16Z
+- **Commands**: `hatch run semgrep-sast --json --output /tmp/specfact-semgrep.json`, `hatch run semgrep-sast-gate --results /tmp/specfact-semgrep.json --baseline tools/semgrep/sast-baseline.json`, `hatch run bandit-scan`, and `hatch run verify-modules-signature-pr --version-check-base HEAD~1`.
+- **Result**: passed with no blocking Semgrep or Bandit findings and all four module manifests verified.
+- **Timestamp**: 2026-09-07T01:17Z
+- **Commands**: `uv lock`, `hatch run python scripts/check_reproducible_delivery.py`, and `uv lock --check`.
+- **Result**: passed after synchronizing the project version in `uv.lock`.
+
+## Baseline and environment limitations
+
+- `hatch run smart-test` completed 3,044 tests with 4 failures and 34 skips. Two failures were corrected by synchronizing the new patch version and lockfile; two unrelated command-audit/import failures require absent external `specfact-backlog` and `specfact-spec` modules.
+- `hatch run yaml-lint` reports pre-existing long-line/blank-line findings in archived `requirements-08-bounded-red-green-proof` evidence and active `requirements-07-runtime-proof-delivery` evidence; it exits zero and reports no finding in this change.
+- `hatch run specfact code review run --json --out .specfact/code-review.json --scope changed` produced the required local report, but its verdict is `UNKNOWN` because the released review module could not acquire its verified OCI analyzer cache. Independent local Ruff, BasedPyright, Semgrep, Bandit, and contract gates were run separately.
+- The sibling `specfact-cli-internal` checkout was unavailable at `/workspace/specfact-cli-internal`; mirror `fix-project-module-command-trust` into `wiki/sources/` and run `python3 scripts/wiki_rebuild_graph.py` from that repository root as a follow-up.

openspec/changes/fix-project-module-command-trust/design.md

@@ -0,0 +1,21 @@
+# Design: Project module command trust boundary
+
+## Context
+
+Project discovery intentionally finds `.specfact/modules`, but discovery must not itself grant permission to execute repository Python. Registration is the narrow trust boundary immediately before lazy loaders become reachable from root CLI commands.
+
+## Decisions
+
+1. Project-sourced packages require both integrity metadata and an official-key-verifiable signature. The existing explicit unsigned override remains the opt-in escape hatch for local development.
+2. A recognized bundle string is insufficient evidence of official bundle ownership. Category mounting also requires the canonical module name `nold-ai/<bundle>`.
+3. Verification remains local and uses the existing artifact verifier and bundled key resolution.
+
+## Alternatives
+
+- A new interactive trust prompt was rejected because non-interactive CI cannot safely prompt and publisher trust alone does not authenticate repository contents.
+- Removing project module discovery was rejected because it would break the supported local module-development workflow.
+- Special-casing only `requirements` was rejected because the same bundle-impersonation primitive applies to every official category mapping.
+
+## Risk and fallback
+
+Unsigned project modules will no longer load by default. Their owners can explicitly opt into the existing unsigned development mode, or sign the artifact. No network-dependent fallback is introduced.

openspec/changes/fix-project-module-command-trust/proposal.md

@@ -0,0 +1,38 @@
+# Change: Verify project modules before command registration
+
+## Why
+
+Workspace-local module manifests are repository-controlled input. An unsigned project module can currently claim an official bundle name and become the root `requirements` command, causing Python import-time code to execute when a developer or CI runner asks for command help.
+
+## What Changes
+
+- Require project-scoped modules to carry valid integrity metadata and a signature before their commands can be registered, unless the operator explicitly enables the existing unsigned-module override.
+- Bind recognized official bundle names to their expected `nold-ai/<bundle>` module identity before mounting category groups.
+- Add regression coverage proving an unsigned project module cannot register or execute and cannot impersonate the requirements bundle.
+
+## Capabilities
+
+### Modified Capabilities
+
+- `module-security`: Project-discovered executable modules fail closed unless cryptographically verified or explicitly allowed as unsigned.
+- `category-command-groups`: Official category bundle mounting requires the expected official module identity.
+
+## Impact
+
+- **Code**: Module registration and category-group eligibility in `src/specfact_cli/registry/module_packages.py`.
+- **Tests**: Focused registry tests for unsigned project modules and official bundle identity binding.
+- **Compatibility**: Existing signed project modules continue to work. Deliberately unsigned project modules require the existing explicit unsigned override.
+- **Offline-first**: Verification uses the bundled public key and local artifact contents; no network request is added.
+- **Documentation**: Review `docs/reference/module-categories.md`, module security documentation, README, site index, and navigation; document the fail-closed project-module rule where module trust is explained.
+- **Rollback**: Revert this change to restore the earlier permissive behavior; doing so reopens repository-triggered code execution and is not recommended.
+
+## Source Tracking
+
+- **Security report**: Aardvark, “Requirements mount trusts unverified project bundle metadata”
+- **Affected commit**: `b75f524750172eda7f1b38a3ca5bcd44f1a3dc09`
+- **Repository**: `nold-ai/specfact-cli`
+- **Last Synced Status**: confirmed against branch HEAD
+
+## Verification Exception
+
+The mandatory SpecFact self-review report was generated and contains no code findings, but its assurance status is `UNKNOWN` because the released review module could not acquire its verified OCI analyzer cache in this environment. This narrowly documented environment exception does not waive analysis: repository Ruff, BasedPyright, Semgrep, Bandit, contract, and focused regression gates run independently, and the report details are preserved in `TDD_EVIDENCE.md`.

openspec/changes/fix-project-module-command-trust/specs/category-command-groups/spec.md

@@ -0,0 +1,20 @@
+## ADDED Requirements
+
+### Requirement: Official bundle category groups are identity-bound
+
+The CLI SHALL mount a recognized official bundle category only when an enabled discovered package declares both the recognized bundle and its expected canonical `nold-ai/<bundle>` module identity.
+
+#### Scenario: Project manifest impersonates requirements bundle
+
+- **GIVEN** a discovered package is named `attacker/evil-requirements`
+- **AND** its manifest declares bundle `specfact-requirements` and command `requirements`
+- **WHEN** installed category groups are mounted
+- **THEN** the package is not treated as the official requirements bundle
+- **AND** no attacker loader is mounted as the root `requirements` command
+
+#### Scenario: Canonical requirements module is eligible
+
+- **GIVEN** an enabled verified package is named `nold-ai/specfact-requirements`
+- **AND** it declares bundle `specfact-requirements`
+- **WHEN** installed category groups are mounted
+- **THEN** the requirements category remains eligible for root mounting

openspec/changes/fix-project-module-command-trust/specs/module-security/spec.md

@@ -0,0 +1,26 @@
+## ADDED Requirements
+
+### Requirement: Project module code requires verified provenance
+
+The CLI SHALL NOT register executable commands from a project-scoped module unless the artifact has valid integrity metadata and a signature verifiable with configured trusted key material, or the operator explicitly enables unsigned modules.
+
+#### Scenario: Unsigned project module is discovered by default
+
+- **GIVEN** a repository contains a project-scoped module with executable Python and no integrity metadata
+- **AND** unsigned modules have not been explicitly allowed
+- **WHEN** module package commands are registered
+- **THEN** the module command is skipped
+- **AND** resolving CLI help does not execute the project module Python
+
+#### Scenario: Operator explicitly allows unsigned project development
+
+- **GIVEN** a project-scoped module has no signature
+- **AND** the operator explicitly enables the unsigned-module override
+- **WHEN** module package commands are registered
+- **THEN** existing unsigned development behavior is preserved
+
+#### Scenario: Signed project module fails trusted-key verification
+
+- **GIVEN** a project-scoped module carries integrity metadata signed by an untrusted key
+- **WHEN** module package commands are registered without the unsigned override
+- **THEN** the module command is skipped

openspec/changes/fix-project-module-command-trust/tasks.md

@@ -0,0 +1,15 @@
+# Tasks
+
+- [x] 1.1 Create the dedicated bugfix worktree and branch.
+- [x] 2.1 Add module-security and category-command-group spec deltas for project-module verification and official identity binding.
+- [x] 3.1 Add unit and CLI-level regression tests derived from every security scenario.
+- [x] 3.2 Run focused tests before production edits and record failing evidence.
+- [x] 4.1 Require integrity and signature verification for project module registration while preserving the explicit unsigned override.
+- [x] 4.2 Bind official bundle category eligibility to canonical module identity.
+- [x] 4.3 Record passing focused-test evidence.
+- [x] 5.1 Run formatting, type checking, linting, YAML linting, contract tests, smart tests, independent static analysis, and applicable signature verification.
+- [x] 5.2 Refresh `.specfact/code-review.json`, resolve every finding, and record review evidence (the report has no findings but records unavailable OCI analyzer evidence as an environment limitation).
+- [x] 6.1 Review `docs/`, README, docs index, and navigation; update module security guidance without adding a page unless necessary.
+- [x] 6.2 If the sibling internal checkout is unavailable, record the follow-up to mirror this change and rebuild its wiki graph.
+- [x] 7.1 Apply the required synchronized patch-version and changelog security entry.
+- [ ] 8.1 Commit the completed change and create the pull request.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.55.4"
+version = "0.55.5"
 description = "AI-bloat defense CLI for Python teams. Run deterministic code review, cleanup forecasts, and spec/contract evidence for AI-assisted and brownfield delivery."
 readme = "README.md"
 requires-python = ">=3.11"

setup.py

@@ -7,7 +7,7 @@
 if __name__ == "__main__":
     _setup = setup(
         name="specfact-cli",
-        version="0.55.4",
+        version="0.55.5",
         description=(
             "AI-bloat defense CLI for Python teams. Run deterministic code review, cleanup forecasts, "
             "and spec/contract evidence for AI-assisted and brownfield delivery."

src/__init__.py

@@ -3,4 +3,4 @@
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.55.4"
+__version__ = "0.55.5"

src/specfact_cli/__init__.py

@@ -76,6 +76,6 @@ def _install_progressive_disclosure() -> None:
 # keeps missing-command and missing-parameter UX consistent outside the root CLI too.
 _install_progressive_disclosure()
 
-__version__ = "0.55.4"
+__version__ = "0.55.5"
 
 __all__ = ["__version__"]

src/specfact_cli/registry/module_packages.py

@@ -1207,7 +1207,8 @@ def get_installed_bundles(
     def _resolved_bundle(meta: Any) -> str | None:
         bundle_name = getattr(meta, "bundle", None)
         if isinstance(bundle_name, str) and bundle_name:
-            return bundle_name
+            expected_module_name = f"nold-ai/{bundle_name}"
+            return bundle_name if getattr(meta, "name", None) == expected_module_name else None
         module_name = getattr(meta, "name", None)
         if not isinstance(module_name, str) or "/" not in module_name:
             return None
@@ -1358,7 +1359,18 @@ def _register_service_bridges_safe(meta: Any, bridge_owner_map: dict[str, str],
 
 
 def _module_integrity_allows_load(package_dir: Path, meta: Any, ctx: _ModuleIntegrityContext) -> bool:
-    if verify_module_artifact(package_dir, meta, allow_unsigned=ctx.allow_unsigned):
+    verify_project_signature = getattr(meta, "source", None) == "project" and not ctx.allow_unsigned
+    if verify_project_signature:
+        verified = verify_module_artifact(
+            package_dir,
+            meta,
+            allow_unsigned=False,
+            require_integrity=True,
+            require_signature=True,
+        )
+    else:
+        verified = verify_module_artifact(package_dir, meta, allow_unsigned=ctx.allow_unsigned)
+    if verified:
         return True
     if _is_builtin_module_package(package_dir):
         ctx.logger.warning(

tests/unit/security/test_release_promotion_security_gates.py

@@ -564,7 +564,7 @@ def run_rg(arguments: list[str], **_kwargs: object) -> subprocess.CompletedProce
 
 def test_patch_release_uses_next_version_in_all_sources() -> None:
     """The security baseline consumes only the next semver patch."""
-    expected = "0.55.4"
+    expected = "0.55.5"
     project = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
     assert project["project"]["version"] == expected
     for path in ("setup.py", "src/__init__.py", "src/specfact_cli/__init__.py"):