permit 3.0.0: fix dependency CVEs, fix major SDK bugs, gate PRs and releases on CVE scans

[zeevmoney]

Linear issue

PER-16176 · fixes PER-16174, PER-16231 · follow-ups: PER-16177, PER-16209, PER-16236

Why

This started as a CVE fix and became the 3.0.0 release.

CVEs. permitio/permit-python had no dependency scanning and no gate on PRs or releases. The resolved dependency tree was clean. All the exposure was in the floors: the package publishes open >= ranges with no lockfile, so aiohttp>=3.12.14 legitimately resolves to 3.12.14 and a consumer inherits every CVE fixed since. That was 34 advisories across aiohttp, h11, anyio and pydantic. A scanner pointed at what CI installs reports all green.

Correctness. Nine major bugs turned up along the way (PER-16174). Among them: context-dependent ABAC checks evaluated against an empty context, authorized_users() could not return under pydantic v2, and the sync client's deprecated facade raised before issuing any request. They survived because 8 of the e2e tests had been @pytest.mark.xfail for about two years. Since the Python floor already had to move (below), this ships as a major version that fixes them properly.

Open backlog. Every open issue and community PR was triaged against this release. The real, still-present ones are fixed here:

• Python 3.14: import permit crashed on 3.14 with the pydantic versions the old ranges allowed.
• Authorization: bearer: the SDK sent a lowercase scheme; it now sends the standard Bearer.
• Typing: the package was untyped, so type checkers skipped it. The one-line py.typed marker a contributor proposed is shipped here together with the typing fixes that make it safe; on its own it would have produced false errors on valid code.

The other open items are already fixed or superseded. They will be closed with an explanation once this ships.

Breaking changes

All of these need a line in the release notes.

Compatibility

1. Python 3.8 and 3.9 dropped (python_requires>=3.10). This can't be avoided: aiohttp 3.14.3 is the only release that fixes CVE-2026-69244, and it requires 3.10. 3.8 was already unsupported in practice, since the old aiohttp floor needed 3.9. A 3.9 user who runs pip install -U permit gets Requires-Python >=3.10, and pip quietly keeps the old, vulnerable version.
2. httpx is no longer installed transitively, and neither are h11, httpcore, anyio or zipp. The SDK never imported httpx. Anyone who relied on permit pulling it in must now declare it themselves.
3. Higher dependency floors. These old floors no longer install or import cleanly on the Pythons the SDK supports, so they rise:
   • pydantic: >=1.10.18,<2 or >=2.4.2 on Python 3.10–3.12; >=1.10.18,<2 or >=2.8.0 on 3.13; >=1.10.25,<2 or >=2.13 on 3.14.
     • 1.10.18 is the first 1.10.x without about 2,400 import-time DeprecationWarnings on 3.13; it also ships the pydantic.v1 package the type hints need.
     • pydantic 2.0–2.4.1 are excluded on every Python. Under pydantic 2 the SDK validates emails with the pydantic.v1 copy that pydantic bundles, and only 2.4.2 and later bundle one fixed for CVE-2024-3772 (1.10.13). pydantic 2.0 exactly also fails every parsed response: its pydantic.v1.parse_obj_as rejects __root__ models.
     • On 3.13, 2.4.2–2.7.x are excluded because they pin a pydantic-core with no Python 3.13 wheels; 2.8.0 (pydantic-core 2.20.0) is the first that has them.
     • On 3.14, earlier releases crash on import permit ("unable to infer type for attribute").
   • typing-extensions: >=4.14.0. Releases before 4.6 break import permit on 3.12+, releases before 4.12 break it on 3.13+, and 4.12–4.13 lose TypedDict keys on 3.14.
   • loguru: >=0.7.3. Earlier releases warn on 3.14 about an asyncio API that Python 3.16 removes.
4. permit is now a typed package (PEP 561 py.typed). Type checkers used to skip permit with import-untyped; now they check calls into it.
   • Consumers can drop ignore_missing_imports or # type: ignore[import-untyped] for permit, but genuine type errors in their code may now surface.
   • SDK models are typed as the pydantic v1 models they have always been at runtime, on both pydantic majors. So v2-only calls such as .model_dump() on an SDK model now fail type checking; they already failed at runtime.
   • mypy users on pydantic 2 who want plugin checking of SDK models should use the pydantic.v1.mypy plugin; no plugin is needed.

API

5. resource_relations.list() now returns PaginatedResultRelationRead, so callers read .data.

   This is a bug fix. This method could not work before it. The SDK declared the return type as List[RelationRead], but the API returns a paginated {"data": [...], ...} envelope. So every call raised ValidationError: value is not a valid list before returning anything. No working code can depend on the old return type. The only visible change is the type: callers now read .data.

6. permit.sync.Permit.authorized_users(), get_user_permissions() and filter_objects() are now synchronous. Callers should drop the await.

   This is a bug fix. These methods could not work before it. Only the sync client is affected; the async permit.Permit still awaits them. The sync client inherited all three unchanged from the async class, so they stayed async def, while the sync enforcer under them is already synchronous. Calling one without await returned a coroutine object instead of a result. Awaiting it raised RuntimeError: This event loop is already running. So no working code can depend on the old behaviour. The only visible change is the signature, from async def to def. They now behave like check() and bulk_check(), which were already synchronous on the sync client.

7. Removed public symbols:
   • ContextStore.register_transform(), ContextStore.transform() and ContextTransform. A registered transform was never applied, so these did nothing.
   • ApiKeyLevel, a deprecated alias of ApiKeyAccessLevel.
   • LoginAsErrorMessages, OpaResult and the JWT alias. None of them had a caller.

Wire behaviour (same API, different bytes). Each change was checked against the API's request definitions:

8. An explicitly-set None is now sent as null, so an update can clear a field. Before, exclude_none dropped it: users.update(key, UserUpdate(email=None)) sent {} and quietly did nothing. Fields you never set are still omitted.
9. users.assign_role / unassign_role omit unset fields, matching role_assignments.assign. The API treats an omitted field and null the same for these fields.
10. elements.login_as sends canonical hyphenated UUIDs instead of 32-character hex. The API accepts both spellings and resolves them to the same record.
11. A 3xx response now raises instead of being treated as success. No 3xx is reachable on any path the SDK calls, and aiohttp follows redirects anyway.
12. Every Authorization header uses Bearer, not bearer. The scheme is case-insensitive (RFC 7235), so nothing breaks; it is listed because the bytes on the wire change.

Kept on purpose: PermitConnectionError still inherits from the deprecated PermitException. Moving it under PermitError would silently stop except PermitException from catching connection failures.

What changed

Dependency CVE fixes

Package	Before	After	Why
aiohttp	>=3.12.14,<4	>=3.14.3,<4	Clears 32 advisories, including CVE-2026-69244: an out-of-bounds heap read in the HTTP response parser, which a client hits on every call
pydantic	>=1.10.7	>=1.10.18,<2 or >=2.4.2 (Python 3.10–3.12); >=1.10.18,<2 or >=2.8.0 (3.13); >=1.10.25,<2 or >=2.13 (3.14)	CVE-2024-3772 (EmailStr ReDoS) needs pydantic.v1 1.10.13: pydantic 1.10.13+, or pydantic 2.4.2+ whose bundled v1 is fixed; the higher floors are compatibility fixes (breaking change 3). Dual v1/v2 support is kept
typing-extensions	>=4.5.0,<5	>=4.14.0,<5	Compatibility: older releases break import permit on 3.12+ (breaking change 3)
loguru	>=0.7.0,<1	>=0.7.3,<1	Compatibility: older releases warn on 3.14 (breaking change 3)
httpx	>=0.24.1,<1	removed	Never imported. It was the only path by which h11 (CVE-2025-43859, CRITICAL) and anyio (CVE-2026-63374, CRITICAL) got into the tree
zipp	>=3.19.1	removed	Unused
werkzeug (dev)	>=2.3.8	>=3.1.6	Clears six advisories
pytest (dev)	unpinned	>=9.0.3	CVE-2025-71176. Caught by this PR's own gate
aioresponses, pytest-mock, pytest-cov (dev)	declared	removed	No test used them. aioresponses 0.7.9 is also incompatible with aiohttp 3.14.3

Every dev dependency now has a floor. Without one, a scanner has nothing to evaluate.

Major bug fixes (PER-16174)

• Sync client. SyncClass now wraps each method exactly once, however deep the inheritance goes; the facade methods had been wrapped twice, so they raised before sending anything. It detects coroutines with inspect.iscoroutinefunction, unwrapping validate_arguments first. permit.sync.Permit overrides the three enforcement methods it was missing.
• Enforcement.
  • parse_obj_as is imported through the same v1/v2 guard the rest of the package uses.
  • bulk_check honours a per-check context, and filter_objects passes the caller's context through.
  • CheckQuery.context is NotRequired, so type checkers accept a bulk_check query without a context, as the runtime always has.
  • UserInput accepts snake_case, so first_name/last_name are no longer silently dropped from every check.
• Serialization. dict and list request bodies now go through the encoder, so a nested datetime/UUID/Enum no longer crashes inside aiohttp. exclude_none is gone.
• Facts proxy. Tenant bulk operations no longer post to the PDP's users endpoint.
• PDP error reporting. The PDP sends auth rejections as plain text. Parsing them as JSON raised an exception that the connectivity handler caught, so a 403 caused by a wrong API key was reported as "cannot connect to the PDP container". The error now shows the real status code and response body.

Python 3.14 support

• Declared (Programming Language :: Python :: 3.14) and tested. The dependency floors above keep resolvers from picking versions that crash on 3.14.
• permit/utils/deprecation.py uses inspect.iscoroutinefunction instead of the asyncio one, which 3.16 removes. This removes 21 import-time warnings on 3.14.
• The pydantic version parser accepts pre-releases such as 2.14.0b2. They used to crash import permit with a ValueError.
• A new compatibility CI job runs the offline suite on Python 3.10–3.14 against the lowest allowed dependency versions (uv pip compile --resolution lowest-direct), the lowest allowed pydantic 2 (lowest-direct with a pydantic>=2 constraint) and the newest, plus 3.14 on pydantic 1. uv is pinned to 0.12.18. It is not a required check, so the existing required pytest contexts are unchanged.

Typed public surface

• Type checkers see the SDK models as the pydantic v1 models that run: each version-conditional import gains an if TYPE_CHECKING: branch, and mypy uses the pydantic.v1.mypy plugin.
• Generated model defaults are keyword arguments (Field(default=...)), so optional fields no longer read as required to pyright and Pylance. generate-models passes --use-default-kwarg.
• API methods that accept dicts at runtime accept them in their annotations. ModelInput/ModelListInput widen the type for type checkers only; at runtime the parameter is still the model, so an invalid dict still fails validation before any request is sent.
• The sync client is typed as synchronous through a generated stub, permit/_sync_types.pyi, built by scripts/generate_sync_stubs.py (make generate-sync-stubs). A test fails if the stub drifts from the async classes.
• Smaller typing fixes so a consumer type-checks clean under mypy --strict and pyright:
  • plain str is accepted for EmailStr fields;
  • UserInput accepts both field spellings;
  • explicit re-exports in permit/__init__.py;
  • deprecated() keeps the decorated signature;
  • PermitConfig() without a token is now a type error, as it already was at runtime.
• permit/py.typed and the stub ship in the wheel and sdist, and both the release build and one compatibility leg assert that they do. The README has a short "Type checking" section.
• Runtime behaviour is unchanged. A snapshot of every public name, signature, @validate_arguments model and model field (defaults and aliases included) matches the previous commit on both pydantic majors and on Python 3.11 and 3.14.

Minor bug fixes

every client now sends Authorization: Bearer (was bearer), checked on the wire by an offline test · resource_instances.list(detailed_key=True) always raised · users.sync() mutated the caller's dict and removed the key field the API requires, so that path always returned 422 · SyncPDPApi never called super().__init__ · pdp_timeout was silently ignored by every permit.pdp_api.* call · a dead access-level branch that could never run was removed · docstrings corrected: resource-instance idents are resource:key or a uuid, never a bare key; a resource role's permissions are bare action keys like read.

Packaging and cleanup

• setup.py no longer ships a top-level tests package to consumers. A bare find_packages() put it in their site-packages, where it shadows their own tests module. The published permit==2.8.3 does this today.
• Removed: duplicate ClientConfig/pagination_params code in pdp_api, a duplicate _model_dump, and unused TypeVars and helpers.
• Repo files: removed .isort.cfg (isort isn't run), a stub uv.lock declaring requires-python >=3.14, and the Makefile publish target, which bypassed the gated release. Fixed the Makefile's .DEFAULT_GOAL, which pointed at a target that didn't exist. Fixed a .gitignore rule that did nothing.
• Version bumped to 3.0.0.

CVE gates

• Dependency Audit runs Trivy over four resolved trees: runtime ceiling, runtime floor, runtime floor with pydantic held to 2, and dev.
  • A plain lowest-direct floor always lands on pydantic 1, so the third tree is the only scan of the lowest pydantic 2. Trivy treats pydantic 2.4.0 as fixed for CVE-2024-3772 and rates it MEDIUM, below the gate, so the offline test test_pydantic_requirement_allows_no_release_affected_by_cve_2024_3772 is what blocks pydantic 2.0–2.4.1; the tree gives visibility.
  • Two Trivy behaviours both pass silently on a scan that never ran, so both are handled explicitly. Trivy only understands == pins and keys on the filename requirements.txt, so the trees are compiled with uv pip compile. It also writes Results: null and exits 0 when it finds nothing to scan, so that case is detected and fails the gate.
  • The runtime floor is compiled on its own. When it was compiled together with dev deps, mypy pulled typing-extensions up and hid the version a consumer can actually get.
  • Blocks only on HIGH/CRITICAL advisories that have a fix. Advisories without a fix are still reported.
  • Posts a sticky PR comment and GitHub annotations (the only channel that reaches fork PRs).
  • The audit job is read-only. The comment is posted from a separate job, so PR-authored setup.py code never runs in a job that holds a write token.
• Release now runs as build → scan → publish with hard needs: edges, so publish can't run unless the scan passed. The gate covers the runtime trees only.
• Weekly cron (Mondays 09:00 UTC) posts the actual findings to Slack: packages, counts and upgrade targets. It warns and skips if SLACK_WEBHOOK_URL isn't set.
• pip-audit runs alongside Trivy but only reports and never blocks, because it gives no severity.
• Dependabot: weekly, with 7/14-day cooldowns. versioning-strategy: increase is required. With a setup.py present, Dependabot's default widen would never raise a >= floor.

Workflow hardening

• zizmor: 48 findings (12 HIGH) down to 0. actionlint is clean.
• Every action is pinned to a SHA, and each SHA was checked against the GitHub API.
• persist-credentials: false everywhere, least-privilege permissions:, template injection removed, and the release-tag validation now checks the whole string.
• Deleted release.yml. It ran on release: created while python-sdk-publish.yml ran on published, so every release uploaded the same version twice.
• The PDP now starts as a CI step instead of a service container. A service container starts before any step runs, so it could only be given PROJECT_API_KEY. The tests authenticate with the per-run environment key, the PDP rejected every decision with a 403, and that is why the RBAC/ReBAC decision tests could never pass.

Test suite

• All 8 xfail markers removed. Those tests now run and pass.
• The e2e tests are isolated from each other. They used to fight over fixed keys (admin, viewer, a shared urn), assert environment-wide counts, and fail the test when cleanup got a 404. Each test now uses unique keys, asserts only on its own objects, and tolerates "already gone" during teardown.
• Rate limiting (HTTP 429) is handled in conftest for the test session only. Requests retry with backoff, honour Retry-After, and add jitter. The xfail markers had been hiding these 429s. The SDK itself doesn't retry: adding hidden retries to a published client would change behaviour callers never asked for.
• test_bulk_operations fixed. It expected a role assignment to survive deleting the user who owns it.
• httpserver_listen_address moved to conftest.py. Its port had depended on which test file pytest collected first.

Architectural changes

No architectural change to the SDK. The release job graph changes:

flowchart TD
  subgraph After["After: publish is unreachable without a passing scan"]
    B2["build: version, sdist and wheel"] --> S2["scan: compile trees, Trivy, gate"]
    S2 --> P2["publish: PyPI"]
  end
  subgraph Before["Before: two workflows raced"]
    R1["release.yml on 'created'"] --> PY1["twine upload"]
    R2["python-sdk-publish.yml on 'published'"] --> PY2["pypi-publish"]
  end

Loading

How it was tested

CI: all 26 checks are green:

• 151 passed, 4 skipped on both required pydantic legs. At the start of this PR it was 45 passed with 8 permanently xfail.
• All 16 compatibility legs (Python 3.10–3.14: lowest dependencies, lowest pydantic 2, newest dependencies, plus 3.14 on pydantic 1) are green.

The 4 skips:

• Three cloud-PDP error tests. CI never reaches the cloud PDP, so they skip with a stated reason.
• The decision assertions in test_abac_e2e, waiting on PER-16209. The control-plane half of that test still runs.

End-to-end harness (internal) against a local Permit stack with a real permitio/pdp-v2: 58 passed, 0 failed, 0 skipped, with 95 data-integrity round-trips and 0 differences.

Against the API: every wire-affecting change was checked against the API's route and request/response definitions. Every one was safe.

Offline:

• 132 offline tests, green on pydantic 1.10.26 and 2.13.5, on every Python from 3.10 to 3.14, and on the pydantic 2 floors (2.4.2 on 3.10–3.12, 2.8.0 on 3.13). Checked that they're real: reverting permit/ makes them fail.
• A consumer fixture type-checks with mypy --strict as part of the suite, and also passes pyright strict against the installed wheel. Each typing fix was mutation-checked: undoing any one of them makes the fixture fail.
• 46 contract tests for the audit report renderer.
• 24 request bodies are byte-identical across both pydantic majors.

The gate itself: it fails (exit 1) on the old vulnerable floor and passes (exit 0) on the fixed one.

Manual test plan

1. Confirm Dependency Audit posts a sticky comment on this PR.
2. Push a commit setting aiohttp>=3.12.14,<4. The check should go red and the comment should list CVE-2026-69244. Revert it.
3. After merge, run gh workflow run security.yml to try the Slack path once SLACK_WEBHOOK_URL is set.
4. In a scratch project, pip install this branch and run mypy --strict on code that uses permit.Permit and permit.sync.Permit. Expect no errors, and sync calls typed as their results rather than coroutines.
5. Publish as 3.0.0 (a major release). The release notes need everything in the breaking-changes section above.

Blast radius and isolation

• Blast radius:
  • consumers on Python 3.8/3.9, or pinned below the new dependency floors;
  • consumers who type-check against permit;
  • consumers of the API changes above;
  • CI for every future PR;
  • the release pipeline.
• Isolation: isolated.

Follow-ups

Already applied outside the diff: secret scanning with push protection, Dependabot security updates, and Dependency Audit / Audit Script Tests / Workflow Hardening added as required checks on main.

Still open:

• Add SLACK_WEBHOOK_URL. Until it's set, nobody gets the weekly results.
• PyPI Trusted Publishing. A publisher has to be registered on PyPI before the workflow can switch over.
• PER-16209
• PER-16177: remaining test-suite debt.
• PER-16236: native pydantic 2 models. Recent FastAPI rejects pydantic.v1 models as request or response bodies.

Scope and size

• SDK runtime: ~1,680 lines added, about 630 of them the mechanical keyword-default rewrite of the generated models. The generated 2,351-line permit/_sync_types.pyi comes on top.
• SDK tests: ~3,500. CI workflows and scripts: ~1,700. Their tests: ~460.
• Single responsibility: no. This combines the CVE fixes, the CI gates and the 3.0.0 correctness work. Kept as one PR for speed, then widened to a major version.

🤖 Generated with Claude Code

[linear-code]

PER-16176

PER-16174

PER-16231

PER-16209

[zeevmoney]

The one remaining red check is pre-existing — here is the proof

tests/endpoints/test_bulk_operations.py::test_bulk_operations fails on this branch. I did not want to hand that over as an unexplained red check, so I isolated it rather than assert it.

Experiment: pushed commit 160f129, which reverted only permit/ back to origin/main while keeping the CI and test changes. Reverted in f9b4857.

Result — with the SDK code identical to main, it still fails identically:

FAILED tests/endpoints/test_bulk_operations.py::test_bulk_operations - assert 0 == (0 + 1)
 +  where 0 = len([])

Corroborated independently: the same test also fails against a local Permit backend + PDP stack built during this work — a completely separate control plane from the shared CI project.

Why it fails. The assertion at line 227 expects a role assignment to survive the deletion of the user who owns it:

await permit.api.users.bulk_delete([user.key for user in CREATED_USERS])
assignments = await permit.api.role_assignments.list()
assert len(assignments) == len_assignments_original + 1  # (tenant role)

The surviving +1 is RoleAssignmentCreate(user=USER_A, role=ADMIN, tenant=TENANT_1). Line 218 asserts the same thing after deleting resource instances and passes, so exactly one assignment exists at that point. users.bulk_delete then removes USER_A, and their tenant role goes with them — leaving 0. The test encodes an assumption that a user's role assignment outlives the user, which the backend does not honour. Nothing in this diff touches users.bulk_delete, role_assignments.bulk_assign or role_assignments.list.

Worth fixing separately — either the test's assumption or the cascade behaviour. Not folded into this PR, which is already larger than it should be.

A useful side effect of the same experiment

With permit/ reverted, the new regression tests failed, which is what should happen:

FAILED test_resource_instances_list_sends_detailed_filter_as_query_string
  - TypeError: Invalid variable type: value should be str, int or float, got True of type <class 'bool'>
FAILED test_users_sync_does_not_mutate_the_caller_dict
  - AssertionError: assert {'email': 'not-an-email'} == {'key': 'user...

So the tests genuinely catch the bugs they target rather than passing vacuously.

Two regressions I did introduce, and fixed

Adding tests/test_offline_regressions.py broke test_api_timeout and test_pdp_timeout. pytest_httpserver's httpserver fixture is session-scoped — the first test to request it binds the one shared server — and the address override lived in test_rbac_e2e.py, so it only applied if that module got there first. The new file sorts earlier, claimed the server on a random port, and those two then failed against their hardcoded localhost:9999. Fixed in e5a88c1 by moving the fixture to conftest.py, which also removes the latent ordering dependency any future test would have tripped over. Both now pass (47 passed, up from 45).

[github-actions]

Dependency Security Audit

Scanned: requirements.txt + requirements-dev.txt, resolved at Python 3.10 (the current resolution, and the lowest versions the published specs permit under each pydantic major)

✅ No known vulnerabilities found.

Both the resolved dependency set and the lowest versions the published specs permit are clean at HIGH and CRITICAL.