How the Supply-Chain Pin Gate in verify-routing-coherence Prevents Unpinned Auto-Installs

The supply-chain pin gate in verify-routing-coherence.ps1 blocks unpinned auto-installs by parsing bootstrap manifests and enforcing deterministic version constraints, aborting the CI pipeline with exit code 1 when any capability lacks a pinned reference.

The zhaoxuya520/reverse-skill repository implements a rigorous supply-chain security model through its verify-routing-coherence.ps1 script. This PowerShell validation gate inspects every auto-install capability to ensure deterministic provenance, preventing the execution environment from fetching uncontrolled external packages at runtime.

How the Supply-Chain Pin Gate Works

The pin gate operates as a three-stage validation pipeline defined in skills/scripts/verify-routing-coherence.ps1. Each stage incrementally builds a compliance report, and any failure accumulates in a $fail counter that forces a non-zero exit status.

Loading Bootstrap Manifests

The script first locates and parses two critical JSON manifests: the generic skills manifest and the Kali-specific manifest. These files define the bootstrap dependencies and capabilities requiring validation.

$skillsManifest = Join-Path $scriptDir 'bootstrap-manifest.json'
$kaliManifest   = Join-Path $packageRoot 'kali/scripts/bootstrap-manifest.json'

These paths resolve to skills/scripts/bootstrap-manifest.json and kali/scripts/bootstrap-manifest.json respectively (see lines 84‑86 of the script). By loading both manifests, the gate ensures no environment-specific dependency evades scrutiny.

Validating Bootstrap Dependencies

Next, the gate inspects every entry under the bootstrapDependencies property. Each dependency must declare both a package name and a version enforced with an exact match operator (== or @). The script constructs a regex pattern that requires the version suffix to appear at the end of the package string.

$expectedSuffix = '(?:==|@)' + [regex]::Escape([string]$dependency.version) + '$'
if ([string]::IsNullOrWhiteSpace([string]$dependency.package) -or
    [string]::IsNullOrWhiteSpace([string]$dependency.version) -or
    [string]$dependency.package -notmatch $expectedSuffix) {
    Bad "unpinned bootstrap dependency: $($dependencyProperty.Name) in $mn"
} else {
    Ok "pinned bootstrap dependency $($dependencyProperty.Name) in $mn"
}

This check (lines 18‑23) rejects any dependency that uses loose versioning or omits the version constraint entirely, ensuring that pip install requests never executes as pip install requests>=2.0.

Enforcing Pins on Auto-Install Capabilities

The final stage targets capabilities flagged with canAutoInstall: true. Each such capability must provide at least one deterministic reference: pinnedVersion, pinnedCommit, or pinPolicy. The gate applies additional bootstrap-kind-specific logic for specialized installation methods.

$hasPin = ($capMap['pinnedVersion'] -or $capMap['pinnedCommit'] -or $capMap['pinPolicy'])
switch ($capMap['bootstrapKind']) {
    'github-release-zip'        { $hasPin = $hasPin -or $capMap['assetSha256'] -or $capMap['preferApiDigest'] }
    'local-http-mcp'           { $hasPin = (-not $fetchesExternalSource) -or $capMap['pinnedCommit'] -or $capMap['pinnedVersion'] }
    'remote-http-mcp'          { $hasPin = (-not $capMap['repoUrl']) -and (-not $capMap['repo']) -and $capMap['pinPolicy'] }
    'apt-package'              { $hasPin = $true }   # distro repos are considered pinned

    'docker-image'             { $hasPin = $true }
    default                    { $hasPin = $hasPin }
}
if (-not $hasPin) {
    Bad "unpinned auto‑install capability: $($capMap['name']) in $mn ($($capMap['bootstrapKind']))"
} else {
    Ok "pinned $($capMap['name']) in $mn"
}

This block (lines 31‑50) permits alternative pinning mechanisms—such as assetSha256 for GitHub release ZIPs—while exempting distro-managed packages like apt-package and docker-image under the assumption that repository mirrors provide deterministic layers. If $hasPin remains false, the script logs a failure and ultimately terminates with exit 1, halting any downstream routing or execution.

Practical Examples of Pin Validation

The following configurations illustrate compliant and non-compliant dependency declarations.

Correctly Pinned Bootstrap Dependency

{
  "bootstrapDependencies": {
    "pip-requests": {
      "package": "requests==2.31.0",
      "version": "2.31.0"
    }
  }
}

Because the package field ends with ==2.31.0, the regex validation succeeds and the gate outputs:

[OK] pinned bootstrap dependency pip-requests in bootstrap-manifest.json

Rejected Unpinned Capability

{
  "capabilities": [
    {
      "name": "some-tool",
      "canAutoInstall": true,
      "bootstrapKind": "github-release-zip"
    }
  ]
}

Missing pinnedVersion, assetSha256, or preferApiDigest, this entry triggers:

[FAIL] unpinned auto-install capability: some-tool in bootstrap-manifest.json (github-release-zip)

The script exits with a non-zero status, blocking the CI run.

Acceptable Pin for GitHub Releases

{
  "capabilities": [
    {
      "name": "tool‑v1",
      "canAutoInstall": true,
      "bootstrapKind": "github-release-zip",
      "assetSha256": "a3f5e2…"
    }
  ]
}

The presence of assetSha256 satisfies the $hasPin condition for the github-release-zip kind, allowing the gate to approve the capability.

Summary

• The supply-chain pin gate in verify-routing-coherence.ps1 enforces deterministic provenance by inspecting bootstrap-manifest.json files across the repository.
• Dependency validation requires exact version pinning using == or @ operators, rejecting ambiguous version ranges.
• Auto-install capability checks mandate at least one pin field (pinnedVersion, pinnedCommit, pinPolicy, or bootstrap-kind-specific alternatives) for every component flagged with canAutoInstall.
• Execution halt occurs via exit 1 when any validation fails, preventing unpinned packages from entering the runtime environment during CI/CD pipelines.

Frequently Asked Questions

What constitutes a valid pin for bootstrap dependencies?

A valid pin requires the package string to terminate with either == or @ followed immediately by the version number, and the version field must be explicitly declared. For example, "package": "requests==2.31.0" satisfies the regex check, while "package": "requests" or "package": "requests>=2.0" causes the gate to flag an unpinned dependency.

Why are apt-package and docker-image bootstrap kinds exempt from explicit pinning?

The script treats apt-package and docker-image as inherently pinned because they rely on distribution-managed repositories or immutable image digests managed by the container registry. According to the source code comments in lines 48‑49, these sources are considered deterministic within the context of the underlying infrastructure, though external auditing of those repositories remains the responsibility of the operator.

How does the pin gate integrate with the repository's CI pipeline?

verify-routing-coherence.ps1 executes as both a standalone test suite component and a pre-flight gate before routing actions. Because the script aggregates failures in a $fail variable and terminates with exit 1 when violations exist, any pull request introducing unpinned auto-install capabilities triggers a CI failure, preventing merge until deterministic references are added.

Can a capability pass validation without pinnedVersion or pinnedCommit?

Yes, depending on the bootstrapKind. For github-release-zip, providing assetSha256 or preferApiDigest satisfies the requirement. For remote-http-mcp, a pinPolicy field suffices under specific repository conditions. However, generic capabilities without a special bootstrap kind must provide at least one of pinnedVersion, pinnedCommit, or pinPolicy to pass the gate.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}