tina4-python 3.13.37__tar.gz → 3.13.39__tar.gz

{tina4_python-3.13.37 → tina4_python-3.13.39}/.gitignore

@@ -6,6 +6,8 @@
 /src/templates/index.twig
 /secrets/
 /.env
+/.env.local
+.env.local
 /public/css/test.css
 /sessions/
 /tests/secrets/domain.cert
@@ -83,3 +85,8 @@ example/store/src/**/__pycache__/
 /data/store.db
 /example/store/
 /example/uv.lock
+
+# macOS $TMPDIR leak guard: tests that mis-resolve an absolute tmp path
+# relative to cwd would create these under the repo. Never commit them.
+/private/
+/var/folders/

{tina4_python-3.13.37 → tina4_python-3.13.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.37
+Version: 3.13.39
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -72,14 +72,14 @@ tina4 init python ./my-app
 cd my-app && tina4 serve
 ```
 
-Open http://localhost:7146 — your app is running.
+Open http://localhost:7146. Your app is running.
 
-> **Two CLIs:** `tina4` is the cross-language Rust CLI — it scaffolds projects, runs the dev server, and watches files. `tina4python` is the Python package's own CLI for project tasks (`migrate`, `seed`, `generate`, `test`). This guide uses `tina4` to scaffold and run, and `tina4python` for those tasks.
+> **Two CLIs:** `tina4` is the cross-language Rust CLI that scaffolds projects, runs the dev server, and watches files. `tina4python` is the Python package's own CLI for project tasks (`migrate`, `seed`, `generate`, `test`). This guide uses `tina4` to scaffold and run, and `tina4python` for those tasks.
 
 <details>
 <summary><strong>Without the Tina4 CLI (Docker / CI only)</strong></summary>
 
-The framework normally refuses to start without the `tina4` Rust CLI (it owns file watching and SCSS compilation). To bypass — e.g. inside a Docker image where you've already built the assets — set `TINA4_OVERRIDE_CLIENT=true` in `.env`:
+The framework normally refuses to start without the `tina4` Rust CLI (it owns file watching and SCSS compilation). To bypass (e.g. inside a Docker image where you've already built the assets), set `TINA4_OVERRIDE_CLIENT=true` in `.env`:
 
 ```bash
 # 1. Create project
@@ -114,12 +114,12 @@ Every feature is built from scratch -- no pip install, no node_modules, no third
 | Category | Features |
 |----------|----------|
 | **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 |
+| **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 |
 | **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) |
+| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |
 | **Data & Storage** (4) | Session (File/Redis/Valkey/MongoDB/DB), response cache (LRU, TTL), seeder + 50+ fake data generators, messenger (SMTP/IMAP) |
 | **Developer Tools** (7) | Dev dashboard (11 tabs), dev toolbar, error overlay (Catppuccin Mocha), dev mailbox, hot reload + CSS hot-reload, code metrics (complexity, coupling, maintainability), AI context installer (7 tools) |
 | **Utilities** (7) | DI container (transient + singleton), HtmlElement builder, inline testing (`@tests` decorator), i18n (6 languages), Swagger/OpenAPI auto-generation, CLI scaffolding (`generate model/route/migration/middleware`), structured logging |
@@ -691,7 +691,7 @@ Frond.clear_cache()
 
 ### Gallery
 
-7 interactive examples with **Try It** deploy — visit the dev admin at `/__dev/` to explore.
+7 interactive examples with **Try It** deploy. Visit the dev admin at `/__dev/` to explore.
 
 ## Environment
 
@@ -716,7 +716,7 @@ Supported: Claude Code, Cursor, GitHub Copilot, Windsurf, Aider, Cline, OpenAI C
 
 ## Performance
 
-Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
+Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 
 | Framework | JSON req/s | Deps | Features |
 |-----------|-----------|------|----------|
@@ -726,7 +726,7 @@ Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
 | Bottle | 4,355 | 0 | ~5 |
 | Django | 4,050 | 20+ | ~22 |
 
-Tina4 Python delivers competitive throughput with **zero dependencies and 55 features** — frameworks with higher req/s have a fraction of the functionality and require dozens of third-party packages.
+Tina4 Python delivers competitive throughput with **zero dependencies and 55 features**. Frameworks with higher req/s have a fraction of the functionality and require dozens of third-party packages.
 
 **Across all 4 Tina4 implementations:**
 
@@ -742,7 +742,7 @@ Run benchmarks locally: `python benchmarks/benchmark.py --python`
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages — same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

{tina4_python-3.13.37 → tina4_python-3.13.39}/README.md

@@ -40,14 +40,14 @@ tina4 init python ./my-app
 cd my-app && tina4 serve
 ```
 
-Open http://localhost:7146 — your app is running.
+Open http://localhost:7146. Your app is running.
 
-> **Two CLIs:** `tina4` is the cross-language Rust CLI — it scaffolds projects, runs the dev server, and watches files. `tina4python` is the Python package's own CLI for project tasks (`migrate`, `seed`, `generate`, `test`). This guide uses `tina4` to scaffold and run, and `tina4python` for those tasks.
+> **Two CLIs:** `tina4` is the cross-language Rust CLI that scaffolds projects, runs the dev server, and watches files. `tina4python` is the Python package's own CLI for project tasks (`migrate`, `seed`, `generate`, `test`). This guide uses `tina4` to scaffold and run, and `tina4python` for those tasks.
 
 <details>
 <summary><strong>Without the Tina4 CLI (Docker / CI only)</strong></summary>
 
-The framework normally refuses to start without the `tina4` Rust CLI (it owns file watching and SCSS compilation). To bypass — e.g. inside a Docker image where you've already built the assets — set `TINA4_OVERRIDE_CLIENT=true` in `.env`:
+The framework normally refuses to start without the `tina4` Rust CLI (it owns file watching and SCSS compilation). To bypass (e.g. inside a Docker image where you've already built the assets), set `TINA4_OVERRIDE_CLIENT=true` in `.env`:
 
 ```bash
 # 1. Create project
@@ -82,12 +82,12 @@ Every feature is built from scratch -- no pip install, no node_modules, no third
 | Category | Features |
 |----------|----------|
 | **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 |
+| **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 |
 | **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) |
+| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |
 | **Data & Storage** (4) | Session (File/Redis/Valkey/MongoDB/DB), response cache (LRU, TTL), seeder + 50+ fake data generators, messenger (SMTP/IMAP) |
 | **Developer Tools** (7) | Dev dashboard (11 tabs), dev toolbar, error overlay (Catppuccin Mocha), dev mailbox, hot reload + CSS hot-reload, code metrics (complexity, coupling, maintainability), AI context installer (7 tools) |
 | **Utilities** (7) | DI container (transient + singleton), HtmlElement builder, inline testing (`@tests` decorator), i18n (6 languages), Swagger/OpenAPI auto-generation, CLI scaffolding (`generate model/route/migration/middleware`), structured logging |
@@ -659,7 +659,7 @@ Frond.clear_cache()
 
 ### Gallery
 
-7 interactive examples with **Try It** deploy — visit the dev admin at `/__dev/` to explore.
+7 interactive examples with **Try It** deploy. Visit the dev admin at `/__dev/` to explore.
 
 ## Environment
 
@@ -684,7 +684,7 @@ Supported: Claude Code, Cursor, GitHub Copilot, Windsurf, Aider, Cline, OpenAI C
 
 ## Performance
 
-Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
+Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 
 | Framework | JSON req/s | Deps | Features |
 |-----------|-----------|------|----------|
@@ -694,7 +694,7 @@ Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
 | Bottle | 4,355 | 0 | ~5 |
 | Django | 4,050 | 20+ | ~22 |
 
-Tina4 Python delivers competitive throughput with **zero dependencies and 55 features** — frameworks with higher req/s have a fraction of the functionality and require dozens of third-party packages.
+Tina4 Python delivers competitive throughput with **zero dependencies and 55 features**. Frameworks with higher req/s have a fraction of the functionality and require dozens of third-party packages.
 
 **Across all 4 Tina4 implementations:**
 
@@ -710,7 +710,7 @@ Run benchmarks locally: `python benchmarks/benchmark.py --python`
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages — same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

{tina4_python-3.13.37 → tina4_python-3.13.39}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.37"
+version = "3.13.39"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.37 → tina4_python-3.13.39}/tina4_python/CLAUDE.md

@@ -725,8 +725,14 @@ api.set_basic_auth("client_id", "client_secret")
 
 # Disable SSL verification (dev only)
 api = Api("https://self-signed.local", ignore_ssl=True)
+
+# Opt-in automatic retry with exponential backoff (default off: max_retries=0).
+# Retries a transport error or a retryable status (429/5xx); 4xx is never retried.
+api = Api("https://api.example.com", max_retries=3, retry_backoff=0.5)
 ```
 
+**Redirect safety:** the client follows redirects, but the `Authorization` header is **stripped on a cross-origin hop** (different scheme/host/port) — so a bearer token is never leaked to a host you didn't authenticate against. Same-origin redirects keep the header.
+
 ### Return format
 Every request method (`get()`, `post()`, `put()`, `patch()`, `delete()`, `send()`) returns:
 ```python
@@ -952,11 +958,10 @@ uv run tina4python migrate
 ### How migrations work internally
 
 - SQL files live in `migrations/` folder, named `NNNNNN_description.sql` (6-digit sequence)
-- Files are executed **alphabetically** and split on the `;` delimiter
-- State is tracked in the `tina4_migration` table (auto-created per engine)
-- A migration only runs once — if `passed = 1` in the tracking table, it is skipped
-- Failed migrations (passed = 0) are deleted and retried on the next run
-- On **any** error, the migration rolls back and the process exits with `sys.exit(1)` — fix the error before re-running
+- Files are executed in **numeric-prefix order** (`9_` before `10_`) and split on the `;` delimiter. A file without a numeric/timestamp prefix logs a warning — its order is undefined
+- State is tracked (row-existence) in the `tina4_migration` table (auto-created per engine): a migration runs once — if a row for it exists, it is skipped. (A vestigial `passed` column exists for back-compat; only applied = `passed=1` rows are ever written — failures are never recorded as `passed=0`.)
+- **Each migration FILE is wrapped in its own transaction**: on a failure the file rolls back and `migrate()` **raises** (it does not write `passed=0`, delete anything, or `sys.exit`). Already-applied files stay applied — fix the bad file and re-run. The explicit `tina4 migrate` CLI surfaces the raise as a non-zero exit; startup auto-migration logs it and the service still boots (see TINA4_AUTO_MIGRATE above).
+- **Atomicity caveat:** per-file transactions are truly atomic only on engines with **transactional DDL (PostgreSQL)**. MySQL, Firebird, and SQLite auto-commit DDL, so a multi-statement migration that fails midway on those engines leaves earlier statements applied — keep one logical change per file. CREATE TABLE / ALTER-ADD are made idempotent on Firebird/MSSQL (existence-checked) so a re-run doesn't error.
 
 ### Engine-specific DDL patterns
 
@@ -1165,6 +1170,8 @@ queue.purge("completed")
 
 Tina4 includes zero-config SOAP 1.1 support with automatic WSDL generation.
 
+**Security:** SOAP requests containing a `<!DOCTYPE>` (DTD) are rejected with a `Client` fault before parsing — SOAP 1.1 forbids DTDs, and this closes the XML entity-expansion (billion-laughs) and external-entity (XXE) attack surface. An operation that raises returns a `Server` fault whose `<faultstring>` is the real cause **only** in debug mode (`TINA4_DEBUG`); in production it is a generic "Internal server error" and the real cause is written to the log — so a resolver exception never leaks internal state to a SOAP client.
+
 ```python
 from typing import List, Optional
 from tina4_python.wsdl import WSDL, wsdl_operation
@@ -1249,7 +1256,7 @@ result = gql.execute('{ users(limit: 3) { id name } }', variables={}, context={}
 # {"data": {"users": [...]}}
 ```
 
-Supports: queries, mutations, variables, fragments, aliases, `@skip`/`@include` directives, nested selections, list types, inline fragments. Resolver exceptions are captured as GraphQL errors.
+Supports: queries, mutations, variables, fragments, aliases, `@skip`/`@include` directives, nested selections, list types, inline fragments. Resolver exceptions are captured as GraphQL errors — the message is the real cause only in debug mode (`TINA4_DEBUG`); in production it is a generic "Internal server error" (the real cause is logged) so a resolver exception never leaks internal state. **Depth guard:** selection-set nesting is bounded by `TINA4_GRAPHQL_MAX_DEPTH` (default `50`; set `<= 0` to disable). An over-deep query or a circular fragment fails with a `"Query exceeds maximum depth of N"` error instead of overflowing the stack.
 
 | ORM Field | GraphQL Type |
 |-----------|-------------|
@@ -1604,7 +1611,7 @@ Key `.env` settings:
 
 ```bash
 # Authentication
-TINA4_SECRET=your-jwt-secret      # JWT signing (warns + uses a blank, insecure secret if unset)
+TINA4_SECRET=your-jwt-secret      # JWT signing. In DEV (TINA4_DEBUG truthy, not CI/prod) a blank value auto-generates a per-machine secret saved to gitignored .env.local; in CI/prod a blank value warns actionably (set it with `openssl rand -hex 32`)
 TINA4_API_KEY=your-api-key        # Static bearer token for API auth (API_KEY fallback supported)
 TINA4_TOKEN_LIMIT=60              # Token lifetime in minutes (default: 60)
 
@@ -1615,7 +1622,7 @@ TINA4_DATABASE_PASSWORD=                 # DB password
 
 # Framework
 TINA4_DEBUG=true                  # Enable dev mode (toolbar, live reload, error overlay)
-TINA4_LOG_LEVEL=ERROR             # Log verbosity: ALL, DEBUG, INFO, WARNING, ERROR (default: ERROR)
+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_OVERRIDE_CLIENT=false       # Set to true to allow running without tina4 CLI (e.g. Docker)
@@ -1636,10 +1643,11 @@ SWAGGER_DEV_URL=http://localhost:7145  # Dev server URL for Swagger
 ```
 
 ### Debug levels
-- `ALL` / `DEBUG` — enables DevReload, hot-patching, verbose logging, error overlay
-- `INFO` — standard logging
-- `WARNING` — warnings and errors only
-- `ERROR` — errors only
+- `ALL` / `DEBUG` — most verbose; every level on the console
+- `INFO` — standard logging (default)
+- `WARNING` — warnings, errors, and critical
+- `ERROR` — errors and critical
+- `CRITICAL` — critical only (highest severity; `Log.critical()` always logs)
 
 ## CORS
 
@@ -1853,7 +1861,7 @@ async def dashboard(request, response):
 - **2,899 tests** passing across all modules
 - **Production server auto-detect**: `tina4python serve --production` auto-installs uvicorn
 - **`tina4python generate`**: model, route, migration, middleware scaffolding
-- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **on by default** (`TINA4_AUTO_CACHING=true`, TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical reads within a request and flushes on writes; persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL` so instances share one cache with global write-invalidation; `cache_stats()` reports `mode` (request/persistent/off) and `backend`, `cache_clear()`
+- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **off by default — opt-in via `TINA4_AUTO_CACHING=true`** (TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical reads within a request and flushes on writes; it ships OFF because a request-scoped cache can return pre-write state in a read-after-write (`SELECT MAX(id)` before an `INSERT` → duplicate keys), so opt in per read-heavy endpoint. Persistent cross-request cache also opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL` so instances share one cache with global write-invalidation; `cache_stats()` reports `mode` (request/persistent/off) and `backend`, `cache_clear()`
 - **Sessions**: 4 backends (file, Redis/Valkey, MongoDB, database)
 - **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
 - **Cache**: unified backend set — memory (default), file, redis, valkey, memcached, mongodb, database — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable

{tina4_python-3.13.37 → tina4_python-3.13.39}/tina4_python/HtmlElement.py

@@ -17,6 +17,25 @@ Usage:
 import html as _html
 
 
+class Raw(str):
+    """Marker for trusted, pre-sanitised HTML that must render UNESCAPED.
+
+    String/scalar children of an HTMLElement are HTML-escaped by default to
+    prevent stored/reflected XSS. Wrap a value in Raw() to opt out of escaping
+    when (and only when) you have already sanitised it yourself.
+
+        HTMLElement("div")("<b>x</b>")        # &lt;b&gt;x&lt;/b&gt;  (escaped)
+        HTMLElement("div")(Raw("<b>x</b>"))   # <b>x</b>              (raw)
+
+    Alias: SafeString.
+    """
+    pass
+
+
+# Alias — some callers/frameworks prefer the SafeString name (matches Frond).
+SafeString = Raw
+
+
 class HTMLElement:
     """A single HTML element that renders itself and its children to a string."""
 
@@ -65,8 +84,13 @@ class HTMLElement:
 
         for child in self.children:
             if isinstance(child, HTMLElement):
+                # Nested elements render themselves (already escape their own children)
+                parts.append(str(child))
+            elif isinstance(child, Raw):
+                # Explicitly trusted markup — emit unescaped
                 parts.append(str(child))
             else:
+                # Plain string/scalar child — escape to defeat XSS
                 parts.append(_html.escape(str(child), quote=True))
 
         parts.append(f"</{self.tag}>")

{tina4_python-3.13.37 → tina4_python-3.13.39}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.13.37"
+__version__ = "3.13.39"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.13.37 → tina4_python-3.13.39}/tina4_python/api/__init__.py

@@ -10,12 +10,57 @@ Make HTTP requests without requests/httpx/aiohttp.
 """
 import json
 import ssl
+import time
 import base64
-from urllib.request import Request, urlopen
-from urllib.parse import urlencode
+from urllib.parse import urlencode, urlparse
+from urllib.request import Request, HTTPRedirectHandler, HTTPSHandler, build_opener
 from urllib.error import HTTPError, URLError
 
 
+# Statuses that warrant an automatic retry when ``max_retries`` > 0: rate-limit
+# (429) plus the transient server-side 5xx family. 4xx client errors (401,
+# 404, …) are NOT retried — a repeat won't succeed.
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+def _same_origin(url_a: str, url_b: str) -> bool:
+    """True when two URLs share scheme + host + (effective) port."""
+    a, b = urlparse(url_a), urlparse(url_b)
+    default = {"http": 80, "https": 443}
+    pa = a.port if a.port is not None else default.get(a.scheme)
+    pb = b.port if b.port is not None else default.get(b.scheme)
+    return (a.scheme, a.hostname, pa) == (b.scheme, b.hostname, pb)
+
+
+class _AuthStripRedirectHandler(HTTPRedirectHandler):
+    """Follow redirects, but drop the Authorization header on a cross-origin hop.
+
+    Plain urllib forwards the Authorization header to ANY redirect target,
+    including a different host — so an ``api.get("/login")`` that 302s to
+    ``https://attacker.example/`` would hand the bearer token to the attacker.
+    Stripping it when the target origin (scheme/host/port) differs matches
+    requests/httpx and closes that leak, while same-origin redirects keep auth.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        new_req = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new_req is not None and not _same_origin(req.full_url, newurl):
+            new_req.headers = {
+                k: v for k, v in new_req.headers.items() if k.lower() != "authorization"
+            }
+            new_req.unredirected_hdrs = {
+                k: v for k, v in getattr(new_req, "unredirected_hdrs", {}).items()
+                if k.lower() != "authorization"
+            }
+        return new_req
+
+
+def _open(req, timeout, opener):
+    """The single network-call indirection point (keeps the call site easy to
+    patch in tests). ``req`` stays the first positional arg on purpose."""
+    return opener.open(req, timeout=timeout)
+
+
 class Api:
     """HTTP client using urllib — zero external dependencies."""
 
@@ -25,7 +70,9 @@ class Api:
                  username: str | None = None,
                  password: str | None = None,
                  headers: dict[str, str] | None = None,
-                 verify_ssl: bool | None = None):
+                 verify_ssl: bool | None = None,
+                 max_retries: int = 0,
+                 retry_backoff: float = 0.5):
         """HTTP client.
 
         Constructor accepts ergonomic kwargs the documentation has long
@@ -44,12 +91,21 @@ class Api:
         ``verify_ssl`` is the docs-friendly inverse of ``ignore_ssl`` —
         ``verify_ssl=False`` is equivalent to ``ignore_ssl=True``. If
         both are supplied, ``ignore_ssl`` wins (legacy precedence).
+
+        ``max_retries`` (default 0 = off) enables automatic retry with
+        exponential backoff (``retry_backoff`` seconds base, doubling each
+        attempt) on a transport error or a retryable status (429/5xx). A
+        retried non-idempotent request (POST/…) may be re-sent — retries are
+        opt-in for that reason.
         """
         self.base_url = base_url.rstrip("/")
         self.auth_header = auth_header
         self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self.retry_backoff = retry_backoff
         self._headers: dict[str, str] = {}
         self._ssl_context = None
+        self._opener_cache = None
 
         # ── kwarg sugar ────────────────────────────────────────────────
         # Bearer token wins over basic auth if both are passed.
@@ -120,9 +176,17 @@ class Api:
             return path
         return f"{self.base_url}/{path.lstrip('/')}" if path else self.base_url
 
-    def _request(self, method: str, url: str, body=None,
-                 content_type: str = "application/json") -> dict:
-        """Execute HTTP request. Returns standardized result dict."""
+    def _opener(self):
+        """Build (once) an opener that follows redirects but strips the
+        Authorization header on a cross-origin hop, honouring the SSL context."""
+        if self._opener_cache is None:
+            handlers = [_AuthStripRedirectHandler()]
+            if self._ssl_context is not None:
+                handlers.append(HTTPSHandler(context=self._ssl_context))
+            self._opener_cache = build_opener(*handlers)
+        return self._opener_cache
+
+    def _build_request(self, method: str, url: str, body, content_type: str) -> Request:
         headers = dict(self._headers)
         if self.auth_header:
             headers["Authorization"] = self.auth_header
@@ -139,10 +203,32 @@ class Api:
                 data = body
                 headers["Content-Type"] = content_type
 
-        req = Request(url, data=data, headers=headers, method=method)
+        return Request(url, data=data, headers=headers, method=method)
+
+    def _request(self, method: str, url: str, body=None,
+                 content_type: str = "application/json") -> dict:
+        """Execute the request with opt-in retry/backoff. Returns a result dict.
+
+        With ``max_retries`` > 0, a transport failure (``http_code`` None) or a
+        retryable status (429/5xx) is retried up to ``max_retries`` times with
+        exponential backoff; any other outcome (2xx, 4xx, 3xx) returns at once.
+        """
+        req = self._build_request(method, url, body, content_type)
+        attempts = self.max_retries + 1
+        result = None
+        for attempt in range(attempts):
+            result = self._attempt(req)
+            code = result.get("http_code")
+            retryable = code is None or code in _RETRY_STATUSES
+            if not retryable or attempt == attempts - 1:
+                return result
+            time.sleep(self.retry_backoff * (2 ** attempt))
+        return result
 
+    def _attempt(self, req: Request) -> dict:
+        """A single HTTP attempt. Returns the standardized result dict."""
         try:
-            resp = urlopen(req, timeout=self.timeout, context=self._ssl_context)
+            resp = _open(req, self.timeout, self._opener())
             raw = resp.read().decode("utf-8", errors="replace")
             resp_headers = dict(resp.headers)
             try:

{tina4_python-3.13.37 → tina4_python-3.13.39}/tina4_python/auth/__init__.py

@@ -49,24 +49,145 @@ class _DualMethod:
         return functools.partial(self._func, obj)
 
 
+def _is_ci() -> bool:
+    """True when running under a CI system.
+
+    Honours the de-facto ``CI`` env var that GitHub Actions, GitLab CI,
+    CircleCI, Travis, etc. all set to a truthy value. We never generate or
+    persist a dev secret in CI — a CI run with a blank secret must surface
+    the actionable warning, not silently mint one.
+    """
+    from tina4_python.dotenv import is_truthy
+    return is_truthy(os.environ.get("CI"))
+
+
+def _is_dev() -> bool:
+    """True when the framework is in development mode (TINA4_DEBUG truthy)."""
+    from tina4_python.dotenv import is_truthy
+    return is_truthy(os.environ.get("TINA4_DEBUG"))
+
+
+def _is_production() -> bool:
+    """True when running in production (TINA4_ENV=production)."""
+    return os.environ.get("TINA4_ENV", "development") == "production"
+
+
+# Actionable message shown when TINA4_SECRET is blank in CI/prod — tells the
+# operator exactly what to set and how. Kept as a constant so the bootstrap
+# and the lazy resolver emit the identical guidance.
+_BLANK_SECRET_WARNING = (
+    "Auth: TINA4_SECRET is not set — JWT signing is insecure. "
+    "Set TINA4_SECRET to a random value (e.g. `openssl rand -hex 32`) "
+    "in your environment or .env before serving traffic."
+)
+
+
+def ensure_dev_secret(cwd: str = None) -> str | None:
+    """Generate a per-machine development JWT secret once, at server boot.
+
+    Fail-safe default for local dev: a blank ``TINA4_SECRET`` used to log a
+    loud warning on every boot even though the developer was never told what
+    to set. Instead, in DEV (and only in dev), we mint a cryptographically
+    random secret, persist it to a gitignored ``.env.local`` so it survives
+    restarts, and set it in the process env for this run.
+
+    Generation happens ONLY when ALL of these hold:
+      * ``TINA4_SECRET`` is currently blank, AND
+      * we are in DEV (``TINA4_DEBUG`` truthy), AND
+      * we are NOT in CI (``CI`` env var not truthy), AND
+      * we are NOT in production (``TINA4_ENV`` != "production").
+
+    SECURITY: never generate or persist a secret in CI or production, and
+    only ever write to ``.env.local`` (gitignored) — never ``.env``. The
+    signing secret must never become a guessable built-in default.
+
+    In CI/prod with a blank secret, this emits the actionable warning instead
+    of generating anything.
+
+    Args:
+        cwd: Directory in which to create/append ``.env.local`` (defaults to
+            the current working directory). Used by tests to point at a temp
+            dir without chdir'ing the whole process.
+
+    Returns:
+        The generated secret string when one was minted, else ``None``.
+    """
+    if os.environ.get("TINA4_SECRET"):
+        return None  # already configured — nothing to do
+
+    if not _is_dev() or _is_ci() or _is_production():
+        # CI / prod / non-dev with a blank secret: warn actionably, never mint.
+        _warn_blank_secret()
+        return None
+
+    # Dev, not CI, not prod, blank secret → mint a per-machine dev secret.
+    new_secret = secrets.token_hex(32)
+    os.environ["TINA4_SECRET"] = new_secret  # available for THIS run immediately
+
+    from pathlib import Path
+    base = Path(cwd) if cwd else Path.cwd()
+    env_local = base / ".env.local"
+    try:
+        # Append (create if missing). A trailing newline keeps the file
+        # parseable if it already held entries without a final newline.
+        prefix = ""
+        if env_local.exists():
+            existing = env_local.read_text(encoding="utf-8")
+            if existing and not existing.endswith("\n"):
+                prefix = "\n"
+        with env_local.open("a", encoding="utf-8") as fh:
+            fh.write(f"{prefix}TINA4_SECRET={new_secret}\n")
+        _log_info(
+            "Auth: generated a development secret, saved to .env.local (gitignored)"
+        )
+    except Exception as exc:
+        # Never crash boot over a file write — keep the in-memory secret for
+        # this run and warn that it won't persist.
+        _log_warning(
+            "Auth: generated a development secret but could not write "
+            f".env.local ({exc}); using it for this run only"
+        )
+    return new_secret
+
+
+def _log_info(message: str) -> None:
+    try:
+        from tina4_python.debug import Log
+        Log.info(message)
+    except Exception:
+        import sys
+        print(message, file=sys.stderr)
+
+
+def _log_warning(message: str) -> None:
+    try:
+        from tina4_python.debug import Log
+        Log.warning(message)
+    except Exception:
+        import sys
+        print(message, file=sys.stderr)
+
+
+def _warn_blank_secret() -> None:
+    _log_warning(_BLANK_SECRET_WARNING)
+
+
 def _resolve_secret(secret: str = None) -> str:
     """Resolve the JWT signing secret.
 
     Reads ``TINA4_SECRET`` from the environment. When neither an explicit
-    secret nor ``TINA4_SECRET`` is set, warns loudly and returns a blank
-    secret — parity with the PHP/Node frameworks. Tina4 never silently signs
-    with a guessable built-in default, which would make tokens forgeable.
+    secret nor ``TINA4_SECRET`` is set, warns loudly with an actionable
+    message and returns a blank secret — parity with the PHP/Node frameworks.
+    Tina4 never silently signs with a guessable built-in default, which would
+    make tokens forgeable. (In dev, ``ensure_dev_secret()`` runs at boot and
+    mints + persists a secret so this blank path is hit only in CI/prod or
+    when auth is used before boot.)
     """
     if secret:
         return secret
     env_secret = os.environ.get("TINA4_SECRET", "")
     if not env_secret:
-        try:
-            from tina4_python.debug import Log
-            Log.warning("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)")
-        except Exception:
-            import sys
-            print("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)", file=sys.stderr)
+        _warn_blank_secret()
         return ""
     return env_secret
 
@@ -403,4 +524,5 @@ class AuthMiddleware:
 __all__ = [
     "Auth", "AuthMiddleware", "get_token", "valid_token", "get_payload",
     "refresh_token", "authenticate_request", "validate_api_key",
+    "ensure_dev_secret",
 ]