Download the PHP package innobrain/soak-time without Composer

Innobrain Soak Time 🛡️

A Composer plugin that enforces a soak time — a minimum age — on every package version before install. New releases stay out of the solver pool until they age past the threshold, blocking zero-day malicious releases (typosquats, account takeovers, malicious co-maintainer pushes).

A date filter alone is defeatable: an attacker can force-push an old tag at a malicious commit with a backdated GIT_COMMITTER_DATE, and Packagist serves that timestamp. Packagist.org locks the source and dist reference of stable versions and refuses moved tags (composer/packagist#1742, docs) — but only for stable versions on packagist.org. The plugin pins each version's git SHA, source URL, dist URL, and dist sha256 in composer-integrity.lock, extending that protection to dev versions, the local download cache, and non-packagist sources, and hard-fails on any later drift. See SECURITY_MODEL.md.

🧭 How it works

Four checks run on every install/update:

Pins are written to composer-integrity.lock when a version is first seen (trust-on-first-use) and verified on every later run.

📦 Installation

Upgrading from ≤ v1.3.0? composer update fails because the old SoakTimeConfig is still in PHP memory. Reinstall instead: composer global remove innobrain/soak-time && composer global require innobrain/soak-time (or the --dev equivalents).

⚙️ Configuration

Default soak time is 168h (7 days). Configure via extra in composer.json:

• Per-run override: SOAK_TIME_HOURS=336 composer update (takes precedence; ignored with a warning if not a non-negative integer).
• Whitelist bypasses the soak filter for trusted packages that update constantly. * is allowed in the name half only — the vendor must be a literal (your-company/*, your-company/lib-*). Vendor-side wildcards (*/x, */*, *) are rejected. SOAK_TIME_SKIP accepts the same patterns.
• Versions with no release date are filtered unless whitelisted. Whitelist path/internal repos only if you trust their metadata.
• Already-locked versions are exempt. The soak window gates adopting a fresh version during resolution; a version already pinned in composer.lock was adopted earlier, so it passes through. This keeps composer install deterministic and stops a partial update (composer require x) from failing on an unrelated, freshly-published dependency you already have locked. Adopting a new or bumped version still gets gated; the artifact itself is still guarded by the integrity checks.

Windows PowerShell sets env vars as $env:SOAK_TIME_HOURS=336; composer update.

Per-package soak time (soak-time-package-hours)

Give individual packages their own soak window — shorter for dependencies you need to track closely, longer for ones you want extra caution on — without touching the global one:

Per-run override as comma-separated pattern:hours pairs:

Patterns follow the whitelist rules (literal vendor, * only in the name half); the first matching entry wins, and env entries beat composer.json ones. This is the scoped alternative to lowering SOAK_TIME_HOURS globally: every other package keeps the full window. Versions with no release date are still dropped — use the whitelist for full bypass.

Security-fix window (soak-time-security-hours)

When the version you have locked is affected by a published security advisory, waiting out the full soak window means running known-vulnerable code for a week. The scoped security override shortens the wait for exactly the versions that fix it: a version younger than the soak window is still admitted if it

1. has aged past the security window (default 72h), and
2. clears every advisory affecting the locked version of that package (per the same registry advisory data composer audit uses).

Per-run override: SOAK_TIME_SECURITY_HOURS=48 composer update. Set it to a value ≥ soak-time-hours to disable the override entirely (no advisory lookups are made then).

This codifies the "temporarily run with SOAK_TIME_HOURS=72" routine with a much smaller attack surface: the shorter window applies per package, only while your locked version is known-vulnerable, and the admitted fix still has to soak. Every admission is reported loudly with the advisory IDs that justified it. Advisory lookups happen lazily — only for a locked package whose fresh version would otherwise be dropped — and a failed lookup falls back to the full soak window. See SECURITY_MODEL.md for the residual risks.

Dev branches (soak-time-dev-branches)

Dev versions like dev-main or 1.x-dev are mutable — their sourceReference (git SHA) legitimately changes every time the branch advances. By default the plugin treats every version as immutable and hard-fails if a pinned reference drifts. That would make composer update permanently broken for any dev-branch dependency once the branch advances.

Declare the packages whose dev versions are intentionally mutable:

Or pass the list as a comma-separated env var for a one-run override:

Patterns follow the same rules as the whitelist — vendor must be a literal, * is allowed only in the name half.

Security trade-off: for a declared dev package, the source reference is allowed to advance when isDev() is true. However, if the reference is unchanged but the downloaded archive's sha256 differs, the plugin still hard-fails — that is cache poisoning of a fixed SHA, not legitimate branch movement. Stable versions are never treated as mutable regardless of this list.

Undeclared dev versions whose reference changed are blocked with an error that names soak-time-dev-branches so you know how to unblock them after investigation.

Ignoring packages (soak-time-integrity-ignore)

Some Composer plugins install multiple dist archives under a single package@version. The clearest example is statamic/cms, which uses pixelfear/composer-dist-plugin to fetch both dist.tar.gz and dist-frontend.tar.gz — both presenting as statamic/cms@dist. The integrity model keys one set of metadata per package@version, so the second archive looks exactly like a drifted dist URL and hard-fails:

There is no safe way to auto-support this: accepting a new dist URL under an already-pinned version on a package's say-so is precisely the altered-historical-release surface the plugin exists to close. Instead, manually greenlight the package after verifying its installs:

Or as a comma-separated env var for a one-run override:

Patterns follow the same rules as the whitelist — vendor must be a literal, * is allowed only in the name half. A listed package is exempt from all integrity checks (drift, hash, and recording); a warning naming the ignored package(s) is printed on every run so the weakened coverage stays visible. The soak/freshness filter is unaffected.

🔐 Integrity lock file

composer-integrity.lock records each version's sha256 (when Composer exposes the archive), sourceReference, sourceUrl, distUrl, and firstSeenAt. Commit it alongside composer.lock — later installs verify against it and hard-fail on drift.

Packages from path repositories are exempt from integrity pinning entirely: they are local code in the same trust domain as the root project, have no archive hash or source reference to pin, and would otherwise fail every install.

Some paths (including plugin self-update) install from dist without exposing the archive; the plugin then fails closed — fix with composer global reinstall innobrain/soak-time --prefer-source. Opt out (not recommended) with soak-time-integrity: false, or relocate via soak-time-integrity-lock:

🚨 Emergency skip

Security fixes for advisories affecting your locked versions are admitted automatically after the security window (72h by default). For a fix that cannot wait even that long, skip the freshness filter for one package (integrity checks still run):

SOAK_TIME_SKIP=1 skips freshness for the whole run.

🔍 Troubleshooting

Run composer update -v to see dropped versions. If the soak time hides every version of a required package, resolution fails — the plugin names the package and its newest version's age up front. Fix with a scoped SOAK_TIME_PACKAGE_HOURS=vendor/package:X (preferred), a global SOAK_TIME_HOURS=X, whitelisting it, or a one-run SOAK_TIME_SKIP.

🙏 Credits & License

Fork of cotonet/soak-time by Cotonet - Resiliência Digital. MIT License — see LICENSE. Copyright Cotonet - Resiliência Digital (original) and Innobrain GmbH (fork).