Using valid env vars names for .npmrc

[theoephraim]

First off, thanks for the env-variables-in-repository-npmrc post and for closing the ${ENV}-in-repo-file exfiltration hole. Locking expansion to trusted sources is the right call. This is a follow-up on the part you flagged as open to suggestions: the suggested env-var form doesn't work in most places people actually inject secrets.

The problem with the current advice

The canonical config key lives in the variable name:

pnpm_config_//registry.npmjs.org/:_authToken=<token>

The name contains /, :, and ., so as the post notes, export and NAME=value reject it and you need env "...=...". But env-prefixing only helps in an interactive or scripted shell. It does nothing for the places that inject secrets by name, which is most of CI/CD:

• GitHub Actions / GitLab CI secret stores
• Docker ENV / --env, Compose, Kubernetes Secrets
• systemd Environment=
• .env files and secret managers

All of those require a POSIX-valid identifier: [A-Za-z_][A-Za-z0-9_]*. So the current guidance quietly excludes declarative injection entirely.

Root cause

The pain comes from putting the registry URL (which carries / : . @) into the variable name. Any fix that keeps the key in the name forces an ugly, lossy escaping scheme (base64, :-to-__, etc.).

The key is data. Put it in the value, and the name becomes a fixed, identifier-safe label.

Proposal: coupled records in the value

Primary form: one npmrc line per variable

PNPM_CONFIG_NPMRC_0=//registry.npmjs.org/:_authToken=<token>
PNPM_CONFIG_NPMRC_1=//npm.myco.com/:_authToken=<other-token>
PNPM_CONFIG_NPMRC_2=@myorg:registry=https://npm.myco.com/

Parse rule: collect every PNPM_CONFIG_NPMRC_<suffix> variable, treat each value as a line of npmrc, and merge them using the existing parser.

Why this shape:

• Valid names everywhere. The illegal characters only ever appear in the value, which has no charset restriction. Works in every injector above.
• Binding stays coupled. Each credential line fuses the URL and the secret in one value, so nobody can re-aim the URL independently of the token. This is npmrc's own native granularity, one coupled credential per line.
• Composes across sources. Different registries can come from different secrets, each as its own variable, with no need to concatenate them.
• Trusted by construction. The value is the same content you already trust in ~/.npmrc, delivered inline. There is no file path that a cloned repo could point back at itself, which is the lingering weakness of the PNPM_CONFIG_NPMRC_AUTH_FILE=.npmrc last resort.

Convenience form: one variable, whole npmrc

For "one secret store hands me everything":

PNPM_CONFIG_NPMRC=$'//registry.npmjs.org/:_authToken=<token>\n@myorg:registry=https://npm.myco.com/'

JSON could be auto-detected as an alternative encoding to avoid multiline quoting in environments like Docker ENV that mangle newlines. The two forms should merge, so you can mix "all at once" and per-line shards.

Details that matter

• Opaque suffix, not a contiguous counter. Collect all matching variables; never scan 0..N and stop at the first gap, or a credential silently vanishes and fails in confusing ways. Allowing non-numeric suffixes (_NPMJS, _MYCO) sidesteps numbering entirely.
• Deterministic merge order. Parse shards in sorted-suffix order and stack them like layered npmrc files (last wins).
• No recursive expansion. Parse each value literally. Never run ${ENV} expansion on it, or the original hole reopens via nesting.
• Redaction. Because these are known, prefixed variable names, log scrubbers can redact their values wholesale.

Alternative: grouped field variables

If individual fields are preferred over npmrc-line values, a grouped form also works:

PNPM_CONFIG_REGISTRY_NPMJS_URL=//registry.npmjs.org/
PNPM_CONFIG_REGISTRY_NPMJS_AUTHTOKEN=<token>
PNPM_CONFIG_REGISTRY_MYCO_URL=//npm.myco.com/
PNPM_CONFIG_REGISTRY_MYCO_USERNAME=ci
PNPM_CONFIG_REGISTRY_MYCO_PASSWORD=<secret>

The handle (NPMJS, MYCO) is arbitrary and identifier-safe. This reads nicely and maps onto secret stores that emit one secret per variable. Two caveats worth knowing:

1. It splits the URL-to-credential binding across variables, so anyone who can set one member can re-aim the others, and a partially specified group (token set, URL missing) can misdirect a token to the default registry. Mitigate by treating each group as atomic and rejecting groups with a missing URL.
2. @scope:registry is a second keyspace (npm scope to URL, not a credential), so a group needs an extra scope field and multi-scope handling.

Because of (1), I'd lead with the coupled value form and offer grouped fields as a secondary option for people who want individual fields.

Where varlock fits

Whatever shape you pick, in some scenarios the sensitive token may still be sitting in a plaintext file, vulnerable to supply chain attacks. varlock is built for exactly this last mile, keeping it out of plaintext (either behind encryption or using plugins to load from external vaults) and injecting it securely. It also adds log redaction and extra guardrails, and can help with the expansion/composition into the format pnpm expects. For example, a .env.schema which sets the necessary vars:

# @sensitive
NPM_TOKEN=somePlugin(...) # loading declaratively, not plaintext
# @sensitive
PNPM_CONFIG_NPMRC_0=`//registry.npmjs.org/:_authToken=${NPM_TOKEN}`

We could make some changes to make it possible to inject into the environment as is it currently supported, but I think it's better to migrate to supporting standard env vars.

Happy to open a PR sketching the parser changes for the per-line form if there's interest.