security: verifiable release gates — every leak type, every artifact type

[lmeyerov]

What was actually happening

Two different files, two different stories — worth separating, since the concern raised was about both:

	tracked?	in main?	in 0.9.0 sdist?
plans/	no — gitignored	0 files	0 entries
plan.md	yes, since c35e416 (2025-08-02)	yes	yes
weekly_report.md	yes	yes	yes

plans/ was never the problem. It was tracked historically, removed long ago, and is gitignored — verified absent from both main and the published 0.9.0 sdist.

The root-level plan.md and weekly_report.md are ordinary tracked files predating this work by a year. Nothing was force-pushed.

They shipped because setuptools' default sdist sweeps in top-level files and the whole test tree unless a MANIFEST.in says otherwise — so tests/ and .env.example went out too. Wheels were never affected.

Fix

• Untrack plan.md and weekly_report.md; gitignore both.
  Anchored as /plan.md — an unanchored entry would also ignore the plan skill's plans/<task>/plan.md files, which are meant to be creatable.
• MANIFEST.in pruning tests, plans, templates, the checked-in test-env-310 virtualenv, and the internal top-level files.
• Sdist: 550 KB → 425 KB (23% smaller). Verified by building and listing the archive — zero matches for any internal path.

Enforcement

tests/unit/test_packaging_hygiene.py fails if internal material becomes tracked again, or if MANIFEST.in loses its exclusions, or if the .gitignore entry is written unanchored.

It earned its keep immediately: I wrote it expecting only plan.md, and it caught weekly_report.md, which I had missed. Nothing had been checking this, which is why it shipped for a year.

Release gates: every leak type, every artifact type

MANIFEST.in is a rule, not an artifact. What actually ships is decided by setuptools defaults and which files happen to be tracked, so a clean repo can still build a dirty archive — which is how plan.md reached PyPI sixteen times. scripts/ci/check_sdist.py opens the archive that is about to be uploaded.

Two surfaces, two gates:

	repository contents	release artifacts
gate	scripts/ci/secret-detection.sh	scripts/ci/check_sdist.py
runs in	quality-checks, pre-commit	every job running python -m build: install-test + both publish.yml jobs
covers	tracked / staged files	what is inside the .tar.gz and .whl

The screen was incomplete

It checked forbidden paths and Graphistry key shapes. An AWS key, a private key block, a keyword-adjacent value or a high-entropy string in a shipped file passed it. Now it also sweeps the extracted archive with detect-secrets, compared against .secrets.baseline.

Archive paths are normalized back to repository paths before comparison — a wheel ships louieai/ where the repo has src/louieai/, and PKG-INFO / METADATA are generated from README.md; without the mapping every artifact finding looks new. Unrecognised paths are left alone, so they fail closed rather than being quietly mapped onto an allowlisted path.

One trap, same shape as the original defect

detect-secrets scan enumerates files through git. In an extracted archive — not a repository — a bare scan exits 0, emits valid JSON, and reports zero findings no matter what the archive contains:

detect-secrets scan               -> 0 finding(s)
detect-secrets scan --all-files   -> 40 finding(s)

That is the same failure class as the gate that started this: a command that cannot fail. --all-files is mandatory here, and a regression test pins it.

Proof that it rejects

tests/unit/security/test_release_artifact_gates.py — 28 cases, a full matrix. It builds real .tar.gz and .whl archives with a real leak planted in each:

leak type	caught by
Graphistry personal key id	literal gate
Graphistry personal key secret	literal gate
internal hostname (*.grph.xyz)	literal gate
AWS access key	detect-secrets sweep
private key block	detect-secrets sweep
keyword-adjacent value	detect-secrets sweep
high-entropy string	detect-secrets sweep
internal-notes path (plan.md)	path list
test-tree path (tests/)	path list

Three controls keep the matrix honest:

1. A clean archive of each type must pass — otherwise "rejects everything" would satisfy every assertion above while blocking all releases.
2. Attribution: each sweep-caught leak is re-run with the sweep disabled and must then survive. If an AWS key were only ever caught incidentally by the literal gate's shape matching, the sweep could rot away silently and the matrix would stay green.
3. detect-secrets missing fails the module rather than skipping it. A skipped security test is indistinguishable from a passing one in CI output.

Plus a wiring test: each workflow must screen at least as often as it runs python -m build.

Verified end to end

Real literals planted in src/louieai/__init__.py, built with python -m build, and rejected in both the sdist and the wheel by both gates:

louieai-…tar.gz: credential-shaped content:
  src/louieai/__init__.py:265: hard-coded personal_key_id literal [value-shape]
  src/louieai/__init__.py:266: hard-coded internal host literal [internal-host]
louieai-…tar.gz: detect-secrets findings:
  src/louieai/__init__.py:264: new secret detected [AWS Access Key]
… same for the .whl …
exit=1

The current release artifacts screen clean.

Validation

638 passed, 5 skipped; lint, format, mypy, both secret gates, uv lock --check, strict docs all pass.

Takes effect next release; 0.9.0 on PyPI is unaffected and contains no credentials (verified before tagging).

🤖 Generated with Claude Code

https://claude.ai/code/session_01MyiG851jxkDkqB5u9gnpox