admitiq 0.3.1__tar.gz

admitiq-0.3.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: admitiq
+Version: 0.3.1
+Summary: AdmitiQ: signed, expiring, revocable tokens for QR codes and links. No AI, no required server.
+Author: LogicLitz
+License: MIT
+Project-URL: Homepage, https://logiclitz.org
+Project-URL: Repository, https://github.com/HyperXfury1873/admitiq
+Project-URL: Issues, https://github.com/HyperXfury1873/admitiq/issues
+Keywords: qr,qrcode,security,tokens,tickets,attendance,coupons
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: qr
+Requires-Dist: qrcode[pil]>=7.4; extra == "qr"
+Provides-Extra: ec
+Requires-Dist: cryptography>=41.0; extra == "ec"
+Provides-Extra: redis
+Requires-Dist: redis>=4.5; extra == "redis"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: fastapi>=0.100; extra == "dev"
+Requires-Dist: flask>=2.3; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+
+# AdmitiQ (Python)
+
+**A [LogicLitz](https://logiclitz.org) open-source project.**
+
+Signed, expiring, revocable tokens for QR codes and links.
+
+> New here? Start with: [../docs/what-is-admitiq.md](../docs/what-is-admitiq.md)
+
+## Install
+
+```bash
+pip install admitiq
+pip install admitiq[qr]     # optional: QR images
+pip install admitiq[ec]     # optional: ES256
+pip install admitiq[redis]  # optional: Redis single-use store
+```
+
+## Tiny example
+
+```python
+from admitiq import issue, verify, issue_url, issue_qr
+
+token = issue({"ticket_id": "abc123"}, ttl_seconds=3600, secret="your-secret-key")
+url = issue_url("https://example.com/scan", {"ticket_id": "abc123"}, ttl_seconds=3600, secret="your-secret-key")
+# issue_qr(..., output_path="ticket.png")  # needs: pip install admitiq[qr]
+
+payload = verify(token, secret="your-secret-key")
+print(payload["data"])
+```
+
+A Node app can verify this same token with the same secret (`npm install admitiq`).
+
+## More
+
+| Topic | Link |
+|-------|------|
+| Full Python guide | [docs/python.md](../docs/python.md) |
+| QR & URL delivery | [docs/delivering-tokens.md](../docs/delivering-tokens.md) |
+| Key rotation | [docs/key-rotation.md](../docs/key-rotation.md) |
+| Security | [SECURITY.md](../SECURITY.md) |
+| Publish to PyPI | [PUBLISH.md](../PUBLISH.md) |
+| Flask demo | [examples/flask-attendance](../examples/flask-attendance) |
+
+## License
+
+MIT — [LogicLitz](https://logiclitz.org)

admitiq-0.3.1/README.md

@@ -0,0 +1,46 @@
+# AdmitiQ (Python)
+
+**A [LogicLitz](https://logiclitz.org) open-source project.**
+
+Signed, expiring, revocable tokens for QR codes and links.
+
+> New here? Start with: [../docs/what-is-admitiq.md](../docs/what-is-admitiq.md)
+
+## Install
+
+```bash
+pip install admitiq
+pip install admitiq[qr]     # optional: QR images
+pip install admitiq[ec]     # optional: ES256
+pip install admitiq[redis]  # optional: Redis single-use store
+```
+
+## Tiny example
+
+```python
+from admitiq import issue, verify, issue_url, issue_qr
+
+token = issue({"ticket_id": "abc123"}, ttl_seconds=3600, secret="your-secret-key")
+url = issue_url("https://example.com/scan", {"ticket_id": "abc123"}, ttl_seconds=3600, secret="your-secret-key")
+# issue_qr(..., output_path="ticket.png")  # needs: pip install admitiq[qr]
+
+payload = verify(token, secret="your-secret-key")
+print(payload["data"])
+```
+
+A Node app can verify this same token with the same secret (`npm install admitiq`).
+
+## More
+
+| Topic | Link |
+|-------|------|
+| Full Python guide | [docs/python.md](../docs/python.md) |
+| QR & URL delivery | [docs/delivering-tokens.md](../docs/delivering-tokens.md) |
+| Key rotation | [docs/key-rotation.md](../docs/key-rotation.md) |
+| Security | [SECURITY.md](../SECURITY.md) |
+| Publish to PyPI | [PUBLISH.md](../PUBLISH.md) |
+| Flask demo | [examples/flask-attendance](../examples/flask-attendance) |
+
+## License
+
+MIT — [LogicLitz](https://logiclitz.org)

admitiq-0.3.1/admitiq/__init__.py

@@ -0,0 +1,34 @@
+from .core import (
+    AdmitiqError,
+    TokenExpiredError,
+    InvalidSignatureError,
+    TokenRevokedError,
+    UnsupportedTokenVersionError,
+    SUPPORTED_VERSIONS,
+    issue,
+    verify,
+    verify_with_secrets,
+)
+from .qr import generate_qr, issue_qr, issue_url_qr
+from .url import DEFAULT_PARAM, embed_in_url, issue_url, token_from_url
+
+__all__ = [
+    "issue",
+    "verify",
+    "verify_with_secrets",
+    "generate_qr",
+    "issue_qr",
+    "issue_url_qr",
+    "embed_in_url",
+    "issue_url",
+    "token_from_url",
+    "DEFAULT_PARAM",
+    "SUPPORTED_VERSIONS",
+    "AdmitiqError",
+    "TokenExpiredError",
+    "InvalidSignatureError",
+    "TokenRevokedError",
+    "UnsupportedTokenVersionError",
+]
+
+__version__ = "0.3.1"

admitiq-0.3.1/admitiq/core.py

@@ -0,0 +1,170 @@
+"""
+admitiq.core — signed, expiring, revocable tokens for QR codes.
+
+No AI, no required server, no vendor lock-in. Pure HMAC signing + expiry
+checking + an optional hook for revocation/single-use enforcement.
+"""
+import base64
+import hashlib
+import hmac
+import json
+import time
+import uuid
+from typing import Any, Callable, Dict, Optional, Sequence
+
+# Wire-format versions this library can verify. Breaking changes require a new v.
+SUPPORTED_VERSIONS = (1,)
+
+
+class AdmitiqError(Exception):
+    """Base exception for all admitiq errors."""
+
+
+class TokenExpiredError(AdmitiqError):
+    """Raised when a token's expiry timestamp has passed."""
+
+
+class InvalidSignatureError(AdmitiqError):
+    """Raised when a token is malformed or its signature doesn't match."""
+
+
+class TokenRevokedError(AdmitiqError):
+    """Raised when the is_revoked callback reports this token as revoked/used."""
+
+
+class UnsupportedTokenVersionError(AdmitiqError):
+    """Raised when the token's header ``v`` is not supported by this library."""
+
+
+def _b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(data: str) -> bytes:
+    padding = "=" * (-len(data) % 4)
+    return base64.urlsafe_b64decode(data + padding)
+
+
+def _sign(message: bytes, secret: str) -> str:
+    digest = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).digest()
+    return _b64url_encode(digest)
+
+
+def _assert_supported_version(header_b64: str) -> Dict[str, Any]:
+    try:
+        header = json.loads(_b64url_decode(header_b64))
+    except (json.JSONDecodeError, ValueError) as e:
+        raise InvalidSignatureError("Malformed token header") from e
+    v = header.get("v")
+    if v not in SUPPORTED_VERSIONS:
+        raise UnsupportedTokenVersionError(
+            f"Unsupported token version {v}. "
+            f"This library supports: {', '.join(str(x) for x in SUPPORTED_VERSIONS)}"
+        )
+    return header
+
+
+def issue(payload: Dict[str, Any], ttl_seconds: int, secret: str) -> str:
+    """
+    Create a signed, expiring AdmitiQ token.
+
+    Args:
+        payload: arbitrary JSON-serializable data to embed (e.g. {"ticket_id": "abc123"})
+        ttl_seconds: how many seconds until this token expires
+        secret: shared HMAC secret used to sign the token (keep this server-side only)
+
+    Returns:
+        A compact token string, safe to encode directly into a QR code.
+    """
+    now = int(time.time())
+    header = {"alg": "HS256", "typ": "QRT", "v": 1}
+    body = {
+        "iat": now,
+        "exp": now + ttl_seconds,
+        "jti": uuid.uuid4().hex,
+        "data": payload,
+    }
+    header_b64 = _b64url_encode(json.dumps(header, separators=(",", ":")).encode())
+    body_b64 = _b64url_encode(json.dumps(body, separators=(",", ":")).encode())
+    signing_input = f"{header_b64}.{body_b64}".encode()
+    signature = _sign(signing_input, secret)
+    return f"{header_b64}.{body_b64}.{signature}"
+
+
+def verify(
+    token: str,
+    secret: str,
+    is_revoked: Optional[Callable[[str], bool]] = None,
+) -> Dict[str, Any]:
+    """
+    Verify a AdmitiQ token's signature, expiry, and (optionally) revocation status.
+
+    Args:
+        token: the token string decoded from the scanned QR code
+        secret: the same HMAC secret used to issue the token
+        is_revoked: optional callback that receives the token's jti (unique id)
+            and returns True if that specific token has been revoked or already
+            used. This is where you'd plug in your own database check, or a
+            call to a hosted revocation service.
+
+    Returns:
+        The embedded payload dict (the "data" field passed to issue()), plus
+        iat/exp/jti metadata.
+
+    Raises:
+        InvalidSignatureError: token is malformed or signature doesn't match
+        TokenExpiredError: token's expiry timestamp has passed
+        TokenRevokedError: is_revoked callback reported this token as revoked
+        UnsupportedTokenVersionError: token header ``v`` is not supported
+    """
+    try:
+        header_b64, body_b64, signature = token.split(".")
+    except ValueError:
+        raise InvalidSignatureError("Malformed token: expected 3 dot-separated parts")
+
+    signing_input = f"{header_b64}.{body_b64}".encode()
+    expected_signature = _sign(signing_input, secret)
+    if not hmac.compare_digest(expected_signature, signature):
+        raise InvalidSignatureError("Signature mismatch")
+
+    # Version is inside the signed header — check only after the signature matches.
+    _assert_supported_version(header_b64)
+
+    body = json.loads(_b64url_decode(body_b64))
+
+    if int(time.time()) > body["exp"]:
+        raise TokenExpiredError(f"Token expired at {body['exp']}")
+
+    if is_revoked is not None and is_revoked(body["jti"]):
+        raise TokenRevokedError(f"Token {body['jti']} has been revoked")
+
+    return body
+
+
+def verify_with_secrets(
+    token: str,
+    secrets: Sequence[str],
+    is_revoked: Optional[Callable[[str], bool]] = None,
+) -> Dict[str, Any]:
+    """
+    Verify against multiple HMAC secrets (key-rotation window).
+
+    Tries secrets in order; succeeds on the first valid signature.
+    Non-signature errors (expired, revoked, unsupported version) propagate immediately.
+
+    Args:
+        token: token string from the QR scan
+        secrets: current secret first, then previous secrets still in the rotation window
+        is_revoked: optional revocation callback (same as ``verify``)
+    """
+    if not secrets:
+        raise InvalidSignatureError("At least one secret is required")
+
+    last_sig_error: Optional[InvalidSignatureError] = None
+    for secret in secrets:
+        try:
+            return verify(token, secret=secret, is_revoked=is_revoked)
+        except InvalidSignatureError as e:
+            last_sig_error = e
+            continue
+    raise last_sig_error or InvalidSignatureError("Signature mismatch")

admitiq-0.3.1/admitiq/ec.py

@@ -0,0 +1,155 @@
+"""
+admitiq.ec — optional asymmetric (ES256 / ECDSA P-256) signing support.
+
+Use this instead of core.issue/verify when the verifier (e.g. a scanner app
+running on someone's phone, or a public endpoint) should NOT hold the same
+secret used to issue tokens. The issuer signs with a private key; anyone
+holding only the public key can verify a token but cannot forge new ones.
+
+Requires the 'cryptography' package:
+    pip install admitiq[ec]
+"""
+import json
+import time
+import uuid
+from typing import Any, Callable, Dict, Optional, Sequence, Tuple
+
+from .core import (
+    InvalidSignatureError,
+    TokenExpiredError,
+    TokenRevokedError,
+    _assert_supported_version,
+    _b64url_decode,
+    _b64url_encode,
+)
+
+
+def generate_keypair() -> Tuple[str, str]:
+    """
+    Generate a new EC (P-256 / secp256r1) keypair.
+
+    Returns:
+        (private_key_pem, public_key_pem) — both as PEM-encoded strings.
+        Keep the private key secret (it issues tokens); the public key can be
+        shared freely with anything that only needs to verify tokens.
+    """
+    try:
+        from cryptography.hazmat.primitives import serialization
+        from cryptography.hazmat.primitives.asymmetric import ec
+    except ImportError as e:
+        raise ImportError(
+            "Asymmetric signing requires the 'cryptography' package. "
+            "Install it with: pip install admitiq[ec]"
+        ) from e
+
+    private_key = ec.generate_private_key(ec.SECP256R1())
+    public_key = private_key.public_key()
+
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    ).decode("ascii")
+    public_pem = public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode("ascii")
+    return private_pem, public_pem
+
+
+def issue(payload: Dict[str, Any], ttl_seconds: int, private_key_pem: str) -> str:
+    """Create a token signed with an EC private key (algorithm: ES256)."""
+    try:
+        from cryptography.hazmat.primitives import hashes, serialization
+        from cryptography.hazmat.primitives.asymmetric import ec
+    except ImportError as e:
+        raise ImportError(
+            "Asymmetric signing requires the 'cryptography' package. "
+            "Install it with: pip install admitiq[ec]"
+        ) from e
+
+    private_key = serialization.load_pem_private_key(
+        private_key_pem.encode("ascii"), password=None
+    )
+
+    now = int(time.time())
+    header = {"alg": "ES256", "typ": "QRT", "v": 1}
+    body = {
+        "iat": now,
+        "exp": now + ttl_seconds,
+        "jti": uuid.uuid4().hex,
+        "data": payload,
+    }
+    header_b64 = _b64url_encode(json.dumps(header, separators=(",", ":")).encode())
+    body_b64 = _b64url_encode(json.dumps(body, separators=(",", ":")).encode())
+    signing_input = f"{header_b64}.{body_b64}".encode()
+
+    signature = private_key.sign(signing_input, ec.ECDSA(hashes.SHA256()))
+    signature_b64 = _b64url_encode(signature)
+    return f"{header_b64}.{body_b64}.{signature_b64}"
+
+
+def verify(
+    token: str,
+    public_key_pem: str,
+    is_revoked: Optional[Callable[[str], bool]] = None,
+) -> Dict[str, Any]:
+    """Verify a token created by issue() using the corresponding EC public key."""
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives import hashes, serialization
+        from cryptography.hazmat.primitives.asymmetric import ec
+    except ImportError as e:
+        raise ImportError(
+            "Asymmetric verification requires the 'cryptography' package. "
+            "Install it with: pip install admitiq[ec]"
+        ) from e
+
+    try:
+        header_b64, body_b64, signature_b64 = token.split(".")
+    except ValueError:
+        raise InvalidSignatureError("Malformed token: expected 3 dot-separated parts")
+
+    public_key = serialization.load_pem_public_key(public_key_pem.encode("ascii"))
+    signing_input = f"{header_b64}.{body_b64}".encode()
+    signature = _b64url_decode(signature_b64)
+
+    try:
+        public_key.verify(signature, signing_input, ec.ECDSA(hashes.SHA256()))
+    except InvalidSignature:
+        raise InvalidSignatureError("Signature mismatch")
+
+    _assert_supported_version(header_b64)
+
+    body = json.loads(_b64url_decode(body_b64))
+
+    if int(time.time()) > body["exp"]:
+        raise TokenExpiredError(f"Token expired at {body['exp']}")
+
+    if is_revoked is not None and is_revoked(body["jti"]):
+        raise TokenRevokedError(f"Token {body['jti']} has been revoked")
+
+    return body
+
+
+def verify_with_public_keys(
+    token: str,
+    public_key_pems: Sequence[str],
+    is_revoked: Optional[Callable[[str], bool]] = None,
+) -> Dict[str, Any]:
+    """
+    Verify against multiple EC public keys (key-rotation window).
+
+    Tries keys in order; succeeds on the first valid signature.
+    """
+    if not public_key_pems:
+        raise InvalidSignatureError("At least one public key is required")
+
+    last_sig_error: Optional[InvalidSignatureError] = None
+    for public_key_pem in public_key_pems:
+        try:
+            return verify(token, public_key_pem=public_key_pem, is_revoked=is_revoked)
+        except InvalidSignatureError as e:
+            last_sig_error = e
+            continue
+    raise last_sig_error or InvalidSignatureError("Signature mismatch")

admitiq-0.3.1/admitiq/frameworks.py

@@ -0,0 +1,75 @@
+"""
+admitiq.frameworks — optional drop-in helpers for common web frameworks.
+
+These are thin wrappers around verify() — you don't need them, the plain
+verify() function works fine on its own. They just save a few lines of
+boilerplate in the frameworks people reach for most often.
+
+FastAPI support requires 'fastapi' installed (you already have it if you're
+using FastAPI). Flask support requires 'flask' installed likewise. Neither
+is a hard dependency of admitiq itself.
+"""
+from functools import wraps
+from typing import Callable, Optional
+
+from .core import AdmitiqError, verify
+
+
+def fastapi_dependency(secret: str, is_revoked: Optional[Callable[[str], bool]] = None):
+    """
+    Build a FastAPI dependency that verifies an AdmitiQ token from the JSON
+    request body (expects {"token": "..."}).
+
+    Example:
+        from fastapi import Depends
+        check_ticket = fastapi_dependency(secret="...", is_revoked=my_check)
+
+        @app.post("/scan")
+        async def scan(payload: dict = Depends(check_ticket)):
+            return {"ok": True, "data": payload["data"]}
+    """
+    from fastapi import HTTPException, Request
+
+    async def dependency(request: Request):
+        body = await request.json()
+        token = body.get("token")
+        if not token:
+            raise HTTPException(status_code=400, detail="Missing QR token")
+        try:
+            return verify(token, secret=secret, is_revoked=is_revoked)
+        except AdmitiqError as e:
+            raise HTTPException(status_code=401, detail=str(e))
+
+    return dependency
+
+
+def flask_require_token(secret: str, is_revoked: Optional[Callable[[str], bool]] = None):
+    """
+    Flask route decorator that verifies an AdmitiQ token from the JSON request
+    body (expects {"token": "..."}) and passes the decoded payload as the
+    `admitiq_payload` keyword argument to your view function.
+
+    Example:
+        @app.route("/scan", methods=["POST"])
+        @flask_require_token(secret="...", is_revoked=my_check)
+        def scan(admitiq_payload):
+            return {"ok": True, "data": admitiq_payload["data"]}
+    """
+    from flask import jsonify, request
+
+    def decorator(view_func):
+        @wraps(view_func)
+        def wrapped(*args, **kwargs):
+            body = request.get_json(silent=True) or {}
+            token = body.get("token")
+            if not token:
+                return jsonify({"error": "Missing QR token"}), 400
+            try:
+                payload = verify(token, secret=secret, is_revoked=is_revoked)
+            except AdmitiqError as e:
+                return jsonify({"error": str(e)}), 401
+            return view_func(*args, admitiq_payload=payload, **kwargs)
+
+        return wrapped
+
+    return decorator

admitiq-0.3.1/admitiq/qr.py

@@ -0,0 +1,67 @@
+"""
+admitiq.qr — optional QR image generation helpers.
+
+Requires the 'qrcode' package:
+    pip install admitiq[qr]
+
+You can encode either a raw token or a full URL (from issue_url / embed_in_url).
+"""
+from typing import Any, Dict, Optional
+
+from .core import issue
+from .url import issue_url, token_from_url
+
+
+def generate_qr(content: str, output_path: Optional[str] = None):
+    """
+    Render a string (token or URL) as a QR code image.
+
+    Args:
+        content: token or URL to encode in the QR
+        output_path: if provided, saves the image and returns the path.
+            If omitted, returns a PIL Image object instead.
+    """
+    try:
+        import qrcode
+    except ImportError as e:
+        raise ImportError(
+            "Generating QR images requires the 'qrcode' package. "
+            "Install it with: pip install admitiq[qr]"
+        ) from e
+
+    img = qrcode.make(content)
+    if output_path:
+        img.save(output_path)
+        return output_path
+    return img
+
+
+def issue_qr(
+    payload: Dict[str, Any],
+    ttl_seconds: int,
+    secret: str,
+    output_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Issue a token and render it as a QR image in one step."""
+    token = issue(payload, ttl_seconds=ttl_seconds, secret=secret)
+    qr = generate_qr(token, output_path=output_path)
+    return {"token": token, "qr": qr}
+
+
+def issue_url_qr(
+    base_url: str,
+    payload: Dict[str, Any],
+    ttl_seconds: int,
+    secret: str,
+    output_path: Optional[str] = None,
+    param: str = "token",
+) -> Dict[str, Any]:
+    """
+    Issue a token embedded in a URL, then render that URL as a QR image.
+
+    Scanning carries the full link (useful for web check-in pages).
+    """
+    url = issue_url(base_url, payload, ttl_seconds=ttl_seconds, secret=secret, param=param)
+    token = token_from_url(url, param=param)
+    qr = generate_qr(url, output_path=output_path)
+    return {"token": token, "url": url, "qr": qr}

admitiq-0.3.1/admitiq/stores/__init__.py

@@ -0,0 +1,3 @@
+from .redis_store import RedisRevocationStore
+
+__all__ = ["RedisRevocationStore"]

admitiq-0.3.1/admitiq/stores/redis_store.py

@@ -0,0 +1,64 @@
+"""
+admitiq.stores.redis_store — optional Redis-backed revocation store.
+
+A ready-made, race-condition-safe "has this token been used" store for
+anyone running multiple servers/processes checking the same tokens, without
+needing the hosted AdmitiQ API. Still fully self-hosted and free.
+
+Requires the 'redis' package:
+    pip install admitiq[redis]
+"""
+from typing import Optional
+
+
+class RedisRevocationStore:
+    """
+    Usage:
+        store = RedisRevocationStore(url="redis://localhost:6379/0")
+        payload = verify(token, secret=SECRET, is_revoked=store.is_revoked)
+        # only after you've decided to actually honor this scan:
+        store.mark_used(payload["jti"])
+    """
+
+    def __init__(
+        self,
+        redis_client=None,
+        url: Optional[str] = None,
+        ttl_seconds: int = 86400,
+        prefix: str = "admitiq:used:",
+    ):
+        """
+        Args:
+            redis_client: an existing redis.Redis instance (preferred if you already have one)
+            url: alternatively, a redis:// URL to connect with
+            ttl_seconds: how long to remember a used jti — should be >= your longest token TTL
+            prefix: key prefix used in Redis
+        """
+        if redis_client is not None:
+            self._client = redis_client
+        else:
+            try:
+                import redis
+            except ImportError as e:
+                raise ImportError(
+                    "RedisRevocationStore requires the 'redis' package. "
+                    "Install it with: pip install admitiq[redis]"
+                ) from e
+            self._client = redis.Redis.from_url(url or "redis://localhost:6379/0")
+        self._ttl = ttl_seconds
+        self._prefix = prefix
+
+    def mark_used(self, jti: str) -> bool:
+        """
+        Atomically mark a token as used. Returns True if this was the FIRST
+        time it was marked (the scan should be allowed), False if it was
+        already used (this is a reuse attempt and should be blocked).
+        """
+        key = f"{self._prefix}{jti}"
+        was_set = self._client.set(key, "1", nx=True, ex=self._ttl)
+        return bool(was_set)
+
+    def is_revoked(self, jti: str) -> bool:
+        """Pass this method directly as the `is_revoked` argument to verify()."""
+        key = f"{self._prefix}{jti}"
+        return bool(self._client.exists(key))

admitiq-0.3.1/admitiq/url.py

@@ -0,0 +1,55 @@
+"""
+admitiq.url — embed tokens in URLs / deep links (and pull them back out).
+
+The token is still a plain signed string. These helpers only attach it to a
+URL you provide (default query param: \"token\").
+"""
+from typing import Any, Dict, Optional
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from .core import issue
+
+DEFAULT_PARAM = "token"
+
+
+def embed_in_url(base_url: str, token: str, param: str = DEFAULT_PARAM) -> str:
+    """
+    Attach an existing token to a base URL as a query parameter.
+
+    Works with https:// links and custom schemes (e.g. myapp://checkin).
+    Existing query parameters are preserved; ``param`` is set/replaced.
+    """
+    if not base_url or not isinstance(base_url, str):
+        raise ValueError("base_url must be a non-empty string")
+    if not token or not isinstance(token, str):
+        raise ValueError("token must be a non-empty string")
+
+    parts = urlsplit(base_url)
+    query = dict(parse_qsl(parts.query, keep_blank_values=True))
+    query[param] = token
+    new_query = urlencode(query)
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, new_query, parts.fragment))
+
+
+def issue_url(
+    base_url: str,
+    payload: Dict[str, Any],
+    ttl_seconds: int,
+    secret: str,
+    param: str = DEFAULT_PARAM,
+) -> str:
+    """Issue a token and return a URL with it embedded."""
+    token = issue(payload, ttl_seconds=ttl_seconds, secret=secret)
+    return embed_in_url(base_url, token, param=param)
+
+
+def token_from_url(url: str, param: str = DEFAULT_PARAM) -> str:
+    """Extract a token from a URL's query string."""
+    if not url or not isinstance(url, str):
+        raise ValueError("url must be a non-empty string")
+    parts = urlsplit(url)
+    query = dict(parse_qsl(parts.query, keep_blank_values=True))
+    token = query.get(param)
+    if not token:
+        raise ValueError(f'No "{param}" query parameter found in URL')
+    return token

admitiq-0.3.1/admitiq.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: admitiq
+Version: 0.3.1
+Summary: AdmitiQ: signed, expiring, revocable tokens for QR codes and links. No AI, no required server.
+Author: LogicLitz
+License: MIT
+Project-URL: Homepage, https://logiclitz.org
+Project-URL: Repository, https://github.com/HyperXfury1873/admitiq
+Project-URL: Issues, https://github.com/HyperXfury1873/admitiq/issues
+Keywords: qr,qrcode,security,tokens,tickets,attendance,coupons
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: qr
+Requires-Dist: qrcode[pil]>=7.4; extra == "qr"
+Provides-Extra: ec
+Requires-Dist: cryptography>=41.0; extra == "ec"
+Provides-Extra: redis
+Requires-Dist: redis>=4.5; extra == "redis"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: fastapi>=0.100; extra == "dev"
+Requires-Dist: flask>=2.3; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+
+# AdmitiQ (Python)
+
+**A [LogicLitz](https://logiclitz.org) open-source project.**
+
+Signed, expiring, revocable tokens for QR codes and links.
+
+> New here? Start with: [../docs/what-is-admitiq.md](../docs/what-is-admitiq.md)
+
+## Install
+
+```bash
+pip install admitiq
+pip install admitiq[qr]     # optional: QR images
+pip install admitiq[ec]     # optional: ES256
+pip install admitiq[redis]  # optional: Redis single-use store
+```
+
+## Tiny example
+
+```python
+from admitiq import issue, verify, issue_url, issue_qr
+
+token = issue({"ticket_id": "abc123"}, ttl_seconds=3600, secret="your-secret-key")
+url = issue_url("https://example.com/scan", {"ticket_id": "abc123"}, ttl_seconds=3600, secret="your-secret-key")
+# issue_qr(..., output_path="ticket.png")  # needs: pip install admitiq[qr]
+
+payload = verify(token, secret="your-secret-key")
+print(payload["data"])
+```
+
+A Node app can verify this same token with the same secret (`npm install admitiq`).
+
+## More
+
+| Topic | Link |
+|-------|------|
+| Full Python guide | [docs/python.md](../docs/python.md) |
+| QR & URL delivery | [docs/delivering-tokens.md](../docs/delivering-tokens.md) |
+| Key rotation | [docs/key-rotation.md](../docs/key-rotation.md) |
+| Security | [SECURITY.md](../SECURITY.md) |
+| Publish to PyPI | [PUBLISH.md](../PUBLISH.md) |
+| Flask demo | [examples/flask-attendance](../examples/flask-attendance) |
+
+## License
+
+MIT — [LogicLitz](https://logiclitz.org)

admitiq-0.3.1/admitiq.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+admitiq/__init__.py
+admitiq/core.py
+admitiq/ec.py
+admitiq/frameworks.py
+admitiq/qr.py
+admitiq/url.py
+admitiq.egg-info/PKG-INFO
+admitiq.egg-info/SOURCES.txt
+admitiq.egg-info/dependency_links.txt
+admitiq.egg-info/requires.txt
+admitiq.egg-info/top_level.txt
+admitiq/stores/__init__.py
+admitiq/stores/redis_store.py
+tests/test_core.py
+tests/test_ec.py
+tests/test_url.py

admitiq-0.3.1/admitiq.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

admitiq-0.3.1/admitiq.egg-info/requires.txt

@@ -0,0 +1,15 @@
+
+[dev]
+pytest>=7.0
+fastapi>=0.100
+flask>=2.3
+httpx>=0.24
+
+[ec]
+cryptography>=41.0
+
+[qr]
+qrcode[pil]>=7.4
+
+[redis]
+redis>=4.5

admitiq-0.3.1/admitiq.egg-info/top_level.txt

@@ -0,0 +1 @@
+admitiq

admitiq-0.3.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "admitiq"
+version = "0.3.1"
+description = "AdmitiQ: signed, expiring, revocable tokens for QR codes and links. No AI, no required server."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "LogicLitz" }]
+keywords = ["qr", "qrcode", "security", "tokens", "tickets", "attendance", "coupons"]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+qr = ["qrcode[pil]>=7.4"]
+ec = ["cryptography>=41.0"]
+redis = ["redis>=4.5"]
+dev = ["pytest>=7.0", "fastapi>=0.100", "flask>=2.3", "httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://logiclitz.org"
+Repository = "https://github.com/HyperXfury1873/admitiq"
+Issues = "https://github.com/HyperXfury1873/admitiq/issues"

admitiq-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

admitiq-0.3.1/tests/test_core.py

@@ -0,0 +1,64 @@
+import pytest
+
+from admitiq.core import (
+    InvalidSignatureError,
+    TokenExpiredError,
+    TokenRevokedError,
+    issue,
+    verify,
+)
+
+SECRET = "test-secret"
+
+
+def test_issue_and_verify_roundtrip():
+    token = issue({"ticket_id": "abc123"}, ttl_seconds=60, secret=SECRET)
+    payload = verify(token, secret=SECRET)
+    assert payload["data"]["ticket_id"] == "abc123"
+    assert "iat" in payload and "exp" in payload and "jti" in payload
+
+
+def test_expired_token_raises():
+    token = issue({"ticket_id": "abc123"}, ttl_seconds=-1, secret=SECRET)
+    with pytest.raises(TokenExpiredError):
+        verify(token, secret=SECRET)
+
+
+def test_tampered_signature_raises():
+    token = issue({"ticket_id": "abc123"}, ttl_seconds=60, secret=SECRET)
+    tampered = token[:-2] + "xx"
+    with pytest.raises(InvalidSignatureError):
+        verify(tampered, secret=SECRET)
+
+
+def test_wrong_secret_raises():
+    token = issue({"ticket_id": "abc123"}, ttl_seconds=60, secret=SECRET)
+    with pytest.raises(InvalidSignatureError):
+        verify(token, secret="wrong-secret")
+
+
+def test_revoked_token_raises():
+    token = issue({"ticket_id": "abc123"}, ttl_seconds=60, secret=SECRET)
+    with pytest.raises(TokenRevokedError):
+        verify(token, secret=SECRET, is_revoked=lambda jti: True)
+
+
+def test_malformed_token_raises():
+    with pytest.raises(InvalidSignatureError):
+        verify("not-a-real-token", secret=SECRET)
+
+
+def test_verify_with_secrets_rotation():
+    from admitiq.core import verify_with_secrets
+
+    token = issue({"ticket_id": "abc123"}, ttl_seconds=60, secret="old-secret")
+    payload = verify_with_secrets(token, secrets=["new-secret", "old-secret"])
+    assert payload["data"]["ticket_id"] == "abc123"
+
+
+def test_verify_with_secrets_all_fail():
+    from admitiq.core import verify_with_secrets
+
+    token = issue({"ticket_id": "abc123"}, ttl_seconds=60, secret=SECRET)
+    with pytest.raises(InvalidSignatureError):
+        verify_with_secrets(token, secrets=["a", "b"])

admitiq-0.3.1/tests/test_ec.py

@@ -0,0 +1,38 @@
+import pytest
+
+cryptography = pytest.importorskip("cryptography")
+
+from admitiq import ec
+from admitiq.core import InvalidSignatureError, TokenExpiredError
+
+
+def test_generate_keypair_and_roundtrip():
+    priv, pub = ec.generate_keypair()
+    token = ec.issue({"ticket_id": "abc123"}, ttl_seconds=60, private_key_pem=priv)
+    payload = ec.verify(token, public_key_pem=pub)
+    assert payload["data"]["ticket_id"] == "abc123"
+
+
+def test_wrong_public_key_rejected():
+    priv, _pub = ec.generate_keypair()
+    _priv2, pub2 = ec.generate_keypair()
+    token = ec.issue({"ticket_id": "abc123"}, ttl_seconds=60, private_key_pem=priv)
+    with pytest.raises(InvalidSignatureError):
+        ec.verify(token, public_key_pem=pub2)
+
+
+def test_expired_ec_token_raises():
+    priv, pub = ec.generate_keypair()
+    token = ec.issue({"ticket_id": "abc123"}, ttl_seconds=-1, private_key_pem=priv)
+    with pytest.raises(TokenExpiredError):
+        ec.verify(token, public_key_pem=pub)
+
+
+def test_verify_with_public_keys_rotation():
+    old_priv, old_pub = ec.generate_keypair()
+    _new_priv, new_pub = ec.generate_keypair()
+    token = ec.issue({"ticket_id": "abc123"}, ttl_seconds=60, private_key_pem=old_priv)
+    payload = ec.verify_with_public_keys(
+        token, public_key_pems=[new_pub, old_pub]
+    )
+    assert payload["data"]["ticket_id"] == "abc123"

admitiq-0.3.1/tests/test_url.py

@@ -0,0 +1,34 @@
+from admitiq import issue, verify
+from admitiq.url import embed_in_url, issue_url, token_from_url
+
+SECRET = "url-test-secret"
+
+
+def test_issue_url_embeds_verifiable_token():
+    url = issue_url("https://example.com/scan", {"seat": "A1"}, ttl_seconds=60, secret=SECRET)
+    assert url.startswith("https://example.com/scan?token=")
+    token = token_from_url(url)
+    payload = verify(token, secret=SECRET)
+    assert payload["data"]["seat"] == "A1"
+
+
+def test_embed_preserves_query():
+    token = issue({"x": 1}, ttl_seconds=60, secret=SECRET)
+    url = embed_in_url("https://example.com/scan?ref=web", token)
+    assert "ref=web" in url
+    assert "token=" in url
+    assert token_from_url(url) == token
+
+
+def test_custom_scheme():
+    token = issue({"x": 1}, ttl_seconds=60, secret=SECRET)
+    url = embed_in_url("myapp://checkin", token)
+    assert url.startswith("myapp://checkin")
+    assert token_from_url(url) == token
+
+
+def test_token_from_url_missing():
+    import pytest
+
+    with pytest.raises(ValueError, match='No "token"'):
+        token_from_url("https://example.com/scan")