socket-addon

Socket's @socketaddon/* npm packages are published from this repo. The GitHub Actions workflow here is the one authorized to push new versions to npm. The native .node binaries themselves are built in socket-btm; this repo only takes finished binaries, verifies them, and publishes them.

Why this repo exists

The npm registry has a feature called trusted publishing: instead of storing a long-lived npm token in CI secrets (which can leak), you tell npm "the GitHub Actions workflow at <owner>/<repo> is allowed to publish package X." When that workflow runs, it asks GitHub for a short-lived OIDC token, presents it to npm, and npm verifies it before accepting the publish.

Because trust is bound to one repo, we split build from publish:

• socket-btm builds NAPI addons and uploads them to GitHub Releases, with embedded SHA-256 checksums.
• socket-addon (this repo) downloads those binaries, verifies the hashes, and is the only repo allowed to push to npm under the @socketaddon/* scope.

Sister repo: socket-bin does the same for @socketbin/* SEA-packed standalone binaries.

Install

End users install the published packages, not this repo:

npm install @socketaddon/<tool>

The umbrella declares each per-platform package as optionalDependencies with os + cpu constraints, and npm installs only the matching one.

Usage

Repository layout:

packages/
  build-infra/                             # shared helpers
    lib/release-checksums/
      core.mts                             # parse + hash + verify
      consumer.mts                         # download from sibling GH releases
    release-assets.json                    # release tag + per-asset SHA-256
    release-assets.schema.json             # JSON Schema validating the .json
  <tool>/                                  # umbrella package on npm (per tool)
  <tool>-<platform>-<arch>/                # per-platform shims (per tool)
scripts/
  publish.mts                              # orchestrator, driven by tools.json
tools.json                                 # which tools to publish + their conventions
tools.schema.json                          # JSON Schema validating tools.json

tools.json is the registry of what this repo knows how to publish. Adding a new tool: drop a new entry in tools.json, add a matching block to packages/build-infra/release-assets.json, create the per-platform package dirs under packages/. Removing one: delete the key + matching dirs + (optionally) deprecate on npm via npm deprecate <pkg>@"*" "<msg>".

How a publish actually goes:

1. socket-btm finishes a build and cuts a GitHub Release like <tool>-YYYYMMDD-<short-sha>. The release contains N .node binaries (one per platform) plus a checksums.txt listing the SHA-256 of each.
2. Someone here updates packages/build-infra/release-assets.json with the new tag and the new per-asset SHA-256s. The $schema pointer in that file makes editors autocomplete + flag typos.
3. Someone triggers the GitHub Actions workflow at .github/workflows/provenance.yml. The workflow runs scripts/publish.mts, which:
   • Reads tools.json to discover which tools to ship.
   • For each tool: reads the embedded SHA-256s from release-assets.json.
   • Downloads each .node from socket-btm's GH Release.
   • Hashes the downloaded file and compares against the embedded SHA-256. Mismatch = abort the whole run, no packages published.
   • Stages the per-platform package in os.tmpdir(), drops the verified .node into the stage, and runs pnpm publish from there.
   • Repeats per-platform across all tools, then publishes the umbrella packages last (each umbrella's optionalDependencies references the per-platforms by exact version, so they have to land on npm first).

If a checksum doesn't match, nothing publishes — fail-loudly.

Current state: tools.json is empty after the iocraft retirement. opentui, ultraviolet, yoga-layout, and onnxruntime are slated to fill it as socket-btm starts shipping releases for those. Adding each is a mechanical follow-up: drop a new entry in tools.json, bump release-assets.json, create the per-platform dirs, open a PR; once merged, dispatch the publish workflow.

Development

Contributor commands

pnpm install              # install dependencies + git hook setup
pnpm run check            # lint + type check
pnpm run lint             # lint files modified vs HEAD
pnpm run lint --all       # lint the whole workspace
pnpm run fix              # auto-fix lint + format
pnpm run test             # run vitest scoped to changes
pnpm run test --all       # full vitest suite
pnpm run cover            # vitest with coverage
pnpm run security         # AgentShield + zizmor scans
pnpm run setup            # download zizmor + sfw with sha256 verification
pnpm run update           # bump dependencies (taze)
pnpm run publish:dry      # stage + verify, but don't actually publish
pnpm run publish:ci       # full publish — CI only, requires OIDC
pnpm run clean            # remove caches

License

MIT (per published package).