gestate 1.0.0__tar.gz

gestate-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --group docs --frozen
+      - run: uv run zensical build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

gestate-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

gestate-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+build/
+dist/
+site/
+*.egg-info/
+
+.coverage
+htmlcov/
+
+.DS_Store

gestate-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lincoln Loop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gestate-1.0.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: gestate
+Version: 1.0.0
+Summary: Set a minimum release age on local package managers to defend against zero-day supply chain attacks.
+Author-email: Lincoln Loop <chris@lincolnloop.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bun,cooldown,deno,npm,pip,pnpm,security,supply-chain,uv,yarn
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.11
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w>=1.0
+Description-Content-Type: text/markdown
+
+# gestate
+
+Set a minimum release age on local package managers so installs ignore versions younger than `N` days. Most malicious packages are caught and yanked within days of publishing; refusing fresh versions blocks the bulk of supply-chain attacks.
+
+## Run
+
+```
+uvx gestate                  # interactive
+uvx gestate set 3            # 3-day minimum, installed tools only
+uvx gestate set 3 --all      # also pre-configure file-based tools (bun, deno, uv)
+uvx gestate revert           # remove gestate's settings
+uvx gestate explain bun      # show how one tool's setting is stored
+```
+
+Interactive mode always shows a plan and asks for explicit confirmation before touching anything. The subcommands skip the confirm — meant for scripts, not your daily shell. Running with no subcommand outside a TTY exits with an error.
+
+Plain text output is used when stdout isn't a terminal (no Rich tables/colors).
+
+## What it sets
+
+| Tool | Where | Key (unit) |
+|---|---|---|
+| npm  | `~/.npmrc`               | `min-release-age` (days) |
+| pnpm | global pnpm config       | `minimumReleaseAge` (minutes) |
+| yarn | `~/.yarnrc.yml` (4.10+)  | `npmMinimalAgeGate` (minutes) |
+| bun  | `~/.bunfig.toml`         | `[install] minimumReleaseAge` (seconds) |
+| deno | shell profile            | `alias deno='command deno --minimum-dependency-age=P<N>D'` |
+| pip  | user pip config          | `global.uploaded-prior-to` (`P<N>D`) |
+| uv   | `~/.config/uv/uv.toml`   | `exclude-newer` (`"N days"`) |
+
+`gestate explain <tool>` prints that tool's current value and the exact mechanism `set` / `revert` use.
+
+Scope:
+- default — only configure installed tools
+- `--all` — also pre-write config files for `bun`, `deno`, `uv` even if they aren't installed yet
+
+## Revert
+
+`uvx gestate revert` removes everything gestate set:
+
+- CLI tools — `config delete` / `config unset`
+- `bun` / `uv` — remove the key; delete the file if it was the only key
+- `deno` — remove our alias line; leave foreign `alias deno=` lines alone
+
+Backups (`.bak`) are written next to any edited shell-profile or TOML file.
+
+## Allowlists
+
+If you publish packages of your own and want them exempt from the delay, see [docs/allowlists.md](docs/allowlists.md). Most managers support an exclude list; npm and pip don't yet.
+
+## Caveats
+
+- **yarn**: 4.10+ only. Older yarn is detected and skipped.
+- **deno**: no global config exists; the shell alias only covers interactive shells. For CI, pass `--minimum-dependency-age=P<N>D` to `deno install`/`deno update`, or commit a project `deno.json` with `"minimumDependencyAge": "P<N>D"`.
+- **npm exclude**: tracked in [npm/cli#8994](https://github.com/npm/cli/issues/8994).
+- **pip exclude**: none — `global.uploaded-prior-to` is global only.
+
+For PR-creation guards (Dependabot, Renovate) and adjacent layers, see [docs/complementary.md](docs/complementary.md).
+
+## Development
+
+```
+uv sync
+uv run pytest
+```
+
+Requires Python 3.11+, macOS or Linux.

gestate-1.0.0/README.md

@@ -0,0 +1,67 @@
+# gestate
+
+Set a minimum release age on local package managers so installs ignore versions younger than `N` days. Most malicious packages are caught and yanked within days of publishing; refusing fresh versions blocks the bulk of supply-chain attacks.
+
+## Run
+
+```
+uvx gestate                  # interactive
+uvx gestate set 3            # 3-day minimum, installed tools only
+uvx gestate set 3 --all      # also pre-configure file-based tools (bun, deno, uv)
+uvx gestate revert           # remove gestate's settings
+uvx gestate explain bun      # show how one tool's setting is stored
+```
+
+Interactive mode always shows a plan and asks for explicit confirmation before touching anything. The subcommands skip the confirm — meant for scripts, not your daily shell. Running with no subcommand outside a TTY exits with an error.
+
+Plain text output is used when stdout isn't a terminal (no Rich tables/colors).
+
+## What it sets
+
+| Tool | Where | Key (unit) |
+|---|---|---|
+| npm  | `~/.npmrc`               | `min-release-age` (days) |
+| pnpm | global pnpm config       | `minimumReleaseAge` (minutes) |
+| yarn | `~/.yarnrc.yml` (4.10+)  | `npmMinimalAgeGate` (minutes) |
+| bun  | `~/.bunfig.toml`         | `[install] minimumReleaseAge` (seconds) |
+| deno | shell profile            | `alias deno='command deno --minimum-dependency-age=P<N>D'` |
+| pip  | user pip config          | `global.uploaded-prior-to` (`P<N>D`) |
+| uv   | `~/.config/uv/uv.toml`   | `exclude-newer` (`"N days"`) |
+
+`gestate explain <tool>` prints that tool's current value and the exact mechanism `set` / `revert` use.
+
+Scope:
+- default — only configure installed tools
+- `--all` — also pre-write config files for `bun`, `deno`, `uv` even if they aren't installed yet
+
+## Revert
+
+`uvx gestate revert` removes everything gestate set:
+
+- CLI tools — `config delete` / `config unset`
+- `bun` / `uv` — remove the key; delete the file if it was the only key
+- `deno` — remove our alias line; leave foreign `alias deno=` lines alone
+
+Backups (`.bak`) are written next to any edited shell-profile or TOML file.
+
+## Allowlists
+
+If you publish packages of your own and want them exempt from the delay, see [docs/allowlists.md](docs/allowlists.md). Most managers support an exclude list; npm and pip don't yet.
+
+## Caveats
+
+- **yarn**: 4.10+ only. Older yarn is detected and skipped.
+- **deno**: no global config exists; the shell alias only covers interactive shells. For CI, pass `--minimum-dependency-age=P<N>D` to `deno install`/`deno update`, or commit a project `deno.json` with `"minimumDependencyAge": "P<N>D"`.
+- **npm exclude**: tracked in [npm/cli#8994](https://github.com/npm/cli/issues/8994).
+- **pip exclude**: none — `global.uploaded-prior-to` is global only.
+
+For PR-creation guards (Dependabot, Renovate) and adjacent layers, see [docs/complementary.md](docs/complementary.md).
+
+## Development
+
+```
+uv sync
+uv run pytest
+```
+
+Requires Python 3.11+, macOS or Linux.

gestate-1.0.0/RELEASE.md

@@ -0,0 +1,38 @@
+# Releasing
+
+## Publishing to PyPI
+
+Requires PyPI credentials in your keyring (see below).
+
+Tag the current release and push it:
+
+```bash
+git pull
+git tag --list "v*"
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push --tags
+```
+
+Build and publish:
+
+```bash
+rm -rf dist
+uv build
+uv publish
+```
+
+## PyPI Credentials Setup
+
+Install keyring (used by uv for publishing) and set your token:
+
+```bash
+uv tool install keyring
+keyring set 'https://upload.pypi.org/legacy/' __token__
+```
+
+Add these environment variables to your shell:
+
+```bash
+export UV_KEYRING_PROVIDER=subprocess
+export UV_PUBLISH_USERNAME=__token__
+```

gestate-1.0.0/docs/allowlists.md

@@ -0,0 +1,65 @@
+# Allowlists
+
+Each manager (where supported) lets you exempt specific packages from the release-age delay. Useful for your own org's packages and trusted hotfixes.
+
+## bun — `minimumReleaseAgeExcludes`
+
+`~/.bunfig.toml`:
+
+```toml
+[install]
+minimumReleaseAge = 604800
+minimumReleaseAgeExcludes = ["@myorg/*", "typescript"]
+```
+
+Globs allowed. Matches every version of the package.
+
+## yarn — `npmPreapprovedPackages`
+
+`~/.yarnrc.yml`:
+
+```yaml
+npmMinimalAgeGate: 10080
+npmPreapprovedPackages:
+  - "@myorg/*"
+  - "@aws-sdk/types@3.877.0"
+```
+
+Globs or exact `name@version` locators.
+
+## pnpm — `minimumReleaseAgeExclude`
+
+`pnpm-workspace.yaml` (or `.npmrc` with kebab-case keys):
+
+```yaml
+minimumReleaseAge: 10080
+minimumReleaseAgeExclude:
+  - '@myorg/*'
+  - nx@21.6.5
+  - 'webpack@4.47.0 || 5.102.1'
+```
+
+Package name, glob, or `name@version-range`.
+
+## uv — `exclude-newer-package`
+
+`pyproject.toml`:
+
+```toml
+[tool.uv]
+exclude-newer-package = { requests = "ALLOW_ANY", setuptools = "30 days" }
+```
+
+`ALLOW_ANY` bypasses the cooldown for that package; a duration string applies a different window.
+
+## npm — not shipped
+
+Tracked in [npm/cli#8994](https://github.com/npm/cli/issues/8994). Until then, `min-release-age` is global only.
+
+## pip — no equivalent
+
+`global.uploaded-prior-to` is global. Pinning a specific newer version in `requirements.txt` is the workaround.
+
+## deno — no equivalent
+
+`--minimum-dependency-age` is global per invocation.

gestate-1.0.0/docs/complementary.md

@@ -0,0 +1,64 @@
+# Complementary Controls
+
+`gestate` guards the **install** step. Pair it with controls at other layers for defense in depth.
+
+## PR-creation layer
+
+Stop bump PRs from landing fresh versions in the first place.
+
+### Dependabot cooldown (GitHub-native)
+
+Added July 2025. Configured per ecosystem in `.github/dependabot.yml`:
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: daily
+    cooldown:
+      default-days: 7
+      semver-major-days: 14
+```
+
+Supported on all Dependabot ecosystems. Different cooldowns per semver bump type are allowed.
+
+See: <https://github.blog/changelog/2025-07-01-dependabot-supports-configuration-of-a-minimum-package-age/>
+
+### Renovate `minimumReleaseAge`
+
+Renovate has shipped this for years. Set in `renovate.json`:
+
+```json
+{
+  "minimumReleaseAge": "7 days"
+}
+```
+
+Applies to all managers Renovate supports (npm, pip, cargo, gomod, etc.).
+
+## Install-script layer
+
+Most supply-chain payloads execute via `postinstall` / `preinstall` hooks. Disable them unless explicitly needed.
+
+- **npm**: `npm config set ignore-scripts true` (global). Allow per-package via dedicated trusted lists.
+- **pnpm**: `onlyBuiltDependencies` in `package.json` — explicit allowlist for which packages may run install scripts.
+- **bun**: `trustedDependencies` in `package.json`.
+
+## Lockfile + provenance layer
+
+- **Lockfiles committed**: `package-lock.json`, `pnpm-lock.yaml`, `bun.lock`, `uv.lock` — pin exact resolved versions so a malicious republish under the same range can't slip in silently.
+- **npm provenance**: `npm publish --provenance` ties published artifacts to a verifiable CI build. Consumers can check `npm view <pkg> --json` for the `dist.attestations` field.
+- **Sigstore / SLSA**: same idea, broader ecosystem coverage.
+
+## Layer summary
+
+| Layer | Tool | Catches |
+|-------|------|---------|
+| PR creation | Dependabot cooldown, Renovate `minimumReleaseAge` | Bump PRs for fresh versions |
+| Install resolution | `gestate` (this repo) | Direct + transitive + ad-hoc installs, CI without bots |
+| Install scripts | `ignore-scripts`, `onlyBuiltDependencies`, `trustedDependencies` | Lifecycle-hook payloads |
+| Identity | Lockfiles, provenance, Sigstore | Republish / typosquat / impersonation |
+
+No single layer is sufficient. The install-time guard in this repo is the broadest net; the others narrow specific attack paths.

gestate-1.0.0/docs/index.md

@@ -0,0 +1,37 @@
+---
+icon: lucide/shield-check
+---
+
+# gestate
+
+Set a minimum release age on local package managers so installs ignore versions younger than `N` days. Most malicious packages are caught and yanked within days of publishing; refusing fresh versions blocks the bulk of supply-chain attacks.
+
+## Run
+
+```sh
+uvx gestate                  # interactive
+uvx gestate set 3            # 3-day minimum, installed tools only
+uvx gestate set 3 --all      # also pre-configure file-based tools (bun, deno, uv)
+uvx gestate revert           # remove gestate's settings
+uvx gestate explain bun      # show how one tool's setting is stored
+```
+
+Interactive mode always shows a plan and asks for confirmation before touching anything. The subcommands skip the confirm — meant for scripts, not your daily shell.
+
+## What it configures
+
+| Tool | Where | Key (unit) |
+|---|---|---|
+| npm  | `~/.npmrc`               | `min-release-age` (days) |
+| pnpm | global pnpm config       | `minimumReleaseAge` (minutes) |
+| yarn | `~/.yarnrc.yml` (4.10+)  | `npmMinimalAgeGate` (minutes) |
+| bun  | `~/.bunfig.toml`         | `[install] minimumReleaseAge` (seconds) |
+| deno | shell profile            | `alias deno='command deno --minimum-dependency-age=P<N>D'` |
+| pip  | user pip config          | `global.uploaded-prior-to` (`P<N>D`) |
+| uv   | `~/.config/uv/uv.toml`   | `exclude-newer` (`"N days"`) |
+
+## More
+
+- [Allowlists](allowlists.md) — exempt your own packages from the delay
+- [Complementary controls](complementary.md) — pair gestate with PR-creation guards and other defense layers
+- [Source on GitHub](https://github.com/lincolnloop/gestate)

gestate-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "gestate"
+version = "1.0.0"
+description = "Set a minimum release age on local package managers to defend against zero-day supply chain attacks."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Lincoln Loop", email = "chris@lincolnloop.com" }]
+keywords = ["supply-chain", "security", "cooldown", "npm", "pip", "uv", "pnpm", "bun", "yarn", "deno"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Topic :: Security",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Installation/Setup",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = [
+    "rich>=13",
+    "tomli-w>=1.0",
+]
+
+[project.scripts]
+gestate = "gestate.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+docs = ["zensical>=0.0.43"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gestate"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

gestate-1.0.0/src/gestate/__init__.py

@@ -0,0 +1,3 @@
+"""Configure package managers with a minimum release age."""
+
+__version__ = "1.0.0"

gestate-1.0.0/src/gestate/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())