Skip to content
llm-usage-metrics

Security

This page documents the security controls and contributor steps that are now configured in this repository.

Section titled “Current security-related controls”

Locked installs and reproducible tool versions

Section titled “Locked installs and reproducible tool versions”
  • CI, Pages, release, performance, and security workflows install dependencies with pnpm install --frozen-lockfile where dependencies are needed.
  • The root package declares "packageManager": "pnpm@10.17.1" in package.json.
  • GitHub Actions workflows use explicit runtime/tool versions:
    • Node.js 24.13.1
    • pnpm 10.17.1
  • OpenCode support requires Node.js 24+ because it uses built-in node:sqlite.

Dependency pinning and integrity

Section titled “Dependency pinning and integrity”
  • Direct dependencies in package.json and site/package.json are pinned to exact versions.
  • .npmrc sets save-exact=true so future additions stay exact by default.
  • The committed pnpm-lock.yaml is the real installation pin for this repo.
  • pnpm-lock.yaml records integrity: sha512-... hashes for downloaded package tarballs.
  • GitHub Actions workflows are pinned to full commit SHAs, with trailing version comments so automated updaters can keep them current.
  • The root package.json also uses pnpm.overrides to force basic-ftp@5.2.0 and lodash@4.17.23, patching vulnerable transitive versions in the current dependency graph.

Automated dependency upgrades

Section titled “Automated dependency upgrades”
  • .github/dependabot.yml enables weekly update PRs for:
    • root npm dependencies
    • site/ npm dependencies
    • GitHub Actions workflow dependencies
  • Dependabot labels those PRs with dependencies and security.

Security scans currently in use

Section titled “Security scans currently in use”

Dedicated security workflows are configured in .github/workflows/security.yml:

  • pnpm audit --audit-level=moderate on pushes, pull requests, manual runs, and the weekly security schedule
  • Dependency Review on pull requests, failing on moderate-or-higher findings in dependency changes
  • CodeQL analysis for JavaScript/TypeScript on pushes, pull requests, and a weekly schedule

The regular CI workflow in .github/workflows/ci.yml still enforces the normal quality gates:

  • lint
  • typecheck
  • tests with coverage threshold enforcement
  • build
  • pack check
  • site check/build

Network and runtime behavior

Section titled “Network and runtime behavior”
  • The CLI is local-first: it parses local session files and local Git history.
  • Startup update checks only query the npm registry for the latest package version and are cached/skippable with LLM_USAGE_SKIP_UPDATE_CHECK=1.
  • Pricing refreshes only fetch the LiteLLM pricing JSON and can run from cache with --pricing-offline.
  • OpenCode parsing opens the SQLite database in read-only mode.

Publishing and CI identity

Section titled “Publishing and CI identity”
  • npm publishing is configured for trusted publishing (OIDC) in .github/workflows/release.yml.
  • The release workflow does not require a long-lived npm publish token.
  • Codecov uploads in CI use OIDC as well.
  • Workflow permissions are declared explicitly where elevated access is needed (for example release publishing, Pages deploy, PR coverage comments, and CodeQL security events upload).

Contributor checklist

Section titled “Contributor checklist”

For any change

Section titled “For any change”

Run the standard verification commands:

Terminal window
pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run format:check
Section titled “For dependency, workflow, or release-related changes”
  1. Verify the target version from authoritative sources first (official changelog/docs, npm registry, or the action’s release page).
  2. Make the smallest necessary change.
  3. Run pnpm install so pnpm-lock.yaml stays in sync.
  4. Review the lockfile diff and confirm only intended packages changed.
  5. Keep integrity: sha512-... entries intact in the lockfile.
  6. Preserve pnpm install --frozen-lockfile in workflows.
  7. Keep GitHub Actions pinned to full commit SHAs.
  8. Keep the trailing action-version comments (for example # v4.3.1) so Dependabot can update pinned refs cleanly.

Recommended validation for dependency or workflow changes:

Terminal window
pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run format:check
pnpm audit --audit-level=moderate
pnpm run build
pnpm run smoke:dist-opencode
pnpm run pack:check
pnpm run site:check
pnpm run site:build

Dependency upgrade process

Section titled “Dependency upgrade process”

Automated path

Section titled “Automated path”

Prefer the existing Dependabot flow for routine upgrades. Review its PRs carefully, especially lockfile and workflow changes.

Manual path

Section titled “Manual path”

For manual upgrades:

Terminal window
pnpm outdated
pnpm up --latest <package-name>
pnpm install

Then:

  • review package.json and/or site/package.json
  • review pnpm-lock.yaml
  • review any workflow diff if GitHub Actions changed
  • run the validation commands above
  • mention noteworthy toolchain or security-related changes in the PR

Release-specific guidance

Section titled “Release-specific guidance”
  • Use the GitHub Actions release workflow for real publishes.
  • Keep OIDC trusted publishing in place; do not replace it with a long-lived npm token unless the repo is intentionally changing publishing strategy.
  • If you modify .github/workflows/release.yml, keep the required Node/npm expectations aligned with docs/development.md.

Reporting issues safely

Section titled “Reporting issues safely”

When opening issues, redact secrets and sensitive local paths from logs before posting them. The bug report template already asks contributors to redact secrets/paths where needed.