Private npm Access

Wavemap consumes @codon-ui/cli from npm as a private package. Each developer uses their own npm identity and their own granular read-only token. Repository files contain package-access policy and provider wiring, but never the token.

@gabrielbourget/i18n-foundation is public. Its registry proof deliberately runs without a credential so an accidental return to private access fails early.

Identity And Access First

Local bootstrap cannot grant npm access. A new developer and an npm administrator complete separate parts of onboarding:

1. The developer creates an npm account, enables two-factor authentication, and gives the administrator only their npm username.
2. The administrator invites that identity to the codon-ui organization and confirms that the automatic developers team has read-only access to the existing @codon-ui/cli package.
3. The developer accepts the invitation and creates their own granular token. The administrator does not create, receive, or distribute the token.

npm’s Member role can still create packages in an organization scope. Team access controls the existing package; it is not a scope-wide deny. Record that residual authority during private onboarding instead of treating read-only team access as a stronger npm guarantee.

Create The Developer Token

Run the non-mutating contract check before creating a token:

pnpm wavemap -- npm-auth bootstrap --check

The command prints the exact package versions discovered from the current workspace manifests and lockfile. Create one granular token on npmjs.com with:

• A person-and-purpose name such as Gabriel Bourget local private npm read.
• Read-only access to every package printed by the command.
• No npm organization permissions.
• No two-factor-authentication bypass.
• A 180-day lifetime, with reminders 30 days and 7 days before expiry.

Do not hard-code the current one-package set into onboarding. When working in both Wavemap and Waveguide, run bootstrap --check in both repositories and select the union of their printed private-package sets. They are the same today, but either repository can declare another private dependency later.

Bootstrap macOS Or Windows

From the Wavemap repository root, run:

pnpm wavemap -- npm-auth bootstrap

The public CLI dispatches to the reviewed adapter for the current operating system:

Platform	Native Store	Installed Provider
macOS	Keychain	~/.local/libexec/tendril-npm-token
Windows	Windows Credential Manager	%LOCALAPPDATA%\Tendril\npm-auth\tendril-npm-token.cmd

Both adapters use the native credential identity dev.tendril.npmjs-private-read. The masked native prompt captures the token without placing it in command arguments or environment variables. Bootstrap then registers the provider in the current user’s .npmrc and runs an exact-package preflight.

The provider writes the credential to pnpm only when the npm registry requests authentication. The npm token’s display name is human inventory metadata; code never looks it up by that name.

Why One Bootstrap Covers Both Products

Wavemap and Waveguide intentionally use the same native credential identity for the same operating-system user. After a successful bootstrap in either repository, both package managers resolve the same provider from the user .npmrc. Product-local policy and tests remain separate; only the developer-owned credential slot is shared.

Prove the sibling repository instead of bootstrapping it again:

pnpm waveguide -- npm-auth bootstrap --check
pnpm waveguide -- npm-auth preflight

Run those commands from the Waveguide repository. Another collaborator, another OS account, and CI each require their own credential; the shared slot is not a team credential.

Verify The Workstation

Use the lightweight preflight after membership, token, policy, or provider changes:

pnpm wavemap -- npm-auth preflight

Use the stronger proof after initial bootstrap or rotation:

pnpm wavemap -- npm-auth preflight --install

The install proof creates a committed-source snapshot, starts with an empty cache and store, disables dependency scripts, and runs a frozen install. That prevents a warm local cache or uncommitted manifest change from hiding a broken registry path.

To prove the Docker boundary without exporting images, use all targets or one named target:

pnpm wavemap -- npm-auth docker-proof
pnpm wavemap -- npm-auth docker-proof --target frontend-deploy

Accepted targets are backend-dev, frontend-dev, backend-deploy, and frontend-deploy. Only the frontend dependency graph consumes the private package, so backend builds receive no npm credential. Docker proof is deliberately expensive; use a named target after a localized failure instead of rebuilding targets that already passed.

Rotate Without Downtime

1. Run bootstrap --check in every consumer repository and create a replacement token for the complete union.

2. Keep the old token active.

3. Store the replacement through the masked prompt:

   pnpm wavemap -- npm-auth bootstrap --rotate

4. Run preflight --install in Wavemap and Waveguide.

5. Delete the old token on npmjs.com only after both proofs pass.

6. Run the lightweight preflight again after deletion.

Ordinary bootstrap preserves a readable existing credential. Use --rotate only when replacement is intentional.

Diagnose Failures By Boundary

Result	First Response
Native credential is missing or unreadable	Run bootstrap; use --rotate only when replacing the credential.
Authentication is rejected	Check token expiry or revocation, then rotate the developer-owned token.
Package access is denied	Review npm membership and the token’s selected package set; do not loop on token creation before checking access.
Locked version is not visible	Check membership, package selection, and whether the exact locked version was published.
npmjs.com cannot be reached	Resolve the network or registry outage before changing credentials.

Use the repository preflight for diagnosis. With the currently pinned pnpm release, pnpm view delegates to npm, which does not consume pnpm’s native token-helper contract and can produce misleading warnings or 404 output.

The enforcing sources are infra/operations/config/private-npm-access-policy.json, infra/operations/src/private-npm, bin/npm-auth, and the Wavemap CLI route tests. Update this page when that contract, the native provider identity, or the supported platforms change.

CI, Docker, trusted publication, offboarding, and incident ownership are documented in Private npm Supply Chain.