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, resolve the live npm channel from the registry rather than from this committed docs snapshot. The release targets are SDK 0.4.1 and CLI 0.5.6; require the exact dist-tags and post-publish smoke before relying on untagged installs. 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.

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

Resolve the current package version immediately before pinning it:

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.

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:

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

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

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

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

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

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

• npm Trusted Publishing
• npm provenance statements
• OpenSSF Scorecard