fastjwt-kit 0.1.0__py3-none-any.whl

fastjwt_kit/__init__.py

@@ -0,0 +1,34 @@
+"""fastjwt-kit: a small, opinionated wrapper around PyJWT.
+
+Usage:
+
+    from fastjwt_kit import create_access_token, verify_token, TokenExpiredError
+
+    token = create_access_token(subject="user-123", secret="change-me")
+    claims = verify_token(token, secret="change-me")
+"""
+from .exceptions import (
+    InvalidClaimsError,
+    InvalidTokenError,
+    TokenError,
+    TokenExpiredError,
+)
+from .tokens import (
+    create_access_token,
+    create_refresh_token,
+    create_token,
+    verify_token,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "create_token",
+    "create_access_token",
+    "create_refresh_token",
+    "verify_token",
+    "TokenError",
+    "TokenExpiredError",
+    "InvalidTokenError",
+    "InvalidClaimsError",
+]

fastjwt_kit/exceptions.py

@@ -0,0 +1,21 @@
+"""Custom exceptions for fastjwt_kit.
+
+Wrapping PyJWT's exceptions means callers only ever need to catch
+fastjwt_kit exceptions, not reach into the underlying jwt library.
+"""
+
+
+class TokenError(Exception):
+    """Base class for all token-related errors."""
+
+
+class TokenExpiredError(TokenError):
+    """Raised when a token's expiry (exp claim) has passed."""
+
+
+class InvalidTokenError(TokenError):
+    """Raised when a token is malformed or its signature is invalid."""
+
+
+class InvalidClaimsError(TokenError):
+    """Raised when required claims (iss, aud, sub, etc.) are missing or wrong."""

fastjwt_kit/tokens.py

@@ -0,0 +1,168 @@
+"""Core JWT creation and verification utilities.
+
+Thin, opinionated wrapper around PyJWT that handles the boilerplate most
+projects rewrite by hand: expiry, claim validation, and friendly errors.
+"""
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any, Optional
+
+import jwt
+
+from .exceptions import (
+    InvalidClaimsError,
+    InvalidTokenError,
+    TokenExpiredError,
+)
+
+DEFAULT_ALGORITHM = "HS256"
+DEFAULT_ACCESS_TOKEN_EXPIRE_MINUTES = 15
+DEFAULT_REFRESH_TOKEN_EXPIRE_DAYS = 7
+
+
+def _now() -> dt.datetime:
+    return dt.datetime.now(dt.timezone.utc)
+
+
+def create_token(
+    subject: str,
+    secret: str,
+    *,
+    expires_in: dt.timedelta,
+    algorithm: str = DEFAULT_ALGORITHM,
+    issuer: Optional[str] = None,
+    audience: Optional[str] = None,
+    extra_claims: Optional[dict[str, Any]] = None,
+) -> str:
+    """Create a signed JWT.
+
+    Args:
+        subject: The "sub" claim — usually a user ID.
+        secret: Signing secret (or private key for RS256/ES256).
+        expires_in: How long until the token expires.
+        algorithm: Signing algorithm, defaults to HS256.
+        issuer: Optional "iss" claim.
+        audience: Optional "aud" claim.
+        extra_claims: Any additional claims to embed (e.g. {"role": "admin"}).
+
+    Returns:
+        Encoded JWT string.
+    """
+    now = _now()
+    payload: dict[str, Any] = {
+        "sub": subject,
+        "iat": now,
+        "exp": now + expires_in,
+    }
+    if issuer:
+        payload["iss"] = issuer
+    if audience:
+        payload["aud"] = audience
+    if extra_claims:
+        payload.update(extra_claims)
+
+    return jwt.encode(payload, secret, algorithm=algorithm)
+
+
+def create_access_token(
+    subject: str,
+    secret: str,
+    *,
+    expires_in: dt.timedelta = dt.timedelta(minutes=DEFAULT_ACCESS_TOKEN_EXPIRE_MINUTES),
+    algorithm: str = DEFAULT_ALGORITHM,
+    issuer: Optional[str] = None,
+    audience: Optional[str] = None,
+    extra_claims: Optional[dict[str, Any]] = None,
+) -> str:
+    """Create a short-lived access token. See create_token for arg details."""
+    claims = dict(extra_claims or {})
+    claims["type"] = "access"
+    return create_token(
+        subject,
+        secret,
+        expires_in=expires_in,
+        algorithm=algorithm,
+        issuer=issuer,
+        audience=audience,
+        extra_claims=claims,
+    )
+
+
+def create_refresh_token(
+    subject: str,
+    secret: str,
+    *,
+    expires_in: dt.timedelta = dt.timedelta(days=DEFAULT_REFRESH_TOKEN_EXPIRE_DAYS),
+    algorithm: str = DEFAULT_ALGORITHM,
+    issuer: Optional[str] = None,
+    audience: Optional[str] = None,
+    extra_claims: Optional[dict[str, Any]] = None,
+) -> str:
+    """Create a long-lived refresh token. See create_token for arg details."""
+    claims = dict(extra_claims or {})
+    claims["type"] = "refresh"
+    return create_token(
+        subject,
+        secret,
+        expires_in=expires_in,
+        algorithm=algorithm,
+        issuer=issuer,
+        audience=audience,
+        extra_claims=claims,
+    )
+
+
+def verify_token(
+    token: str,
+    secret: str,
+    *,
+    algorithm: str = DEFAULT_ALGORITHM,
+    issuer: Optional[str] = None,
+    audience: Optional[str] = None,
+) -> dict[str, Any]:
+    """Verify and decode a JWT, raising fastjwt_kit exceptions on failure.
+
+    Args:
+        token: The encoded JWT string.
+        secret: Signing secret (or public key for RS256/ES256).
+        algorithm: Expected signing algorithm.
+        issuer: If set, the token's "iss" claim must match this exactly.
+        audience: If set, the token's "aud" claim must match this exactly.
+
+    Returns:
+        The decoded claims dict.
+
+    Raises:
+        TokenExpiredError: if the token's exp claim has passed.
+        InvalidClaimsError: if iss/aud don't match what was expected.
+        InvalidTokenError: for any other malformed/invalid token.
+    """
+    try:
+        options = {}
+        kwargs: dict[str, Any] = {}
+        if audience is not None:
+            kwargs["audience"] = audience
+        else:
+            options["verify_aud"] = False
+
+        claims = jwt.decode(
+            token,
+            secret,
+            algorithms=[algorithm],
+            options=options,
+            **kwargs,
+        )
+    except jwt.ExpiredSignatureError as exc:
+        raise TokenExpiredError("Token has expired") from exc
+    except jwt.InvalidAudienceError as exc:
+        raise InvalidClaimsError("Token audience does not match") from exc
+    except jwt.InvalidIssuerError as exc:
+        raise InvalidClaimsError("Token issuer does not match") from exc
+    except jwt.PyJWTError as exc:
+        raise InvalidTokenError(f"Invalid token: {exc}") from exc
+
+    if issuer is not None and claims.get("iss") != issuer:
+        raise InvalidClaimsError("Token issuer does not match")
+
+    return claims

fastjwt_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: fastjwt-kit
+Version: 0.1.0
+Summary: A small, opinionated JWT toolkit: create, verify, expire, and handle errors without writing the same PyJWT boilerplate every project.
+Project-URL: Homepage, https://github.com/yourusername/fastjwt-kit
+Project-URL: Issues, https://github.com/yourusername/fastjwt-kit/issues
+Author-email: Shreyas G <shreyasg2526@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auth,authentication,fastapi,jwt,security,token
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: pyjwt>=2.8.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fastjwt-kit
+
+A small, opinionated wrapper around [PyJWT](https://pyjwt.readthedocs.io/) that
+handles the boilerplate every project rewrites: token creation, expiry,
+claim validation, and clean error handling — without you having to import
+`jwt` exceptions directly.
+
+## Install
+
+```bash
+pip install fastjwt-kit
+```
+
+## Quickstart
+
+```python
+from fastjwt_kit import create_access_token, verify_token, TokenExpiredError
+
+token = create_access_token(subject="user-123", secret="change-me")
+
+try:
+    claims = verify_token(token, secret="change-me")
+    print(claims["sub"])  # "user-123"
+except TokenExpiredError:
+    print("Token expired — ask the user to log in again")
+```
+
+That's it — no manual `exp` math, no catching raw `jwt.ExpiredSignatureError`.
+
+## Access + refresh tokens
+
+```python
+from fastjwt_kit import create_access_token, create_refresh_token
+
+access = create_access_token(subject="user-123", secret="change-me")          # 15 min default
+refresh = create_refresh_token(subject="user-123", secret="change-me")        # 7 days default
+```
+
+## Custom expiry, issuer, audience, and extra claims
+
+```python
+import datetime as dt
+from fastjwt_kit import create_token, verify_token
+
+token = create_token(
+    subject="user-123",
+    secret="change-me",
+    expires_in=dt.timedelta(hours=1),
+    issuer="my-app",
+    audience="my-app-clients",
+    extra_claims={"role": "admin"},
+)
+
+claims = verify_token(token, secret="change-me", issuer="my-app", audience="my-app-clients")
+```
+
+## Error handling
+
+All errors inherit from `TokenError`, so you can catch broadly or specifically:
+
+```python
+from fastjwt_kit import TokenError, TokenExpiredError, InvalidTokenError, InvalidClaimsError
+
+try:
+    claims = verify_token(token, secret="change-me")
+except TokenExpiredError:
+    ...  # token was valid but has expired
+except InvalidClaimsError:
+    ...  # issuer/audience didn't match
+except InvalidTokenError:
+    ...  # malformed or tampered token
+except TokenError:
+    ...  # catch-all
+```
+
+## API
+
+| Function | Description |
+|---|---|
+| `create_token(subject, secret, *, expires_in, ...)` | Create a JWT with full control over claims. |
+| `create_access_token(subject, secret, ...)` | Create a short-lived token (default 15 min), tagged `type: access`. |
+| `create_refresh_token(subject, secret, ...)` | Create a long-lived token (default 7 days), tagged `type: refresh`. |
+| `verify_token(token, secret, *, algorithm, issuer, audience)` | Decode and validate a token, raising `fastjwt_kit` exceptions. |
+
+## Why not just use PyJWT directly?
+
+You can! This package just wraps the parts everyone ends up rewriting:
+expiry defaults, issuer/audience checks, and exception types that don't
+leak the underlying library. If you only need raw encode/decode, PyJWT
+alone is enough.
+
+## Roadmap
+
+- [ ] Password hashing module
+- [ ] FastAPI signup/login router + `get_current_user` dependency
+- [ ] Config/env validation helpers
+
+Feedback and issues welcome — this is an early release and will evolve
+based on real usage.
+
+## License
+
+MIT

fastjwt_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+fastjwt_kit/__init__.py,sha256=18YV5WECksqnK7PZaPPwfzedQgvk4GFHqrlnvgkfBU0,730
+fastjwt_kit/exceptions.py,sha256=MIpm54TmPX2fWMAHswMEAH6FBgPs0-FJuqA3uinSkl4,592
+fastjwt_kit/tokens.py,sha256=nrqPj9vPk8Hsop2s8pV3CHH-lImt8V00UN6Plqai5as,4819
+fastjwt_kit-0.1.0.dist-info/METADATA,sha256=KIMgnXEs3abNj7-3IhFT2a4p6eYYyc1H8GWUK7qlJTU,4256
+fastjwt_kit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fastjwt_kit-0.1.0.dist-info/licenses/LICENSE,sha256=Pfrz0aGFmWyOqX6CLppTalPP6KvVYEZaY7yq--lPxS4,1065
+fastjwt_kit-0.1.0.dist-info/RECORD,,

fastjwt_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fastjwt_kit-0.1.0.dist-info/licenses/LICENSE

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