[v1.1] NPM token support for private packages

[frankbria]

Problem

E2B sandboxes cannot install private npm packages because npm authentication tokens are not configured.

Use Case

• Teams with private npm packages
• Projects using private npm registries
• Enterprise npm instances

Proposed Solution

CLI Flag

parallel-cc sandbox-run --repo . --prompt "Task" \
  --npm-token "npm_xxx"

Environment Variable

export PARALLEL_CC_NPM_TOKEN="npm_xxx"

Implementation

1. Accept npm token via CLI or environment
2. Create ~/.npmrc in sandbox with token
3. Support custom registry URLs
4. Handle scoped packages (@org/package)

Configuration

# Custom registry support
parallel-cc sandbox-run --repo . --prompt "Task" \
  --npm-token "xxx" \
  --npm-registry "https://npm.company.com"

Files to Modify

• src/cli.ts - Add npm flags
• src/e2b/sandbox-manager.ts - Inject npm config
• src/e2b/file-sync.ts - Handle .npmrc correctly

Acceptance Criteria

• NPM token can be passed via CLI or env var
• Private packages install successfully
• Custom registries supported
• Token never logged or exposed
• Documentation updated

Dependencies

• Related to [v1.1] SSH key injection for private repository access #24 (credential injection pattern)

[traycerai]

Plan

Observations

The codebase already has a well-established pattern for credential injection into E2B sandboxes. The sandbox-run command in file:src/cli.ts accepts various authentication options (ANTHROPIC_API_KEY, GITHUB_TOKEN), and credentials are injected via export statements in file:src/e2b/claude-runner.ts. The file sync module (file:src/e2b/file-sync.ts) has security patterns for sensitive data scanning. The .npmrc file is not in the ALWAYS_EXCLUDE list, which allows flexibility for npm configuration. The system uses Commander.js for CLI parsing and follows a consistent pattern of CLI flag → environment variable → sandbox injection.

Approach

The implementation will follow the existing credential injection pattern used for ANTHROPIC_API_KEY and GITHUB_TOKEN. Add two new CLI options (--npm-token and --npm-registry) to the sandbox-run command, with fallback to environment variables. The npm token will be injected into the sandbox by creating a ~/.npmrc file before npm install operations. This approach ensures tokens are never logged, maintains consistency with existing patterns, and supports both public and private npm registries including scoped packages. The implementation will be minimal and focused, touching only the three files mentioned in the issue.

Implementation Steps

1. Add CLI Flags and Environment Variable Support

File: file:src/cli.ts

Locate the sandbox-run command definition (around line 1352) and add two new options after the existing options:

.option('--npm-token <token>', 'NPM authentication token for private packages (or set PARALLEL_CC_NPM_TOKEN env var)')
.option('--npm-registry <url>', 'Custom NPM registry URL (default: https://registry.npmjs.org)', 'https://registry.npmjs.org')

In the action handler (around line 1384), after the existing validation blocks and before Step 1, add npm token validation:

• Read npm token from options.npmToken or process.env.PARALLEL_CC_NPM_TOKEN
• If npm token is provided, validate it's a non-empty string
• Store the token and registry URL for later use
• Do NOT log the token value (only log "NPM token provided: yes/no")

2. Inject NPM Configuration into Sandbox

File: file:src/e2b/sandbox-manager.ts

Add a new method configureNpmAuth to the SandboxManager class (after the extendTimeout method around line 543):

Method signature:

async configureNpmAuth(
  sandbox: Sandbox,
  npmToken: string,
  npmRegistry: string = 'https://registry.npmjs.org'
): Promise<boolean>

Implementation logic:

• Validate inputs (non-empty token, valid registry URL format)
• Create .npmrc content with authentication configuration:
  • For default registry: //registry.npmjs.org/:_authToken=${npmToken}
  • For custom registry: extract hostname from registry URL and use //hostname/:_authToken=${npmToken}
  • Add registry=${npmRegistry} line
  • For scoped packages, add @scope:registry=${npmRegistry} support
• Use sandbox.files.write() to create /root/.npmrc file with the configuration
• Use single quotes in shell commands to prevent token interpolation
• Log success/failure without exposing token value
• Return boolean indicating success

3. Integrate NPM Configuration into Sandbox Execution Flow

File: file:src/cli.ts

In the sandbox-run command action handler, after sandbox creation and upload (around line 1617, after "Workspace uploaded" message):

• Check if npm token was provided (from CLI flag or environment variable)
• If provided, call sandboxManager.configureNpmAuth(sandbox, npmToken, npmRegistry)
• Log the result: "✓ NPM authentication configured" or "⚠ NPM authentication failed"
• Continue with execution regardless of npm config result (non-blocking)

File: file:src/e2b/claude-runner.ts

No changes needed to this file. The .npmrc file created in the sandbox will be automatically used by npm/yarn/pnpm commands executed by Claude Code.

4. Security Considerations

File: file:src/e2b/file-sync.ts

No changes needed. The existing security patterns already handle .npmrc files appropriately:

• .npmrc is NOT in ALWAYS_EXCLUDE (lines 51-70), so local .npmrc files can be uploaded if present
• The SENSITIVE_PATTERNS array (lines 31-46) already includes TOKEN pattern which will flag .npmrc files during credential scanning
• The sandbox-injected .npmrc will not be downloaded back to local machine (only changed files are downloaded)

5. Documentation Updates

Add documentation for the new flags in the command description (in file:src/cli.ts around line 1354):

NPM Authentication:
  --npm-token <token>     NPM token for private packages (or PARALLEL_CC_NPM_TOKEN env var)
  --npm-registry <url>    Custom NPM registry (default: registry.npmjs.org)

Add example usage:

# Private npm packages
parallel-cc sandbox-run --repo . --prompt "Install deps" --npm-token "npm_xxx"

# Custom registry
parallel-cc sandbox-run --repo . --prompt "Task" \
  --npm-token "xxx" --npm-registry "https://npm.company.com"

# Using environment variable
export PARALLEL_CC_NPM_TOKEN="npm_xxx"
parallel-cc sandbox-run --repo . --prompt "Task"

Implementation Flow Diagram

sequenceDiagram
    participant CLI as CLI (cli.ts)
    participant SM as SandboxManager
    participant E2B as E2B Sandbox
    participant NPM as NPM Registry

    CLI->>CLI: Parse --npm-token flag
    CLI->>CLI: Fallback to PARALLEL_CC_NPM_TOKEN
    CLI->>SM: createSandbox()
    SM->>E2B: Create sandbox
    CLI->>E2B: Upload workspace tarball
    
    alt NPM token provided
        CLI->>SM: configureNpmAuth(token, registry)
        SM->>SM: Validate token & registry
        SM->>SM: Build .npmrc content
        SM->>E2B: Write /root/.npmrc
        E2B-->>SM: Success
        SM-->>CLI: Configuration complete
    end
    
    CLI->>E2B: Execute Claude Code
    E2B->>NPM: npm install (uses .npmrc)
    NPM-->>E2B: Private packages installed
    E2B-->>CLI: Execution complete
    CLI->>E2B: Download changed files
    
    Note over E2B,CLI: .npmrc NOT downloaded (only changed files)

Loading

Security Guarantees

Aspect	Implementation
Token Logging	Never log token value, only log "token provided: yes/no"
Token Storage	Token only exists in sandbox memory, never written to local disk
Token Exposure	Use single quotes in shell commands to prevent interpolation
Token Cleanup	.npmrc in sandbox is destroyed when sandbox terminates
Token Download	.npmrc is NOT downloaded back to local machine
Validation	Validate token is non-empty string before use

Testing Considerations

While not explicitly requested, implementers should verify:

• CLI flag parsing works correctly
• Environment variable fallback functions
• .npmrc file is created with correct format
• Private packages install successfully
• Custom registries work as expected
• Scoped packages (@org/package) authenticate correctly
• Token is never visible in logs or output

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase already has a well-established pattern for credential injection into E2B sandboxes. The `sandbox-run` command in `file:src/cli.ts` accepts various authentication options (ANTHROPIC_API_KEY, GITHUB_TOKEN), and credentials are injected via export statements in `file:src/e2b/claude-runner.ts`. The file sync module (`file:src/e2b/file-sync.ts`) has security patterns for sensitive data scanning. The .npmrc file is not in the ALWAYS_EXCLUDE list, which allows flexibility for npm configuration. The system uses Commander.js for CLI parsing and follows a consistent pattern of CLI flag → environment variable → sandbox injection.

## Approach

The implementation will follow the existing credential injection pattern used for ANTHROPIC_API_KEY and GITHUB_TOKEN. Add two new CLI options (`--npm-token` and `--npm-registry`) to the `sandbox-run` command, with fallback to environment variables. The npm token will be injected into the sandbox by creating a `~/.npmrc` file before npm install operations. This approach ensures tokens are never logged, maintains consistency with existing patterns, and supports both public and private npm registries including scoped packages. The implementation will be minimal and focused, touching only the three files mentioned in the issue.

## Implementation Steps

### 1. Add CLI Flags and Environment Variable Support

**File: `file:src/cli.ts`**

Locate the `sandbox-run` command definition (around line 1352) and add two new options after the existing options:

```
.option('--npm-token <token>', 'NPM authentication token for private packages (or set PARALLEL_CC_NPM_TOKEN env var)')
.option('--npm-registry <url>', 'Custom NPM registry URL (default: https://registry.npmjs.org)', 'https://registry.npmjs.org')
```

In the action handler (around line 1384), after the existing validation blocks and before Step 1, add npm token validation:

- Read npm token from `options.npmToken` or `process.env.PARALLEL_CC_NPM_TOKEN`
- If npm token is provided, validate it's a non-empty string
- Store the token and registry URL for later use
- Do NOT log the token value (only log "NPM token provided: yes/no")

### 2. Inject NPM Configuration into Sandbox

**File: `file:src/e2b/sandbox-manager.ts`**

Add a new method `configureNpmAuth` to the `SandboxManager` class (after the `extendTimeout` method around line 543):

**Method signature:**
```typescript
async configureNpmAuth(
  sandbox: Sandbox,
  npmToken: string,
  npmRegistry: string = 'https://registry.npmjs.org'
): Promise<boolean>
```

**Implementation logic:**
- Validate inputs (non-empty token, valid registry URL format)
- Create `.npmrc` content with authentication configuration:
  - For default registry: `//registry.npmjs.org/:_authToken=${npmToken}`
  - For custom registry: extract hostname from registry URL and use `//hostname/:_authToken=${npmToken}`
  - Add `registry=${npmRegistry}` line
  - For scoped packages, add `@scope:registry=${npmRegistry}` support
- Use `sandbox.files.write()` to create `/root/.npmrc` file with the configuration
- Use single quotes in shell commands to prevent token interpolation
- Log success/failure without exposing token value
- Return boolean indicating success

### 3. Integrate NPM Configuration into Sandbox Execution Flow

**File: `file:src/cli.ts`**

In the `sandbox-run` command action handler, after sandbox creation and upload (around line 1617, after "Workspace uploaded" message):

- Check if npm token was provided (from CLI flag or environment variable)
- If provided, call `sandboxManager.configureNpmAuth(sandbox, npmToken, npmRegistry)`
- Log the result: "✓ NPM authentication configured" or "⚠ NPM authentication failed"
- Continue with execution regardless of npm config result (non-blocking)

**File: `file:src/e2b/claude-runner.ts`**

No changes needed to this file. The .npmrc file created in the sandbox will be automatically used by npm/yarn/pnpm commands executed by Claude Code.

### 4. Security Considerations

**File: `file:src/e2b/file-sync.ts`**

No changes needed. The existing security patterns already handle .npmrc files appropriately:
- .npmrc is NOT in `ALWAYS_EXCLUDE` (lines 51-70), so local .npmrc files can be uploaded if present
- The `SENSITIVE_PATTERNS` array (lines 31-46) already includes TOKEN pattern which will flag .npmrc files during credential scanning
- The sandbox-injected .npmrc will not be downloaded back to local machine (only changed files are downloaded)

### 5. Documentation Updates

Add documentation for the new flags in the command description (in `file:src/cli.ts` around line 1354):

```
NPM Authentication:
  --npm-token <token>     NPM token for private packages (or PARALLEL_CC_NPM_TOKEN env var)
  --npm-registry <url>    Custom NPM registry (default: registry.npmjs.org)
```

Add example usage:

```bash
# Private npm packages
parallel-cc sandbox-run --repo . --prompt "Install deps" --npm-token "npm_xxx"

# Custom registry
parallel-cc sandbox-run --repo . --prompt "Task" \
  --npm-token "xxx" --npm-registry "https://npm.company.com"

# Using environment variable
export PARALLEL_CC_NPM_TOKEN="npm_xxx"
parallel-cc sandbox-run --repo . --prompt "Task"
```

## Implementation Flow Diagram

```mermaid
sequenceDiagram
    participant CLI as CLI (cli.ts)
    participant SM as SandboxManager
    participant E2B as E2B Sandbox
    participant NPM as NPM Registry

    CLI->>CLI: Parse --npm-token flag
    CLI->>CLI: Fallback to PARALLEL_CC_NPM_TOKEN
    CLI->>SM: createSandbox()
    SM->>E2B: Create sandbox
    CLI->>E2B: Upload workspace tarball
    
    alt NPM token provided
        CLI->>SM: configureNpmAuth(token, registry)
        SM->>SM: Validate token & registry
        SM->>SM: Build .npmrc content
        SM->>E2B: Write /root/.npmrc
        E2B-->>SM: Success
        SM-->>CLI: Configuration complete
    end
    
    CLI->>E2B: Execute Claude Code
    E2B->>NPM: npm install (uses .npmrc)
    NPM-->>E2B: Private packages installed
    E2B-->>CLI: Execution complete
    CLI->>E2B: Download changed files
    
    Note over E2B,CLI: .npmrc NOT downloaded (only changed files)
```

## Security Guarantees

| Aspect | Implementation |
|--------|----------------|
| Token Logging | Never log token value, only log "token provided: yes/no" |
| Token Storage | Token only exists in sandbox memory, never written to local disk |
| Token Exposure | Use single quotes in shell commands to prevent interpolation |
| Token Cleanup | .npmrc in sandbox is destroyed when sandbox terminates |
| Token Download | .npmrc is NOT downloaded back to local machine |
| Validation | Validate token is non-empty string before use |

## Testing Considerations

While not explicitly requested, implementers should verify:
- CLI flag parsing works correctly
- Environment variable fallback functions
- .npmrc file is created with correct format
- Private packages install successfully
- Custom registries work as expected
- Scoped packages (@org/package) authenticate correctly
- Token is never visible in logs or output

---

Execution Information

Branch: main
Commit: 136df60

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.