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

Semver and conformance policy for a future 1.0: Public client 1.0 contract

LLM-readable source: /llms.mdx/docs/build/package-trust/content.md

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, use the default npm channel after the stable release workflow has completed. The current public package train is 0.1.2; public install instructions must wait until latest for SDK, CLI, and MCP resolves to 0.1.2 and the post-publish registry verifier plus hosted public-client smoke pass.

npx -y @starkscan/mcp doctor
npx -y @starkscan/cli doctor
npm install @starkscan/sdk

After that verifier passes, the latest dist-tag points to 0.1.2. Unattended workflows that need reproducible installs should pin the smoked exact version, for example @starkscan/cli@0.1.2. The historical beta and alpha tags remain prerelease or rollback channels only.

Rollback

If 0.1.2 regresses, roll back by pinning the previous known-good version explicitly and rerunning the same smoke checks before putting it in an unattended agent:

npx -y @starkscan/mcp@<previous-known-good-version> doctor
npx -y @starkscan/cli@<previous-known-good-version> doctor
npm install @starkscan/sdk@<previous-known-good-version>

Keep MCP and CLI on the same package version. The MCP launcher depends on the matching CLI package, so mixing @starkscan/mcp with a different CLI version is not a supported rollback shape.

Package status

The current package trust fields live under packageTrust in public-client-surface-matrix.json.

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, CLI, and MCP 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

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 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 required before this docs revision is public:

• package 0.1.2 is published on the latest dist-tag for SDK, CLI, and MCP
• the historical alpha and beta dist-tags remain available for rollback or prerelease testing only
• the post-publish dist-tag verifier checks that latest resolves to 0.1.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 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/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://api.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 scoped API key is available
• npm Trusted Publishing is configured for all three 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

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 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
• @starkscan/cli on Socket
• @starkscan/mcp on Socket

If Socket is unavailable behind a browser challenge, npm and GitHub release evidence remain the primary trust sources.

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

• 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 or MCP launcher with elevated OS privileges.
• Log the package version, X-Request-Id, and route class when reporting a bug.
• Treat latest as the default channel; pin 0.1.2 when reproducibility matters.

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

• npm Trusted Publishing
• npm provenance statements
• OpenSSF Scorecard