Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/_components/VersionSpecifierTable.mdx
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
| Form | Example | Resolution |
|------|---------|------------|
| Latest release | `latest` | Newest available release from the mirror index. |
| Latest stable | `latest` | Newest **stable** (non-prerelease) release from the mirror index. Skips tags that contain `-` (for example alphas). |
| Latest alpha | `alpha` | Newest release whose version contains `-alpha`. Keeps the full prerelease tag for download. |
| Latest LTS | `lts` | Newest available LTS release. |
| Named LTS line | `lts/iron` | Newest release from the named LTS line. |
| User alias | `legacy` | Version assigned with [`nvm alias add`](../command/nvm/alias/add). |
| Major only | `24` | Newest matching `24.x.x` release. |
| Major.minor | `24.1` | Newest matching `24.1.x` release. |
| Exact version | `24.1.0`, `v24.1.0` | The specified release. The `v` prefix is optional. |
| Exact version | `24.1.0`, `v24.1.0`, `27.0.0-alpha.0.0.0` | The specified release. The `v` prefix is optional. Prerelease suffixes are preserved. |
36 changes: 36 additions & 0 deletions docs/_data/siemQueries.js
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,42 @@ export const siemQueries = {
| STATS People = COUNT_DISTINCT(winlog.computer_name)`,
wevtutil: `wevtutil qe "${CHANNEL}" /q:"*[System[(EventID=120)] and EventData[Data[@Name='EventName']='nvm.system.changed']]" /f:text /c:20`,
},
unstableInstalled: {
wevtutilListsOnly: true,
sentinel: `Event
| where EventLog == "${CHANNEL}"
| where EventID == 120
| where EventData.EventName == "nvm.system.changed"
| extend Payload = parse_json(tostring(EventData.Payload))
| where Payload.Action == "install"
| where Payload.Outcome == "Succeeded"
| where tostring(Payload.ReleaseType) == "unstable"
| summarize Hosts = dcount(tostring(Payload.hostname)) by tostring(Payload.NodeVersion), tostring(Payload.hostname)`,
splunk: `index=wineventlog Channel="${CHANNEL}" EventCode=120 EventData.EventName="nvm.system.changed"
| eval action=json_extract('EventData.Payload',"Action"), outcome=json_extract('EventData.Payload',"Outcome"), release_type=json_extract('EventData.Payload',"ReleaseType"), node_version=json_extract('EventData.Payload',"NodeVersion"), hostname=json_extract('EventData.Payload',"hostname")
| search action=install outcome=Succeeded release_type=unstable
| stats dc(hostname) as Hosts by node_version, hostname`,
elastic: `FROM logs-*
| WHERE winlog.channel == "${CHANNEL}" AND winlog.event_id == 120 AND winlog.event_data.EventName == "nvm.system.changed" AND winlog.event_data.Payload LIKE "*\\"Action\\":\\"install\\"*" AND winlog.event_data.Payload LIKE "*\\"Outcome\\":\\"Succeeded\\"*" AND winlog.event_data.Payload LIKE "*\\"ReleaseType\\":\\"unstable\\"*"
| STATS Hosts = COUNT_DISTINCT(winlog.computer_name)`,
wevtutil: `wevtutil qe "${CHANNEL}" /q:"*[System[(EventID=120)] and EventData[Data[@Name='EventName']='nvm.system.changed']]" /f:text /c:20`,
},
legacyLatestHosts: {
wevtutilListsOnly: true,
sentinel: `Event
| where EventLog == "${CHANNEL}"
| where EventID == 120
| where EventData.EventName == "nvm.resolution.legacy_latest"
| extend Payload = parse_json(tostring(EventData.Payload))
| summarize Events = count() by tostring(Payload.hostname), tostring(Payload.ResolvedVersion)`,
splunk: `index=wineventlog Channel="${CHANNEL}" EventCode=120 EventData.EventName="nvm.resolution.legacy_latest"
| eval hostname=json_extract('EventData.Payload',"hostname"), resolved=json_extract('EventData.Payload',"ResolvedVersion")
| stats count as Events by hostname, resolved`,
elastic: `FROM logs-*
| WHERE winlog.channel == "${CHANNEL}" AND winlog.event_id == 120 AND winlog.event_data.EventName == "nvm.resolution.legacy_latest"
| STATS Events = COUNT(*) BY host = winlog.computer_name`,
wevtutil: `wevtutil qe "${CHANNEL}" /q:"*[System[(EventID=120)] and EventData[Data[@Name='EventName']='nvm.resolution.legacy_latest']]" /f:text /c:20`,
},
uninstalledVersions: {
wevtutilListsOnly: true,
sentinel: `Event
Expand Down
3 changes: 2 additions & 1 deletion docs/cfg/aliases.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,8 @@ next -> v24.11.0
| Name | Why |
|:-|:-|
| `default`, `current`, `latest`, `lts`, `last` | Built-in command semantics |
| `daily`, `alpha`, `beta`, `prerelease` | Reserved for future use |
| `alpha` | Built-in: newest `-alpha*` catalog release |
| `daily`, `beta`, `prerelease` | Reserved for future use |
| `link`, `shim` | Operating mode names |
| `lts/*` (for example `lts/iron`) | Reserved LTS namespace |

Expand Down
5 changes: 3 additions & 2 deletions docs/cfg/enterprise/registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,9 @@ These keys appear in the **Governance** ADMX pack. The Policies hive (including
|**Approved modules (local installs)**|`ApprovedModules`|**Certified Builds.** Shim mode. Allow list for local package-manager installs (npm/pnpm/yarn/npx). Empty defaults to `ALL`. Supports name, `@org/*`, version pins/ranges, `NOT`/`!` negation, or a single `https://` policy URL. See [NVM Firewall](/features/firewall).<br /><br />`REG_MULTI_SZ`|
|**Approved global modules**|`ApprovedGlobalModules`|**Certified Builds.** Shim mode. Allow list for global package-manager installs. Empty defaults to `ALL`. Same rule syntax as `ApprovedModules`.<br /><br />`REG_MULTI_SZ`|
|**Untrusted module change action**|`UntrustedModuleHandlerAction`|Shim mode. When a global module changes and is not on `TrustedModules`:<br /><br />- `deny` (default) — skip reshim<br />- `prompt` — console or Trust/Cancel toast<br />- `allow` — auto-reshim with a quiet toast<br /><br />`REG_SZ`|
|**Allowed Node.js versions**|`VersionAllowList`|**Governance.** Allow list for `nvm install`, `nvm use`, and the shim. Ignored without a Governance license. Invalid entries fail enforcement. Allow wins over block when both lists come from the same source. The shim loads allow and block as a pair from HKLM Policies when Governance is active. Also feeds Author-mirror JWT version claims (magic tokens such as `EOL`, `ALPHA`, `MAINTENANCE`, `ALL`). Those magic tokens are ignored locally at install, use, and shim launch.<br /><br />Supports exact semver, wildcards (e.g. `20.x`), aliases, and `NOT`/`!` negation (one rule per line).<br /><br />`REG_SZ`|
|**Blocked Node.js versions**|`VersionBlockList`|**Governance.** Block list for `nvm install`, `nvm use`, and the shim. Same rule formats and pairing as `VersionAllowList`. Ignored without Governance.<br /><br />`REG_SZ`|
|**Allowed Node.js versions**|`VersionAllowList`|**Governance.** Allow list for `nvm install`, `nvm use`, and the shim. Ignored without a Governance license. Invalid entries fail enforcement. Allow wins over block when both lists come from the same source. The shim loads allow and block as a pair from HKLM Policies when Governance is active. Also feeds Author-mirror JWT version claims (`EOL`, `ALPHA`, `MAINTENANCE`, `ALL`). **`ALPHA` is enforced locally** against versions containing `-alpha`. **`EOL` and `MAINTENANCE` remain mirror-only** (ignored by local gates).<br /><br />Supports exact semver, wildcards (e.g. `20.x`), aliases, and `NOT`/`!` negation (one rule per line).<br /><br />`REG_SZ`|
|**Blocked Node.js versions**|`VersionBlockList`|**Governance.** Block list for `nvm install`, `nvm use`, and the shim. Same rule formats and pairing as `VersionAllowList`. Ignored without Governance. `ALPHA` blocks local alpha installs (for example `nvm install alpha`).<br /><br />`REG_SZ`|
|**Legacy tip-of-index latest**|`LatestIncludesPrerelease`|**Governance.** When `1`, the reserved `latest` alias resolves to the absolute tip of the Node.js index (including prereleases). Default `0` = newest stable only. Machine policy only. Emits `nvm.resolution.legacy_latest` when used. See [Legacy latest policy](/guide/legacy-latest-policy).<br /><br />- `0` = stable `latest` (default)<br />- `1` = tip-of-index (legacy)<br /><br />`REG_DWORD`|

:::info[License secrets]
`AccessToken`, `AccessKey`, and `JwksCose` are **not** ADMX policies. Deploy with portal scripts (`Set-NvmWindowsAccessToken.ps1` on stock certified build; `Set-NvmWindowsLicensing.ps1` for governance builds, which also sets `AccessKey` for Author mirrors) or `nvm license`.
Expand Down
9 changes: 6 additions & 3 deletions docs/command/nvm/install/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ Install one or more versions of Node.js.
## Usage

```powershell
nvm install <version> [<version> ...] [flags]
nvm install [<version> ...] [flags]
```

Default subcommand when you pass version arguments directly (for example `nvm install 24`).
Default subcommand when you pass version arguments directly (for example `nvm install 24`). With no version, installs `latest` (newest stable release) — same as `nvm install latest`.

## Subcommands

Expand All @@ -28,7 +28,7 @@ Default subcommand when you pass version arguments directly (for example `nvm in

| Argument | Required | Description |
|----------|----------|-------------|
| `<version> ...` | Yes | One or more [version specifiers](../../../guide/version-resolution). |
| `<version> ...` | No | One or more [version specifiers](../../../guide/version-resolution). Omit to install `latest` (stable). |

## Flags

Expand All @@ -46,7 +46,10 @@ Internal flags (`--notify`, `--debug`) exist for automation and are hidden from
## Examples

```powershell
nvm install
nvm install latest
nvm install lts
nvm install alpha
nvm install 24
nvm install 22.14.0 20.19.1
nvm install lts/iron
Expand Down
2 changes: 1 addition & 1 deletion docs/features/all-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ See [What's new in v2](./newv2) for a shorter v2 summary.
| Community feature mode | A Certified Build without a commercial license keeps running with Community features. |
| License | Hidden `nvm license` writes HKLM. Certified Builds, Advanced Logging, and Governance need a sitewide license. |
| License expiry notifications | Certified Builds warn at 7, 3, and 1 day, on the expiry day, and daily in the 7-day grace window. |
| [Author Mirror](./author-mirror) | Governance host `https://mirror.author.io/runtime/nodejs`. JWT version lists. EOL/ALPHA/MAINTENANCE need this host. |
| [Author Mirror](./author-mirror) | Governance host `https://mirror.author.io/runtime/nodejs`. JWT version lists. `ALPHA` is also enforced locally; `EOL`/`MAINTENANCE` need this host. |
| [Basic HTTP proxy](./http-proxy) | Proxy URL, `user:pass`, or Bearer. WinINET fallback. Community Builds and Certified Builds. |
| [Advanced proxy](./http-proxy#capabilities-by-license) | IWA (NTLM/Negotiate) and PAC/WPAD. [Governance](./certified-builds/governance) add-on. |
| Administrative templates | ADMX/ADML lock or override preferences. See [Administrative Templates](../cfg/ad) and [Governance](./certified-builds/governance). |
Expand Down
2 changes: 1 addition & 1 deletion docs/features/author-mirror.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ There are two (combinable) ways to enforce dynamic policies on the Author mirror
`VersionAllowList` / `VersionBlockList` (see [Governance registry keys](/cfg/registry#governance-keys)) do double duty:

- **Static entries** — enforced by [NVM Firewall](./firewall) before any download.
- **Dynamic aliases** (`EOL`, `ALPHA`, `MAINTENANCE`) — ignored on the client; included in the short-lived license JWT sent only to `mirror.author.io`. The mirror applies those lifecycle rules when serving the archive.
- **Dynamic aliases** — `ALPHA` is enforced locally against versions containing `-alpha` and is also included in the short-lived license JWT sent to `mirror.author.io`. `EOL` and `MAINTENANCE` are ignored on the client; the mirror applies those lifecycle rules when serving the archive.

| Policy entry | Local client | Author mirror (`mirror.author.io`) | Public mirror (`nodejs.org`) |
|:-|:-|:-|:-|
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/builds/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ The Governance package for Certified Builds introduce policy management. With th
- Freeze V8 intrinsics (`--frozen-intrinsics`) to prevent prototype pollution of built-ins (also applied to npm/npx/pnpm scripts when the policy is on).
- Disallow `eval()` / `new Function()` (`--disallow-code-generation-from-strings`) (also applied to npm/npx/pnpm scripts when the policy is on).
- Limit to local installations (airgapping).
- Restrict version installations with the version firewall. Lifecycle aliases such as `EOL` and `ALPHA` apply on the Author Mirror, not the client.
- Restrict version installations with the version firewall. `ALPHA` is enforced locally; `EOL` and `MAINTENANCE` apply on the Author Mirror.

Governance builds ship with ADMX/ADML files and official scripts to support Microsoft Active Directory group policies, Microsoft Entra, and other device management platforms.

Expand Down
68 changes: 68 additions & 0 deletions docs/guide/legacy-latest-policy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
title: Legacy latest policy
sidebar_label: Legacy latest policy
sidebar_position: 2.5
---

# Legacy latest policy

On Certified Builds with a **Governance** license, administrators can restore the older tip-of-index meaning of the reserved `latest` alias without changing scripts.

By default in v2, `nvm install latest` and `nvm use latest` resolve to the newest **stable** (non-prerelease) Node.js release. That avoids installing alphas that temporarily lead [nodejs.org/dist/index.tab](https://nodejs.org/dist/index.tab).

Some fleets still have automation that expects `latest` to mean “whatever sits at the tip of the catalog,” including prereleases. The Governance policy below keeps those scripts working while logging hosts that still rely on that behavior.

## Policy

| Item | Value |
|------|--------|
| Registry | `HKLM\SOFTWARE\Policies\Author Software\nvm\LatestIncludesPrerelease` |
| Type | `REG_DWORD` |
| Default | `0` (stable `latest`) |
| Enabled | `1` (tip-of-index, including prereleases) |
| Scope | Machine policy only (no HKCU preference) |
| License | Governance |

Deploy with the Governance ADMX (**Use legacy tip-of-index for latest**) or Intune/Registry CSP.

Community Builds ignore this key. Without Governance, the key has no effect.

## Behavior when enabled

1. `latest` resolves to the first non-empty row of the Node.js index, **keeping** any prerelease suffix (for example `27.0.0-alpha.0.0.0`).
2. Scripts keep the same command shape: `nvm install latest`.
3. NVM writes a structured warning: EventName `nvm.resolution.legacy_latest`.
4. Successful installs driven by `latest` under this policy also set `LatestMode=legacy` on `nvm.system.changed`.

Prefer migrating callers to:

```powershell
nvm install alpha
# or
nvm install 26.13.0
```

`alpha` is the explicit reserved alias for the newest `-alpha*` release.

## Interaction with the version firewall

`LatestIncludesPrerelease` does **not** bypass Governance version lists.

If `VersionBlockList` contains `ALPHA`, an install of an alpha (including one reached via legacy `latest`) is still denied locally (**NVM4411**).

See [Version Firewall + Author Mirror](../features/author-mirror) and [Registry Policy Reference](../cfg/enterprise/registry).

## SIEM

Use the SIEM guide queries for:

- Hosts that resolved `latest` under legacy mode (`nvm.resolution.legacy_latest`)
- Installs with `ReleaseType=unstable` or `LatestMode=legacy`

See [SIEM Integration](./siem).

## Related

- [Version Resolution](./version-resolution) — `latest` vs `alpha`
- [Upgrading from v1](./upgrade-from-v1)
- [Registry Policy Reference](../cfg/enterprise/registry)
2 changes: 1 addition & 1 deletion docs/guide/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ The **Governance** pack ships **ADMX/ADML** templates for Active Directory and E

Organizations can deny public `nodejs.org/dist` at the network edge and allow-list `mirror.author.io`. NVM then downloads through Author’s policy-aware mirror. Controls combine:

- Client/GPO lists (`VersionAllowList` / `VersionBlockList`) for exact versions and ranges — lifecycle aliases such as `EOL` / `ALPHA` / `MAINTENANCE` are **ignored on the client** and only applied by the Author Mirror at download
- Client/GPO lists (`VersionAllowList` / `VersionBlockList`) for exact versions and ranges — `ALPHA` is enforced locally against `-alpha*` versions; `EOL` / `MAINTENANCE` are **ignored on the client** and only applied by the Author Mirror at download
- **Hosted rules** in the [customer portal](https://portal.author.io) (IP, geo, domain/tenant, SID, license group)

Walkthrough: [Version Firewall + Author Mirror](../features/author-mirror). Domain/tenant IDs: [Find Your AD Domain or Entra Tenant ID](./find-domain-tenant-id).
Expand Down
15 changes: 14 additions & 1 deletion docs/guide/siem.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,13 +81,25 @@ Host count for the same event:

<SiemQuery id="installedVersions" />

`nvm.system.changed` payloads include `ReleaseType` (`stable` or `unstable`). Unstable means the Node.js version string contains a prerelease suffix (any `-`).

### Hosts with unstable Node.js installs

<SiemQuery id="unstableInstalled" />

### Who installed Node.js 20

<SiemQuery id="installedNode20" />

Change `20.` to another major version, or to an EOL line your policy tracks.
The event does not mark EOL for you.

### Hosts still using legacy `latest`

Governance `LatestIncludesPrerelease` writes `nvm.resolution.legacy_latest` when `latest` resolves to tip-of-index. Successful installs also set `LatestMode=legacy` on `nvm.system.changed`. See [Legacy latest policy](./legacy-latest-policy).

<SiemQuery id="legacyLatestHosts" />

### Who uninstalled a Node.js version

<SiemQuery id="uninstalledVersions" />
Expand Down Expand Up @@ -162,7 +174,8 @@ Query these by `EventName`.

| EventName | What it records |
|:-|:-|
| `nvm.system.changed` | Install, uninstall, and similar lifecycle results. Payload: `Action`, `NodeVersion`, `Outcome`, `User`, `sid`, `hostname`, `correlation_id`. |
| `nvm.system.changed` | Install, uninstall, and similar lifecycle results. Payload: `Action`, `NodeVersion`, `ReleaseType` (`stable` \| `unstable`), `Outcome`, `User`, `sid`, `hostname`, `correlation_id`. Installs driven by `latest` under Governance `LatestIncludesPrerelease` also include `LatestMode=legacy`. |
| `nvm.resolution.legacy_latest` | Warning when reserved `latest` resolves under Governance `LatestIncludesPrerelease`. Payload: `ResolvedVersion`, `LatestMode`, `User`, `hostname`, `Detail`. |
| `nvm.configuration.changed` | A setting change. Payload: `Configuration`, `Value`, `Old`, `Outcome`. |
| `nvm.version.activated` | The active Node.js version changed. Payload: `version`, `previous_version`, `user`, `hostname`. |
| `nodejs.executed` | A `node` launch when `LogExecutions` is `1`. Source `node-shim`. When permission allow flags were supplied, applied, or removed, the payload includes `permission_allow.supplied`, `permission_allow.applied`, and `permission_allow.removed`. |
Expand Down
6 changes: 6 additions & 0 deletions docs/guide/upgrade-from-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,12 @@ Installed Node.js versions from a supported v1 install are merged into v2 storag
You do not re-download those versions when the copy succeeds.
After install, open a **new** terminal and run `nvm list` to confirm the versions.

### `latest` alias

In v2, `nvm install latest` resolves to the newest **stable** Node.js release (it skips prereleases such as alphas).
Use `nvm install alpha` for the newest `-alpha*` release.
Governance fleets that must keep tip-of-index `latest` for existing scripts can enable `LatestIncludesPrerelease` — see [Legacy latest policy](./legacy-latest-policy).

### Backup in restricted environments

The installer copies Node.js version trees and related files during migration.
Expand Down
Loading