fix: add .npmrc with legacy-peer-deps for ERESOLVE errors

[imran-siddique]

npm shows typescript as 'undefined' during peer dep resolution, causing ERESOLVE failures across packages. Adding legacy-peer-deps=true to .npmrc bypasses strict peer checking.

[github-actions]

🤖 AI Agent: security-scanner — Security Analysis of the Change

Security Analysis of the Change

The addition of the .npmrc file with the legacy-peer-deps=true setting modifies how npm resolves peer dependencies. While this change may resolve immediate dependency conflicts, it introduces potential security risks in the context of a security-focused library like microsoft/agent-governance-toolkit.

---

Findings

🔴 Supply Chain Risk: Dependency Downgrade and Typosquatting

• Attack Vector: The legacy-peer-deps=true setting bypasses strict peer dependency resolution, allowing npm to install packages with potentially incompatible or outdated versions. This increases the risk of introducing vulnerable or malicious dependencies into the project. Attackers could exploit this by typosquatting or injecting malicious versions of dependencies that would otherwise be blocked by strict peer dependency checks.
• Impact:
  • Dependency Downgrade: Older versions of dependencies may lack critical security patches, exposing the project to known vulnerabilities.
  • Typosquatting: If a malicious package mimics a legitimate dependency, it could be installed without triggering warnings.
  • Trust Chain Weakness: Weakens the integrity of the dependency resolution process, undermining the security of the entire toolkit.
• Fix:
  • Avoid using legacy-peer-deps=true unless absolutely necessary. Instead, resolve the dependency conflicts explicitly by updating or pinning compatible versions of the affected packages in package.json.
  • Use tools like npm audit or yarn audit to identify and address vulnerabilities in the dependency tree.
  • If legacy-peer-deps=true must be used temporarily, document the rationale and plan to remove it as soon as possible.

---

🟠 Policy Engine Circumvention

• Attack Vector: The toolkit itself is a security layer. By allowing potentially incompatible or unverified dependencies, the policy engine's integrity could be compromised. A malicious or outdated dependency might introduce vulnerabilities that allow attackers to bypass policy enforcement.
• Impact:
  • Weakens the policy engine's ability to enforce security measures.
  • Could lead to scenarios where crafted inputs or malicious actors exploit the weakened policy engine.
• Fix:
  • Perform a thorough review of all dependencies and their transitive dependencies to ensure they are secure and compatible.
  • Use a dependency locking mechanism (e.g., package-lock.json or yarn.lock) to ensure consistent dependency resolution across environments.

---

🟡 Credential Exposure

• Attack Vector: The .npmrc file is often used to store npm credentials (e.g., tokens for private registries). While this PR does not include any credentials, the introduction of a .npmrc file increases the risk of accidental credential exposure in the future.
• Impact: If credentials are accidentally committed to the repository, they could be exploited by attackers to gain unauthorized access to private npm packages or other sensitive resources.
• Fix:
  • Add .npmrc to the .gitignore file to prevent accidental commits of sensitive information.
  • Use environment variables or secure secrets management solutions (e.g., GitHub Actions secrets) to handle sensitive credentials.

---

Overall Risk Rating: 🔴 CRITICAL

The use of legacy-peer-deps=true introduces significant supply chain risks, which are particularly concerning for a security-focused library. The potential for dependency downgrade, typosquatting, and weakened policy enforcement could compromise the security of downstream users.

---

Recommendations

1. Resolve Dependency Conflicts Explicitly: Instead of using legacy-peer-deps=true, update or pin compatible versions of dependencies in package.json.
2. Audit Dependencies: Use tools like npm audit to identify and address vulnerabilities in the dependency tree.
3. Lock Dependencies: Use package-lock.json or yarn.lock to ensure consistent dependency resolution.
4. Secure .npmrc: Add .npmrc to .gitignore and avoid storing sensitive credentials in the file.
5. Document Temporary Changes: If legacy-peer-deps=true is a temporary workaround, document the rationale and create an issue to track its removal.

By addressing these issues, the project can maintain its integrity as a security-focused library and protect its downstream users from potential vulnerabilities.

[github-actions]

🤖 AI Agent: code-reviewer

Review Feedback

🔴 CRITICAL

1. Security Implications of legacy-peer-deps:
   Adding legacy-peer-deps=true to .npmrc bypasses strict peer dependency checks, which can lead to the installation of potentially incompatible or insecure versions of dependencies. This introduces a risk of pulling in packages with known vulnerabilities or breaking changes that are not properly resolved. While this may resolve immediate ERESOLVE errors, it is not a long-term solution for dependency management in a security-focused library like microsoft/agent-governance-toolkit.

   Actionable Recommendation:

   • Investigate and resolve the root cause of the peer dependency conflicts instead of bypassing them.
   • Use tools like npm audit or npm ls to identify problematic dependencies and update them to compatible versions.
   • Consider pinning dependency versions explicitly in package.json to ensure compatibility.

💡 SUGGESTION

2. Documentation Update:
   If legacy-peer-deps=true is temporarily necessary, document the rationale clearly in the repository (e.g., in a README.md or CONTRIBUTING.md file). This will help contributors understand why this configuration is being used and encourage them to address the underlying dependency issues.

3. Automated Dependency Management:
   Consider integrating tools like Dependabot or Renovate to automate dependency updates and ensure compatibility across packages. This can help prevent similar issues in the future.

🟡 WARNING

4. Potential Breaking Changes:
   While this change itself does not directly modify the library's public API, the use of legacy-peer-deps may lead to unexpected behavior in downstream projects if incompatible dependencies are installed. This could indirectly result in breaking changes for users of the library.

   Actionable Recommendation:

   • Test the library thoroughly after applying this change to ensure that all packages function correctly with the resolved dependencies.
   • Communicate any potential risks to users in the release notes or changelog.

---

Summary

While this change resolves immediate ERESOLVE errors, it introduces security risks and potential compatibility issues. Addressing the root cause of dependency conflicts is a more robust and secure approach. If this workaround is necessary, document it clearly and test thoroughly to mitigate risks.