tina4-python 3.13.94__tar.gz → 3.13.95__tar.gz

{tina4_python-3.13.94 → tina4_python-3.13.95}/.gitignore

@@ -10,6 +10,13 @@
 .env.local
 /public/css/test.css
 /sessions/
+# Runtime session files written by the suite. This was the ONE gap of the four:
+# php ignores /data/, node ignores data/, ruby ignores sessions/ (and defaults to
+# pwd/sessions anyway) - only python left data/sessions/ visible, so a plain test
+# run dirtied the tree and `git add -A` committed session payloads. It did: five
+# of them are tracked on feature/audit-auth. FileSessionHandler already does
+# mkdir(parents=True, exist_ok=True), so a fresh clone needs nothing here.
+/data/sessions/
 /tests/secrets/domain.cert
 /tests/secrets/private.key
 /tests/secrets/public.key
@@ -98,3 +105,8 @@ example/src/**/__pycache__/
 # relative to cwd would create these under the repo. Never commit them.
 /private/
 /var/folders/
+/data/sessions/
+
+# Local file-backend queue store - runtime artefacts, never committed.
+# Four probe .queue-data files were swept in by `git add -A` on 2026-08-03.
+data/queue/

{tina4_python-3.13.94 → tina4_python-3.13.95}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.94
+Version: 3.13.95
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -14,6 +14,8 @@ Requires-Dist: pymssql>=2.3; extra == 'all-db'
 Requires-Dist: pyodbc>=5.0; extra == 'all-db'
 Provides-Extra: firebird
 Requires-Dist: firebird-driver>=1.10; extra == 'firebird'
+Provides-Extra: kafka
+Requires-Dist: confluent-kafka>=2.0; extra == 'kafka'
 Provides-Extra: memcache
 Requires-Dist: pymemcache>=4.0; extra == 'memcache'
 Provides-Extra: mongo
@@ -26,8 +28,24 @@ Provides-Extra: odbc
 Requires-Dist: pyodbc>=5.0; extra == 'odbc'
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
+Provides-Extra: rabbitmq
+Requires-Dist: pika>=1.3; extra == 'rabbitmq'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Provides-Extra: test
+Requires-Dist: boto3>=1.34; extra == 'test'
+Requires-Dist: confluent-kafka>=2.0; extra == 'test'
+Requires-Dist: firebird-driver>=1.10; extra == 'test'
+Requires-Dist: mysql-connector-python>=9.0; extra == 'test'
+Requires-Dist: pika>=1.3; extra == 'test'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'test'
+Requires-Dist: pymemcache>=4.0; extra == 'test'
+Requires-Dist: pymongo>=4.0; extra == 'test'
+Requires-Dist: pymssql>=2.3; extra == 'test'
+Requires-Dist: pyodbc>=5.0; extra == 'test'
+Requires-Dist: redis>=5.0; extra == 'test'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -116,7 +134,7 @@ Every feature is built from scratch -- no pip install, no node_modules, no third
 | **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
 | **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird: unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
 | **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
-| **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
+| **Auth & Security** (5) | JWT (HS256/HS384/HS512, zero-dependency; RS256 opt-in, needs `cryptography`), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
 | **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8x faster), SCSS auto-compilation, built-in CSS (~24 KB) |
 | **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
 | **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |

{tina4_python-3.13.94 → tina4_python-3.13.95}/README.md

@@ -84,7 +84,7 @@ Every feature is built from scratch -- no pip install, no node_modules, no third
 | **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
 | **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird: unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
 | **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
-| **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
+| **Auth & Security** (5) | JWT (HS256/HS384/HS512, zero-dependency; RS256 opt-in, needs `cryptography`), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
 | **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8x faster), SCSS auto-compilation, built-in CSS (~24 KB) |
 | **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
 | **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |

tina4_python-3.13.95/pyproject.toml

@@ -0,0 +1,121 @@
+[project]
+name = "tina4-python"
+version = "3.13.95"
+description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
+authors = [
+    {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+
+# ZERO core dependencies — this is v3's defining feature
+dependencies = []
+
+[project.optional-dependencies]
+# Database drivers — install what you need
+postgres = ["psycopg2-binary>=2.9"]
+mysql = ["mysql-connector-python>=9.0"]
+mssql = ["pymssql>=2.3"]
+firebird = ["firebird-driver>=1.10"]
+mongo = ["pymongo>=4.0"]
+odbc = ["pyodbc>=5.0"]
+
+# Session backends — install what you need
+redis = ["redis>=5.0"]
+memcache = ["pymemcache>=4.0"]
+
+# File-storage backends — install what you need.
+# The `local` filesystem backend is the zero-dependency default; S3Storage
+# (TINA4_STORAGE_BACKEND=s3) is opt-in and imports boto3 lazily.
+s3 = ["boto3>=1.34"]
+
+# Queue backends — install what you need
+kafka = ["confluent-kafka>=2.0"]
+rabbitmq = ["pika>=1.3"]
+
+# All database drivers
+all-db = [
+    "psycopg2-binary>=2.9",
+    "mysql-connector-python>=9.0",
+    "pymssql>=2.3",
+    "firebird-driver>=1.10",
+    "pymongo>=4.0",
+    "pyodbc>=5.0",
+]
+
+# Every client the TEST SUITE needs against live services.
+#
+# These were installed ad hoc by CI (`uv pip install pymongo confluent-kafka
+# pika ...`) and declared nowhere, so a fresh host had no way to know what the
+# suite requires. confluent-kafka and pika in particular were in NO extra: the
+# lab host's first full-suite run failed with three "confluent-kafka not
+# installed" errors, correctly raised by the TINA4_REQUIRE_SERVICES gate, and
+# `uv sync --all-extras` could not have fixed it because the dependency was not
+# expressed anywhere. One declared extra means `uv sync --extra test` is
+# reproducible on any machine.
+#
+# Includes firebird-driver even though the Firebird CI job installs it on its
+# own: `uv sync --extra X` PRUNES anything outside the named extras, so a test
+# extra that omitted it would silently uninstall it on a host that had it.
+#
+# boto3 is here for exactly that reason, MEASURED on the lab 2026-08-06
+# (Ubuntu 24.04.4 LTS x86_64, Python 3.13.3): it was declared in NO extra, but
+# happened to be installed ad hoc, so the two REAL-MinIO tests in
+# tests/test_realtime_files.py were passing. Running `uv sync --extra test`
+# pruned boto3 (plus s3transfer and jmespath) and those tests went straight from
+# "2 passed" to "2 skipped" -- with the suite still GREEN under
+# TINA4_REQUIRE_SERVICES=1, because the skip reason matched neither a service
+# keyword nor an unavailable hint in the conftest gate. Live S3 coverage
+# evaporated silently. Declaring it here is the fix; tests/conftest.py now also
+# recognises a missing boto3 so the gate can never miss it again.
+test = [
+    "psycopg2-binary>=2.9",
+    "mysql-connector-python>=9.0",
+    "pymssql>=2.3",
+    "firebird-driver>=1.10",
+    "pymongo>=4.0",
+    "pyodbc>=5.0",
+    "redis>=5.0",
+    "pymemcache>=4.0",
+    "confluent-kafka>=2.0",
+    "pika>=1.3",
+    "boto3>=1.34",
+]
+
+[dependency-groups]
+dev = [
+    "bottle>=0.13.4",
+    "cython>=3.2.4",
+    "django>=6.0.3",
+    "fastapi>=0.135.1",
+    "flask>=3.1.3",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "reportlab>=4.4.10",
+    "ruff>=0.4",
+    "setuptools>=82.0.1",
+    "uvicorn>=0.42.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+include = ["tina4_python/**/*"]
+
+[project.scripts]
+tina4python = "tina4_python.cli:main"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "slow: a test that needs real wall-clock time to reproduce a timing bug (deselect with -m 'not slow')",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120

{tina4_python-3.13.94 → tina4_python-3.13.95}/tina4_python/CLAUDE.md

@@ -514,8 +514,11 @@ TINA4_TOKEN_LIMIT is used to set the session time, default 60 minutes
 
 Set `TINA4_SESSION_BACKEND` to choose a backend:
 
-The value is the backend NAME, not a class name. An unknown value falls back to
-the file backend without raising.
+The value is the backend NAME, not a class name, and it is normalised (trimmed and
+lowercased), so " Redis " resolves. An UNRECOGNISED value raises `ValueError` at
+startup, naming the bad value and the valid ones -- it used to fall back to the
+file backend silently, which turned a typo into sessions quietly written to local
+disk. Unset or blank still means file.
 
 | Value | Backend | Required package |
 |---------|---------|-----------------|
@@ -1641,17 +1644,23 @@ TINA4_TOKEN_LIMIT=60              # Token lifetime in minutes (default: 60)
 TINA4_DATABASE_URL=sqlite:///app.db     # Connection URL (driver://host:port/database)
 TINA4_DATABASE_USERNAME=                 # DB username (for PostgreSQL, MySQL, etc.)
 TINA4_DATABASE_PASSWORD=                 # DB password
+TINA4_DATABASE_CONNECT_TIMEOUT=10        # Seconds a database connect may block (default 10). Set <= 0 to wait
+                                         # indefinitely (the old behaviour); a non-numeric value warns and uses 10.
+                                         # On expiry the error names the host, port, elapsed seconds and this variable.
+                                         # Applies to postgres/mysql/mssql/odbc/firebird, and to mongodb's deferred
+                                         # connect. SQLite is exempt: it opens a local file, there is no peer to hang on
 
 # Framework
 TINA4_DEBUG=true                  # Enable dev mode (toolbar, live reload, error overlay)
 TINA4_LOG_LEVEL=INFO              # Log verbosity: ALL, DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
 TINA4_LOCALE=en                   # Language for framework messages (en, fr, af, zh, ja, es)
-TINA4_DEFAULT_WEBSERVER=FALSE     # Set to TRUE to use Tina4's built-in webserver instead of ASGI
+TINA4_DEFAULT_WEBSERVER=FALSE     # TRUE pins Tina4's built-in asyncio webserver even when a production ASGI server (uvicorn/hypercorn/granian) is installed. Unset/FALSE: a production server is used when one is importable and TINA4_DEBUG is off
+TINA4_SHUTDOWN_TIMEOUT=30         # Seconds to drain in-flight requests on SIGTERM/SIGINT (default 30). Honoured on the built-in server, and mapped onto uvicorn's timeout_graceful_shutdown / hypercorn's graceful_timeout. granian has no drain deadline, so it is not honoured there (logged at startup). A non-positive or unparseable value warns and uses 30
 TINA4_OVERRIDE_CLIENT=false       # Set to true to allow running without tina4 CLI (e.g. Docker)
 HOST_NAME=localhost:7145
 
 # Sessions
-TINA4_SESSION_BACKEND=file                # file, redis, valkey, mongodb, database (unknown value falls back to file)
+TINA4_SESSION_BACKEND=file                # file, redis, valkey, mongodb, memcached, database (an unknown value RAISES; unset/blank = file)
 TINA4_SESSION_SAMESITE=Lax               # SameSite attribute for session cookies (default: Lax)
 
 # Swagger/OpenAPI
@@ -1713,7 +1722,7 @@ anywhere (the production on/off switch, wired for real in 3.13.40).
 
 ## CORS
 
-Built-in — all origins allowed by default. CORS headers and OPTIONS pre-flight are handled automatically.
+Built-in, and it DENIES by default (ADR-0018). Set `TINA4_CORS_ORIGINS` to the origins you want to allow (comma-separated), or `*` for any. With it unset no `Access-Control-Allow-Origin` is sent and the browser blocks the cross-origin request. `TINA4_CORS_CREDENTIALS=true` is never sent alongside a `*` origin (the Fetch Standard forbids the pair). OPTIONS pre-flight is handled automatically.
 
 ## SCSS Workflow
 

{tina4_python-3.13.94 → tina4_python-3.13.95}/tina4_python/__init__.py

@@ -51,7 +51,7 @@ def _resolve_version() -> str:
     #
     # test_version_constant.py now asserts this literal equals the pyproject
     # version, so the release bump cannot leave it behind again.
-    return "3.13.94"
+    return "3.13.95"
 
 
 __version__ = _resolve_version()

{tina4_python-3.13.94 → tina4_python-3.13.95}/tina4_python/auth/__init__.py

@@ -1,7 +1,19 @@
 # Tina4 Auth — Zero-dependency JWT, password hashing, and token validation.
 """
-JWT implementation using Python stdlib only (hmac + hashlib).
-No PyJWT, no cryptography package.
+JWT implementation using Python stdlib only (hmac + hashlib). No PyJWT.
+
+HMAC — HS256 (default), HS384, HS512 — is Tina4's JWT algorithm family, and it is
+zero-dependency in all four frameworks. RS256 is OPT-IN: Python's standard library
+has no asymmetric crypto, so it needs the ``cryptography`` package, which Tina4
+never declares as a dependency. Nothing about RS256 is loaded, probed or warned
+about unless a caller actually asks for it; when they do without a backend
+installed, they get ``RS256UnavailableError`` naming the exact install command.
+
+SECURITY — HMAC IS SYMMETRIC. Every service that VERIFIES a token holds the SAME
+secret that signs it, so any verifier can also MINT tokens. That is fine for one
+app or a trusted fleet, and wrong for handing tokens to a third party you do not
+control. RS256 exists so a verifier can hold only a public key; reach for it (and
+install ``cryptography``) when the verifier is not someone you trust to sign.
 
     from tina4_python.auth import Auth
 
@@ -196,8 +208,9 @@ def _resolve_secret(secret: str = None) -> str:
     return env_secret
 
 
-# Supported JWT algorithms. HMAC only — the whole family is in hashlib, so this
-# stays zero-dependency. The header's "alg" is now always the one we actually sign
+# The STANDARD JWT algorithm family for Tina4: HMAC, in every framework, with zero
+# dependencies (python: hmac + hashlib, php: hash_hmac, ruby: OpenSSL::HMAC, node:
+# node:crypto createHmac). The header's "alg" is always the one we actually sign
 # with (python#105): the digest is looked up here rather than hardcoded.
 _HMAC_ALGORITHMS = {
     "HS256": hashlib.sha256,
@@ -205,24 +218,170 @@ _HMAC_ALGORITHMS = {
     "HS512": hashlib.sha512,
 }
 
+# RS256 is OPT-IN. It is a recognised algorithm NAME everywhere, but it only works
+# where the runtime provides asymmetric crypto. Python's standard library provides
+# NONE, so RS256 in Python needs a library the app already installed - and Tina4
+# still declares no dependency on one. See _require_rs256() for the contract.
+_RSA_ALGORITHMS = ("RS256",)
+
+# Every algorithm name Tina4 recognises. RS256's PRESENCE here is deliberate: an app
+# may configure it, and whether it WORKS is decided later, at the point of use.
+_SUPPORTED_ALGORITHMS = tuple(_HMAC_ALGORITHMS) + _RSA_ALGORITHMS
+
+
+class RS256UnavailableError(RuntimeError):
+    """RS256 was asked to sign or verify and no RSA backend is installed.
+
+    Raised at the POINT OF USE (signing or verifying), never at import, boot, or
+    construction - an app that never touches RS256 never sees this type at all.
+
+    It is deliberately loud. Returning ``None`` here would be indistinguishable
+    from "that token is invalid", so a missing deployment dependency would read
+    as an authentication failure and be debugged as the wrong problem.
+
+    Cross-framework contract: the BEHAVIOUR is identical in all four - loud, at
+    the point of use, naming the remedy - while the raised TYPE is each runtime's
+    own idiom, because that is what a developer's existing handlers already
+    catch:
+
+        python  RS256UnavailableError(RuntimeError)   pip install cryptography
+        php     \\RuntimeException                     install ext-openssl
+        ruby    NotImplementedError                   rebuild Ruby with OpenSSL
+        node    Error                                 (node:crypto is builtin)
+
+    Only Python and PHP can realistically raise: Ruby's OpenSSL is a stdlib
+    default gem and Node's crypto is builtin, so their branches are unreachable
+    on any normal build. A single shared class name in four languages would be
+    four new public types for a state two of them cannot reach, so the contract
+    is pinned on the message and the timing instead - see
+    tests/test_auth_rs256_optin.py and the equivalents in the other three.
+    """
+
+
+# The message a developer actually sees. It names the package, the exact install
+# command, and the zero-dependency alternative, because "RS256 unavailable" with no
+# remedy is the mysterious failure this ruling exists to remove.
+#
+# ONE library is named on purpose. Supporting cryptography AND PyJWT AND
+# python-jose would double this code to buy nothing: they all end up calling
+# cryptography for RSA, and the base64url header.payload.signature envelope is
+# something Auth already builds for HMAC. cryptography supplies the missing
+# PRIMITIVE and nothing else.
+_RS256_UNAVAILABLE_MESSAGE = (
+    "JWT algorithm RS256 was requested, but no RSA backend is installed. "
+    "Python's standard library has no asymmetric crypto, so Tina4 cannot sign or "
+    "verify RS256 on its own - and Tina4 will not add a dependency for you. "
+    "Install it:\n"
+    "    uv add cryptography       (or: pip install cryptography)\n"
+    "Or stay zero-dependency: the HMAC family (HS256/HS384/HS512) is Tina4's "
+    "default and works in all four frameworks with no install at all - set "
+    "TINA4_JWT_ALGORITHM=HS256."
+)
+
+
+def _require_rs256():
+    """Return the RSA primitives RS256 needs, or raise ``RS256UnavailableError``.
+
+    LAZY CAPABILITY DETECTION. This function is called from the RS256 signing and
+    verifying paths and NOWHERE else: there is no import-time probe, no boot-time
+    probe, no startup warning and no log line. An app on the default HMAC path
+    never executes a line of this function, so it pays nothing - not an import,
+    not a warning - for a feature it does not use.
+
+    The import is the detection: if ``cryptography`` is installed we use it, and
+    if it is not, the ImportError becomes the actionable error above.
+    """
+    try:
+        from cryptography.hazmat.primitives import hashes, serialization
+        from cryptography.hazmat.primitives.asymmetric import padding
+    except ImportError:
+        raise RS256UnavailableError(_RS256_UNAVAILABLE_MESSAGE) from None
+    return hashes, serialization, padding
+
+
+def _pem_bytes(key: str) -> bytes:
+    """Coerce PEM key material to bytes.
+
+    The key travels in the same ``secret`` slot the HMAC family uses, which is the
+    contract PHP and Node already implement (PHP hands ``$secret`` straight to
+    openssl_pkey_get_private/openssl_pkey_get_public). One slot, one env var
+    (TINA4_SECRET), no new API surface for the other three to mirror.
+    """
+    return key.encode() if isinstance(key, str) else bytes(key or b"")
+
+
+def _rs256_sign(signing_input: bytes, private_key_pem: str) -> bytes:
+    """RSASSA-PKCS1-v1_5 over SHA-256 - the signature RFC 7518 calls RS256."""
+    hashes, serialization, padding = _require_rs256()
+    private_key = serialization.load_pem_private_key(
+        _pem_bytes(private_key_pem), password=None
+    )
+    return private_key.sign(signing_input, padding.PKCS1v15(), hashes.SHA256())
+
+
+def _rs256_verify(signing_input: bytes, signature: bytes, key_pem: str) -> bool:
+    """Verify an RS256 signature with a public (or private) PEM key.
+
+    A verifier normally holds ONLY the public key - that is the entire reason
+    RS256 exists. A private PEM is accepted too so one configured key round-trips
+    in a single-service app.
+    """
+    hashes, serialization, padding = _require_rs256()
+    pem = _pem_bytes(key_pem)
+    try:
+        public_key = serialization.load_pem_public_key(pem)
+    except Exception:
+        try:
+            public_key = serialization.load_pem_private_key(pem, password=None).public_key()
+        except Exception:
+            return False  # unusable key material is a failed verification
+    try:
+        public_key.verify(signature, signing_input, padding.PKCS1v15(), hashes.SHA256())
+        return True
+    except Exception:
+        return False
+
 # Seconds of clock skew tolerated on the "nbf" (not-before) claim. Without this a
 # token minted on one host and validated on another a second behind is rejected
 # for no real reason; RFC 7519 explicitly allows "a small leeway".
 _JWT_LEEWAY_SECONDS = 60
 
 
+def _numeric_date(value) -> "int | None":
+    """Coerce an RFC 7519 NumericDate claim to int seconds, else ``None``.
+
+    RFC 7519 s2 defines ``exp``/``nbf``/``iat`` as a NumericDate — a JSON
+    numeric value. A claim that is PRESENT but not a number is malformed, and a
+    malformed constraint must never read as "no constraint": treating a
+    non-numeric ``exp`` as absent turns a broken token into one that never
+    expires. ``bool`` is excluded deliberately — it is an ``int`` subclass in
+    Python, so ``exp: true`` would otherwise compare as the year 1970.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return int(value)
+
+
 def _resolve_algorithm(algorithm: str = None) -> str:
     """Pick the JWT algorithm: explicit arg, else TINA4_JWT_ALGORITHM, else HS256.
 
-    Raises ValueError naming the supported set when asked for one we cannot sign
-    (python#106 — the env var was registered in the CLI's known_vars and then
-    silently ignored, so a user could set HS512 and still get HS256 tokens).
+    Raises ValueError naming the supported set when asked for one we do not
+    recognise at all (python#106 — the env var was registered in the CLI's
+    known_vars and then silently ignored, so a user could set HS512 and still get
+    HS256 tokens).
+
+    RS256 RESOLVES HERE WITHOUT ANY PROBE. Recognising the name is not the same as
+    being able to sign with it: whether an RSA backend exists is decided lazily, in
+    _require_rs256(), the first time a token is actually signed or verified. That
+    split is what keeps the HMAC majority free of any RS256 detection cost.
     """
     chosen = (algorithm or os.environ.get("TINA4_JWT_ALGORITHM") or "HS256").strip()
-    if chosen not in _HMAC_ALGORITHMS:
+    if chosen not in _SUPPORTED_ALGORITHMS:
         raise ValueError(
             f"Unsupported JWT algorithm {chosen!r}. Tina4 signs with "
-            f"{', '.join(sorted(_HMAC_ALGORITHMS))} (HMAC only, zero-dependency). "
+            f"{', '.join(sorted(_HMAC_ALGORITHMS))} (HMAC, zero-dependency, the "
+            f"default and the cross-framework standard) or RS256 (opt-in, needs an "
+            f"RSA backend installed - see RS256UnavailableError). "
             f"Set TINA4_JWT_ALGORITHM to one of those."
         )
     return chosen
@@ -310,29 +469,51 @@ class Auth:
 
             # Pin the algorithm to OUR configured one instead of trusting the
             # token's header. A token asking to be verified as anything else --
-            # "none", a weaker HMAC, or an RSA alg we do not implement -- is
+            # "none", a weaker HMAC, or RS256 when we are configured for HMAC -- is
             # rejected before any signature work. Matches the Ruby check.
+            #
+            # This matters MORE now that RS256 is opt-in, not less: pinning is what
+            # stops an attacker re-labelling a token's header to pick an algorithm
+            # we did not choose, and it also means an RS256-labelled token can never
+            # drive an HMAC-configured app into the RS256 capability check.
             header = json.loads(_b64url_decode(h))
             if header.get("alg") != self.algorithm:
                 return None
 
-            expected = self._sign(f"{h}.{p}")
-            if not hmac.compare_digest(sig, expected):
+            if not self._verify(f"{h}.{p}", sig):
                 return None
 
             payload = json.loads(_b64url_decode(p))
 
-            now = time.time()
-            if "exp" in payload and now > payload["exp"]:
-                return None
-
-            # "nbf" (not-before): a post-dated token is not valid yet. Was
-            # honoured only by Ruby, so Python/PHP/Node accepted tokens their
-            # issuer had explicitly marked as not-yet-usable (python#107).
-            if "nbf" in payload and now + _JWT_LEEWAY_SECONDS < payload["nbf"]:
-                return None
+            # Integer seconds, so all four frameworks compare the SAME number.
+            # PHP/Ruby read an integer clock and Python/Node a float one; with a
+            # float clock "now > exp" and "now >= exp" differ only on an exactly
+            # integral instant, so truncating here is what makes the boundary
+            # identical everywhere rather than merely close.
+            now = int(time.time())
+
+            # RFC 7519 s4.1.4: "The processing of the 'exp' claim requires that
+            # the current date/time MUST be before the expiration date/time".
+            # now == exp is therefore ALREADY expired, so the test is >=.
+            if "exp" in payload:
+                exp = _numeric_date(payload["exp"])
+                if exp is None or now >= exp:
+                    return None
+
+            # "nbf" (not-before): a post-dated token is not valid yet. Tolerates
+            # _JWT_LEEWAY_SECONDS of clock skew, which RFC 7519 s4.1.5 permits.
+            if "nbf" in payload:
+                nbf = _numeric_date(payload["nbf"])
+                if nbf is None or now + _JWT_LEEWAY_SECONDS < nbf:
+                    return None
 
             return payload
+        except RS256UnavailableError:
+            # A missing RSA backend is a DEPLOYMENT fault, not an invalid token.
+            # Swallowing it into the None below would report "authentication
+            # failed" for every request and hide the one-line fix, so it is the
+            # single exception this catch-all deliberately lets through.
+            raise
         except Exception:
             return None
 
@@ -362,6 +543,11 @@ class Auth:
         return self.get_token(payload, expires_in=expires_in)
 
     def _sign(self, message: str) -> str:
+        # RS256 is the opt-in branch: the capability check happens HERE, at the
+        # point of use, and raises RS256UnavailableError naming the fix if no RSA
+        # backend is installed. self.secret carries the PEM private key.
+        if self.algorithm in _RSA_ALGORITHMS:
+            return _b64url_encode(_rs256_sign(message.encode(), self.secret))
         # Digest comes from the configured algorithm, so the "alg" we advertise in
         # the header is the one that actually produced this signature.
         sig = hmac.new(
@@ -369,6 +555,19 @@ class Auth:
         ).digest()
         return _b64url_encode(sig)
 
+    def _verify(self, message: str, signature: str) -> bool:
+        """Check a signature against the CONFIGURED algorithm.
+
+        Symmetric and asymmetric verification are genuinely different operations:
+        HMAC recomputes the signature and compares it in constant time, while RS256
+        verifies against a public key it cannot use to sign. Recomputing an RSA
+        signature would demand the private key on every verifier, which is exactly
+        the property RS256 exists to avoid.
+        """
+        if self.algorithm in _RSA_ALGORITHMS:
+            return _rs256_verify(message.encode(), _b64url_decode(signature), self.secret)
+        return hmac.compare_digest(signature, self._sign(message))
+
     # ── Legacy aliases ─────────────────────────────────────────────
 
     # get_token and valid_token are the primary names
@@ -410,7 +609,8 @@ class Auth:
     def authenticate_request_static(cls, headers: dict) -> dict | None:
         """Extract and validate auth from request headers without instantiating Auth.
 
-        Reads TINA4_SECRET from env. Checks: Bearer JWT, Bearer API key, Basic auth.
+        Reads TINA4_SECRET from env. Checks a Bearer JWT, then a Bearer API key.
+        There is no Basic branch - see authenticate_request.
         Returns payload dict on success, None on failure.
         """
         secret = _resolve_secret()
@@ -481,8 +681,17 @@ class Auth:
             secret:    Override signing secret (default: self.secret / TINA4_SECRET env var).
             algorithm: JWT algorithm override (default: self.algorithm / TINA4_JWT_ALGORITHM).
 
-        Checks: Bearer JWT, Bearer API key, Basic auth.
-        Returns payload dict on success, None on failure.
+        Checks a Bearer JWT, then falls back to a Bearer API key. Returns the
+        verified payload dict on success, ``None`` on failure.
+
+        There is deliberately NO Basic branch. This method used to decode
+        ``Authorization: Basic`` and return a truthy
+        ``{"auth_type": "basic", "username": ..., "password": ...}`` — but it
+        never checked those credentials against anything, so every caller
+        following the documented ``if auth is None: return 401`` idiom
+        authenticated any client that sent a base64 string. PHP, Ruby and Node
+        all returned None there. An app that wants Basic auth must verify the
+        credentials itself against its own user store.
         """
         # Both overrides used to be accepted and then dropped on the floor: the
         # body called self.valid_token(), so a caller passing secret= or
@@ -498,18 +707,13 @@ class Auth:
             token = auth_header[7:]
             if self.valid_token(token):
                 return self.get_payload(token)
+            # "_auth" is the cross-framework key for a non-JWT auth result; PHP
+            # and Node already used it, Python used "auth_type" and Ruby
+            # "api_key", so the same successful auth read three different ways.
             if self.validate_api_key(token):
-                return {"auth_type": "api_key"}
+                return {"_auth": "api_key"}
             return None
 
-        if auth_header.startswith("Basic "):
-            try:
-                decoded = base64.b64decode(auth_header[6:]).decode()
-                username, password = decoded.split(":", 1)
-                return {"auth_type": "basic", "username": username, "password": password}
-            except Exception:
-                return None
-
         return None
 
 
@@ -584,7 +788,7 @@ class AuthMiddleware:
 
 
 __all__ = [
-    "Auth", "AuthMiddleware", "get_token", "valid_token", "get_payload",
-    "refresh_token", "authenticate_request", "validate_api_key",
+    "Auth", "AuthMiddleware", "RS256UnavailableError", "get_token", "valid_token",
+    "get_payload", "refresh_token", "authenticate_request", "validate_api_key",
     "ensure_dev_secret",
 ]