Releases and verification

What each SDK release carries, how to verify it before you install it, and how long a version is supported.

Every SDK release is on npm as @doshi/sdk, and comes with the evidence to check it: a checksum file, a bill of materials and a signed build attestation. Your security team can verify all three before anyone installs the package.

What a release carries

Each release’s files are at https://developers.doshi.app/releases/<version>/, from 0.2.0 on.

File	What it is
`doshi-sdk-<version>.tgz`	The package, the same file npm serves.
`SHA512SUMS`	The SHA-512 checksums of the tarball and the SBOM.
`doshi-sdk-<version>.cdx.json`	The CycloneDX 1.6 SBOM: the tarball’s hash, and each runtime dependency with its version and license.
`doshi-sdk-<version>.tgz.sigstore.json`	The Sigstore attestation: SLSA build provenance for the tarball, naming the workflow, tag and commit that built it.

The release notes list what changed since the previous release, and the runtime dependencies.

Verify a release

Fetch the package from npm and the rest from this site, into one directory:

version=0.3.2
npm pack "@doshi/sdk@$version"
for file in SHA512SUMS "doshi-sdk-$version.cdx.json" "doshi-sdk-$version.tgz.sigstore.json"; do
  curl -fsSO "https://developers.doshi.app/releases/$version/$file"
done

npm pack downloads doshi-sdk-<version>.tgz, the same file npm install fetches, checked against the same integrity hash. So the tarball you verify is the one your lockfile pins.

Check the checksums. Every line must print OK.

sha512sum -c SHA512SUMS    # macOS: shasum -a 512 -c SHA512SUMS

Check the SBOM. SHA512SUMS covers it, so the step above proves it is the SBOM we published. It names the tarball it describes by hash: the SHA-512 in its metadata.component.hashes must equal the tarball’s line in SHA512SUMS.

jq -r '.metadata.component.hashes[] | select(.alg == "SHA-512") | .content' "doshi-sdk-$version.cdx.json"

It is standard CycloneDX JSON, so your existing scanner can read it too. Its components are everything the bundle carries: the package declares no dependencies of its own, so installing it installs nothing else.

Check the attestation with cosign, Sigstore’s CLI, version 3 or later:

cosign verify-blob-attestation "doshi-sdk-$version.tgz" \
  --bundle "doshi-sdk-$version.tgz.sigstore.json" --type slsaprovenance1 \
  --certificate-identity "https://github.com/Doshi-App/platform/.github/workflows/sdk-release.yml@refs/tags/sdk-v$version" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Verified OK means the tarball is byte-for-byte what our release workflow built from that version’s tag. The signature names the workflow and the tag, not who pushed it; a tag ruleset lets only Doshi administrators create release tags. The attestation is recorded in Sigstore’s public transparency log.

Versions

The SDK follows semver over its public API: mount, its options and its events.

A new option or event field is a minor version. Removing or renaming one is a major version.
0.x releases may break. Any 0.x minor may rename or remove an option.
The API freezes at 1.0.0, the first release a client runs in production. From then on, only a major version breaks it.

Cadence and support

We release every week, usually as a minor version, plus an out-of-band release whenever a security fix cannot wait for the next one. Nothing changes on your page until you install a new version, so you choose when to upgrade.

A major version stays supported for 12 months after its successor ships. So when 2.0.0 ships, 1.x keeps working against our hosts for 12 months more.