DEV Community: Nick Harin

Verify your Composer dependencies' provenance

Nick Harin — Sun, 05 Jul 2026 19:11:25 +0000

When the xz backdoor landed in 2024, it was a wake-up call for every package
ecosystem: the code you install is only as trustworthy as the pipeline that built
it. PHP is no exception. Run composer install and you pull down code from dozens
of repositories — but nothing checks who built each package, or whether the
archive you received is the one its maintainer actually published.

composer.lock doesn't solve this. It pins a dist hash, so it verifies you got
the same bytes every time — but it says nothing about where those bytes came
from. If an attacker publishes a malicious release, the lock file faithfully pins
the malicious hash. Integrity is not provenance.

The rest of the software world has an answer to this now: Sigstore and
build-provenance attestations. npm ships Sigstore-signed provenance. GitHub
Actions can attest any build artifact, recording a signed statement — "this
artifact was built by this workflow in this repository" — in a public
transparency log. Until recently, PHP had no way to produce or consume any of it.

This post shows the whole loop working end to end, on real packages.

The one subtlety that matters: attest the zipball

Here's the trap that makes naïve provenance for Composer silently useless.

Most "sign your release" setups attest a release tarball — the output of
git archive, uploaded as a GitHub release asset. But Composer doesn't install
that. It installs the dist zipball: api.github.com/repos/{owner}/{repo}/zipball/{commit}
— a different artifact with a different digest. Attest the tarball and your
attestation covers a file nobody installs. A verifier checking what Composer
actually downloaded finds nothing.

The fix is to attest the exact zipball Composer fetches. Its digest is
reproducible for a given commit, and — crucially — the commit is the same
reference Packagist records as the package's dist. Attest that, and the
attestation covers the bytes that land in vendor/.

Signing: one line in your release workflow

k2gl/composer-attest-action is
a GitHub Action that does exactly this — it attests both the tarball and the dist
zipball. Drop it into a workflow that runs on version tags:

name: Attest
on:
  push:
    tags: ['[0-9]*.[0-9]*.[0-9]*']
permissions:
  id-token: write        # request the Sigstore signing certificate
  attestations: write    # record the attestation
  contents: write        # attach signed assets to the release
jobs:
  attest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { persist-credentials: false }
      - uses: k2gl/composer-attest-action@v1

On every version tag it builds and attests the tarball, fetches and attests the
Composer dist zipball, and records both in Sigstore's public transparency log —
bound to your repository's GitHub Actions identity. No keys to manage; the signing
certificate is short-lived and issued against your workflow's OIDC token.

Verifying: at install time

k2gl/composer-attest is a Composer
plugin that verifies these attestations as packages are downloaded:

composer require --dev k2gl/composer-attest

As Composer downloads each package, the plugin hashes the dist, asks GitHub for an
attestation bound to that digest, and verifies the Sigstore bundle — checking the
certificate chain, the transparency-log inclusion, and that the signing identity is
a GitHub Actions workflow of the package's own repository. Configure how strict it
is in composer.json:

{
  "extra": {
    "k2gl-attest": {
      "mode": "enforce",
      "require-attestation": false
    }
  }
}

In warn mode it reports and continues; in enforce it fails the install on a
bad attestation. Under the hood it reuses
k2gl/sigstore-verify, a pure-PHP
Sigstore verifier that passes the official sigstore-conformance suite.

Does it work? Here's the proof

The entire k2gl package family attests its dist zipball on every release. Verifying
one against the live GitHub attestations API:

dsse zipball — hasAttestation: yes, verified: YES (k2gl/dsse)

The plugin even verifies itself: composer-attest's own release is attested by
composer-attest-action, and the plugin confirms its own provenance. The loop is
closed — sign with the Action, verify with the plugin, on real published packages.

The honest caveat

The verification is real, but adoption is a chicken-and-egg problem worth stating
plainly. Today almost no package on Packagist attests its dist zipball, so for a
typical project the plugin will mostly report "no attestation." That's not a bug in
the plugin — it's the state of the ecosystem. The plugin verifies whatever is
attested; the more maintainers add the Action, the more it can check.

That's why the Action matters as much as the plugin: it makes attesting a one-line
change, so the pool of verifiable packages can grow. The endgame is registry-level
support — if Packagist hosts attestations directly, client-side verification
becomes the default for the whole registry, and these tools verify it with no
changes.

A PHP starter where the promises are CI jobs, not README adjectives

Nick Harin — Fri, 12 Jun 2026 14:40:08 +0000

Most project skeletons are demos: they run composer install, serve a hello
page, and stop where your actual work begins. We took the opposite route —
Pragmatic FrankenPHP is the template real production projects actually
grew out of, with the lessons ported back. About 25 of the first 40 commits
of the first product built on it were infrastructure repair; every one of
those commits is now pre-paid in the template.

github.com/k2gl/pragmatic-franken — PHP 8.5, Symfony 8, FrankenPHP worker
mode, PostgreSQL 17, Vertical Slices + CQRS over Messenger, MIT.

Claims you can check, not believe

Every marketing sentence in the README is backed by a required CI job:

"The production image boots." The prod-image job builds the real php_prod target on every PR, runs it against Postgres+Redis and asserts /ready returns {"ok":true,"db":true,"redis":true}. (When we added this job, it immediately found three independent reasons the previous image could never start. That's the point.)
"AI agents land green here." The agent-smoke job scaffolds a vertical slice with the same generator agents use (make slice) and requires it to pass Pint + PHPStan level 10 + tests with zero manual edits. On its very first run it caught a code-style drift in the scaffolder.
"You can verify what you deploy." Release images carry SLSA build provenance (GitHub Artifact Attestations, keyless). The deploy script can refuse unverified images, and bin/console app:verify-attestation verifies any artifact offline in pure PHP (k2gl/sigstore-verify — passes the official sigstore-conformance suite). The test suite commits a real signed artifact and proves fail-closed behavior: one tampered byte → rejected.
"Docs don't lie." make docs-check is a CI gate that greps every claimed route, make target and ADR reference against the codebase. The agent-facing context file (AGENTS.md, ≤2000 tokens, budget-linted) cannot silently drift from reality.

What's actually inside

A real example vertical: Task entity → migration → typed repository → Foundry factory → validated 422 problem+json → e2e tests → async TaskCompleted event → Mercure publish to the /tasks topic. Delete it with one flag when you start your own domain (make init name=my-app prune=1).
SharedKernel ported from production: typed DoctrineRepository<T> (PHPStan level 10, zero magic), RFC 9457 problem+json listeners, worker heartbeat for container healthchecks.
A deploy story that ends in production: blue-green rollout gated on /ready (a failing container never replaces the old one), pre-migration dumps, encrypted off-site backups with a documented restore drill, front Caddy with dynamic upstreams — all on one cheap VDS.
Parallel agent sessions: dev/worktree.sh spins isolated stacks (own branch, own docker project, own port slot) so several Claude/Codex sessions work without colliding.
Opt-in recipes instead of bloat: JWT auth (production-proven configs), feature flags, SPA frontend, PR preview environments.

Non-goals (on purpose)

No auth in core (it's a product decision — recipe included), no bundled SPA,
no Kubernetes, no multi-DB. A template that won't say "no" accretes
everything and dies.

Try it

gh repo create my-app --template k2gl/pragmatic-franken --clone && cd my-app
make install && make init name=my-app && make smoke

# or straight from Packagist:
composer create-project k2gl/pragmatic-franken my-app

Feedback welcome — especially the critical kind. All 17 architecture
decision records are in the repo.