Skip to content

feat(core): Support npm registry token authentication to install private community node packages#28228

Merged
maspio merged 8 commits intomasterfrom
npm-community-packages-auth-token-config-support
Apr 15, 2026
Merged

feat(core): Support npm registry token authentication to install private community node packages#28228
maspio merged 8 commits intomasterfrom
npm-community-packages-auth-token-config-support

Conversation

@maspio
Copy link
Copy Markdown
Contributor

@maspio maspio commented Apr 9, 2026

Summary

Adds an env config N8N_COMMUNITY_PACKAGES_AUTH_TOKEN to install community nodes from authenticated npm registry accounts. Usage in combination with N8N_COMMUNITY_PACKAGES_REGISTRY enables enterprises and oem partners to build secure custom node publishing pipelines.

  • N8n used to support npm registry authentication placing an /home/node/.npmrc file with an auth token
  • The community node installer service used to rely fully on npm cli commands so each action could pick up auth
  • Some time ago n8n developers introduced npm http request for certain actions, like version/update checks
  • Naturally these requests did not pick up the auth token, so the strategy broke the .npmrc workaround
  • I decided to not build in support for .npmrc because env var configurations are much easier to do

This PR is critical for an OEM partner launch. Compared to our alternative "load nodes from filesystem" strategy, our community package installer supports remote api management and node upgrades without restart that are distributed across main and worker instances.

Related Linear tickets, Github issues, and Community forum posts

Review / Merge checklist

  • I have seen this code, I have run this code, and I take responsibility for this code.
  • PR title and summary are descriptive. (conventions)
  • Docs updated or follow-up ticket created.
  • Tests included.
  • PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)

@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 9, 2026

Codecov Report

❌ Patch coverage is 95.83333% with 2 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...s/community-packages/community-packages.service.ts 90.00% 1 Missing ⚠️
...es/cli/src/modules/community-packages/npm-utils.ts 97.29% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@n8n-assistant n8n-assistant Bot added core Enhancement outside /nodes-base and /editor-ui n8n team Authored by the n8n team labels Apr 9, 2026
@maspio maspio changed the title initial npm auth token and config claude code feat(core): support npm registry token authentication to install private community node packages Apr 9, 2026
@maspio maspio changed the title feat(core): support npm registry token authentication to install private community node packages feat(core): Support npm registry token authentication to install private community node packages Apr 10, 2026
@maspio maspio marked this pull request as ready for review April 10, 2026 07:20
Copy link
Copy Markdown
Contributor

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3 issues found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/modules/community-packages/npm-utils.ts">

<violation number="1" location="packages/cli/src/modules/community-packages/npm-utils.ts:86">
P1: Custom agent: **Security Review**

The `fullArgs` array logged here includes the raw `_authToken=<secret>` value when authentication is configured. Even at `debug` level, this exposes the npm registry credential to log sinks. Redact or omit the auth-related arguments before logging.</violation>

<violation number="2" location="packages/cli/src/modules/community-packages/npm-utils.ts:148">
P1: Custom agent: **Security Review**

The `headers` object logged here contains the `Authorization: Bearer <token>` value when authentication is configured. Even at `debug` level, this exposes the npm registry credential to log sinks. Omit or redact the `Authorization` header before logging.</violation>
</file>

<file name="packages/cli/src/modules/community-packages/community-packages.service.ts">

<violation number="1" location="packages/cli/src/modules/community-packages/community-packages.service.ts:515">
P1: Passing `authToken` into npm helpers causes registry credentials to be logged in plaintext debug logs (CLI args and Authorization headers).</violation>
</file>
Architecture diagram
sequenceDiagram
    participant Svc as CommunityPackagesService
    participant Config as CommunityPackagesConfig
    participant Utils as npm-utils
    participant API as NPM Registry (HTTP)
    participant CLI as NPM CLI (Process)

    Note over Svc,CLI: Community Package Installation / Update Flow

    Svc->>Config: NEW: Fetch N8N_COMMUNITY_PACKAGES_AUTH_TOKEN
    Config-->>Svc: Auth Token (if set)

    rect rgb(240, 240, 240)
    Note over Svc,API: Step 1: Metadata Verification (Integrity & Version)
    Svc->>Utils: verifyIntegrity(packageName, version, registry, token)
    
    Utils->>API: CHANGED: executeNpmRequest() with "Bearer <token>" header
    alt Request Successful
        API-->>Utils: Package Metadata (dist.integrity)
    else Request Failed (Fallback)
        Utils->>CLI: CHANGED: executeNpmCommand("view") with "--//registry/:_authToken=<token>"
        CLI-->>Utils: JSON Metadata
    end
    Utils-->>Svc: Verification Result
    end

    rect rgb(240, 240, 240)
    Note over Svc,CLI: Step 2: Download Package
    Svc->>Utils: downloadPackage(packageName, version, token)
    Utils->>CLI: CHANGED: npm pack --registry=<url> --//<host>/:_authToken=<token>
    CLI-->>Utils: .tgz file
    Utils-->>Svc: Tarball path
    end

    rect rgb(240, 240, 240)
    Note over Svc,CLI: Step 3: Local Dependency Installation
    Svc->>Utils: executeNpmCommand("install", { registry, token })
    Utils->>CLI: CHANGED: npm install [args] --registry=<url> --//<host>/:_authToken=<token>
    CLI-->>Utils: Success/Failure
    Utils-->>Svc: Done
    end

    Svc->>Svc: Load nodes into n8n runtime
Loading

Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.

Comment thread packages/cli/src/modules/community-packages/npm-utils.ts Outdated
Comment thread packages/cli/src/modules/community-packages/npm-utils.ts Outdated
['pack', `${packageName}@${packageVersion}`, `--registry=${registry}`, '--quiet'],
{ cwd: this.downloadFolder },
['pack', `${packageName}@${packageVersion}`, '--quiet'],
{ cwd: this.downloadFolder, registry, authToken },
Copy link
Copy Markdown
Contributor

@cubic-dev-ai cubic-dev-ai Bot Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: Passing authToken into npm helpers causes registry credentials to be logged in plaintext debug logs (CLI args and Authorization headers).

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/modules/community-packages/community-packages.service.ts, line 515:

<comment>Passing `authToken` into npm helpers causes registry credentials to be logged in plaintext debug logs (CLI args and Authorization headers).</comment>

<file context>
@@ -500,8 +511,8 @@ export class CommunityPackagesService {
-			['pack', `${packageName}@${packageVersion}`, `--registry=${registry}`, '--quiet'],
-			{ cwd: this.downloadFolder },
+			['pack', `${packageName}@${packageVersion}`, '--quiet'],
+			{ cwd: this.downloadFolder, registry, authToken },
 		);
 
</file context>
Fix with Cubic

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has been addressed

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update!

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Apr 13, 2026

Performance Comparison

Comparing currentlatest master14-day baseline

Idle baseline with Instance AI module loaded

Metric Current Latest Master Baseline (avg) vs Master vs Baseline Status
instance-ai-rss-baseline 342.85 MB 380.71 MB 369.52 MB (σ 24.20) -9.9% -7.2% ⚠️
instance-ai-heap-used-baseline 186.82 MB 186.02 MB 186.31 MB (σ 0.25) +0.4% +0.3% 🔴

Memory consumption baseline with starter plan resources

Metric Current Latest Master Baseline (avg) vs Master vs Baseline Status
memory-heap-used-baseline 114.02 MB 114.20 MB 113.67 MB (σ 1.06) -0.2% +0.3%
memory-rss-baseline 285.28 MB 352.66 MB 283.64 MB (σ 42.70) -19.1% +0.6%

docker-stats

Metric Current Latest Master Baseline (avg) vs Master vs Baseline Status
docker-image-size-runners 393.00 MB 418.00 MB 391.43 MB (σ 11.93) -6.0% +0.4%
docker-image-size-n8n 1269.76 MB 1269.76 MB 1269.76 MB (σ 0.00) +0.0% +0.0%
How to read this table
  • Current: This PR's value (or latest master if PR perf tests haven't run)
  • Latest Master: Most recent nightly master measurement
  • Baseline: Rolling 14-day average from master
  • vs Master: PR impact (current vs latest master)
  • vs Baseline: Drift from baseline (current vs rolling avg)
  • Status: ✅ within 1σ | ⚠️ 1-2σ | 🔴 >2σ regression

@sandra0503
Copy link
Copy Markdown
Contributor

Testing done

Manually verified that installing packages from authenticated registry works with auth token.

Setup

  • Started a local Verdaccio npm registry at http://localhost:4873
  • Configured Verdaccio to require authentication for reads (access: $authenticated)
  • Created a registry user and obtained an auth token
  • Published a minimal test community node package (n8n-nodes-test) with a valid n8n.nodes manifest

Test execution

  • Started n8n with N8N_COMMUNITY_PACKAGES_REGISTRY, N8N_COMMUNITY_PACKAGES_AUTH_TOKEN, and N8N_LOG_LEVEL=debug
  • Installed n8n-nodes-test through the UI (Settings → Community Nodes → Install)

Results

Check Result
Install with correct token Succeeded
Install with wrong token Failed with auth error (confirms Verdaccio enforces auth)
_authToken value in debug logs Redacted as _authToken=*****
Authorization header in debug logs Redacted as Bearer *****
Actual token value in logs Not present

sandra0503
sandra0503 previously approved these changes Apr 13, 2026
@maspio maspio added this pull request to the merge queue Apr 15, 2026
Merged via the queue into master with commit 8b105cc Apr 15, 2026
56 checks passed
@maspio maspio deleted the npm-community-packages-auth-token-config-support branch April 15, 2026 09:43
Aijeyomah pushed a commit to Aijeyomah/n8n that referenced this pull request Apr 15, 2026
…ate community node packages (n8n-io#28228)

Co-authored-by: Sandra Zollner <sandra.zollner@n8n.io>
@n8n-assistant n8n-assistant Bot mentioned this pull request Apr 21, 2026
@n8n-assistant
Copy link
Copy Markdown
Contributor

n8n-assistant Bot commented Apr 21, 2026

Got released with n8n@2.18.0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core Enhancement outside /nodes-base and /editor-ui n8n team Authored by the n8n team Released

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants