feat(sandbox): support & detect private-registry auth (protected ~/.npmrc)

[nhuelstng]

What

Give harnesses a supported, discoverable way to authenticate against a private package registry from inside the sandbox, and detect when a private-registry auth token is present but unreachable because the file that holds it is protected.

Today ~/.npmrc is a protected path (internal/sandboxprofile/baseline.go:51, protectedCommon()), classified as an "npm token" secret (internal/profileaudit/check.go:141). It is denied by default even under a broader home-dir grant. It is not hard-blocked — it is overridable via filesystem.override_deny (EffectiveProtectedPaths, baseline.go:188) — but nothing surfaces that escape hatch, and the failure it produces is silent.

Why

This is the filesystem/credential counterpart to #148 (which explains blocked registry fetches on the network axis). The two failures stack for the private-registry case:

1. feat(netproxy): explain blocked package-registry fetches #148 covers the network: the registry host is denied or unreachable (VPN down).
2. This issue covers auth: even when the host is reachable and allowed, npm/pip/cargo must read the auth token from ~/.npmrc (or ~/.pypirc, cargo credentials, …), and that read is denied by the protected-path policy. The install fails 401/403 at the registry, not at the proxy.

Related to #143 (harness fetching a config-declared plugin into a cold cache): a private-registry plugin can clear the network gate and still fail auth, with no legible cause.

The protection itself is correct — the token is a secret and must not leak to arbitrary sandboxed code. The gap is that there is (a) no documented, scoped way to opt a real private-registry workflow in, and (b) no signal that this is what went wrong.

Detection — can omac detect it?

Not at runtime via the proxy. For HTTPS the proxy splices a raw TCP tunnel and TLS bytes pass through unread (internal/netproxy/server.go:266, handleConnect). It is not a MITM, so it cannot observe the registry's 401/403 auth response or body. The #148 hints fire on the proxy's own deny (403 denyBody) or dial failure (502 upstreamErrorBody) — a registry-issued auth failure is invisible to it. So we cannot bolt private-registry-auth detection onto the #148 network path.

Yes, proactively at launch — this is the tractable path. Mirror #148's isPackageRegistry(host) host detector on the config file instead of the wire:

• At sandbox setup, if ~/.npmrc exists, is not listed in filesystem.override_deny, and contains a registry-scoped auth entry (_authToken, //<host>/:_authToken, _auth, _password) pointing at a non-public registry (reuse the private-registry heuristic from feat(netproxy): explain blocked package-registry fetches #148's isPackageRegistry), emit an actionable note:

  ~/.npmrc holds a private-registry token but is protected by the sandbox; private-package installs will fail auth. To allow it, add ~/.npmrc to filesystem.override_deny, or supply the token via NPM_TOKEN/NODE_AUTH_TOKEN through the env allowlist.

• Same shape generalizes to ~/.pypirc (check.go:147) and cargo credentials.

This is a static, read-side heuristic used only to enrich a likely-failing setup, so a false positive is harmless — same design principle #148 applied to its host matcher.

Proposed remedies to document/support

• Escape hatch (exists, undocumented): filesystem.override_deny: ["~/.npmrc"] punches the specific hole while keeping every other credential protected.
• Env-based token (preferred, no file grant): forward NPM_TOKEN/NODE_AUTH_TOKEN (and pip/cargo equivalents) via the env allowlist and let the harness synthesize a minimal .npmrc in the workdir — no home-dir secret exposure. Aligns with the env-forwarding pattern already used for provider creds.
• Document both in the sandbox profile reference alongside the protected-path list.

Scope

• Launch-time detector + hint for a protected-but-populated ~/.npmrc (npm first; pypirc/cargo as follow-ups).
• Reuse / share feat(netproxy): explain blocked package-registry fetches #148's private-registry heuristic so the file-side and host-side detectors agree on what "private registry" means.
• Docs: private-registry auth section — override_deny vs env-token, with the security tradeoff spelled out.

Non-goals

• Auto-granting ~/.npmrc (would defeat the secret protection).
• Runtime MITM of registry auth responses (proxy is a passthrough tunnel by design).

Related: #148 (network-axis registry hints), #143 (cold-cache plugin fetch).

[nhuelstng]

Design detail: proactive launch-time detection

Reacting to the auth failure is impossible for HTTPS — the proxy splices TLS blind (internal/netproxy/server.go:266). So detection must predict the failure before the sandbox starts. The predicate is a pure read-side check, all three facts knowable at launch:

~/.npmrc exists
  ∧ it contains a private-registry auth entry
  ∧ ~/.npmrc is NOT in filesystem.override_deny
  ⟹ warn: "token present but protected; private installs will 401"

Where it lives — and the design tension

Two existing homes, not interchangeable:

• profileaudit.Check() (internal/profileaudit/) has the right vocabulary — Finding{Severity,Category,Field,Value,Message}, a curated secret list (knownsecrets.go), a CatOverrideDeny category. But it is deliberately config-only: it lints the resolved profile and never touches the filesystem (no stat, no $HOME). That purity keeps it deterministic and testable without a home dir. Parsing ~/.npmrc there breaks the contract.
• The launch path (internal/sandboxrun/run.go:78, diag.Logf) runs on every invocation and legitimately touches the real FS while resolving grants. Natural home for "token present but protected," since the whole point is correlating profile config with on-disk state.

Clean split: keep profileaudit config-only; put the FS-aware detection in a small helper on the launch/grant-resolution path, emitting via diag.Logf. If it's also wanted in provenance --check, expose it as a separate opt-in FS-aware pass, not folded into Check().

Detection logic

1. Locate — ~/.npmrc first; ~/.pypirc (already in ExtensionSecretPaths) and cargo credentials as follow-ups.
2. Parse — .npmrc is INI-ish key=value; match auth keys _authToken, //<host>/:_authToken, _auth, _password, scoped @scope:registry=. Extract host from //<host>/:... lines.
3. Classify host as private — reuse feat(netproxy): explain blocked package-registry fetches #148's isPackageRegistry heuristic; the strong signal is a token scoped to a non-public host (registry.<corp> shape, not registry.npmjs.org). Sharing the predicate keeps file-side and host-side detectors agreeing on "private."
4. Check the escape hatch — is ~/.npmrc in profile.Filesystem.OverrideDeny? Reuse sandboxprofile.BuildOverrideLookup / the same expansion EffectiveProtectedPaths uses so ~/$VAR forms match. If overridden → stay silent (already opted in).
5. Emit — one line naming the file, the registry host, and the two remedies (filesystem.override_deny: ["~/.npmrc"] or NPM_TOKEN/NODE_AUTH_TOKEN via the env allowlist).

Why it's safe (the #148 principle)

Read-only enrichment of a setup already heading for a silent 401 — never grants or mutates policy.

• False positive (token present, no private install intended): one extra advisory line. Harmless — same rationale feat(netproxy): explain blocked package-registry fetches #148 gives for its host matcher.
• False negative (unparsed exotic layout): no worse than today's silent failure.
• Reads ~/.npmrc from the host setup process (which can already see it) and prints only host + knob — never the token value. No secret crosses into the sandbox.

Limits

• Predicts the ingredients of failure, not a verdict — a hint, not proof.
• Doesn't cover a token injected purely via env with no .npmrc on disk — but that path already works.
• Launch-time only; won't catch a .npmrc written mid-run. Acceptable — the grant set is fixed at launch.

[Retr0MrWave]

Field case for this issue — with a failure mode the proposed detector would miss.

Confirmed the impact is real (repro in #155/#241: a config-declared opencode plugin from an internal registry never installs under omac). But the shape differs from what this issue assumes, in a way that changes both the detector and the remedy.

This issue keys on auth. The proposed detector fires when ~/.npmrc "contains a registry-scoped auth entry (_authToken, //<host>/:_authToken, _auth, _password)", and the failure is described as "401/403 at the registry".

The observed failure has no token and no 401. The whole npmrc is one line, no credentials:

@tngtech:registry=https://tng-artifacts.int.tngtech.com

With that file masked, npm doesn't fail auth against the right registry — it asks the wrong registry and gets a truthful 404:

$ omac sandbox run -- npm view @tngtech/opencode-skainet version
npm error 404 Not Found - GET https://registry.npmjs.org/@tngtech%2fopencode-skainet

So a scope→registry mapping is load-bearing config, independent of credentials:

• Detection: an _authToken-keyed heuristic returns nothing for this file. The detector should also fire on @scope:registry= / registry= lines pointing at a non-public host, with no auth entry present. That's the more common corporate shape (anonymous read on an internal mirror), and it fails more silently — 404 looks like "package doesn't exist", not "you're not authenticated".
• Remedy: the preferred fix here — forward NPM_TOKEN/NODE_AUTH_TOKEN through the env allowlist — doesn't apply. There is no token to forward; what's missing is a URL. Candidate alternatives worth evaluating: (a) a scrubbed npmrc projection — omac generates a copy containing only registry= / @scope:registry= lines with every _auth*/_password/certfile stripped, and points NPM_CONFIG_USERCONFIG at it (keeps the secret protected, restores the mapping, no user action); (b) npm_config_@scope:registry via the env allowlist (untested — unclear whether opencode's bundled Bun installer honors it).
• filesystem.override_deny: ["~/.npmrc"] does work today — verified A/B in Generic per-harness cache pre-warm before sandboxing (first-launch plugin/dep fetch fails through omac's proxy; opencode is the first concrete case) #155 — but it grants the whole file, including any token, which is exactly what this issue is trying to avoid. Fine as a documented escape hatch, wrong as the default answer.

Suggest widening the scope checklist:

• Detector also matches mapping-only npmrc (@scope:registry=/registry= → non-public host) with no auth entry.
• Evaluate a scrubbed-npmrc projection (NPM_CONFIG_USERCONFIG) as the no-secret-exposure remedy for the mapping case.
• Distinguish the two symptoms in the hint text: 404-wrong-registry vs 401-no-auth. They read completely differently to a user.

Refs #155, #241.

[Retr0MrWave]

Correcting three things I proposed earlier in this thread, after
implementing it in #259.

The detector predicate I suggested would have missed the case. I proposed
reusing #148's isPackageRegistry so the file-side and host-side detectors
agree. Verified against the real host before building on it:

tng-artifacts.int.tngtech.com    isPackageRegistry=false
registry.npmjs.org               isPackageRegistry=true
npm.acme.test                    isPackageRegistry=true
artifacts.corp.example           isPackageRegistry=false

It answers a different question — "does this host look like a registry?" —
and returns false for exactly the corporate shape this issue exists for (no
registry/npm label, no ecosystem fragment). #259 uses "the mapping points
somewhere other than npm's default registry" instead.

The preferred remedy does not apply to this shape. Forwarding
NPM_TOKEN/NODE_AUTH_TOKEN through the env allowlist assumes the missing
thing is a credential. In the observed npmrc there is no token at all — just
@tngtech:registry=https://tng-artifacts.int.tngtech.com. There is nothing
to forward; what is missing is a URL mapping, which only a file (or an
npm_config_@scope:registry env var, untested) can supply. #259 projects a
credential-stripped copy and points NPM_CONFIG_USERCONFIG at it.

The 404-vs-401 hint split is dropped. registryDenyHint returns early
when isPackageRegistry is false, so a note there could never fire for the
host in question; and as this issue already notes, the proxy splices a raw
CONNECT tunnel and cannot observe either status code. Adding the text would
have been dead code. The proactive omac doctor check covers the detection
need instead.

Two design points worth recording, both found in review of #259 and fixed
there, because they constrain any future ecosystem (.pypirc, cargo):

• Stripping only URL userinfo is not sufficient to make "no credential can
  survive" true. @acme:registry=https://npm.acme.test/api/?apiKey=SECRET
  was projected verbatim. A query string or fragment must be refused, not
  stripped — omac cannot distinguish a secret parameter from a load-bearing
  one.
• Projecting the global registry key when the file holds a credential
  for that host is a regression, not a fix: it redirects all resolution to a
  registry omac cannot authenticate to, so public installs that work today
  (with the file masked, npm falls back to registry.npmjs.org) start failing.
  feat(sandbox,cli): project a credential-free registry config into the sandbox #259 refuses that case and keeps scoped mappings, which were already
  failing, with a 401/403 warning.