cntm-nucleus 0.1.0__tar.gz

cntm_nucleus-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+/target
+dashboard/node_modules
+node_modules/
+
+# Secrets & credentials — NEVER commit these
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+*.jks
+*.keystore
+*.cert
+*.crt
+*.der
+credentials.json
+service-account.json
+*.credential
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Flutter
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+.packages
+build/
+
+# .NET
+**/obj/
+**/bin/
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.venv/
+venv/
+
+# Go
+vendor/
+
+# Rust
+*.profraw
+lcov.info
+tarpaulin-report.html
+
+# Worktrees
+.worktrees/
+
+# OS
+Thumbs.db

cntm_nucleus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Continuum
+
+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.

cntm_nucleus-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: cntm-nucleus
+Version: 0.1.0
+Summary: Nucleus authentication SDK for Python.
+Project-URL: Homepage, https://github.com/cntm-labs/nucleus
+Project-URL: Repository, https://github.com/cntm-labs/nucleus
+Project-URL: Issues, https://github.com/cntm-labs/nucleus/issues
+Author-email: cntm-labs <dev@cntm-labs.dev>
+License: MIT
+License-File: LICENSE
+Keywords: auth,authentication,jwt,nucleus,oauth,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=43.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.9
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == 'flask'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: respx>=0.22; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cntm-labs-nucleus
+
+> **Warning: DEV PREVIEW** — This package is under active development
+> and is NOT ready for production use. APIs may change without notice.
+> For updates, watch the [Nucleus repo](https://github.com/cntm-labs/nucleus).
+
+Nucleus authentication SDK for Python.
+
+## Installation
+
+```bash
+pip install cntm-labs-nucleus==0.1.0.dev1
+```
+
+## Quick Start
+
+```python
+from nucleus import NucleusClient
+
+client = NucleusClient(secret_key="sk_...")
+session = client.verify_session(token)
+```
+
+## License
+
+MIT

cntm_nucleus-0.1.0/README.md

@@ -0,0 +1,26 @@
+# cntm-labs-nucleus
+
+> **Warning: DEV PREVIEW** — This package is under active development
+> and is NOT ready for production use. APIs may change without notice.
+> For updates, watch the [Nucleus repo](https://github.com/cntm-labs/nucleus).
+
+Nucleus authentication SDK for Python.
+
+## Installation
+
+```bash
+pip install cntm-labs-nucleus==0.1.0.dev1
+```
+
+## Quick Start
+
+```python
+from nucleus import NucleusClient
+
+client = NucleusClient(secret_key="sk_...")
+session = client.verify_session(token)
+```
+
+## License
+
+MIT

cntm_nucleus-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cntm-nucleus"
+version = "0.1.0"
+description = "Nucleus authentication SDK for Python."
+license = {text = "MIT"}
+authors = [{name = "cntm-labs", email = "dev@cntm-labs.dev"}]
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["authentication", "auth", "nucleus", "sdk", "jwt", "oauth"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: FastAPI",
+    "Framework :: Django",
+    "Framework :: Flask",
+    "Topic :: Security",
+]
+dependencies = ["httpx>=0.27", "PyJWT[crypto]>=2.9", "cryptography>=43.0"]
+
+[project.urls]
+Homepage = "https://github.com/cntm-labs/nucleus"
+Repository = "https://github.com/cntm-labs/nucleus"
+Issues = "https://github.com/cntm-labs/nucleus/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nucleus"]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.115"]
+django = ["django>=4.2"]
+flask = ["flask>=3.0"]
+test = ["pytest>=8.0", "respx>=0.22"]

cntm_nucleus-0.1.0/src/nucleus/__init__.py

@@ -0,0 +1,14 @@
+import warnings
+
+__version__ = "0.1.0.dev1"
+if "dev" in __version__:
+    warnings.warn(
+        f"[Nucleus] You are using a dev preview ({__version__}). Do not use in production.",
+        stacklevel=2,
+    )
+
+from .client import NucleusClient
+from .verify import verify_token
+from .claims import NucleusClaims
+
+__all__ = ["NucleusClient", "verify_token", "NucleusClaims"]

cntm_nucleus-0.1.0/src/nucleus/claims.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+@dataclass
+class NucleusClaims:
+    user_id: str
+    project_id: str
+    email: str | None = None
+    first_name: str | None = None
+    last_name: str | None = None
+    avatar_url: str | None = None
+    email_verified: bool | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    org_id: str | None = None
+    org_slug: str | None = None
+    org_role: str | None = None
+    permissions: list[str] = field(default_factory=list)

cntm_nucleus-0.1.0/src/nucleus/client.py

@@ -0,0 +1,34 @@
+import httpx
+from .claims import NucleusClaims
+from .verify import verify_token
+
+class NucleusClient:
+    def __init__(self, secret_key: str, base_url: str = "https://api.nucleus.dev"):
+        self.secret_key = secret_key
+        self.base_url = base_url
+        self._client = httpx.AsyncClient(base_url=f"{base_url}/api/v1/admin",
+            headers={"Authorization": f"Bearer {secret_key}", "Content-Type": "application/json"})
+        self.users = UsersApi(self._client)
+        self.orgs = OrgsApi(self._client)
+
+    def verify_token(self, token: str, audience: str | None = None) -> NucleusClaims:
+        return verify_token(token, self.base_url, audience=audience)
+
+    async def close(self):
+        await self._client.aclose()
+
+class UsersApi:
+    def __init__(self, client: httpx.AsyncClient): self._client = client
+    async def get(self, user_id: str): return (await self._client.get(f"/users/{user_id}")).json()
+    async def list(self, limit: int = 20, cursor: str | None = None, email_contains: str | None = None):
+        params = {"limit": limit}
+        if cursor: params["cursor"] = cursor
+        if email_contains: params["email_contains"] = email_contains
+        return (await self._client.get("/users", params=params)).json()
+    async def ban(self, user_id: str): await self._client.post(f"/users/{user_id}/ban")
+    async def unban(self, user_id: str): await self._client.post(f"/users/{user_id}/unban")
+
+class OrgsApi:
+    def __init__(self, client: httpx.AsyncClient): self._client = client
+    async def get(self, org_id: str): return (await self._client.get(f"/orgs/{org_id}")).json()
+    async def list(self, limit: int = 20): return (await self._client.get("/orgs", params={"limit": limit})).json()

cntm_nucleus-0.1.0/src/nucleus/django.py

@@ -0,0 +1,21 @@
+from django.conf import settings
+from .verify import verify_token
+
+class NucleusMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self.base_url = getattr(settings, 'NUCLEUS_BASE_URL', 'https://api.nucleus.dev')
+
+    def __call__(self, request):
+        auth = request.META.get('HTTP_AUTHORIZATION', '')
+        if auth.startswith('Bearer '):
+            try:
+                request.nucleus_claims = verify_token(auth[7:], self.base_url)
+            except Exception:
+                request.nucleus_claims = None
+        else:
+            request.nucleus_claims = None
+        return self.get_response(request)
+
+def nucleus_claims(request):
+    return getattr(request, 'nucleus_claims', None)

cntm_nucleus-0.1.0/src/nucleus/fastapi.py

@@ -0,0 +1,27 @@
+from fastapi import Depends, HTTPException, Request
+from .claims import NucleusClaims
+from .verify import verify_token
+
+class NucleusAuth:
+    def __init__(self, secret_key: str | None = None, base_url: str = "https://api.nucleus.dev"):
+        self.base_url = base_url
+
+    async def __call__(self, request: Request) -> NucleusClaims:
+        auth = request.headers.get("authorization", "")
+        if not auth.startswith("Bearer "):
+            raise HTTPException(401, detail="Missing authorization header")
+        try:
+            return verify_token(auth[7:], self.base_url)
+        except Exception:
+            raise HTTPException(401, detail="Invalid or expired token")
+
+def require_permission(permission: str):
+    def decorator(func):
+        from functools import wraps
+        @wraps(func)
+        async def wrapper(*args, claims: NucleusClaims = Depends(), **kwargs):
+            if permission not in (claims.permissions or []) and claims.org_role != "owner":
+                raise HTTPException(403, detail="Insufficient permissions")
+            return await func(*args, claims=claims, **kwargs)
+        return wrapper
+    return decorator

cntm_nucleus-0.1.0/src/nucleus/flask.py

@@ -0,0 +1,30 @@
+from functools import wraps
+from flask import request, g, jsonify
+from .verify import verify_token
+from .claims import NucleusClaims
+
+class NucleusAuth:
+    def __init__(self, app=None, secret_key=None, base_url="https://api.nucleus.dev"):
+        self.base_url = base_url
+        if app: self.init_app(app)
+
+    def init_app(self, app):
+        app.before_request(self._before_request)
+
+    def _before_request(self):
+        auth = request.headers.get('Authorization', '')
+        if auth.startswith('Bearer '):
+            try: g.nucleus_claims = verify_token(auth[7:], self.base_url)
+            except: g.nucleus_claims = None
+        else: g.nucleus_claims = None
+
+    def required(self, f):
+        @wraps(f)
+        def decorated(*args, **kwargs):
+            if not getattr(g, 'nucleus_claims', None):
+                return jsonify({"error": "Unauthorized"}), 401
+            return f(*args, **kwargs)
+        return decorated
+
+def current_claims() -> NucleusClaims | None:
+    return getattr(g, 'nucleus_claims', None)

cntm_nucleus-0.1.0/src/nucleus/sync.py

@@ -0,0 +1,19 @@
+import httpx
+from .claims import NucleusClaims
+from .verify import verify_token
+
+class SyncNucleusClient:
+    def __init__(self, secret_key: str, base_url: str = "https://api.nucleus.dev"):
+        self.secret_key = secret_key
+        self.base_url = base_url
+        self._client = httpx.Client(base_url=f"{base_url}/api/v1/admin",
+            headers={"Authorization": f"Bearer {secret_key}", "Content-Type": "application/json"})
+        self.users = SyncUsersApi(self._client)
+
+    def verify_token(self, token: str) -> NucleusClaims:
+        return verify_token(token, self.base_url)
+
+class SyncUsersApi:
+    def __init__(self, client: httpx.Client): self._client = client
+    def get(self, user_id: str): return self._client.get(f"/users/{user_id}").json()
+    def list(self, limit: int = 20): return self._client.get("/users", params={"limit": limit}).json()

cntm_nucleus-0.1.0/src/nucleus/verify.py

@@ -0,0 +1,36 @@
+import jwt
+import httpx
+from functools import lru_cache
+from .claims import NucleusClaims
+
+@lru_cache(maxsize=1)
+def _get_jwks(base_url: str) -> dict:
+    res = httpx.get(f"{base_url}/.well-known/jwks.json")
+    res.raise_for_status()
+    return res.json()
+
+def verify_token(
+    token: str,
+    base_url: str = "https://api.nucleus.dev",
+    audience: str | None = None,
+) -> NucleusClaims:
+    jwks = _get_jwks(base_url)
+    header = jwt.get_unverified_header(token)
+    key = next((k for k in jwks["keys"] if k["kid"] == header.get("kid")), None)
+    if not key:
+        raise ValueError("No matching key found in JWKS")
+    public_key = jwt.algorithms.RSAAlgorithm.from_jwk(key)
+    decode_opts: dict = {}
+    decode_kwargs: dict = {"algorithms": ["RS256"]}
+    if audience:
+        decode_kwargs["audience"] = audience
+    else:
+        decode_opts["verify_aud"] = False
+    payload = jwt.decode(token, public_key, options=decode_opts, **decode_kwargs)
+    return NucleusClaims(
+        user_id=payload["sub"], project_id=payload.get("aud", ""),
+        email=payload.get("email"), first_name=payload.get("first_name"),
+        last_name=payload.get("last_name"), avatar_url=payload.get("avatar_url"),
+        email_verified=payload.get("email_verified"), metadata=payload.get("metadata", {}),
+        org_id=payload.get("org_id"), org_slug=payload.get("org_slug"),
+        org_role=payload.get("org_role"), permissions=payload.get("org_permissions", []))

cntm_nucleus-0.1.0/tests/conftest.py

@@ -0,0 +1,72 @@
+"""Shared test fixtures for Nucleus Python SDK tests."""
+
+import json
+import pytest
+from datetime import datetime, timezone, timedelta
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives import serialization
+import jwt as pyjwt
+
+# Generate a test RSA key pair (reused across all tests in the session)
+_private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+_public_key = _private_key.public_key()
+
+
+@pytest.fixture
+def private_key():
+    return _private_key
+
+
+@pytest.fixture
+def public_key():
+    return _public_key
+
+
+@pytest.fixture
+def jwks_response():
+    """Build a JWKS JSON response from the test public key."""
+    pub_numbers = _public_key.public_numbers()
+    # Build JWK from public key components
+    import base64
+
+    def _int_to_base64url(n: int, length: int) -> str:
+        return base64.urlsafe_b64encode(n.to_bytes(length, "big")).rstrip(b"=").decode()
+
+    n = _int_to_base64url(pub_numbers.n, 256)  # 2048 bits = 256 bytes
+    e = _int_to_base64url(pub_numbers.e, 3)
+
+    return {
+        "keys": [
+            {
+                "kty": "RSA",
+                "kid": "test-key-1",
+                "alg": "RS256",
+                "use": "sig",
+                "n": n,
+                "e": e,
+            }
+        ]
+    }
+
+
+def make_token(claims: dict, kid: str = "test-key-1") -> str:
+    """Sign a JWT with the test private key."""
+    return pyjwt.encode(claims, _private_key, algorithm="RS256", headers={"kid": kid})
+
+
+def valid_claims(**overrides) -> dict:
+    """Build a valid set of JWT claims."""
+    now = datetime.now(timezone.utc)
+    claims = {
+        "sub": "user_123",
+        "iss": "https://api.test.com",
+        "aud": "project_456",
+        "exp": int((now + timedelta(hours=1)).timestamp()),
+        "iat": int(now.timestamp()),
+        "jti": "jwt_abc",
+        "email": "test@example.com",
+        "first_name": "Test",
+        "last_name": "User",
+    }
+    claims.update(overrides)
+    return claims

cntm_nucleus-0.1.0/tests/test_client.py

@@ -0,0 +1,82 @@
+"""Tests for nucleus.client — NucleusClient initialization and delegation."""
+
+import pytest
+from unittest.mock import patch, AsyncMock
+from nucleus.client import NucleusClient
+from nucleus.claims import NucleusClaims
+from .conftest import make_token, valid_claims
+
+
+class TestNucleusClientInit:
+    def test_default_base_url(self):
+        client = NucleusClient(secret_key="sk_test")
+        assert client.base_url == "https://api.nucleus.dev"
+
+    def test_custom_base_url(self):
+        client = NucleusClient(secret_key="sk_test", base_url="https://custom.api.dev")
+        assert client.base_url == "https://custom.api.dev"
+
+    def test_has_users_api(self):
+        client = NucleusClient(secret_key="sk_test")
+        assert client.users is not None
+
+    def test_has_orgs_api(self):
+        client = NucleusClient(secret_key="sk_test")
+        assert client.orgs is not None
+
+
+class TestNucleusClientVerifyToken:
+    def test_delegates_to_verify_token(self, jwks_response):
+        from nucleus.verify import _get_jwks
+        _get_jwks.cache_clear()
+        client = NucleusClient(secret_key="sk_test", base_url="https://test.local")
+        token = make_token(valid_claims())
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            claims = client.verify_token(token)
+
+        assert isinstance(claims, NucleusClaims)
+        assert claims.user_id == "user_123"
+
+    def test_forwards_audience_parameter(self, jwks_response):
+        from nucleus.verify import _get_jwks
+        _get_jwks.cache_clear()
+        client = NucleusClient(secret_key="sk_test", base_url="https://test.local")
+        token = make_token(valid_claims(aud="project_456"))
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            claims = client.verify_token(token, audience="project_456")
+
+        assert claims.project_id == "project_456"
+
+    def test_wrong_audience_via_client_raises(self, jwks_response):
+        import jwt as pyjwt
+        from nucleus.verify import _get_jwks
+        _get_jwks.cache_clear()
+        client = NucleusClient(secret_key="sk_test", base_url="https://test.local")
+        token = make_token(valid_claims(aud="project_456"))
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            with pytest.raises(pyjwt.InvalidAudienceError):
+                client.verify_token(token, audience="wrong_project")
+
+
+class TestNucleusClaims:
+    def test_default_values(self):
+        claims = NucleusClaims(user_id="u1", project_id="p1")
+        assert claims.user_id == "u1"
+        assert claims.project_id == "p1"
+        assert claims.email is None
+        assert claims.metadata == {}
+        assert claims.permissions == []
+
+    def test_all_fields(self):
+        claims = NucleusClaims(
+            user_id="u1", project_id="p1",
+            email="test@example.com", first_name="Test", last_name="User",
+            avatar_url="https://img.test/a.png", email_verified=True,
+            metadata={"role": "admin"}, org_id="org_1", org_slug="my-org",
+            org_role="admin", permissions=["read", "write"],
+        )
+        assert claims.email == "test@example.com"
+        assert claims.email_verified is True
+        assert claims.metadata == {"role": "admin"}
+        assert claims.org_role == "admin"
+        assert claims.permissions == ["read", "write"]

cntm_nucleus-0.1.0/tests/test_verify.py

@@ -0,0 +1,101 @@
+"""Tests for nucleus.verify — token verification with JWKS."""
+
+import pytest
+from unittest.mock import patch
+from datetime import datetime, timezone, timedelta
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+import jwt as pyjwt
+
+from nucleus.verify import verify_token, _get_jwks
+from nucleus.claims import NucleusClaims
+from .conftest import make_token, valid_claims
+
+
+class TestVerifyTokenSuccess:
+    def test_returns_nucleus_claims(self, jwks_response):
+        token = make_token(valid_claims())
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            claims = verify_token(token, base_url="https://test.local")
+
+        assert isinstance(claims, NucleusClaims)
+        assert claims.user_id == "user_123"
+        assert claims.project_id == "project_456"
+        assert claims.email == "test@example.com"
+        assert claims.first_name == "Test"
+        assert claims.last_name == "User"
+
+    def test_maps_org_claims(self, jwks_response):
+        token = make_token(valid_claims(
+            org_id="org_1",
+            org_slug="my-org",
+            org_role="admin",
+            org_permissions=["read", "write"],
+        ))
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            claims = verify_token(token, base_url="https://test.local")
+
+        assert claims.org_id == "org_1"
+        assert claims.org_slug == "my-org"
+        assert claims.org_role == "admin"
+        assert claims.permissions == ["read", "write"]
+
+
+class TestVerifyTokenFailures:
+    def test_expired_token_raises(self, jwks_response):
+        expired = valid_claims(
+            exp=int((datetime.now(timezone.utc) - timedelta(hours=1)).timestamp())
+        )
+        token = make_token(expired)
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            with pytest.raises(pyjwt.ExpiredSignatureError):
+                verify_token(token, base_url="https://test.local")
+
+    def test_wrong_key_raises(self, jwks_response):
+        wrong_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+        token = pyjwt.encode(
+            valid_claims(), wrong_key, algorithm="RS256", headers={"kid": "test-key-1"}
+        )
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            with pytest.raises(pyjwt.InvalidSignatureError):
+                verify_token(token, base_url="https://test.local")
+
+    def test_missing_kid_raises(self, jwks_response):
+        token = make_token(valid_claims(), kid="nonexistent-kid")
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            with pytest.raises(ValueError, match="No matching key"):
+                verify_token(token, base_url="https://test.local")
+
+    def test_invalid_token_string_raises(self, jwks_response):
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            with pytest.raises(Exception):
+                verify_token("not.a.valid.token", base_url="https://test.local")
+
+
+class TestAudienceValidation:
+    def test_valid_audience_passes(self, jwks_response):
+        token = make_token(valid_claims(aud="project_456"))
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            claims = verify_token(token, base_url="https://test.local", audience="project_456")
+        assert claims.project_id == "project_456"
+
+    def test_wrong_audience_raises(self, jwks_response):
+        token = make_token(valid_claims(aud="project_456"))
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            with pytest.raises(pyjwt.InvalidAudienceError):
+                verify_token(token, base_url="https://test.local", audience="wrong_project")
+
+    def test_no_audience_skips_validation(self, jwks_response):
+        token = make_token(valid_claims(aud="project_456"))
+        _get_jwks.cache_clear()
+        with patch("nucleus.verify._get_jwks", return_value=jwks_response):
+            claims = verify_token(token, base_url="https://test.local")
+        assert claims.project_id == "project_456"