build: Add NuGet package release-age verification workflow

[aoirint]

Warning

This issue was created with assistance from LLMs.

Summary

• Follow up on Strengthen skill guidance for supply-chain-safe ad hoc tool execution #68 for the NuGet-specific part of the repository supply-chain baseline.
• The repository currently uses locked NuGet restore, package source mapping, and pinned/resolved package hashes, but it does not appear to enforce a package release-age cooldown for NuGet packages.
• Treat NuGet release-age verification as a minimum gate for dependency updates, not as proof that a package is trustworthy after the cooldown window.

Details

• Current restore path uses dotnet restore --locked-mode and CruiserJumpPractice/packages.lock.json.
• CruiserJumpPractice/nuget.config limits sources through package source mapping.
• CruiserJumpPractice/CruiserJumpPractice.csproj still includes direct package references, including floating analyzer/build helper versions such as BepInEx.Analyzers 1.* and BepInEx.PluginInfoProps 2.*, with resolved versions captured by the lock file.
• The missing piece is release-age verification for the resolved NuGet package versions before accepting dependency updates or lock-file changes.
• Release-age verification does not replace normal package trust judgment. Provenance, configured sources, package identity, pinning/lockfile behavior, vulnerability signals, package permissions or build behavior where relevant, and stricter current security requirements still matter.
• This should stay practical and project-scoped: verify the package versions this repository resolves, document blockers when registry metadata is unavailable, and avoid attempting broader ecosystem trust guarantees.

Proposed Implementation Plan

• Add a small verification script or documented command that reads CruiserJumpPractice/packages.lock.json and checks the resolved package versions.
• For each resolved package, query the configured NuGet source metadata for the package publish/listed timestamp when available.
• Fail or report a blocker when a resolved package version is newer than the repository cooldown period, currently 7 days.
• Fail or report a blocker when release-age metadata cannot be retrieved from the expected source and no maintainer-approved exception is recorded.
• Document how maintainers should run the check after changing PackageReference entries or regenerating packages.lock.json.
• Consider adding the check to CI only after the local command is deterministic enough for the repository's configured NuGet sources.
• Record any unavoidable NuGet API/source limitations in the security Agent Skill or package-management documentation.

Acceptance Criteria

• NuGet dependency updates have a documented release-age verification workflow.
• The workflow checks resolved package versions from packages.lock.json, not only direct PackageReference entries.
• The workflow uses source-backed publish/release metadata where available.
• The workflow presents cooldown as a minimum gate and explicitly says cooldown expiry is not sufficient trust by itself.
• The workflow preserves broader dependency trust checks, such as configured source provenance, package identity, pinning/lockfile behavior, vulnerability signals where available, and stricter current security requirements.
• The workflow reports a clear blocker or requires a documented exception when release age cannot be verified.
• The workflow is referenced from the broader security Agent Skill follow-up in Strengthen skill guidance for supply-chain-safe ad hoc tool execution #68.

[aoirint]

Warning

This comment was created with assistance from LLMs.

Request addressed: Research Note for NuGet release-age verification implementation.

Research Note

As of 2026-05-04, the most concrete implementation should be a repository-local verifier that checks the resolved versions in CruiserJumpPractice/packages.lock.json, with Dependabot cooldown used only as an additional automation guard.

Findings

• NuGet V3 package metadata is available through the RegistrationsBaseUrl resource advertised by each source's service index. The metadata can expose published, listed, catalogEntry, and package content URLs. Source: https://learn.microsoft.com/en-us/nuget/api/registration-base-url-resource
• packages.lock.json is the right input because NuGet lock files persist the full direct and transitive dependency closure, and locked restore uses the listed package versions. Source: https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#locking-dependencies
• CruiserJumpPractice/nuget.config already maps every resolved package to nuget.org or bepinex. NuGet package source mapping requires direct and transitive packages to match a source pattern, and precedence is exact ID, then longest prefix, then *. Source: https://learn.microsoft.com/en-us/nuget/consume-packages/package-source-mapping
• GitHub Dependabot now documents cooldown for NuGet version updates, so it can delay Dependabot-created dependency PRs. It is not enough by itself for this issue because it does not independently verify arbitrary lock-file changes or manual update PRs. Source: https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#cooldown
• Renovate has minimumReleaseAge, but its own docs call out lockfile/transitive gaps where a package manager can introduce transitive dependencies without Renovate applying the age check. That supports keeping a repo-local lock-file verifier even if Renovate is adopted later. Source: https://docs.renovatebot.com/key-concepts/minimum-release-age/
• I tested the current resolved package set against https://api.nuget.org/v3/index.json and https://nuget.bepinex.dev/v3/index.json. Both sources expose RegistrationsBaseUrl, and every currently resolved package version returned publish metadata. The newest current resolved package appears to be LethalCompany.GameLibs.Steam 81.0.5-ngd.0, published 2026-04-24T17:22:29Z; that is already older than the proposed 7-day cooldown on 2026-05-04.

Recommended Implementation

• Add tools/Verify-NuGetReleaseAge.ps1 and call it from documentation as:
  • pwsh tools/Verify-NuGetReleaseAge.ps1 -LockFile CruiserJumpPractice/packages.lock.json -NuGetConfig CruiserJumpPractice/nuget.config -CooldownDays 7
• Script behavior:
  • Parse every target framework under dependencies in packages.lock.json.
  • Collect unique (id, resolved) pairs, including both Direct and Transitive entries.
  • Parse nuget.config package sources and packageSourceMapping.
  • Resolve the expected source using NuGet's mapping precedence: exact package ID first, longest Prefix.* next, * last.
  • Fail if a package maps to zero sources, or to multiple equally valid sources, unless an explicit maintainer exception records why ambiguity is accepted.
  • Fetch the selected source service index and prefer a SemVer 2-capable RegistrationsBaseUrl/3.6.0 or RegistrationsBaseUrl/Versioned resource when available; otherwise fall back to RegistrationsBaseUrl.
  • Fetch the registration index for the lowercased package ID, follow the page/leaf links discovered from the index, and find the exact normalized resolved version.
  • Read published from the leaf or its catalogEntry. If published is absent, unparsable, or 1900-01-01 for nuget.org/unlisted packages, treat release age as unverifiable and fail unless an exception is present.
  • Compare now_utc - published_utc with CooldownDays; fail with a clear package/source/version message when the package is too new.
  • Emit a small table containing package ID, resolved version, source, published timestamp, age in days, and result.
• Add an optional exceptions file such as tools/nuget-release-age-exceptions.json with fields like id, version, source, reason, approvedBy, and expiresUtc. Require exact (id, version, source) matches and reject expired exceptions.
• Add a CI workflow after the local script is stable:
  • Run dotnet restore CruiserJumpPractice/CruiserJumpPractice.csproj --locked-mode.
  • Run the release-age verifier.
  • Keep the check on PRs that touch *.csproj, packages.lock.json, nuget.config, or the verifier/exception files.
• If Dependabot is enabled, add cooldown.default-days: 7 for package-ecosystem: nuget as a first-line delay for Dependabot version PRs, but keep the verifier as the required PR gate.

Suggested Acceptance Check

A future implementation is complete when a maintainer can regenerate packages.lock.json, run the verifier locally, and get either:

• a pass for every resolved direct and transitive package version with source-backed publish metadata older than 7 days; or
• a deterministic failure naming the exact package/version/source that is too new or unverifiable, plus the exception file entry needed if maintainers intentionally proceed.

Cooldown should remain documented as a minimum gate only. Passing the age check does not prove package trust; source provenance, package identity, lock-file/content-hash review, vulnerability/deprecation signals, package permissions/build behavior where relevant, and stricter current security requirements still need normal review.

[aoirint]

Warning

This comment was created with assistance from LLMs.

Request addressed: Check whether NuGet, Microsoft, or notable C#/.NET-adjacent organizations already provide an official release-age solution.

Discussion Note

I found no NuGet/.NET SDK/Microsoft-supported restore-time or install-time option that directly enforces "do not resolve or accept NuGet package versions newer than N days" as of 2026-05-04.

The closest NuGet-official signal is an open NuGet/Home feature request: NuGet/Home#14657: Add update cooldown option to NuGet. It explicitly proposes a NuGet update cooldown for Visual Studio Package Management UI and .NET CLI, and also mentions a possible restore strict mode, but says restore support may be challenging for protocol reasons. The issue is still open and includes a maintainer note that an implementation would need internal security review, especially around how vulnerability fixes should bypass cooldown.

Official Or Established Options Found

• NuGet/Microsoft built-in equivalent: Not found. NuGet has official supply-chain controls, but they are adjacent controls rather than release-age enforcement:
  • Package Source Mapping limits which sources are searched for direct and transitive package IDs.
  • NuGet lock files / locked restore pin the resolved graph after restore.
  • NuGet Audit checks known vulnerability data during restore.
  • Trusted signers / signature validation can require packages to be signed by trusted authors or repositories.
  • Trusted Publishing on nuget.org improves publisher credential safety, but it protects publishing credentials rather than consumer-side release-age selection.
• GitHub Dependabot: Dependabot cooldown is official GitHub support and includes NuGet in the SemVer-supported package manager list. It delays Dependabot version update PRs only; the docs state it is not available for security updates. This is useful as an automation guard, but it does not verify arbitrary manual lock-file changes.
• Renovate: Renovate minimumReleaseAge is an established updater-side solution, and Renovate supports the NuGet manager with packages.lock.json lock-file maintenance. Its own docs still recommend package-manager-side checks too, because transitive dependencies and lock-file artifacts can be introduced by the delegated package manager outside Renovate's direct awareness.

Resulting Decision

There is no official NuGet/Microsoft drop-in replacement for the repository-local verifier proposed above. The strongest practical path remains:

• keep using NuGet's official baseline controls: package source mapping, lock files, locked restore, NuGet Audit, and signature/trust checks where practical;
• optionally configure Dependabot cooldown.default-days: 7 if Dependabot version updates are enabled;
• optionally use Renovate minimumReleaseAge if the project later adopts Renovate;
• add a repository-local verifier that reads packages.lock.json and checks source-backed published timestamps from each configured NuGet V3 source.

That verifier should be treated as the missing NuGet-specific gate until NuGet/Home#14657 or an equivalent NuGet client feature ships.

[aoirint]

Warning

This comment was created with assistance from LLMs.

Request addressed: Record maintainer feedback about scope and issue tracking status.

Discussion Note

Maintainer feedback received: there does not appear to be a realistic, user-executable NuGet release-age verification mechanism available today, and that limitation is understood.

Based on that feedback, a repository-local NuGet release-age verifier should be considered outside this project's current responsibility scope. The project can still consider adjacent NuGet official baseline controls, but it should not take ownership of implementing a custom release-age gate unless the scope changes later.

For now, this issue should remain open to track the missing NuGet-official capability. The current expectation is that this may not be resolved in the near future, and the issue should continue tracking NuGet/Home#14657 or an equivalent official NuGet release-age/cooldown feature until NuGet provides one.

I will add a separate Research Note with currently actionable C#/NuGet supply-chain defense options that stay within practical project scope.

[aoirint]

Warning

This comment was created with assistance from LLMs.

Request addressed: New Research Note on currently actionable C#/NuGet supply-chain defenses.

Research Note

This note intentionally does not propose a repository-local release-age verifier. The items below are currently actionable controls for a C#/NuGet repository, but none of them fully replace a NuGet-official release-age/cooldown gate.

Actionable NuGet Baseline Controls

• Keep package source mapping strict. NuGet documents Package Source Mapping as a supply-chain security control, especially when multiple package sources are configured. Once enabled, direct and transitive packages must match source patterns. This repository already uses CruiserJumpPractice/nuget.config; the practical next step is to keep mappings narrow and review any new wildcard before dependency updates are accepted. Source: https://learn.microsoft.com/en-us/nuget/consume-packages/package-source-mapping
• Keep locked restore in CI. NuGet lock files persist the full direct and transitive dependency closure, and dotnet restore --locked-mode fails instead of silently changing the resolved graph. This repository already has CruiserJumpPractice/packages.lock.json; the practical guard is to keep lock-file diffs reviewable and require locked restore on CI. Source: https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#locking-dependencies
• Enable or tighten NuGet Audit. dotnet restore can check packages against configured vulnerability data. For this repository, a practical baseline would be repository-level MSBuild settings such as NuGetAudit=true, NuGetAuditMode=all when supported by the SDK in use, and treating high/critical findings as errors through WarningsAsErrors for NU1903;NU1904. Source: https://learn.microsoft.com/en-us/nuget/concepts/auditing-packages
• Configure auditSources explicitly. NuGet supports separate audit sources, so a project can use vulnerability data from https://api.nuget.org/v3/index.json without broadening package restore sources. This is useful when package sources are intentionally constrained. Source: https://learn.microsoft.com/en-us/nuget/concepts/auditing-packages#audit-sources
• Use dotnet package list for review workflows. dotnet package list --include-transitive, --vulnerable, --deprecated, and --outdated provide maintainer-facing review data. They are not gates by themselves, but they are practical commands for dependency-update PR review and periodic audits. Source: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-package-list
• Consider signature trust boundaries carefully. NuGet can require signed packages by setting signatureValidationMode=require and configuring trustedSigners; repository signatures can also be restricted by owner metadata. This can be valuable for sources that consistently provide signatures, but it may be disruptive if a configured source or package set does not meet the signing policy. Source: https://learn.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages
• Consider Central Package Management only if version ownership grows. CPM centralizes versions in Directory.Packages.props and supports transitive pinning. For this single project, CPM may be optional overhead, but it becomes more useful if package versions spread across multiple projects. Transitive pinning should be evaluated carefully because it can affect packed library dependency metadata. Source: https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management

Actionable GitHub / Automation Controls

• Dependabot version updates with cooldown. GitHub documents cooldown for version updates and lists NuGet as a SemVer-supported package manager. This can delay Dependabot-created NuGet update PRs, but it is not available for security updates and does not verify manual lock-file changes. Source: https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#cooldown
• Dependency Review Action on PRs. GitHub's Dependency Review Action can fail PRs based on vulnerability severity, dependency scope, and license policy. This is a PR-level review gate for dependency changes, not NuGet release-age verification. Source: https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configuring-the-dependency-review-action
• Dependabot security alerts and updates. If enabled for the repository, Dependabot can track known vulnerable dependencies and propose security update PRs. This complements NuGet Audit because both are advisory-driven rather than release-age-driven. Source: https://docs.github.com/en/code-security/dependabot

Practical Priority For This Repository

Given the current project scope, the most realistic near-term alternatives to a release-age gate are:

1. Keep this issue open for NuGet-official release-age support.
2. Preserve strict nuget.config package source mapping and packages.lock.json locked restore.
3. Add or document NuGet Audit settings, especially NuGetAuditMode=all where supported and high/critical findings as CI failures.
4. Add explicit auditSources if the repository wants vulnerability data independent of package restore sources.
5. Consider Dependency Review Action and Dependabot cooldown as GitHub-side review helpers.
6. Treat signature validation / trusted signers as a separate follow-up only after confirming that all required sources and packages can satisfy the policy without blocking normal development.

These controls reduce dependency-confusion risk, accidental graph drift, known-vulnerability exposure, and unreviewed dependency changes. They do not solve the original release-age problem, so this issue should remain open for the official NuGet feature track.