Security

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

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@12.9.1" in package.json.
GitHub Actions workflows use explicit runtime/tool versions:
- Node.js 24.21.0
- pnpm 12.9.1
- npm bundled with Node.js 24.21.0 in the release workflow
The CLI requires Node.js 22.16+ or 24+ for built-in node:sqlite with a busy timeout (ledger and SQLite-backed sources) and zstd; no Node 23 release has the DatabaseSync timeout option.

Dependency pinning and integrity

Direct dependencies in package.json and site/package.json are pinned to exact versions.
pnpm-workspace.yaml sets saveExact: true so future additions stay exact by default.
pnpm-workspace.yaml allows dependency build scripts only for esbuild and sharp.
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.
Repository settings require GitHub Actions to be pinned to full commit SHAs.
The complete transitive dependency override policy lives in pnpm-workspace.yaml, keeping pnpm install policy in one place.

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 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

Temporary audit exception

pnpm-workspace.yaml excludes only GHSA-ch52-4w7c-c8xp from audit failures. The advisory affects http-cache-semantics through 4.2.0 and has no published fixed version as of October 4, 2026.

The dependency is pulled in by Astro for remote-image caching during site builds. Astro 7.3.5 uses storable() and timeToLive() in that path, not the affected satisfiesWithoutRevalidation() method. This repository deploys static files to GitHub Pages, does not run a shared HTTP cache, and does not ship Astro in the CLI package. These facts make the reported cross-user cache disclosure path inapplicable to the current deployment.

Remove the exception when a patched release is available, and reassess it before adding a server adapter or shared response cache. All other moderate-or-higher advisories still fail the audit job.

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

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

Network and runtime behavior

The CLI is local-first: it parses local session files and local Git history. Machine sync runs your system ssh only to machines you added yourself.
Privacy lists every network request the CLI makes.
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; --pricing-offline runs from cache or the bundled LiteLLM snapshot.
The SQLite sources (OpenCode, Goose, Antigravity) open their databases read-only.
The parsers live in packages/core (@ayagmar/agent-sessions). Lint forbids network modules and APIs there, the package has no dependencies (pnpm run core:pack:check fails if one appears), and importing it reads no file, environment variable or home directory. See the library overview.
--share writes a self-contained HTML file to the current directory and opens it with the system opener (xdg-open on Linux, open on macOS, rundll32.exe on Windows); --no-open skips that.
The event store retains usage, session, and repository metadata. On POSIX systems, the default directory uses mode 0700, and the database plus present WAL/SHM files use mode 0600. Custom store parent-directory permissions remain the user’s responsibility. Deleting the ledger deletes its retained history.

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 and pin the downloaded Codecov CLI version.
The release workflow uses the npm version bundled with its pinned Node.js runtime; it does not install an ad-hoc global npm package.
Workflows default to read-only repository contents and grant write access only to the jobs that need it, such as release publishing, Pages deployment, PR coverage comments, and CodeQL security-event uploads.
Non-release checkouts disable credential persistence. The release checkout deliberately retains credentials because release-it pushes the release commit and tag.

Contributor checklist

For any change

Run the standard verification commands:

pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run format:check

Verify the target version from authoritative sources first (official changelog/docs, npm registry, or the action’s release page).
Make the smallest necessary change.
Run pnpm install so pnpm-lock.yaml stays in sync.
Review the lockfile diff and confirm only intended packages changed.
Keep integrity: sha512-... entries intact in the lockfile.
Preserve pnpm install --frozen-lockfile in workflows.
Keep GitHub Actions pinned to full commit SHAs and preserve repository-level SHA enforcement once it is enabled.
Keep the trailing action-version comments (for example # v4.3.1) so Dependabot can update pinned refs cleanly.
Keep build-script permissions limited to the explicit allowBuilds entries in pnpm-workspace.yaml.

Recommended validation for dependency or workflow changes:

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

Automated path

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

Manual path

For manual upgrades:

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

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

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.