Signed `@aidokit/*` packages

Every @aidokit/* package published to npm ships with an npm provenance statement (Sigstore). The statement links the published tarball back to the specific GitHub Actions workflow run that built it, so you can verify a package was published by aidokit's own publish pipeline and not by a compromised maintainer credential.

What you get #

When you npm install @aidokit/core (or any sibling package), npm fetches not just the tarball but an attestation bundle generated during the publish run. The bundle proves:

the tarball was built by GitHub Actions in the aidokit-project/aidokit repository,
by the specific workflow file (.github/workflows/publish.yml),
triggered by a specific commit SHA on the main branch,
with Node 20 in the canonical CI environment,
and the resulting bytes match the attestation hash.

The attestation is signed by Sigstore's transparency log (rekor.sigstore.dev), publicly verifiable, and immutable.

Verifying a package #

# Quickest check — show the attestations field
npm view @aidokit/core --json | jq '.dist.attestations'

# Full chain — recompute the hash and verify against Sigstore
npm audit signatures

If npm audit signatures reports any unsigned @aidokit/* package after v1.0, treat it as a supply-chain incident. Open an issue tagged security immediately.

What provenance does NOT guarantee #

Be honest with yourself about the threat model:

Provenance does not vouch for code quality. A buggy or intentionally malicious commit on main will still be published, and the attestation will still verify. Code review matters as much as ever.
Provenance does not vouch for upstream dependencies. If @aidokit/cli depends on a malicious package, the attestation says nothing about that supply chain.
Provenance does not replace pinning. Use a lockfile (pnpm-lock.yaml / package-lock.json) and review version bumps explicitly.
Provenance does not protect against social-engineering attacks on maintainers (e.g. a coerced PR merge). It only proves the publish happened in the published workflow.

If your threat model requires defense against compromised maintainer accounts, also pin to specific SHAs of the workflow file via actions/checkout and require branch protection — both standard hardening practices.

How publishing works (for maintainers) #

The .github/workflows/publish.yml workflow:

Triggers on push to main (typically after a Changesets "Version Packages" PR has been merged).
Installs, builds, typechecks, and tests across the workspace.
Verifies the v4 reference snapshot is present (the dogfood gate).
Calls changesets/action@v1, which either opens a release PR or — if one has just been merged — runs pnpm changeset publish.
The publish step has NPM_CONFIG_PROVENANCE=true set and the workflow has id-token: write, so every tarball gets a provenance statement attached automatically.

Manual publishes are deliberately not supported — see ADR-0004.

What we don't sign (yet) #

The git tags that Changesets pushes — npm provenance covers the tarball, not the tag. Tag signing is a separate hardening step (sigstore-go, gitsign) tracked in workstream G5+.
The .aidokit/ artifacts emitted into user projects. Those are user-owned and stay in the user's repo; signing them would require the user's own signing infrastructure.
The wiki / docs site. Static content, no signing planned.

Signed @aidokit/* packages