safeuploads 1.1.2__tar.gz → 2.0.0__tar.gz

safeuploads-2.0.0/.agents/skills/conventional-commits/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: conventional-commits
+description: Write commit messages, commit titles and pull request titles/descriptions for safeuploads following Conventional Commits. Use whenever creating a git commit, amending or squashing commits, or opening/updating a pull request.
+---
+
+# Conventional Commits for safeuploads
+
+Every commit subject and every PR title is validated in CI by `.github/workflows/conventional-commits.yml`
+(script: `.github/scripts/check_conventional_commits.py`). A non-compliant title blocks the PR, so get it
+right the first time.
+
+## Header format
+
+```
+<type>(<scope>)!: <description>
+```
+
+- `(<scope>)` and `!` are optional.
+- A single space after the colon is required.
+- Only the first line is validated; the body and footers are free-form.
+
+### Allowed types (project whitelist)
+
+| Type | Use for |
+| --- | --- |
+| `feat` | New public capability |
+| `fix` | Bug fix (including security fixes) |
+| `docs` | Documentation only (`docs/`, README, comments) |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `perf` | Performance improvement |
+| `test` | Adding or correcting tests |
+| `build` | Build system, dependencies, packaging |
+| `ci` | CI configuration and workflows |
+| `chore` | Maintenance that fits nowhere else (version bumps, housekeeping) |
+| `style` | Formatting only, no logic change |
+| `revert` | Reverting a previous commit |
+
+Any other type (e.g. `feature`, `bugfix`, `security`, `deps`) fails validation.
+
+### Scope
+
+Optional, any non-empty string without parentheses.
+Prefer the package or area touched, matching what recent history uses: `validators`, `inspectors`, `config`, `audit`, `utils`, `docs`, `deps`.
+Omit the scope when the change spans many areas.
+
+### Description
+
+- Imperative mood, describes what the change does: `add polyglot check`, not `added` / `adds`.
+- Specific, not vague (`fix: bound nested archive depth`, not `fix: bug`).
+- No trailing period; keep the header readable (aim for ~72 characters or fewer).
+
+### Breaking changes
+
+Mark with `!` after the type/scope and/or a `BREAKING CHANGE: <explanation>` footer in the body.
+Use whenever the public API (see `docs/api-stability.md` where it exists), a configuration field, an error code or the stored schema changes in a way that requires action from users.
+
+## Examples
+
+```
+feat(validators): add a polyglot signature check
+fix(inspectors): bound nested archive depth
+docs: update the integration checklist
+test(fuzz): add regression test for a Unicode filename
+refactor(config)!: rename SecurityLimits.max_size to max_file_size
+chore: bump version to 1.1.4
+```
+
+## Committing
+
+1. Inspect the change first: `git status`, `git diff --staged` (and `git log --format=%s -10` to match recent style and scopes).
+2. Choose the type by the *primary intent* of the change. If a diff mixes unrelated concerns, split it into separate commits, one concern each.
+3. Write the header per the rules above. Add a body (blank line after the header) only when the *why* isn't obvious; wrap at ~72 columns.
+4. Reference issues in the body/footer, e.g. `Closes #123` or `Refs #123`.
+5. Do not use `--no-verify`, and do not rewrite or force-push shared history unless explicitly asked.
+6. Include any attribution/co-author trailer that the session instructs you to add.
+
+Optionally self-check before committing:
+
+```bash
+python3 .github/scripts/check_conventional_commits.py "feat(scope): your header"
+```
+
+## Pull requests
+
+Opening or updating a PR (title, template, `gh pr create`): read `references/pull-requests.md`.
+A PR title must itself be a valid header; every non-merge commit subject on the branch is validated too.

safeuploads-2.0.0/.agents/skills/conventional-commits/references/pull-requests.md

@@ -0,0 +1,19 @@
+# Pull requests
+
+- **PR title**: must itself be a valid Conventional Commit header (same rules and whitelist). If the PR
+  has a single commit, reuse its header. If it has several, write one header that summarizes the whole
+  change, with the type of the most significant change.
+- **Commits in the PR**: every non-merge commit subject on the branch is validated too, so make sure each
+  one complies before pushing (`git log --no-merges --format=%s origin/main..HEAD`). Fix offenders
+  with an interactive-free approach (e.g. `git commit --amend` for the last commit) or ask the user.
+- **PR description**: fill in `.github/PULL_REQUEST_TEMPLATE.md`:
+  - *What does this PR do?* - clear description of the change and why.
+  - *Related issue* - `Closes #XYZ` so it auto-closes; required for anything beyond a small fix/typo.
+  - *Type of change* - tick the matching boxes.
+  - *Checklist* - tick only what is true (single concern, ~300 lines max excluding lockfiles/migrations/
+    generated code, tests and docs updated, Conventional Commits followed).
+  - *Notes for the reviewer* - tricky areas, alternatives considered, screenshots.
+- A `feat` PR, a refactor or a public API change needs prior discussion in an issue, linked in the description (see `CONTRIBUTING.md`).
+- A public API change also needs a `CHANGELOG.md` entry.
+- Base branch is `main`. Create the PR with `gh pr create --title "<header>" --body "<filled template>"`.
+  Pushing and opening a PR are outward-facing: only do so when the user asked.

safeuploads-2.0.0/.agents/skills/debugging/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: debugging
+description: Root-cause workflow for bugs, failing tests and CI failures. Use before changing code to fix unexpected behavior.
+---
+
+# Debugging
+
+## Order of work
+
+1. Reproduce the failure with a command or a test; if you cannot reproduce it, say so instead of guessing.
+2. Read the full error and trace it to the first wrong value or call, not the line that raised.
+3. State the cause in one sentence and confirm it with evidence (a log, a failing assertion, a minimal call).
+4. For a behavior bug, write a failing test that captures it (`safeuploads-library` `references/testing.md`); for a lint, type or environment failure, the original failing command is the check.
+5. Fix the cause with the smallest change; do not patch the symptom or widen the change.
+6. Run the new test, then the area's tests, then the checks listed in the `safeuploads-library` skill.
+
+## Rules
+
+- Change one thing at a time; revert an attempt that did not help before trying the next.
+- After two failed fixes, stop and re-read the evidence; the diagnosis is probably wrong.
+- Never skip, loosen or delete a test to get green, and never lower `fail_under` to pass the coverage gate.
+- Reproduce a CI failure locally with the job's command when feasible; if runner-specific conditions block that, record the CI evidence and verify the fix in CI.
+- Report what was verified and what was not; do not say "fixed" without a passing run.

safeuploads-2.0.0/.agents/skills/safeuploads-library/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: safeuploads-library
+description: safeuploads library conventions (validators, inspectors, config, fail-closed security). Use when adding, moving, refactoring or reviewing code in safeuploads/ or tests/.
+---
+
+# safeuploads library
+
+`docs/security/architecture.md` states the pipeline and component roles, `docs/security/threat-model.md` the threats each check answers and `docs/api.md` the public API.
+Where this skill and any of them disagree, they win.
+
+## Core rules (always apply)
+
+- Fail closed: reject what cannot be positively accepted; never turn a failed check into a log line.
+- One validator or inspector per concern, extending `BaseValidator` where it validates; `FileValidator` orchestrates and holds no check logic of its own.
+- A new limit or allow-list entry lives in `FileSecurityConfig` or `SecurityLimits`, with its cross-field validation and a docs entry.
+- Never loosen a default (limit, allow-list, block-list, ratio, depth) to make a test or one caller pass; ask first.
+- Keep the filename check order: Unicode sanitization, then Windows reserved names, then the remaining normalization.
+- Raise a `safeuploads.exceptions` subclass with its `ErrorCode`; the message is safe to show a caller and never contains file contents or filesystem paths.
+- Blocking work (archive inspection, hashing, magic) stays off the event loop; use the existing worker-thread offload and `executor` option.
+- A released `ErrorCode` never changes meaning; a new failure mode gets a new code.
+- A new public name goes in `safeuploads/__init__.py` (`__all__`), `docs/api.md`, the README example if it changes usage, and `CHANGELOG.md`.
+- A rename, removal, signature change, default change that accepts or rejects different input, or `ErrorCode` change is breaking: mark it `!` and say so in the changelog.
+- KISS, YAGNI, DRY: search the package for an existing helper first; add no parameter, protocol or config field without a current caller; extract on the third repetition.
+- Comments and docstrings say what the code does now and why; history goes in the commit message.
+
+## Read on demand
+
+| When you are | Read |
+| --- | --- |
+| Writing code, docstrings, logging, errors or typing | `references/code-standards.md` |
+| Writing or fixing tests, fuzzing or corpus work | `references/testing.md` |
+| Adding or changing a check, limit, parser or anything on the threat model | `references/security.md` |
+
+## Before finishing
+
+```bash
+uv run ruff check safeuploads tests examples
+uv run ruff format --check safeuploads tests examples
+uv run mypy
+uv run pytest
+```
+
+`uv run pytest` enforces the 90% branch-coverage gate.
+`uv run ty check` is advisory in CI and not a gate.
+`libmagic` must be installed on the machine (`brew install libmagic` or `apt-get install libmagic1`).
+
+## Repo hygiene
+
+- Do only what was asked: no extra docs, summaries or READMEs.
+- Prefer existing patterns and utilities over new files; keep it simple, build only what is needed now, do not repeat existing code.
+- Do not add dependencies, and do not touch CI, publish configuration, supported Python versions or constraints unless asked.
+- Local notes go in `devdocs/`, helper scripts in `devscripts/` (gitignored).
+- Never run `git commit` unless asked; use the `conventional-commits` skill for messages.

safeuploads-2.0.0/.agents/skills/safeuploads-library/references/code-standards.md

@@ -0,0 +1,45 @@
+# Code standards
+
+## Python
+- Python 3.13 syntax (`requires-python = ">=3.13"`): `int | None`, `list[str]`, `dict[str, Any]`; no `typing.Optional/List/Dict`.
+- Lines up to 79 characters, enforced by `ruff format` (`line-length = 79`); keep comments and docstrings within it too.
+- Imports grouped stdlib / third-party / local; `TYPE_CHECKING` to avoid cycles.
+- Every module has a top-level docstring.
+- Comments and docstrings state what the code does now and why. History goes in the commit message.
+- Performance and safety outrank brevity; correctness, explicit logging and clear validation messages matter.
+
+## Docstrings (PEP 257, Google sections)
+Enforced by ruff `D` (`convention = "pep257"`) outside `tests/` and `examples/`.
+- Summary on the opening line, then a blank line, then sections.
+- Every public module, class, function and method has a docstring.
+- `Args`: every parameter of a public function. A `_private` helper gets a summary and `Args` only for a non-obvious parameter.
+- `Returns`: when a value comes back. `Returns: None.` is not required.
+- `Raises`: the exceptions the function raises or deliberately lets propagate, especially the security ones. Omit it when there are none.
+- Classes: summary plus `Attributes`.
+- No examples in docstrings; they belong in `docs/` and `examples/`.
+- A docstring is not a design document: what, then why, in the fewest lines.
+- A docstring with backslashes is a raw string (`r"""`).
+
+## Typing
+- `mypy` runs with `strict = true`; every def is fully and precisely typed, and a bare `Any` is a smell.
+- Do not add `# type: ignore` or `# noqa` to pass; fix the type or the code. A `per-file-ignores` entry in `pyproject.toml` needs a comment saying why.
+- Structural types for uploads live in `protocols.py` (`SeekableFile`, `UploadFileProtocol`); depend on them, not on FastAPI.
+
+## Async
+- Keep validator entry points `async`; never call blocking I/O or CPU-heavy inspection directly in an `async def` (ruff `ASYNC` catches the common cases).
+- Blocking inspection runs through `FileValidator`'s worker-thread offload.
+
+## Errors
+- Raise the subclasses in `exceptions.py` with an `ErrorCode`; a configuration mistake raises `FileSecurityConfigurationError`.
+- Keep the hierarchy: filename, size, MIME, signature, compression and processing errors each have their base; add a new subclass, not a new base.
+- Do not swallow an exception from a check; an inspector that cannot finish rejects (`FileProcessingError` / `ResourceLimitError`).
+
+## Logging
+- `logging.getLogger(__name__)` for diagnostics; security decisions go through `SecurityAuditLogger` with a correlation id.
+- The host owns handlers, levels and formatting; never call `basicConfig`, add handlers or set levels.
+- Never log file contents, or a filename that has not been sanitized.
+- Log text and error wording are not public API.
+
+## Dependencies and extras
+- Runtime dependencies stay `python-magic` and `defusedxml`; FastAPI is the `fastapi` extra and imported lazily.
+- Adding or changing a dependency is a request-level decision: ask first.

safeuploads-2.0.0/.agents/skills/safeuploads-library/references/security.md

@@ -0,0 +1,31 @@
+# Security
+
+`docs/security/threat-model.md` is the list of threats and `docs/security/integration-checklist.md` is what a host must do; update them when a change moves the boundary.
+
+## Fail closed
+- Unknown, unparsable or unverifiable input is rejected.
+- A check never degrades into a warning, a truncated inspection or a default "allow" because a limit was reached; hitting a limit is a rejection.
+- Order matters: normalize and sanitize the name before any extension or reserved-name decision is made on it.
+
+## Filenames and paths
+- Never build a filesystem path from an uploaded filename; the library returns a sanitized name and the host generates the storage name.
+- Reject null bytes, control characters, bidirectional overrides, homoglyph tricks, double extensions, trailing dots/spaces and Windows reserved names.
+- Compare extensions and MIME types case-insensitively against allow-lists; a block-list is a supplement, not the only gate.
+
+## Content
+- Verify the MIME type and the file signature (`python-magic`) against the claimed extension; a mismatch is a rejection.
+- Parse XML only with `defusedxml`; disable DTDs, external entities and network access (XXE, billion laughs).
+- Inspect archives without extracting to disk, and bound compressed and uncompressed size, ratio, entry count, nesting depth and total work (ZIP bombs, recursive archives, gzip bombs).
+- Treat embedded scripts, polyglot signatures and executable payloads in content analysis as hostile.
+
+## Resource limits
+- Bound memory, CPU time and wall time per validation (`ResourceMonitor`, `SecurityLimits`); stream large files in chunks instead of reading them whole.
+- A new limit has a conservative default, validation in `FileSecurityConfig`/`SecurityLimits` and a test on both sides of the boundary.
+- Concurrency and rate limiting belong to the host (`docs/rate-limiting.md`); the library only bounds the cost of one validation.
+
+## Secrets and logging
+- No secrets in code, tests or examples.
+- Audit events carry a correlation id and sanitized identifiers; never file contents or raw, unsanitized filenames.
+- Error messages are safe to show a client: no paths, stack detail or internal limits beyond what the code already exposes.
+
+When you add a mitigation, state what it protects against; when you flag a vulnerability, explain the risk.

safeuploads-2.0.0/.agents/skills/safeuploads-library/references/testing.md

@@ -0,0 +1,23 @@
+# Testing
+
+- Tests live in `tests/`, files `test_*.py`, grouped in `Test*` classes; validator and inspector tests mirror the package under `tests/validators/` and `tests/inspectors/`; shared fixtures in `tests/conftest.py`.
+- Every new check has at least one accepted payload and one hostile payload, and covers the boundary on both sides of each limit.
+- Build hostile inputs in memory (ZIP bombs, nested archives, polyglots, XXE documents, Unicode tricks); never commit real malware or a large binary.
+- Cover empty/None, zero-length, truncated, malformed and over-limit input, and assert the exception type and `ErrorCode`, not only that something raised.
+- `with pytest.raises(...) as exc_info` for exceptions.
+- Async tests: `async def test_*` (`asyncio_mode = "auto"`).
+- Markers are declared in `pyproject.toml` (`unit`, `integration`, `slow`, `performance`, `fuzz`) and run with `--strict-markers`; mark a new test accordingly.
+- Skips need `reason=`.
+- Coverage is branch coverage with `fail_under = 90`; it is a ratchet, raise it when coverage rises and never lower it.
+- Tests are deterministic and offline; a performance test asserts a generous bound, never an exact time.
+- Do not mock a validator to test the orchestrator's decision; run the real one on a small payload.
+
+## Fuzzing
+- Property tests use Hypothesis under `tests/fuzz/` (`test_fuzz_filenames.py`, `test_fuzz_zip.py`, `test_fuzz_images.py`, `test_fuzz_config.py`) and run weekly in CI (`fuzz.yml`) as well as in the suite.
+- A fuzz failure that is a real bug becomes a fixed regression test with the minimal reproducer; do not only raise the example count or add `assume()` to hide it.
+
+```bash
+uv run pytest tests/validators -v
+uv run pytest -m "not performance and not fuzz"
+uv run pytest --cov=safeuploads --cov-report=term-missing
+```

safeuploads-2.0.0/.agents/skills/skill-authoring/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: skill-authoring
+description: How to create or edit skills in this repo. Use when adding, splitting, trimming or reviewing a file under .agents/skills.
+---
+
+# Authoring skills for safeuploads
+
+Goal: the least text loaded per task that still prevents the mistakes the skill exists for.
+
+## Where skills live
+
+- Source of truth: `.agents/skills/<name>/SKILL.md`.
+- Expose to Claude Code with a relative symlink: `ln -s ../../.agents/skills/<name> .claude/skills/<name>`.
+- Name is kebab-case and matches the folder.
+
+## What is paid for, and when
+
+| Part | Cost |
+| --- | --- |
+| Frontmatter `description` | Every session, whether used or not |
+| `SKILL.md` body | Each time the skill is invoked |
+| `references/*.md` | Only when the body says to read one and it does |
+
+## Rules
+
+1. **Description:** one sentence of what plus one sentence of when.
+   - No keyword lists; the trigger is the task, not synonyms.
+   - Keep it under about 200 characters.
+2. **Body:** only rules that apply to every use of the skill, ideally under 60 lines.
+3. **References:** put situational detail in `references/<topic>.md`, one topic per file.
+   - Link each from a "read when" table in `SKILL.md`; a reference nothing points to never loads.
+   - Do not nest references from references.
+4. **Do not duplicate a guide.** If `docs/` already states a rule, summarize it in one line and point to the doc; say which wins on conflict.
+5. **Rules, not history.** Leave out incident stories, rationale essays and changelog; keep the rule and, if it is non-obvious, a clause of why.
+6. **Imperative and checkable.** "Run `uv run ruff check .`" beats "ensure code quality".
+7. **Format:** one sentence per line (clean diffs), tables for lookups, code blocks for commands only.
+8. **One concern per skill.** Split by trigger, not by size; do not create several skills that always fire together.
+9. **No secrets or personal paths;** commands are repo-relative.
+10. **KISS, YAGNI, DRY:** no rule, reference or section for a hypothetical case; state each rule once and link to it.
+
+## Splitting an existing skill
+
+1. List what applies to every invocation; that stays in `SKILL.md`.
+2. Group the rest by the task that needs it; one reference file per group.
+3. Add the "read when" table and keep the always-apply rules above it.
+4. Check nothing was lost: every rule is in exactly one place.
+
+## Before finishing
+
+- `wc -l` the body and each reference; reconsider anything over about 100 lines.
+- Confirm the symlink resolves: `ls -L .claude/skills/<name>/SKILL.md`.
+- Invoke the skill on a real task and confirm it reads the reference it should.
+- Skills under `.agents/` and their `.claude/skills` symlinks are tracked; stage a new skill and its symlink together.

safeuploads-2.0.0/.github/copilot-instructions.md

@@ -0,0 +1,5 @@
+# safeuploads
+
+The agent instructions for this repository live in [`AGENTS.md`](../AGENTS.md); follow it.
+
+Detailed conventions are in the skills under [`.agents/skills/`](../.agents/skills/) and in `docs/`.

{safeuploads-1.1.2 → safeuploads-2.0.0}/.github/scripts/check_conventional_commits.py

@@ -27,7 +27,8 @@ from collections.abc import Iterable
 # Allowed types. This whitelist is a *project policy* layered on top of the
 # Conventional Commits 1.0.0 spec (the spec recommends but does not mandate a
 # fixed set of types). Keep this list in sync with the project's commit
-# conventions documented in ``.github/copilot-instructions.md``.
+# conventions documented in the ``conventional-commits`` skill
+# (``.agents/skills``).
 #
 # Per the spec, types are matched case-insensitively.
 ALLOWED_TYPES: tuple[str, ...] = (

{safeuploads-1.1.2 → safeuploads-2.0.0}/.github/workflows/audit-safeuploads.yml

@@ -39,7 +39,7 @@ jobs:
           fetch-depth: 1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.

{safeuploads-1.1.2 → safeuploads-2.0.0}/.github/workflows/conventional-commits.yml

@@ -28,7 +28,9 @@ jobs:
         # before the commit-range check below can run.
         if: github.event.action != 'synchronize'
         # The PR title is untrusted data: passed through an environment variable
-        # (never interpolated into the shell) to the trusted base-ref checker.
+        # (never interpolated into the shell) to the checker, which runs from the
+        # PR's own checkout. The job has read-only permissions
+        # (`contents: read`).
         env:
           PR_TITLE: ${{ github.event.pull_request.title }}
         run: |

{safeuploads-1.1.2 → safeuploads-2.0.0}/.github/workflows/docs.yml

@@ -40,7 +40,7 @@ jobs:
           fetch-depth: 1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.

{safeuploads-1.1.2 → safeuploads-2.0.0}/.github/workflows/fuzz.yml

@@ -28,7 +28,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libmagic1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           version-file: pyproject.toml
 

{safeuploads-1.1.2 → safeuploads-2.0.0}/.github/workflows/lint-and-test.yml

@@ -32,7 +32,7 @@ jobs:
           fetch-depth: 1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.
@@ -50,6 +50,34 @@ jobs:
       - name: Type check with mypy
         run: uv run mypy
 
+  # ----------------------------------------------------------------
+  # Type check with ty (advisory)
+  # ty is pre-1.0 and runs beside mypy for evaluation: findings are
+  # reported but never block a merge. mypy is the gate.
+  # ----------------------------------------------------------------
+  typecheck-ty:
+    name: Type check (ty, advisory)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version-file: pyproject.toml
+
+      - name: Install dependencies
+        # Same environment as the mypy step: ty resolves third-party types from it.
+        run: uv sync --frozen --dev --extra fastapi
+
+      - name: Type check (ty)
+        run: uv run --no-sync ty check --python .venv
+
   # ----------------------------------------------------------------
   # Test
   # Runs the full pytest suite with coverage. Only runs after lint
@@ -68,7 +96,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libmagic1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           version-file: pyproject.toml
 

{safeuploads-1.1.2 → safeuploads-2.0.0}/.github/workflows/publish-safeuploads.yml

@@ -36,7 +36,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.
@@ -149,7 +149,7 @@ jobs:
       id-token: write
     steps:
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           # This job never checks the repository out, so there is no
           # pyproject.toml to read `required-version` from; keep this in step

{safeuploads-1.1.2 → safeuploads-2.0.0}/.github/workflows/test-matrix-safeuploads.yml

@@ -51,7 +51,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libmagic1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.
@@ -78,7 +78,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libmagic1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.

safeuploads-2.0.0/AGENTS.md

@@ -0,0 +1,100 @@
+# safeuploads
+
+Secure file upload validation for Python 3.13+ applications.
+Catches dangerous filenames, malicious extensions, Windows reserved names, compression bombs, polyglots and unsafe XML before an upload is accepted.
+Runtime dependencies are minimal (`python-magic`, `defusedxml`; FastAPI behind the `fastapi` extra).
+Published to PyPI; the public API is governed by SemVer.
+
+## Where the detail lives
+
+| Working on | Read |
+| --- | --- |
+| Library code or tests | `.agents/skills/safeuploads-library/SKILL.md` |
+| Fixing a bug, failing test or CI failure | `.agents/skills/debugging/SKILL.md` |
+| Commit messages and PRs | `.agents/skills/conventional-commits/SKILL.md` |
+| Writing or editing a skill | `.agents/skills/skill-authoring/SKILL.md` |
+| Validation pipeline and component roles | `docs/security/architecture.md` |
+| Threats and mitigations | `docs/security/threat-model.md` |
+| What a host must do to integrate safely | `docs/security/integration-checklist.md` |
+| Public API reference | `docs/api.md` |
+| Rate limiting guidance | `docs/rate-limiting.md` |
+
+Skills are plain Markdown; read the relevant `SKILL.md` and the reference files it points to when your tool does not load skills itself.
+
+## Layout
+
+```text
+safeuploads/    Package: file_validator, config, exceptions, enums, audit, utils, validators/, inspectors/
+tests/          Test suite (unit, integration, fuzz/, performance)
+examples/       Runnable usage examples
+docs/           Documentation site (mkdocs)
+.agents/skills/ Agent skills (symlinked into .claude/skills)
+```
+
+## Commands
+
+From the repository root (Python 3.13+, `uv`, system `libmagic`):
+
+```bash
+uv sync --dev --extra fastapi
+uv run ruff check safeuploads tests examples
+uv run ruff format --check safeuploads tests examples
+uv run mypy
+uv run pytest
+```
+
+## Rules for every change
+
+- Do only what was asked; no extra docs, summaries, READMEs or "helpful" files.
+- Prefer existing patterns, utilities and files over new ones.
+- KISS: pick the simplest design that solves the underlying problem; no indirection, abstraction layer or option without a current need. Simple means few moving parts, not a small diff or a patch over the symptom.
+- YAGNI: build only what the task needs now; no speculative parameters, flags, hooks, config or extension points. What you do build must be complete and proper, not a stub or shortcut.
+- DRY: reuse an existing helper, validator or fixture before writing another; extract shared code at the third repetition, not the second, and only when the copies change for the same reason.
+- Do not add third-party dependencies, and do not change CI workflows, release or publish configuration, supported Python versions, dependency constraints or the `uv` settings unless asked.
+- Never run `git commit` (or any commit-creating command) unless the user explicitly asks; staging for inspection is fine.
+- Commit messages and PR titles follow Conventional Commits (enforced in CI); see the `conventional-commits` skill.
+- Local-only notes go in `devdocs/`, helper scripts in `devscripts/` (both gitignored).
+- No hardcoded secrets; real malware samples never enter the repository, tests build hostile payloads in memory.
+- Ask for clarification when scope is unclear instead of assuming extra deliverables.
+- A change touching the public API, the validation order or more than one validator/inspector starts with a short task list in chat for approval; keep plans in chat or `devdocs/`, never in tracked files.
+- Bug fixes and new behavior start with a failing test, with both a valid and a malicious payload.
+- A change to the public API is done only when `docs/api.md`, the affected docs page, `README.md` examples and `CHANGELOG.md` agree with the code.
+- Done means the checks that apply to what changed ran and their output was read; say which ran and which did not (code checks do not apply to docs, `AGENTS.md` or skill-only changes).
+- Before reporting a larger change done, compare the diff to the request and remove anything not asked for.
+
+## Fixing problems
+
+- Fix the root cause, not the symptom. Before changing code, state the cause you found and the evidence for it.
+- Do not add workarounds: no special-case branches, swallowed exceptions, retries or sleeps to hide a failure, `type: ignore` / `# noqa`, test skips or loosened assertions, or defensive checks that mask bad state upstream.
+- If the proper fix is larger than the request (touches other validators, changes a boundary or the public API, needs a refactor), stop and ask before editing. Present the options:
+  1. Proper fix: what it changes and why it is the right one.
+  2. Minimal fix: what it leaves broken or the debt it creates.
+
+  Recommend one. Never apply the minimal option without the user's choice.
+- If unsure whether a fix is a workaround, treat it as one and ask.
+- A security-relevant weakening (a raised limit, a removed check, a widened allow-list, a skipped validation) is never a fix; ask first.
+
+## Building features
+
+- Build the feature the way the architecture intends: correct component, layering and validation order, even when a shortcut would be quicker.
+- Do not take shortcuts: no placeholder or stubbed logic, hardcoded values, TODOs standing in for required behavior, copy-pasted code instead of reuse, logic in the wrong layer, or skipped tests, validation, error handling or docs.
+- Before writing code, state the approach and the files it touches. If more than one reasonable design exists, or the proper design is larger than the request implies, stop and ask. Present the options:
+  1. Proper design: what it involves and why it fits the architecture.
+  2. Simpler design: what it cuts or defers, and the debt it creates.
+
+  Recommend one. Never apply the simpler option without the user's choice.
+- Scope still applies: complete means done properly, not bigger. Do not add features, options or files that were not requested.
+
+## Library invariants
+
+- Fail closed: an input the library cannot positively accept is rejected, and a failing check never degrades to a warning.
+- A validator is single-purpose and extends `BaseValidator`; `FileValidator` orchestrates, and a new check gets its own validator or inspector in the matching package.
+- Configuration changes go through `FileSecurityConfig` and `SecurityLimits`, and a new field updates their cross-field validation.
+- Failures raise the exceptions in `safeuploads/exceptions.py` (with a stable `ErrorCode`), never a bare `ValueError` or `Exception`.
+- The order of filename checks is significant: Unicode sanitization first, Windows reserved names before other normalization.
+- Blocking inspection never runs on the event loop; it goes through `FileValidator`'s worker-thread offload.
+- XML is parsed only through `defusedxml` (XXE-safe); archives are inspected without extracting to disk and under size, ratio, depth and entry limits.
+- Never build a filesystem path from an uploaded filename.
+- Logging uses `logging.getLogger(__name__)` and the `SecurityAuditLogger`; never log file contents.
+- Comments and docstrings state what the code does now, not what it used to do.
+- Python 3.13 syntax, 79-character lines (`pyproject.toml`), PEP 257 docstrings with `Args`, `Returns`, `Raises` where applicable.