flog
Documentation menu

Registry and authentication client

Flog's internal registry client is shared by installation and publishing. It uses HTTP directly and never shells out to another package manager.

Configuration#

The client defaults to https://registry.npmjs.org/ and supports compatible .npmrc settings for:

  • registry;
  • @scope:registry;
  • _authToken;
  • //host/path/:_authToken;
  • ${ENVIRONMENT_VARIABLE} substitutions; and
  • NPM_CONFIG_USERCONFIG and NPM_CONFIG_REGISTRY environment overrides.

Registry selection precedence is the npm default, the user npmrc, the nearest project npmrc, NPM_CONFIG_REGISTRY, and finally an auth command's explicit --registry. NPM_CONFIG_USERCONFIG selects the user file; otherwise flog uses the platform user's .npmrc. Project configuration can explicitly override user registry or credential settings. Authentication is matched by host and the longest configured path prefix, preventing a token for one registry from being sent to another.

Bearer tokens are never included in request errors. Configuration and OTP values are redacted from diagnostics. Request errors omit URL user information, query strings, and fragments; web-auth completion URLs are never displayed. The login URL itself is intentionally displayed so the operator can complete authentication.

Login, identity, and logout#

Use the npm-compatible web authentication flow proactively:

flog login
flog whoami
flog logout

Each command accepts --registry <url>. login prints the safe browser URL, polls cancellably, validates the returned token through /-/whoami, and only then stores it. whoami always asks the registry to verify the selected credential; it does not merely report that configuration exists. logout removes only the exact selected host/path credential.

Login writes a host/path-scoped //host/path/:_authToken entry to the user npmrc, never the project npmrc. It preserves unrelated bytes, comments, ordering, and newline style, writes through a restrictive atomic replacement, and refuses unsafe files, duplicate matching entries, or an environment-backed matching token that cannot safely be replaced. Login also refuses to guess how an unscoped _authToken should be migrated. Symlinks in either the npmrc itself or any existing parent directory are rejected before reading or staging a credential. Non-canonical userconfig paths containing lexical . or .. traversal are also rejected so configuration reads and credential writes cannot resolve the selected path differently. Logout applies the same checks. Cancellation, denial, timeout, validation failure, and file errors leave the original npmrc unchanged.

Because project credentials take precedence over user credentials, login refuses to authenticate when the nearest project npmrc contains an exact or more-specific credential for the selected registry. Remove or update that project entry first, or run login outside the project. Flog never silently rewrites the project npmrc. Since browser authentication can take time, flog rechecks the project file after authentication and again around the user-file commit; a credential added while login is in progress prevents a successful login report.

Login also refuses a more-specific user credential below the selected registry path. Such an entry would continue to win longest-prefix selection for some requests (including nested registry endpoints), so the diagnostic identifies the scoped entry that must be removed or updated. Unrelated hosts and sibling paths remain untouched.

HTTP authentication is rejected by default. FLOG_ALLOW_HTTP=1 exists only for isolated local testing and must not be used for real credentials.

For CI, continue supplying a host/path-scoped npmrc token, commonly through a ${TOKEN} environment substitution. login is an interactive bootstrap flow and does not overwrite environment variables. Revoking a token at the registry is separate from flog logout, which only removes the local entry.

Redirects are handled explicitly rather than delegated to Go's default client. Every metadata, tarball, and polling redirect re-runs host/path credential selection for its destination, and HTTPS-to-HTTP downgrades are rejected. State-changing requests such as publication and login are never replayed across redirects, preventing bearer tokens, OTP values, or upload bodies from being silently forwarded to a different endpoint.

Reads and publishing#

Dependency resolution requests npm's abbreviated install metadata media type. flog view requests the full application/json representation so published fields omitted from install metadata remain queryable. Tarball reads support SHA-512/SHA-1 Subresource Integrity values and legacy hexadecimal SHA-1 shasums, using constant-time digest comparison. A mismatch is a typed integrity error and downloaded bytes are not returned.

Publication sends the caller's complete npm publication document with PUT. The document is retained for safe replay only when web authentication succeeds; publishing therefore consumes the exact artifact metadata prepared by the publisher rather than repacking.

Transport failures and HTTP registry rejections have separate error types and retryability decisions. OTP challenges return a typed error so callers can prompt securely and resubmit using the npm-otp header.

Querying published metadata#

flog view reads one top-level scalar field from a selected published version:

flog view package-name version
flog view @scope/package@next version
flog view package-name@1.2.3 version --json

An omitted selector uses the latest dist-tag. Explicit selectors may be exact versions or dist-tags; version ranges are intentionally rejected because a read-only metadata query should not imply dependency resolution. Plain output is exactly one string, number, boolean, or null followed by a newline. --json emits that same scalar as JSON, for example "1.2.3".

Fields are literal top-level keys in the selected version document. Nested paths and expression syntax are not supported. Missing packages, tags, versions, and fields are reported separately, as are malformed documents, authentication rejections, and transport failures. The command uses the normal registry and credential selection above, but never writes a manifest, flog.lock, cache, installation, credential, or registry resource.

Web authentication#

Flog supports npm's /-/v1/login flow and registry-requested authUrl / doneUrl challenges. It can print the login URL, invoke an optional browser opener, and invoke an optional QR renderer. Polling handles pending, success, denial, and timeout responses.

Every request and polling delay observes the caller's context. Cancellation stops immediately and the original publication request is never replayed after an interrupted authentication flow. The client does not place the terminal in a special mode, so no terminal state needs to be recovered after Ctrl+C.