# Package Trust (/docs/build/package-trust) # Package trust [#package-trust] Use this page before installing Starkscan npm packages in agents, CI, or production services. This page is the public trust source for Starkscan packages. The canonical engineering repository is private, so package README files, homepage metadata, and agent-facing metadata should link here instead of sending users to a private GitHub URL as their human-facing trust entrypoint. Package manifests still carry the canonical private repository URL only for npm Trusted Publishing publisher verification; it is not a public source link or provenance claim. Machine-readable source for agents: [`public-client-surface-matrix.json`](/public-client-surface-matrix.json) Semver and conformance policy for a future `1.0`: [Public client 1.0 contract](/docs/build/public-client-1-0-contract) LLM-readable source: [`/llms.mdx/docs/build/package-trust/content.md`](/llms.mdx/docs/build/package-trust/content.md) ## Current decision [#current-decision] There is no single npm badge that should be treated as a security certification. The production-grade trust model is layered: * publish only from the `@starkscan` npm organization * pin exact versions for unattended agents * publish from checked release scripts, not package directories * verify package entrypoints, bundled native artifacts, manifests, and checksums before publish * use GitHub build attestations for release artifacts * use npm Trusted Publishing/OIDC on package pages for CI publishes * keep package `repository.url` on the checked-in private repository URL string used by package manifests and CI only for npm's GitHub publisher verification * do not claim npm provenance while the canonical repository remains private * use Socket and OpenSSF as external risk signals, not as proof that a package is safe For normal users, resolve the live npm channel from the registry rather than from this committed docs snapshot. The release targets are SDK `0.5.0` and CLI `0.6.0`; require the exact dist-tags and post-publish smoke before relying on untagged installs. Both carry the November 2026 API-audit client fixes and are unpublished source targets; the registry check on 2026-11-11 returned SDK `0.4.2` and CLI `0.5.7`. Merging source does not publish them. The pre-cutover registry snapshot was SDK `0.4.0` and CLI `0.4.3`. CLI `0.4.3` and older still probe the retired `/mcp` route in `doctor`. ```bash npx -y @starkscan/cli doctor npm install @starkscan/sdk ``` Resolve the current package version immediately before pinning it: ```bash npm view @starkscan/sdk@latest version --registry https://registry.npmjs.org npm view @starkscan/cli@latest version --registry https://registry.npmjs.org ``` Require each command to resolve the package-specific version in the table below before pinning it. The historical `beta` and `alpha` tags remain prerelease or rollback channels only. ## CLI security update [#cli-security-update] The certificate-trust issue was confirmed in CLI `0.5.6`. The `0.5.7` patch rejects the compromised emSign intermediate certificates, including when an older native trust store contains their roots, and preserves approved custom CA support. It also updates archive-decoding and async-runtime dependencies. This finding does not establish that credentials were intercepted. `0.5.7` is published, and `0.6.0` keeps the patch. Upgrade and replace old exact pins in CI and agents: ```bash npm install -g @starkscan/cli@0.5.7 --ignore-scripts starkscan --version ``` For a one-off run, use `npx -y @starkscan/cli@0.5.7 doctor`. Native binaries are bundled in the package; installation does not require dependency install scripts. ## Rollback [#rollback] If a current stable package regresses, roll back by pinning the previous known-good version explicitly and rerunning relevant smoke checks before putting it in an unattended agent. After the hosted MCP route is removed, CLI versions before `0.5.0` fail `doctor` on that missing route; use `status` to check REST reads and do not restore MCP solely to satisfy the old probe: ```bash npx -y @starkscan/cli@ status npm install @starkscan/sdk@ ``` ## Package status [#package-status] | Package | Public channel | Trust status | | ---------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`@starkscan/sdk`](https://www.npmjs.com/package/@starkscan/sdk) | `latest` (registry-authoritative); `0.5.0` target | Require the `0.5.0` dist-tag, clean import, and hosted typed-search, address-range and wallet-portfolio smoke before claiming this source contract is published. | | [`@starkscan/cli`](https://www.npmjs.com/package/@starkscan/cli) | `latest` (registry-authoritative); `0.6.0` target | Require the `0.6.0` dist-tag, four native artifacts, clean install, custom-CA behavior, TLS-cause errors, `api` command behavior, and hosted CLI verification smoke before claiming the release is public. | | [`@starkscan/mcp`](https://www.npmjs.com/package/@starkscan/mcp) | Retired | Hosted MCP is no longer served. Use `@starkscan/cli` or the REST API. | The current package trust fields live under `packageTrust` in [`public-client-surface-matrix.json`](/public-client-surface-matrix.json). ## Agent contract [#agent-contract] Agents should read this section as policy, not marketing copy: * Public docs and `public-client-surface-matrix.json` are the public source of truth. * `onePointZeroContract` in the matrix is the compatibility source for SDK and CLI `1.0` claims. * The private GitHub repository is not a public trust link. * The npm package name must be under `@starkscan`. * The package version should be pinned exactly in unattended jobs. * The package should not run as root or with elevated OS privileges. * The API key must come from the agent secret store or shell environment. * Reports should include package version, `X-Request-Id`, route class, host, and command. ## Signals we use [#signals-we-use] ### npm Trusted Publishing and provenance [#npm-trusted-publishing-and-provenance] Trusted Publishing is the preferred CI publish path because it removes long-lived npm publish tokens from GitHub Actions. It is not the same control as npm provenance. Decision: Starkscan accepts carrying the checked-in private repository URL string in package metadata so npm can verify the GitHub publisher and CI can use tokenless Trusted Publishing. npm documents that GitHub trusted publishing requires npm CLI 11.5.1 or newer and that `repository.url` must match the exact repository URL string used for publishing. Normalization differences such as `git+https://...` versus `https://github.com/...` can break verification, so the packages keep the same private repository URL string that package manifests and CI assert. npm provenance is stronger but has a public-source constraint. npm documents that provenance generation is not supported for private repositories, even for public packages. Trusted Publishing is configured on the npm package pages for SDK and CLI. The release proof must be an OIDC publish from `public-client-release.yml` without `NPM_PUBLISH_TOKEN`. Do not switch npm package access to disallow tokens until that OIDC path has passed for the stable channel. Npm provenance remains a later public-source decision. Release-proof state at this source revision: * the pre-cutover registry snapshot was SDK `0.4.0` and CLI `0.4.3`; recheck `latest` before treating either as current * CLI `0.4.3` is the pre-cutover rollback baseline, but its `doctor` probe is incompatible with the retired MCP route * the historical `alpha` and `beta` dist-tags remain available for rollback or prerelease testing only * the post-publish dist-tag verifier checks each package-specific stable version * release workflow has `id-token: write` for tokenless Trusted Publishing * release workflow uses public scoped package publishing * package manifests set `repository.url` to the checked-in private repository URL string asserted by CI for npm publisher matching * publish jobs explicitly set `NPM_CONFIG_PROVENANCE=false` * release scripts and workflow dispatch reject prerelease package versions before publishing to `latest` * manual publishes exist only for historical alpha packages; stable publishes should use the owner-controlled Trusted Publishing lane * the prerelease package train proved tokenless OIDC publishing * post-publish smoke proves unauthenticated CLI error responses emit the `starkscan-cli-` request-id prefix and never the legacy prefix * live SDK and CLI public status smoke passed against `https://api.starkscan.co` * CLI request-id smoke passed against the default hosted endpoint; authenticated `doctor` remains a per-client smoke when a scoped API key is available * npm Trusted Publishing is configured for the SDK and CLI package pages * next step is tightening package publishing access to disallow token publishes after the successful OIDC path is accepted as the owner-controlled release lane * legacy placeholder releases remain only as fail-closed rollback artifacts * npm provenance remains blocked while the canonical repository is private ### GitHub build attestations [#github-build-attestations] The release workflow attests SDK and native CLI artifacts before npm packaging. This gives maintainers a build evidence trail for artifacts. Public users should use this page, npm package metadata, and the machine-readable matrix as their public trust entrypoint unless a public source mirror is introduced. ### Socket [#socket] Socket is a package-risk and supply-chain scanner. It is useful as an external signal for dependency risk, maintainer/package metadata, and malware-style patterns, but it is not a formal audit certificate. Package pages: * [`@starkscan/sdk` on Socket](https://socket.dev/npm/package/@starkscan/sdk) * [`@starkscan/cli` on Socket](https://socket.dev/npm/package/@starkscan/cli) If Socket is unavailable behind a browser challenge, npm and GitHub release evidence remain the primary trust sources. ### OpenSSF [#openssf] OpenSSF Scorecard and the OpenSSF Best Practices badge are good repository posture signals. They should be added as repository-level launch hardening, not as per-package certification. For the current private-repository setup, OpenSSF signals belong on the internal maintainer checklist. The public package trust path should stay honest: npm identity, exact package version, checked tarball contents, CLI checksum verification, Socket as a risk signal, and this public docs page. ## Agent install rules [#agent-install-rules] * Use `STARKSCAN_*` env vars and keep API keys in the agent secret store. * Pin exact package versions for unattended production agents. * Do not run prerelease tags such as `@beta` in an unattended production loop without a version allowlist. * Do not run the CLI with elevated OS privileges. * Log the package version, `X-Request-Id`, and route class when reporting a bug. * Treat `latest` as the default channel after live verification. For reproducible unattended use, resolve `latest` immediately before setup and pin that exact registry result; do not pin a target version from this docs snapshot before its registry and post-publish proof are complete. ## Promotion bar [#promotion-bar] Before promoting any stable successor to `latest`: * `latest` does not point at a beta prerelease. * SDK package imports under Node ESM from the packed tarball. * CLI package includes all supported native platform archives. * CLI verifies manifest and sha256 before executing a native binary. * Live SDK and CLI smoke tests pass against the hosted API for the version being promoted. * npm Trusted Publishing is configured for the package, or maintainers have explicitly accepted manual passkey publishing while the repo remains private. * npm provenance is present only if the source repository is public or a public source mirror exists. * Socket/OpenSSF status is checked and linked as an external signal. ## External references [#external-references] * [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers) * [npm provenance statements](https://docs.npmjs.com/generating-provenance-statements) * [OpenSSF Scorecard](https://scorecard.dev/)