# 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) 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 beta users, use the `alpha` channel only when you can tolerate package updates. The current alpha package train is `0.1.0-alpha.2`; it is published and post-publish smoke-tested. Pin the exact version for unattended beta workflows: ```bash npx -y @starkscan/mcp@0.1.0-alpha.2 npx -y @starkscan/cli@0.1.0-alpha.2 doctor npm install @starkscan/sdk@0.1.0-alpha.2 ``` `alpha` currently points to `0.1.0-alpha.2`. `latest` currently points to the stable fail-closed placeholder `0.0.2`, not the alpha prerelease. Use exact versions for unattended jobs. This placeholder keeps fail-closed behavior while giving the npm default page professional install guidance, package purpose, trust policy, and public docs links. ## Alpha rollback [#alpha-rollback] If `0.1.0-alpha.2` regresses, roll back by pinning the prior alpha explicitly and rerunning the same smoke checks before putting it in an unattended agent: ```bash npx -y @starkscan/mcp@0.1.0-alpha.1 doctor npx -y @starkscan/cli@0.1.0-alpha.1 doctor npm install @starkscan/sdk@0.1.0-alpha.1 ``` Keep MCP and CLI on the same package version. The MCP launcher depends on the matching CLI package, so mixing `@starkscan/mcp@0.1.0-alpha.1` with a different CLI version is not a supported rollback shape. ## Package status [#package-status] | Package | Public channel | Trust status | | ---------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`@starkscan/sdk`](https://www.npmjs.com/package/@starkscan/sdk) | `alpha` | `0.1.0-alpha.2` is published on `alpha` and imports under Node ESM from a clean package install. | | [`@starkscan/cli`](https://www.npmjs.com/package/@starkscan/cli) | `alpha` | `0.1.0-alpha.2` is published on `alpha` with bundled native artifacts, manifest/checksum verification, and unauthenticated request IDs using the `starkscan-cli-` prefix. | | [`@starkscan/mcp`](https://www.npmjs.com/package/@starkscan/mcp) | `alpha` | `0.1.0-alpha.2` is published on `alpha`, delegates to the exact matching `@starkscan/cli` version, and passes packaged launcher smoke. | 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. * 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, CLI, and MCP. The next release proof is 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 once. Npm provenance remains a later public-source decision. Current Starkscan state: * package `0.1.0-alpha.2` is currently published on the `alpha` dist-tag * the npm `latest` dist-tag points at the stable fail-closed placeholder `0.0.2`, not the alpha prerelease * the post-publish dist-tag verifier checks that alpha resolves to `0.1.0-alpha.2` and latest resolves to `0.0.2` * 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 for `0.1.0-alpha.0`, `0.1.0-alpha.1`, and `0.1.0-alpha.2` using npm passkey/2FA * alpha2 proved unauthenticated CLI/MCP error responses emit the `starkscan-cli-` request-id prefix and never the legacy prefix * live SDK and CLI public `status` smoke passed against `https://starkscan.co` * MCP `print-config` / `tools` and CLI/MCP request-id smoke passed against the default hosted endpoint; authenticated `doctor` remains a per-client smoke when a beta API key is available * npm Trusted Publishing is configured for all three package pages * next step is proving one tokenless OIDC publish, then tightening package publishing access to disallow token publishes * stable placeholder `0.0.2` gives npm `latest` complete README metadata while still failing closed * 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) * [`@starkscan/mcp` on Socket](https://socket.dev/npm/package/@starkscan/mcp) 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 `npx @starkscan/*@alpha` in an unattended production loop without a version allowlist. * Do not run the CLI or MCP launcher with elevated OS privileges. * Log the package version, `X-Request-Id`, and route class when reporting a bug. * Treat `latest` as a convenience tag only after the package is explicitly promoted out of alpha. ## Promotion bar [#promotion-bar] Before promoting any package channel beyond `alpha`: * `latest` does not point at an alpha 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. * MCP package depends on the exact matching CLI version. * Live SDK, CLI, and MCP 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/)