lpm trust

Review and manage the security decisions stored in a project's package.json.

lpm trust <COMMAND>
lpm trust diff [OPTIONS]
lpm trust prune [OPTIONS]
lpm trust lifecycle-scope <COMMAND>
lpm trust lifecycle-scope add <SCOPE> [OPTIONS]
lpm trust lifecycle-scope remove <SCOPE> [OPTIONS]
lpm trust lifecycle-scope list [OPTIONS]
lpm trust release-age-exclude <COMMAND>
lpm trust release-age-exclude add <SELECTOR> [OPTIONS]
lpm trust release-age-exclude remove <SELECTOR> [OPTIONS]
lpm trust release-age-exclude list [OPTIONS]

Quickstart

# Review trust changes before installation updates the baseline
lpm trust diff

# Preview approvals for packages no longer in the lockfile
lpm trust prune --dry-run

Use lpm approve-scripts for individual package approvals. Use lpm rebuild to run approved dependency scripts.

Examples

# Fail CI when package approvals differ from the saved baseline
lpm trust diff --assert-none --json

# Remove stale approvals without a prompt
lpm trust prune --yes --json

# List project lifecycle scopes
lpm trust lifecycle-scope list --json

# Exclude one exact version from the cooldown
lpm trust release-age-exclude add react@19.1.0 --json

# Remove that exact exclusion
lpm trust release-age-exclude remove react@19.1.0 --json

For a reusable trust check, define an uncached task:

{
  "tasks": {
    "deps:trust": {
      "command": "lpm trust diff --assert-none",
      "cache": false
    }
  }
}

lpm run deps:trust

There is no dedicated trust configuration in lpm.json. The task's command holds the flags. cache: false checks the current files each time.

For an informational check on one run, use lpm trust diff directly. An explicit lpm.json task command takes precedence in lpm run.

Project scope and storage

These commands use the nearest directory with a package.json, as lpm install does, and print the directory they chose when it is not the current one. Inside a workspace member, they use that member's manifest.

Mutations preserve other manifest fields and use atomic file replacement. Project commands do not copy entries into user or global configuration.

The lockfile supplies dependency names for pruning. It does not store lifecycle approvals, lifecycle scopes, or release-age exclusions.

Sharing package.json shares the declared policy. It does not transfer local signed authorization to another user or machine.

lpm trust diff

lpm trust diff
lpm trust diff --assert-none --json

The command compares lpm.trustedDependencies with .lpm/trust-snapshot.json:

Keys can include a package name, version, and artifact identifier. The comparison preserves each complete key.

The diff does not compare capability approvals, provenance, lifecycle scopes, or release-age exclusions.

If the snapshot is absent or unusable, the previous set is empty. Current approvals appear as additions and can fail --assert-none.

If both sets are empty, the diff is empty. Plain diff reports changes without failing. --assert-none exits 1 when any change exists.

The snapshot records the approval set used for the install. Later lifecycle-script edits stay visible in the next diff.

LPM CLI saves the baseline after a successful install.

A failed install, including failed dependency or root lifecycle scripts, preserves the previous snapshot. Snapshot writes are best effort.

If a snapshot cannot be saved, the install can succeed with a warning. A later diff then uses the previous baseline, if available.

CI sequence

Run the diff before lpm install or lpm ci updates the baseline:

- run: lpm trust diff --assert-none --json
- run: lpm ci
- run: lpm trust prune --dry-run --json

A fresh checkout needs a saved baseline from a reviewed install for change detection. Treat that baseline as reviewed input.

Installing first accepts the current approval set as the new baseline. A diff after that install cannot detect the earlier changes.

The JSON report includes added, removed, changed, diff_count, current_binding_count, and snapshot_captured_at. Each change contains key, previous, and current.

On assertion failure, the same report contains success: false, assertion_failed: true, and error_code: "trust_diff_assert_none".

lpm trust prune

lpm trust prune --dry-run
lpm trust prune --yes
lpm trust prune --dry-run --json
lpm trust prune --yes --json

Prune removes approval entries whose package names do not appear in the selected lockfile graph. It requires a usable lockfile.

A different installed version does not make an entry stale. Moving a package between dependency sections does not make it stale either.

For a workspace member, pruning uses that member's lockfile projection. It does not change sibling or root manifests.

Interactive pruning asks before removal. For non-interactive mutation, pass --yes.

JSON mode requires --yes or --dry-run, even when no entries are stale. --dry-run keeps the manifest unchanged.

The JSON report includes stale, stale_count, dry_run, and mutated. mutated is false for previews and no-op results.

A preview succeeds even when it finds stale entries. Input errors still fail. To fail CI on stale entries:

set -o pipefail
lpm trust prune --dry-run --json | jq -e '.success and .stale_count == 0'

lpm trust lifecycle-scope

lpm trust lifecycle-scope add '@company/*'
lpm trust lifecycle-scope list
lpm trust lifecycle-scope remove '@company/*'

A lifecycle scope trusts all packages in one npm scope, across versions and script contents. Use it only for a scope you control. Trusted scripts still run in the sandbox, which keeps them out of LPM CLI's state in the project's .lpm/ directory.

The selector must be a lowercase npm scope wildcard, such as @company/*. Package names, versions, uppercase scopes, and nested patterns are invalid.

An addition widens the security policy and requires local signed authorization. In an interactive terminal, LPM CLI requests native approval.

For non-interactive use, first authorize the project from a user-controlled terminal:

lpm security unlock trust-scope-widen --project . --ttl 10m
lpm trust lifecycle-scope add '@company/*' --json

The unlock command itself requires user approval. JSON mode does not bypass authorization.

Install and rebuild also require authorization for project scope trust. Other users must authorize the policy on their own machines.

Removal needs no widening approval. It removes the matching scope and its signed authorization, and revokes trust-scope-widen from active project unlocks.

Other authorization scopes remain active. Adding the removed lifecycle scope again requires new authorization.

list shows only the project's lifecycle scopes. It does not include individual package approvals or global trust.

lpm trust release-age-exclude

lpm trust release-age-exclude add react
lpm trust release-age-exclude add react@19.1.0
lpm trust release-age-exclude add '@company/*'
lpm trust release-age-exclude list
lpm trust release-age-exclude remove react@19.1.0

An exclusion lets matching packages bypass the minimum release-age cooldown:

Version ranges are invalid. Removal matches the complete selector, so removing react@19.1.0 leaves a separate react entry intact.

A duplicate addition preserves a normalized manifest without rewriting it. If stored entries need normalization, the command repairs them.

list shows only project exclusions. During install, CLI, project, and user exclusions combine and duplicate selectors collapse.

For a one-run exception, use:

lpm install --min-release-age-exclude react@19.1.0

User release-age exclusions

For user-level exclusions, use lpm config:

lpm config release-age-exclude add '@company/*'
lpm config release-age-exclude list
lpm config release-age-exclude remove '@company/*'

These commands use ~/.lpm/config.toml > minimum-release-age-exclude.

List and mutation reports

Lifecycle-scope and release-age-exclude JSON reports include success, schema_version, command, scope, action, changed, normalized, and count.

Lifecycle reports use scopes. Release-age reports use exclusions. Add and remove reports also include selector.

changed indicates a selector change. normalized indicates a repair to the stored list. Both can differ in the same report.

Fix common problems

If the command cannot find package.json in the current directory or above, run it from the intended project or workspace member.

If prune cannot read the lockfile, repair the installation before pruning:

lpm install
lpm trust prune --dry-run

If a trust assertion fails, review the listed keys and their manifest changes before the next install.

If scope authorization fails, use the unlock command shown in the error from a user-controlled terminal.

Flags

See the global flags for other shared options.

See also

• lpm approve-scripts — approve individual dependency scripts
• lpm rebuild — run approved scripts
• lpm install — install dependencies and update the trust baseline
• Project script configuration — lifecycle settings
• Package approvals — approval format
• Project release-age exclusions — cooldown exceptions
• User configuration — user-level policy