Upload 5 files

README.md

@@ -123,19 +123,23 @@ All variables are set in **Space → Settings → Repository secrets**.
 | Variable | Required? | Scope | Description |
 |---|---|---|---|
 | `HF_TOKEN` | Yes (for Path 3) | Read / inference-api | Injected as `Bearer` into Path 1 and Path 3 upstream requests.  Use a **read-only** fine-grained token — it never needs write permission. |
+| `HF_TOKEN_TYPE` | No | — | Declares the type of `HF_TOKEN`.  Accepted: `fine-grained` \| `read` \| `write`.  When set, startup validation enforces least-privilege without network calls.  When absent, a length-based heuristic is used and type shows as `"unknown"` on the status page.  Setting `"write"` triggers a startup `WARNING`. |
 | `HF_WRITE_TOKEN` | No | Write (dataset repo only) | Dedicated write token used **only** by `POST /v1/contribute` to push JSONL files to `TRAINING_DATASET_REPO`.  When set, `HF_TOKEN` remains strictly read-only.  When absent, the proxy falls back to `HF_TOKEN` for writes (single-token mode, backward compatible but less secure). |
+| `HF_WRITE_TOKEN_TYPE` | No | — | Declares the type of `HF_WRITE_TOKEN`.  Accepted: `fine-grained` \| `write`.  Enables startup validation to detect a read token used for writes (which would cause every `/v1/contribute` call to fail with 403). |
 
 > **Why two tokens?** Principle of least privilege.  `HF_TOKEN` is forwarded
 > to external model backends on every inference request — if it carried write
 > permission a compromised upstream could modify your repos.  `HF_WRITE_TOKEN`
 > never leaves the proxy and is scoped to one dataset repo.
 
-The `/` status page shows both token states without exposing values:
+The `/` status page shows all token states without exposing values:
 
 ```json
 "tokens": {
-  "hf_token_set":        true,
-  "hf_write_token_set":  true,
+  "hf_token_set":         true,
+  "hf_token_type":        "fine-grained",
+  "hf_write_token_set":   true,
+  "hf_write_token_type":  "fine-grained",
   "least_privilege_mode": true
 },
 "training": {
@@ -144,6 +148,10 @@ The `/` status page shows both token states without exposing values:
 }
 ```
 
+`hf_token_type: "unknown"` means `HF_TOKEN_TYPE` is not set and the length
+heuristic could not determine the type — set `HF_TOKEN_TYPE=fine-grained` or
+`HF_TOKEN_TYPE=read` in Space secrets to resolve.
+
 `least_privilege_mode: false` means `HF_WRITE_TOKEN` is absent and writes fall
 back to `HF_TOKEN` — functional but not recommended for production.
 
@@ -155,7 +163,7 @@ back to `HF_TOKEN` — functional but not recommended for production.
 | `HF_SPACES_MODEL_URL` | No | — | **Path 2** — Custom ZeroGPU Space URL (e.g. `https://scikit-plots-ai-model.hf.space/v1/chat/completions`). Receives requests whose `model` matches `HF_SPACES_MODEL_NAMESPACES`. |
 | `HF_SPACES_MODEL_NAMESPACES` | No | `scikit-plots` | Comma-separated model owner prefixes routed to Path 2 (e.g. `scikit-plots,my-org`). |
 | `HF_BASE` | No | `https://router.huggingface.co` | **Path 3** — HF Serverless API base URL.  Only used when Path 1 and Path 2 do not match. |
-| `DEFAULT_MODEL` | No | `scikit-plots/Qwen2.5-Coder-32B-Instruct` | Fallback model when the request body omits `"model"`. |
+| `DEFAULT_MODEL` | No | `scikit-plots/Qwen2.5-Coder-7B-Instruct` | Fallback model when the request body omits `"model"`. |
 
 ### Training data collection
 
@@ -224,6 +232,26 @@ read  role  →  HF_TOKEN       (inference only; set in Space secrets)
 write role  →  HF_WRITE_TOKEN (dataset push;   set in Space secrets)
 ```
 
+### Declare token types in Space secrets
+
+After creating the tokens, set the corresponding type variables so the proxy
+can validate least-privilege at startup without network calls:
+
+```
+# Fine-grained tokens (recommended):
+HF_TOKEN_TYPE       = fine-grained
+HF_WRITE_TOKEN_TYPE = fine-grained
+
+# Classic read/write tokens (legacy):
+HF_TOKEN_TYPE       = read
+HF_WRITE_TOKEN_TYPE = write
+```
+
+If you omit these variables the proxy applies a length-based heuristic
+(tokens ≥ 52 chars → `fine-grained`; shorter → `unknown`).  The startup log
+and status page will show `"unknown"` for the type, which suppresses
+least-privilege warnings — always set explicit types in production.
+
 ---
 
 ## Training data setup
@@ -314,7 +342,7 @@ below.
 HF_SPACES_MODEL_URL        = https://scikit-plots-ai-model.hf.space/v1/chat/completions
 HF_SPACES_MODEL_NAMESPACES = scikit-plots
 PATH2_TIMEOUT              = 600   ← CPU cold start takes 4–5 minutes
-DEFAULT_MODEL              = scikit-plots/Qwen2.5-Coder-32B-Instruct
+DEFAULT_MODEL              = scikit-plots/Qwen2.5-Coder-7B-Instruct
 ```
 
 ### Path 1 — Local / custom backend (Docker Model Runner, Ollama)
@@ -332,14 +360,16 @@ export HF_TOKEN=hf_<optional-for-path-1>
 ```
 # Inference
 HF_TOKEN                   = hf_<read-token>
+HF_TOKEN_TYPE              = fine-grained
 HF_SPACES_MODEL_URL        = https://scikit-plots-ai-model.hf.space/v1/chat/completions
 HF_SPACES_MODEL_NAMESPACES = scikit-plots
-DEFAULT_MODEL              = scikit-plots/Qwen2.5-Coder-32B-Instruct
+DEFAULT_MODEL              = scikit-plots/Qwen2.5-Coder-7B-Instruct
 PATH2_TIMEOUT              = 600
 PATH3_TIMEOUT              = 120
 
 # Training data collection
 HF_WRITE_TOKEN             = hf_<write-token>
+HF_WRITE_TOKEN_TYPE        = fine-grained
 TRAINING_DATASET_REPO      = scikit-plots/ai-assistant-contributions
 
 # Security
@@ -355,7 +385,7 @@ BASE=https://scikit-plots-ai.hf.space
 
 # 1. Liveness probe
 curl $BASE/health
-# {"status":"ok","version":"6.0.0"}
+# {"status":"ok","version":"6.1.0"}
 
 # 2. Full status — check routing, token slots, and training readiness
 curl $BASE/ | python3 -m json.tool
@@ -371,7 +401,7 @@ curl $BASE/v1/chat/completions \
 # 4. Test a chat completion (Path 2 — custom Space)
 curl $BASE/v1/chat/completions \
   -H "Content-Type: application/json" \
-  -d '{"model":"scikit-plots/Qwen2.5-Coder-32B-Instruct","messages":[{"role":"user","content":"hi"}]}'
+  -d '{"model":"scikit-plots/Qwen2.5-Coder-7B-Instruct","messages":[{"role":"user","content":"hi"}]}'
 
 # 5. Test training contribution (requires TRAINING_DATASET_REPO + write token)
 curl $BASE/v1/contribute \
@@ -400,7 +430,7 @@ curl $BASE/v1/contribute \
 
 ## Why mirror repos fail — and how Path 2 solves it
 
-`scikit-plots/gpt-oss-20b` and `scikit-plots/Qwen2.5-Coder-32B-Instruct` are
+`scikit-plots/gpt-oss-20b` and `scikit-plots/Qwen2.5-Coder-7B-Instruct` are
 **mirror repositories** — weights copied from the originals but **not
 registered with any HF Inference Provider**.
 
@@ -413,7 +443,7 @@ registered with any HF Inference Provider**.
 Path 2 intercepts requests whose `model` field starts with a configured
 namespace **before** they reach the HF Serverless router, and forwards them to
 the custom ZeroGPU Space that actually has the weights loaded.  This is why
-`DEFAULT_MODEL = scikit-plots/Qwen2.5-Coder-32B-Instruct` works when
+`DEFAULT_MODEL = scikit-plots/Qwen2.5-Coder-7B-Instruct` works when
 `HF_SPACES_MODEL_NAMESPACES = scikit-plots` is set.
 
 ---
@@ -433,6 +463,10 @@ the custom ZeroGPU Space that actually has the weights loaded.  This is why
 | `least_privilege_mode: false` on status page | `HF_WRITE_TOKEN` not set | Set `HF_WRITE_TOKEN`; proxy works but uses `HF_TOKEN` for writes (less secure) |
 | Container crashes: `ModuleNotFoundError: No module named '_shared_logic'` | `_shared_logic.py` missing from the Space repo | Commit `_shared_logic.py` alongside `app.py` |
 | 413 on large conversation export | Body exceeds `MAX_BODY_BYTES` (default 10 MB) | Increase `MAX_BODY_BYTES` in Space secrets |
+| Startup log: `WARNING: Startup token-config check: HF_TOKEN has type 'write' …` | A write token is being used for inference — violates least-privilege | Replace `HF_TOKEN` with a read or fine-grained token scoped to Inference only; set `HF_TOKEN_TYPE=read` or `HF_TOKEN_TYPE=fine-grained` in Space secrets |
+| Startup log: `WARNING: Startup token-config check: HF_WRITE_TOKEN has type 'read' …` | A read-only token is configured as the write token | Replace `HF_WRITE_TOKEN` with a write or fine-grained token that has dataset write scope; set `HF_WRITE_TOKEN_TYPE=write` or `HF_WRITE_TOKEN_TYPE=fine-grained` |
+| Status page shows `hf_token_type: "unknown"` | `HF_TOKEN_TYPE` not set; length-based heuristic could not determine token type | Set `HF_TOKEN_TYPE=fine-grained` or `HF_TOKEN_TYPE=read` in Space secrets to enable least-privilege startup checks |
+| Status page shows `hf_token_type: "write"` with a startup WARNING | `HF_TOKEN` is a write token — too many permissions for inference | Create a separate read or fine-grained token for `HF_TOKEN` and set `HF_TOKEN_TYPE=read`; keep the write token only in `HF_WRITE_TOKEN` |
 
 ---
 

_shared_logic.py

@@ -1,4 +1,4 @@
-# _shared_logic.py  v6.0.0
+# _shared_logic.py  v6.1.0
 #
 # Single source of truth for shared constants, pure helper functions, and
 # type aliases used by the deployed proxy (_hf_spaces_proxy/app.py) and the
@@ -56,6 +56,26 @@
 #   Callers who hard-code ``HF_BASE`` to the old hostname must migrate to
 #   the new router URL.
 #
+# New in v6.1.0 — Three-type HF token system
+# -------------------------------------------
+# + ``HFTokenType`` literal type alias added: ``"fine-grained" | "read" |
+#   ``"write" | "unknown"``.  Maps directly to the three token types exposed
+#   in HF Settings → Tokens.
+# + ``HF_TOKEN_TYPE_*`` string constants and ``HF_INFERENCE_TOKEN_TYPES`` /
+#   ``HF_WRITE_TOKEN_TYPES`` frozensets added for type-safe comparisons.
+# + ``_classify_token_type()`` — classify a token by explicit env-var
+#   declaration (``HF_TOKEN_TYPE``, ``HF_WRITE_TOKEN_TYPE``) with a length-
+#   based heuristic fallback.
+# + ``_token_suitable_for_inference()`` / ``_token_suitable_for_writes()``
+#   predicates for principle-of-least-privilege validation.
+# + ``_validate_token_config()`` — returns actionable WARNING / ERROR strings
+#   for token-type mismatches detected at startup.
+# + ``_token_log_fragment()`` gains an optional ``token_type`` parameter so
+#   log lines include the token type (e.g. ``hf_abcde...1234 (read)``).
+# + ``load_proxy_env()`` extended with ``hf_token_type`` and
+#   ``hf_write_token_type`` keys read from the matching env vars.
+# + ``_safe_float`` added to ``__all__`` (was importable but unadvertised).
+#
 # SPDX-License-Identifier: BSD-3-Clause
 # Authors: The scikit-plots developers
 
@@ -134,10 +154,12 @@ from __future__ import annotations
 
 import json
 import os
-from typing import Any
+from typing import Any, Literal
 
 __all__ = [
-    # Constants
+    # Version
+    "PROXY_VERSION",
+    # Constants — routing / timeout
     "DEFAULT_HF_BASE",
     "DEFAULT_HF_SPACES_MODEL_NAMESPACES",
     "DEFAULT_HF_SPACES_MODEL_URL",
@@ -146,14 +168,28 @@ __all__ = [
     "DEFAULT_PATH2_READ_TIMEOUT",
     "DEFAULT_PATH3_READ_TIMEOUT",
     "DEFAULT_PROXY_TIMEOUT",
-    "PROXY_VERSION",
-    # Helpers
+    # Constants — token type system (v6.1.0)
+    "HFTokenType",
+    "HF_TOKEN_TYPE_FINE_GRAINED",
+    "HF_TOKEN_TYPE_READ",
+    "HF_TOKEN_TYPE_WRITE",
+    "HF_TOKEN_TYPE_UNKNOWN",
+    "HF_INFERENCE_TOKEN_TYPES",
+    "HF_WRITE_TOKEN_TYPES",
+    # Helpers — general
     "_build_cors_headers",
     "_is_custom_model_namespace",
     "_parse_model",
-    "_resolve_upstream_url",
+    "_safe_float",
     "_safe_int",
     "_token_log_fragment",
+    # Helpers — token type system (v6.1.0)
+    "_classify_token_type",
+    "_token_suitable_for_inference",
+    "_token_suitable_for_writes",
+    "_validate_token_config",
+    # Helpers — routing / env
+    "_resolve_upstream_url",
     "_validate_env",
     "load_proxy_env",
 ]
@@ -164,7 +200,7 @@ __all__ = [
 # ─────────────────────────────────────────────────────────────────────────────
 
 #: Proxy release version — bump on every breaking change.
-PROXY_VERSION: str = "6.0.0"
+PROXY_VERSION: str = "6.1.0"
 
 #: HuggingFace Inference Providers router base URL (no trailing slash).
 #: Only used for Path 3 (standard provider models) when ``BACKEND_URL`` is
@@ -179,7 +215,7 @@ DEFAULT_HF_BASE: str = "https://router.huggingface.co"
 
 #: Fallback model ID when the request body omits the ``model`` field.
 #: Must have a registered HF Inference Provider for Path 3.
-DEFAULT_MODEL: str = "scikit-plots/Qwen2.5-Coder-32B-Instruct"
+DEFAULT_MODEL: str = "scikit-plots/Qwen2.5-Coder-7B-Instruct"
 
 #: Global upstream read timeout in seconds (used for Path 1 / backward compat).
 #:
@@ -224,6 +260,90 @@ DEFAULT_HF_SPACES_MODEL_URL: str = (
 DEFAULT_HF_SPACES_MODEL_NAMESPACES: tuple[str, ...] = ("scikit-plots",)
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# HuggingFace token type system  (v6.1.0)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# HuggingFace exposes exactly three token types in
+# https://huggingface.co/settings/tokens:
+#
+#   ① Fine-grained   — New-style token.  Permissions set at creation time:
+#                      choose any combination of per-repo access levels and
+#                      API capabilities.  Recommended for production because
+#                      each token carries only the minimum required scope.
+#
+#   ② Read (classic) — Legacy read-only token.  Grants read access to all
+#                      public repos and any private repos you can access.
+#                      Always includes the Serverless Inference API capability.
+#                      Cannot push commits or create repos.
+#
+#   ③ Write (classic)— Legacy read+write token.  All read permissions plus
+#                      the ability to push commits, create repos, manage
+#                      members, etc.  Over-privileged for inference-only use.
+#
+# Mapping to proxy env vars
+# ─────────────────────────
+#   HF_TOKEN       — inference token (Path 2 private Space + Path 3 HF API).
+#                    Best practice: fine-grained with inference-api scope only,
+#                    OR classic read.  Never use a write token here.
+#
+#   HF_WRITE_TOKEN — dataset write token (/v1/contribute → HfApi.create_commit).
+#                    Best practice: fine-grained scoped to ONE dataset repo,
+#                    OR classic write.  Never use a read token here.
+#
+# Optional type-declaration env vars (Space → Settings → Repository secrets):
+#   HF_TOKEN_TYPE       = fine-grained | read | write   (default: auto-detect)
+#   HF_WRITE_TOKEN_TYPE = fine-grained | write          (default: auto-detect)
+#
+# ─────────────────────────────────────────────────────────────────────────────
+
+#: Literal type for HuggingFace token type labels.
+#: Use as type annotation and for exhaustive ``isinstance``-free comparisons.
+HFTokenType = Literal["fine-grained", "read", "write", "unknown"]
+
+#: New-style fine-grained HF token.  Permissions defined at creation time.
+#: Declare via env var: ``HF_TOKEN_TYPE=fine-grained``.
+HF_TOKEN_TYPE_FINE_GRAINED: str = "fine-grained"
+
+#: Classic HF read token.  Read + Inference API; no write capability.
+#: Declare via env var: ``HF_TOKEN_TYPE=read``.
+HF_TOKEN_TYPE_READ: str = "read"
+
+#: Classic HF write token.  All read permissions + repo push capability.
+#: Declare via env var: ``HF_TOKEN_TYPE=write`` or ``HF_WRITE_TOKEN_TYPE=write``.
+HF_TOKEN_TYPE_WRITE: str = "write"
+
+#: Sentinel: token type not declared and could not be inferred.
+#: Runtime operations are not blocked, but :func:`_validate_token_config` omits
+#: least-privilege warnings because the type is unknown.
+HF_TOKEN_TYPE_UNKNOWN: str = "unknown"
+
+#: Token types that are appropriate for HF Serverless Inference API calls
+#: (Path 3) and private HF Space access (Path 2).
+#:
+#: Classic write tokens ARE technically capable of inference (write ⊇ read),
+#: but are excluded from this set so :func:`_validate_token_config` can emit
+#: a startup warning when a write token is used where a read / fine-grained
+#: token is the correct choice.  The ``"unknown"`` sentinel is included so
+#: that un-declared tokens do not trigger false-positive warnings.
+HF_INFERENCE_TOKEN_TYPES: frozenset[str] = frozenset({
+    HF_TOKEN_TYPE_FINE_GRAINED,
+    HF_TOKEN_TYPE_READ,
+    HF_TOKEN_TYPE_UNKNOWN,
+})
+
+#: Token types that can push commits to HuggingFace repos and datasets.
+#:
+#: Classic read tokens **cannot** write — any ``HfApi.create_commit`` call
+#: returns HTTP 403 / 401.  ``"unknown"`` is excluded so that
+#: :func:`_validate_token_config` can flag a read token configured as the write
+#: token as a hard error rather than silently failing at request time.
+HF_WRITE_TOKEN_TYPES: frozenset[str] = frozenset({
+    HF_TOKEN_TYPE_FINE_GRAINED,
+    HF_TOKEN_TYPE_WRITE,
+})
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Pure helper functions
 # ─────────────────────────────────────────────────────────────────────────────
@@ -340,11 +460,11 @@ def _parse_model(body: bytes, default: str = DEFAULT_MODEL) -> str:
     >>> _parse_model(b'{"model": "Qwen/Qwen2.5-Coder-7B-Instruct"}')
     'Qwen/Qwen2.5-Coder-7B-Instruct'
     >>> _parse_model(b"{}")
-    'scikit-plots/Qwen2.5-Coder-32B-Instruct'
+    'scikit-plots/Qwen2.5-Coder-7B-Instruct'
     >>> _parse_model(b"not-json")
-    'scikit-plots/Qwen2.5-Coder-32B-Instruct'
+    'scikit-plots/Qwen2.5-Coder-7B-Instruct'
     >>> _parse_model(b'{"model": "  "}')
-    'scikit-plots/Qwen2.5-Coder-32B-Instruct'
+    'scikit-plots/Qwen2.5-Coder-7B-Instruct'
     """
     try:
         data: Any = json.loads(body)
@@ -441,7 +561,7 @@ def _build_cors_headers(allowed_origin: str = "*") -> dict[str, str]:
     }
 
 
-def _token_log_fragment(token: str) -> str:
+def _token_log_fragment(token: str, token_type: str = "") -> str:
     """
     Produce a safely-truncated token string for log output.
 
@@ -449,6 +569,11 @@ def _token_log_fragment(token: str) -> str:
     ----------
     token : str
         A HuggingFace API token (typically ``hf_xxx...``).
+    token_type : str, optional
+        Token type string (one of the ``HF_TOKEN_TYPE_*`` constants).
+        When non-empty and not ``"unknown"``, appended as a parenthetical
+        suffix so log lines identify the token class without exposing the
+        value.  Example: ``hf_abcde...1234 (read)``.
 
     Returns
     -------
@@ -466,13 +591,322 @@ def _token_log_fragment(token: str) -> str:
     --------
     >>> _token_log_fragment("hf_abcdefghij1234")
     'hf_abcde...1234'
+    >>> _token_log_fragment("hf_abcdefghij1234", token_type="read")
+    'hf_abcde...1234 (read)'
     >>> _token_log_fragment("")
     '<not-set>'
     """
     if not token or len(token) < 12:  # noqa: PLR2004
         return "<not-set>"
-    return f"{token[:8]}...{token[-4:]}"
+    fragment = f"{token[:8]}...{token[-4:]}"
+    if token_type and token_type != HF_TOKEN_TYPE_UNKNOWN:
+        return f"{fragment} ({token_type})"
+    return fragment
+
+
+def _classify_token_type(
+    token: str,
+    declared_type: str | None = None,
+) -> HFTokenType:
+    """
+    Classify a HuggingFace token by its declared type or format heuristics.
+
+    Token type classification is used at startup by :func:`_validate_token_config`
+    to enforce the principle of least privilege before any requests arrive.
+
+    Parameters
+    ----------
+    token : str
+        The HuggingFace API token string.
+    declared_type : str or None, optional
+        Explicitly declared type from an environment variable
+        (``HF_TOKEN_TYPE`` or ``HF_WRITE_TOKEN_TYPE``).
+        Accepted values: ``"fine-grained"``, ``"read"``, ``"write"``
+        (and minor formatting variants: ``"finegrained"``,
+        ``"fine_grained"``).  When provided and recognized, it takes
+        precedence over all heuristics.
 
+    Returns
+    -------
+    HFTokenType
+        One of ``"fine-grained"``, ``"read"``, ``"write"``, or ``"unknown"``.
+
+    Notes
+    -----
+    **Security note** — Token type cannot be verified without an authenticated
+    call to the HF API (``GET https://huggingface.co/api/whoami-v2``).  This
+    function applies lightweight format heuristics only.  For production
+    deployments, always declare the type explicitly via ``HF_TOKEN_TYPE`` /
+    ``HF_WRITE_TOKEN_TYPE`` so :func:`_validate_token_config` can enforce
+    least-privilege at startup without any network calls.
+
+    **Developer note** — As of 2025, classic HF tokens are approximately 34
+    characters total (``hf_`` prefix + 30 alphanumeric chars).  Fine-grained
+    tokens are substantially longer (≥ 52 characters total as of the HF 2025
+    token format).  This length heuristic is imprecise and subject to silent
+    change by HF; explicit declaration via env vars is always preferred.
+
+    Examples
+    --------
+    Explicit declaration takes precedence over heuristics:
+
+    >>> _classify_token_type("hf_" + "a" * 30, declared_type="read")
+    'read'
+    >>> _classify_token_type("hf_" + "a" * 30, declared_type="write")
+    'write'
+
+    Heuristic: token ≥ 52 chars → fine-grained:
+
+    >>> _classify_token_type("hf_" + "a" * 50)
+    'fine-grained'
+
+    Short classic token without declaration → unknown:
+
+    >>> _classify_token_type("hf_" + "a" * 28)
+    'unknown'
+
+    Empty or malformed token → unknown:
+
+    >>> _classify_token_type("")
+    'unknown'
+    """
+    # Normalise accepted declared-type values (tolerate minor formatting variants).
+    _declared_map: dict[str, HFTokenType] = {
+        "fine-grained": "fine-grained",
+        "finegrained":  "fine-grained",
+        "fine_grained": "fine-grained",
+        "read":         "read",
+        "write":        "write",
+    }
+    if declared_type:
+        normalised = _declared_map.get(declared_type.lower().strip())
+        if normalised is not None:
+            return normalised
+
+    # Validate basic token format — all HF tokens start with "hf_".
+    if not token or not token.startswith("hf_") or len(token) < 10:  # noqa: PLR2004
+        return "unknown"
+
+    # Heuristic: fine-grained tokens are substantially longer than classic tokens.
+    # Classic tokens: ~34 chars total.  Fine-grained tokens: ≥ 52 chars (HF 2025).
+    # Best-effort only; explicit declaration via env vars is always preferred.
+    if len(token) >= 52:  # noqa: PLR2004
+        return "fine-grained"
+
+    # Cannot distinguish classic read vs write by token string alone.
+    return "unknown"
+
+
+def _token_suitable_for_inference(token_type: str) -> bool:
+    """
+    Return ``True`` when *token_type* is appropriate for HF Inference API calls.
+
+    This predicate guards inference paths (Path 2 private Space access and
+    Path 3 HF Serverless API).  Returning ``False`` for a classic write token
+    does not block the token at runtime — it causes :func:`_validate_token_config`
+    to emit a startup ``WARNING`` so the operator knows they are running with
+    more permission than necessary.
+
+    Parameters
+    ----------
+    token_type : str
+        One of the ``HF_TOKEN_TYPE_*`` constants or a free-form string parsed
+        from an environment variable.
+
+    Returns
+    -------
+    bool
+        ``True`` for ``"fine-grained"``, ``"read"``, and ``"unknown"``.
+        ``False`` for ``"write"`` (classic write token — over-privileged).
+
+    Notes
+    -----
+    The recommended configuration is a fine-grained token scoped exclusively
+    to ``Make calls to the serverless Inference API``, or a classic read
+    token.  Classic write tokens carry unnecessary repo-write permission
+    and violate the principle of least privilege.
+
+    Examples
+    --------
+    >>> _token_suitable_for_inference("read")
+    True
+    >>> _token_suitable_for_inference("fine-grained")
+    True
+    >>> _token_suitable_for_inference("write")
+    False
+    >>> _token_suitable_for_inference("unknown")
+    True
+    """
+    return token_type in HF_INFERENCE_TOKEN_TYPES
+
+
+def _token_suitable_for_writes(token_type: str) -> bool:
+    """
+    Return ``True`` when *token_type* can authorize HuggingFace write operations.
+
+    This predicate guards the ``/v1/contribute`` endpoint.  Returning ``False``
+    for a classic read or unknown token causes :func:`_validate_token_config`
+    to emit a startup ``ERROR`` string because the token WILL fail at
+    ``HfApi.create_commit`` time (HTTP 403 / 401 from HF).
+
+    Parameters
+    ----------
+    token_type : str
+        One of the ``HF_TOKEN_TYPE_*`` constants or a free-form string parsed
+        from an environment variable.
+
+    Returns
+    -------
+    bool
+        ``True`` for ``"fine-grained"`` and ``"write"``.
+        ``False`` for ``"read"`` and ``"unknown"``.
+
+    Notes
+    -----
+    Fine-grained tokens can write **only if** write permission was granted to
+    the target repo at token-creation time.  A fine-grained token created
+    with only inference-API scope will also fail on write operations, but the
+    proxy cannot verify fine-grained permissions without an authenticated API
+    call.  Fine-grained tokens are therefore accepted here and any permission
+    failures surface at operation time with a clear HTTP 503 error.
+
+    Examples
+    --------
+    >>> _token_suitable_for_writes("write")
+    True
+    >>> _token_suitable_for_writes("fine-grained")
+    True
+    >>> _token_suitable_for_writes("read")
+    False
+    >>> _token_suitable_for_writes("unknown")
+    False
+    """
+    return token_type in HF_WRITE_TOKEN_TYPES
+
+
+def _validate_token_config(
+    hf_token: str,
+    hf_write_token: str,
+    training_dataset_repo: str = "",
+    *,
+    hf_token_type: str = HF_TOKEN_TYPE_UNKNOWN,
+    hf_write_token_type: str = HF_TOKEN_TYPE_UNKNOWN,
+) -> list[str]:
+    """
+    Validate token types and return actionable warning / error strings.
+
+    Enforces the principle of least privilege and detects token-type
+    misconfigurations that would cause silent failures at request time.
+    Returns a list of strings rather than raising exceptions so the proxy
+    can start in degraded mode and surface issues through structured logs.
+
+    Call this at startup **after** :func:`_validate_env` so routing is
+    confirmed viable before type checks are run.
+
+    Parameters
+    ----------
+    hf_token : str
+        HuggingFace token used for inference (``HF_TOKEN`` env var).
+    hf_write_token : str
+        HuggingFace token used for dataset writes (``HF_WRITE_TOKEN`` env
+        var).  Pass empty string when not configured.
+    training_dataset_repo : str, optional
+        HuggingFace Dataset repo ID (``TRAINING_DATASET_REPO`` env var).
+        Pass empty string when ``/v1/contribute`` is not enabled.
+    hf_token_type : str, optional
+        Classified type for *hf_token* (from :func:`_classify_token_type`).
+        Defaults to ``"unknown"``.
+    hf_write_token_type : str, optional
+        Classified type for *hf_write_token*.  Defaults to ``"unknown"``.
+
+    Returns
+    -------
+    list[str]
+        Zero or more diagnostic strings.  Each message is prefixed with
+        ``"WARNING:"`` or ``"ERROR:"`` so callers can log at the correct
+        level.  An empty list means the configuration passes all checks.
+
+    Notes
+    -----
+    **Security note** — ``"write"`` token used for inference is a WARNING
+    (not an error) because it functions correctly at runtime.  The warning
+    exists to prompt the operator to apply least-privilege.
+
+    **Security note** — ``"read"`` token used for writes is a hard ERROR:
+    the token WILL fail on every ``HfApi.create_commit`` call.  The proxy
+    can still start (useful for operators who only need inference), but
+    ``/v1/contribute`` will be permanently non-functional until the token is
+    replaced.
+
+    Examples
+    --------
+    Clean configuration — no messages:
+
+    >>> _validate_token_config("hf_readtok", "", hf_token_type="read")
+    []
+
+    Write token for inference (overprivileged) → WARNING:
+
+    >>> msgs = _validate_token_config("hf_writetok", "", hf_token_type="write")
+    >>> any("WARNING" in m for m in msgs)
+    True
+
+    Read token for writes → ERROR:
+
+    >>> msgs = _validate_token_config(
+    ...     "hf_tok", "hf_readtok",
+    ...     training_dataset_repo="org/dataset",
+    ...     hf_write_token_type="read",
+    ... )
+    >>> any("ERROR" in m for m in msgs)
+    True
+    """
+    messages: list[str] = []
+
+    # ── Inference token (HF_TOKEN) type check ────────────────────────────────
+    if hf_token and not _token_suitable_for_inference(hf_token_type):
+        messages.append(
+            f"WARNING: HF_TOKEN type is {hf_token_type!r} (classic write token). "
+            "Write tokens carry unnecessary repo-push permission and violate the "
+            "principle of least privilege for inference. "
+            "Replace HF_TOKEN with: (a) a fine-grained token scoped to "
+            "'Make calls to the serverless Inference API' only, or "
+            "(b) a classic read token. "
+            "See HF Settings → Tokens → New token → Fine-grained. "
+            "Set HF_TOKEN_TYPE=read or HF_TOKEN_TYPE=fine-grained after replacing."
+        )
+
+    # ── Write token (HF_WRITE_TOKEN) type check ──────────────────────────────
+    if hf_write_token and not _token_suitable_for_writes(hf_write_token_type):
+        messages.append(
+            f"ERROR: HF_WRITE_TOKEN type is {hf_write_token_type!r}. "
+            "Classic read tokens cannot push commits to HuggingFace repositories "
+            "(HF API returns HTTP 403 / 401). "
+            "Every POST /v1/contribute will fail with HTTP 503. "
+            "Replace HF_WRITE_TOKEN with: (a) a fine-grained token with write "
+            "access scoped to the training dataset repo, or (b) a classic write "
+            "token. "
+            "See HF Settings → Tokens → New token → Fine-grained → Write access."
+        )
+
+    # ── Training repo + effective write token consistency ────────────────────
+    if training_dataset_repo:
+        # Effective write token is HF_WRITE_TOKEN when set; else falls back to
+        # HF_TOKEN.  Check that the effective token type can authorize writes.
+        effective_token = hf_write_token or hf_token
+        effective_type = hf_write_token_type if hf_write_token else hf_token_type
+        if effective_token and not _token_suitable_for_writes(effective_type):
+            messages.append(
+                f"ERROR: TRAINING_DATASET_REPO={training_dataset_repo!r} is "
+                "configured but the effective write token type "
+                f"({effective_type!r}) cannot push to HuggingFace repositories. "
+                "POST /v1/contribute will always fail with HTTP 503. "
+                "Set HF_WRITE_TOKEN to a write-capable token (fine-grained with "
+                "write access to the dataset repo, or a classic write token). "
+                f"Set HF_WRITE_TOKEN_TYPE accordingly."
+            )
+
+    return messages
 
 def _resolve_upstream_url(
     body: bytes,
@@ -711,6 +1145,12 @@ def load_proxy_env() -> dict[str, Any]:
             Path 3 read timeout (env ``PATH3_TIMEOUT``).
         ``max_body_bytes`` : int
         ``allowed_origins`` : str
+        ``hf_token_type`` : str
+            Classified token type for *hf_token* (env ``HF_TOKEN_TYPE``).
+            One of ``"fine-grained"``, ``"read"``, ``"write"``, ``"unknown"``.
+        ``hf_write_token_type`` : str
+            Classified token type for *hf_write_token* (env ``HF_WRITE_TOKEN_TYPE``).
+            One of ``"fine-grained"``, ``"write"``, ``"unknown"``.
 
     Examples
     --------
@@ -736,6 +1176,18 @@ def load_proxy_env() -> dict[str, Any]:
     _hf_token: str = os.environ.get("HF_TOKEN", "").strip()
     _hf_write_token: str = os.environ.get("HF_WRITE_TOKEN", "").strip()
 
+    # Classify token types from explicit declarations (preferred) or heuristics.
+    # Explicit: set HF_TOKEN_TYPE=read|write|fine-grained in Space secrets.
+    # Heuristic: length-based guess (fine-grained tokens are ≥ 52 chars).
+    _hf_token_type: str = _classify_token_type(
+        _hf_token,
+        declared_type=os.environ.get("HF_TOKEN_TYPE"),
+    )
+    _hf_write_token_type: str = _classify_token_type(
+        _hf_write_token,
+        declared_type=os.environ.get("HF_WRITE_TOKEN_TYPE"),
+    )
+
     return {
         "backend_url":      os.environ.get("BACKEND_URL", "").strip(),
         "hf_token":         _hf_token,
@@ -743,8 +1195,13 @@ def load_proxy_env() -> dict[str, Any]:
         # Principle of least privilege: set HF_WRITE_TOKEN to a write-scoped
         # fine-grained token so HF_TOKEN can remain read-only / inference-only.
         # Falls back to hf_token when absent for backward compatibility.
-        "hf_write_token":   _hf_write_token,
-        "hf_dataset_token": _hf_write_token or _hf_token,
+        "hf_write_token":        _hf_write_token,
+        "hf_dataset_token":      _hf_write_token or _hf_token,
+        # Token type metadata — used by _validate_token_config at startup.
+        # Operators can override auto-detection by setting HF_TOKEN_TYPE /
+        # HF_WRITE_TOKEN_TYPE to "fine-grained", "read", or "write".
+        "hf_token_type":         _hf_token_type,
+        "hf_write_token_type":   _hf_write_token_type,
         "hf_base": os.environ.get("HF_BASE", DEFAULT_HF_BASE).rstrip("/"),
         "default_model": (
             os.environ.get("DEFAULT_MODEL", DEFAULT_MODEL).strip() or DEFAULT_MODEL

app.py

@@ -1,4 +1,4 @@
-# scikit-plots/ai  ·  _hf_spaces_proxy/app.py  v6.0.0
+# scikit-plots/ai  ·  _hf_spaces_proxy/app.py  v6.1.0
 #
 # Thin OpenAI-compatible reverse proxy for sphinx-ai-assistant.
 #
@@ -51,13 +51,23 @@
 #   HF_BASE             HF Serverless API base URL.
 #                       Default: https://router.huggingface.co
 #   DEFAULT_MODEL       Fallback model when request body omits "model".
-#                       Default: scikit-plots/Qwen2.5-Coder-32B-Instruct
+#                       Default: scikit-plots/Qwen2.5-Coder-7B-Instruct
 #   PROXY_TIMEOUT       Path 1 read timeout in seconds.  Default: 600.
 #   PATH2_TIMEOUT       Path 2 read timeout in seconds.  Default: 600.
 #   PATH3_TIMEOUT       Path 3 read timeout in seconds.  Default: 120.
 #   PROXY_CONNECT_TIMEOUT TCP handshake timeout.  Default: 10.
 #   PROXY_WRITE_TIMEOUT   Request body upload timeout.  Default: 30.
 #   PROXY_POOL_TIMEOUT    Connection pool acquire timeout.  Default: 10.
+#   HF_TOKEN_TYPE       Declare the type of HF_TOKEN so startup validation can
+#                       enforce principle-of-least-privilege without network calls.
+#                       Accepted values: fine-grained | read | write
+#                       When absent the proxy applies a length-based heuristic.
+#                       Set to "read" when using a classic read token; set to
+#                       "fine-grained" for new-style scoped tokens.  Never set
+#                       "write" — that triggers a startup WARNING.
+#   HF_WRITE_TOKEN_TYPE Declare the type of HF_WRITE_TOKEN.
+#                       Accepted values: fine-grained | write
+#                       Set to match the token created in HF Settings → Tokens.
 #   ALLOWED_ORIGINS     Comma-separated CORS origins.  Default: *.
 #   MAX_BODY_BYTES      Maximum accepted body size.  Default: 10485760.
 #
@@ -129,11 +139,13 @@ try:
         DEFAULT_PATH3_READ_TIMEOUT,
         DEFAULT_PROXY_TIMEOUT,
         PROXY_VERSION,
+        _classify_token_type,
         _resolve_upstream_url,
         _safe_float,
         _safe_int,
         _token_log_fragment,
         _validate_env,
+        _validate_token_config,
     )
 except ImportError:
     from .._shared_logic import (  # type: ignore[import]
@@ -146,11 +158,13 @@ except ImportError:
         DEFAULT_PATH3_READ_TIMEOUT,
         DEFAULT_PROXY_TIMEOUT,
         PROXY_VERSION,
+        _classify_token_type,
         _resolve_upstream_url,
         _safe_float,
         _safe_int,
         _token_log_fragment,
         _validate_env,
+        _validate_token_config,
     )
 
 
@@ -281,6 +295,29 @@ HF_WRITE_TOKEN: str = os.environ.get("HF_WRITE_TOKEN", "").strip()
 #: Never forward this token to model inference backends.
 HF_DATASET_TOKEN: str = HF_WRITE_TOKEN or HF_TOKEN
 
+#: Classified type for HF_TOKEN — used by startup validation and log output.
+#:
+#: Source priority:
+#:   1. Explicit ``HF_TOKEN_TYPE`` env var (``fine-grained`` | ``read`` | ``write``).
+#:   2. Length-based heuristic: tokens ≥ 52 chars are classified ``"fine-grained"``;
+#:      shorter classic tokens that cannot be distinguished return ``"unknown"``.
+#:
+#: Set ``HF_TOKEN_TYPE=read`` or ``HF_TOKEN_TYPE=fine-grained`` in Space secrets
+#: to enable accurate least-privilege startup warnings.
+HF_TOKEN_TYPE: str = _classify_token_type(
+    HF_TOKEN,
+    declared_type=os.environ.get("HF_TOKEN_TYPE"),
+)
+
+#: Classified type for HF_WRITE_TOKEN.
+#: Source priority mirrors HF_TOKEN_TYPE above.
+#: Accepted values: ``"fine-grained"``, ``"write"``.
+#: Returns ``"unknown"`` when the token is absent or type cannot be inferred.
+HF_WRITE_TOKEN_TYPE: str = _classify_token_type(
+    HF_WRITE_TOKEN,
+    declared_type=os.environ.get("HF_WRITE_TOKEN_TYPE"),
+)
+
 #: HF Serverless Inference API base URL (no trailing slash).
 HF_BASE: str = os.environ.get("HF_BASE", DEFAULT_HF_BASE).rstrip("/")
 
@@ -388,6 +425,21 @@ _feedback_rl_lock = asyncio.Lock()
 
 _validate_env(BACKEND_URL, HF_TOKEN, HF_SPACES_MODEL_URL)
 
+# Token-type least-privilege validation.  Runs after _validate_env confirms
+# that routing is viable.  Issues are logged at WARNING or ERROR level but
+# never block startup — the proxy starts in degraded mode so operators can
+# read the log and fix the configuration without a redeploy loop.
+_token_config_issues: list[str] = _validate_token_config(
+    HF_TOKEN,
+    HF_WRITE_TOKEN,
+    TRAINING_DATASET_REPO,
+    hf_token_type=HF_TOKEN_TYPE,
+    hf_write_token_type=HF_WRITE_TOKEN_TYPE,
+)
+for _issue in _token_config_issues:
+    _log_level = logging.ERROR if _issue.startswith("ERROR:") else logging.WARNING
+    logger.log(_log_level, "Startup token-config check: %s", _issue)
+
 if not BACKEND_URL and not HF_TOKEN:
     logger.warning(
         "HF_TOKEN is not set. Requests to standard HF Inference API models "
@@ -459,8 +511,8 @@ async def _lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         BACKEND_URL or None,
         HF_SPACES_MODEL_URL or None,
         list(HF_SPACES_MODEL_NAMESPACES),
-        _token_log_fragment(HF_TOKEN),
-        _token_log_fragment(HF_WRITE_TOKEN) if HF_WRITE_TOKEN else "<using-hf-token-fallback>",
+        _token_log_fragment(HF_TOKEN, token_type=HF_TOKEN_TYPE),
+        _token_log_fragment(HF_WRITE_TOKEN, token_type=HF_WRITE_TOKEN_TYPE) if HF_WRITE_TOKEN else "<using-hf-token-fallback>",
         DEFAULT_MODEL,
     )
     logger.info(
@@ -878,8 +930,15 @@ async def root() -> JSONResponse:
             },
             "tokens": {
                 # Never expose token values — only whether each slot is filled.
-                "hf_token_set":       bool(HF_TOKEN),
-                "hf_write_token_set": bool(HF_WRITE_TOKEN),
+                # hf_token_type / hf_write_token_type reflect the classified token
+                # class so operators can verify least-privilege configuration without
+                # reading Space logs.  Possible values: fine-grained | read | write |
+                # unknown.  "unknown" means the type could not be inferred — set
+                # HF_TOKEN_TYPE / HF_WRITE_TOKEN_TYPE in Space secrets to resolve.
+                "hf_token_set":         bool(HF_TOKEN),
+                "hf_token_type":        HF_TOKEN_TYPE,
+                "hf_write_token_set":   bool(HF_WRITE_TOKEN),
+                "hf_write_token_type":  HF_WRITE_TOKEN_TYPE,
                 # True when HF_WRITE_TOKEN is set; False means writes fall
                 # back to HF_TOKEN (single-token mode, less secure).
                 "least_privilege_mode": bool(HF_WRITE_TOKEN),