In today's software ecosystem, publishing packages to repositories like PyPI, npm, or RubyGems is a critical step in the software supply chain. These packages are widely used and often form the backbone of projects worldwide. But with great power comes great responsibility: how can repositories ensure that only authorized workflows are allowed to publish packages?
Enter Trusted Publishers, a new system built around OpenID Connect (OIDC). It is designed to improve security while reducing reliance on long-lived credentials, helping package maintainers protect their projects against hijacking and supply chain attacks. For smaller publishers who might be new to these concepts, understanding Trusted Publishers is an essential step toward safer software distribution.
Why This Matters Now: Recent Supply Chain Attacks
The urgency of implementing Trusted Publishers becomes clear when examining recent high-profile attacks that have shaken the npm ecosystem.
The September 2025 Credential Phishing Attack
On September 8, 2025, a sophisticated phishing attack compromised popular npm packages including debug
and chalk
, affecting packages with billions of weekly downloads. The attacker used a convincing 2FA reset email from a fake domain (npmjs.help
) to capture the maintainer's credentials and publish malicious versions that targeted cryptocurrency wallets and blockchain transactions.
Despite being live for only two hours, the attack demonstrated how long-lived API keys stored in maintainer accounts create single points of failure. The malicious code included browser-targeted payloads that could intercept MetaMask wallet calls and redirect cryptocurrency transactions to attacker-controlled addresses.
The Shai-Hulud Self-Replicating Worm
Just one week later, on September 15, 2025, the Shai-Hulud worm infected over 500 npm packages using an even more sophisticated approach. This self-replicating malware executed during npm install
, harvested cloud credentials and GitHub tokens from environment variables, and then automatically propagated to other packages owned by the same compromised maintainers.
The worm's capabilities included:
- Scanning filesystems for secrets using TruffleHog-like methods
- Creating backdoor GitHub Actions workflows to maintain persistent access
- Exfiltrating stolen credentials to publicly accessible GitHub repositories
- Querying the npm registry to find and infect additional packages owned by compromised accounts
Both attacks exploited the same fundamental vulnerability: static, long-lived credentials that, once compromised, granted attackers full publishing rights across multiple packages.
How Trusted Publishers Works
At its core, Trusted Publishers allows a package repository to authenticate publishing workflows from identity providers (IdPs) like GitHub Actions, GitLab Pipelines, or other OIDC-compatible platforms. The process generally works as follows:
1. Set Up a Trust Policy
Before publishing, the repository owner defines a trust policy that specifies which workflows or repositories can publish which packages. This can include:
- Repository and branch restrictions (e.g., only
main
orrelease
branches). - Workflow file constraints (specific CI/CD workflow YAML files).
- Owner or organization validation (ensuring only approved maintainers can trigger publishing).
Think of this as creating a "guest list" for who is allowed to publish.
2. Publishing Workflow Requests a Token
When a workflow attempts to publish a package, it requests an OIDC ID token from its IdP. This token functions like a digital passport, containing metadata (claims) about:
- The repository and workflow triggering the request.
- The owner or organization initiating the workflow.
- The intended audience (the repository) and the token issuer.
Tokens are short-lived, typically expiring within a few minutes, and are automatically rotated by the IdP-eliminating the risk associated with static credentials.
3. Repository Verifies the Token
The repository checks the token against several security criteria:
-
Issuer (
iss
) – Confirms the token comes from a trusted IdP. -
Audience (
aud
) – Ensures the token was intended for this specific repository. - Workflow-specific claims – Validates the repository name, workflow file, and owner match the trust policy.
- Signature validation – Uses the IdP's public keys (JWKs) to verify the token has not been tampered with.
If all checks pass, the repository can safely allow the publish operation.
4. Publish is Allowed
Once verified, the repository may exchange the OIDC token for a short-lived internal token that completes the publishing process. This ensures that even if a token is intercepted, it is valid only for a single, brief operation.
Why This Is Safer Than Traditional API Keys
Many small publishers rely on API keys or tokens stored in CI/CD pipelines. These keys are long-lived and, if exposed, can allow attackers to publish malicious packages. Trusted Publishers addresses these risks:
- Eliminates long-lived secrets – Tokens are short-lived and automatically rotated.
- Ties publishing to specific workflows – Each token is linked to a particular workflow, repository, and branch.
- Policy-driven publishing – Only workflows explicitly allowed by the trust policy can publish packages.
- Auditable history – Token validation logs provide a clear audit trail of who published what and when.
For small package maintainers, this means a much lower risk of accidental or malicious package uploads.
Addressing Potential Concerns
While Trusted Publishers improves security, some issues are worth considering:
1. Could this create a monopoly of providers?
Currently, Trusted Publishers often supports major IdPs like GitHub and GitLab first. Smaller or self-hosted workflows may be left out, which could create dependency on a few platforms, potentially allowing them to charge for publishing access in the future.
Mitigation strategies:
- Repositories can support multiple IdPs to avoid single-provider lock-in.
- Trust policies can allow alternative publishing methods alongside OIDC.
- Open-source communities can encourage forks, mirrors, or alternative registries to maintain choice and competition.
2. Could malicious actors act as publishers?
Yes, in theory, any IdP could implement OIDC-even a malicious one. However, repositories enforce trust policies:
- Only tokens from recognized IdPs are accepted.
- Tokens must match specific claims (repository, workflow, owner).
- Invalid or unrecognized tokens are rejected, even if cryptographically valid.
This ensures that even if a rogue IdP issues a token, it cannot be used unless explicitly trusted by the repository. Security is therefore policy-driven, not just cryptography-driven.
3. Learning curve for small publishers
For smaller maintainers, configuring trust policies and understanding OIDC may seem intimidating at first. Start small:
- Restrict publishing to main branches initially.
- Test workflows in a sandbox repository before enabling real publishing.
- Gradually expand trust policies as confidence grows.
Practical Tips for Small Package Maintainers
- Audit existing credentials: Revoke old API keys and tokens before adopting Trusted Publishers.
-
Use branch restrictions: Limit publishing to stable branches like
main
orrelease
. - Test with staging repositories: Before implementing in production, try publishing to a test package or private registry.
- Enable logging and alerts: Monitor publishing activity to detect unexpected attempts.
- Document your policy: Clearly define which workflows can publish which packages. Documentation helps onboard new maintainers safely.
The Big Picture
Trusted Publishers is a significant step forward in securing the software supply chain. It allows repositories to trust only authorized workflows without relying on static secrets. While there are trade-offs-such as potential provider consolidation and careful policy configuration-it provides a flexible, auditable, and short-lived approach to package publishing.
By combining open standards like OIDC with repository-managed trust policies, the ecosystem can reduce risk, improve security, and maintain flexibility for multiple identity providers-keeping package publishing both safe and practical.
Analogy: Think of it as a VIP club: only guests with the right digital ID (OIDC token) and pre-approved credentials (trust policy) can enter. Rogue guests with fake IDs won't get in, no matter how convincing their tokens look.
Trusted Publishers may not be perfect, but with careful implementation and a commitment to openness, it's a solid step forward for the security of package ecosystems.
Top comments (0)