Package Trust

Public trust source for Starkscan npm SDK, CLI, and MCP packages.

API reference Reference Quickstart TypeScript SDK

In this guide

Current decision Alpha rollback Package status Agent contract Signals we use npm Trusted Publishing and provenance

Loading documentation content…

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

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

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:

npx -y @starkscan/[email protected]
npx -y @starkscan/[email protected] doctor
npm install @starkscan/[email protected]

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

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:

npx -y @starkscan/[email protected] doctor
npx -y @starkscan/[email protected] doctor
npm install @starkscan/[email protected]

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

Package status

Package	Public channel	Trust status
`@starkscan/sdk`	`alpha`	`0.1.0-alpha.2` is published on `alpha` and imports under Node ESM from a clean package install.
`@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`	`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.

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

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 with STARKSCAN_BASE_URL=https://starkscan.co/api; 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

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:

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

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.