Upload 34 files

README.md

@@ -246,10 +246,95 @@ pages/WAL remnants, backups, CDN/provider logs, and infrastructure snapshots are
 
 ## Configuration
 
-Configure values in **Space → Settings** using the correct surface:
+Configure the Space from **Settings → Variables and secrets**. Hugging Face exposes
+Variables as non-sensitive deployment configuration and keeps Secrets private. See
+[Managing Spaces variables and secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets).
+
+### Variables and secrets
+
+Use one simple rule: **configuration goes in Variables; credentials and capabilities go in Secrets**.
+Both surfaces become environment variables inside the container, so putting a non-secret value
+in Secrets still works technically, but it makes maintenance harder and hides which settings are
+actually sensitive.
+
+#### Variables — public / non-sensitive
+
+| Name | Required? | Typical value | Notes |
+|---|---:|---|---|
+| `RECORD_STORAGE_TARGETS` | Multi-store deployments | JSON array | Provider-neutral Primary + Mirrors topology. May contain repo IDs and `token_env` **names**, never token values. If repository topology itself is confidential, it is acceptable to store this JSON as a Secret instead. |
+| `TRAINING_DATASET_REPO` | Legacy HF-only mode | `scikit-plots/ai-assistant-contributions` | Repository identifier, not a credential. If this is currently stored as a Secret, it can be moved to Variables unless you intentionally treat the repo identity as confidential. Ignored as the active topology when `RECORD_STORAGE_TARGETS` is set. |
+| `ALLOWED_MODELS` | No | comma-separated model IDs | Exact Path-3 model allow-list. Do not use `*`; an explicit model list prevents the proxy from becoming a general-purpose inference relay. |
+| `HF_SPACES_MODEL_NAMESPACES` | No | `scikit-plots` | Model owner prefixes routed through the configured Path-2 model Space. |
+| `ALLOWED_ORIGINS` | Custom sites only | comma-separated origins | Exact browser origins such as `https://docs.example.org`. Origins contain only scheme + host (+ optional port): no path, query, fragment, or trailing page URL. |
+| `ALLOWED_ORIGINS_MODE` | No | `additive` | `additive` keeps the bundled Scikit-plots origins and adds `ALLOWED_ORIGINS`; `replace` trusts only `ALLOWED_ORIGINS` and is the recommended mode for forks/downstream sites that want their own CORS boundary. |
+| `CONTRIBUTION_REVIEW_MODE` | No | `provider-pr` or `ledger` | Native provider PR/MR review or historical ledger review. |
+| `HF_TOKEN_TYPE` | Recommended | `fine-grained` / `read` / `write` | Non-secret classification label for `HF_TOKEN`; avoids `unknown` startup diagnostics. |
+| `HF_DATASET_TOKEN_TYPE` | Legacy HF persistence | `fine-grained` | Non-secret classification label for the dataset-persistence token. |
+
+The proxy has two built-in browser origins because this extension is currently deployed on both
+Scikit-plots documentation sites:
 
-- **Secrets** — credentials such as HF/GitHub/GitLab/Bitbucket tokens.
-- **Variables** — non-sensitive configuration such as repository IDs, token-type labels, booleans, and `RECORD_STORAGE_TARGETS`.
+```text
+https://scikit-plots.github.io
+https://scikit-plots-learn.readthedocs.io
+```
+
+With the default `ALLOWED_ORIGINS_MODE=additive`, both remain trusted and any
+`ALLOWED_ORIGINS` entries are appended. A downstream/open-source deployment can take complete
+control without editing `app.py`:
+
+```text
+# Custom/fork deployment: trust only these sites
+ALLOWED_ORIGINS=https://docs.example.org,https://learn.example.org
+ALLOWED_ORIGINS_MODE=replace
+```
+
+To add a site while retaining the two Scikit-plots defaults:
+
+```text
+ALLOWED_ORIGINS=https://preview.example.org
+ALLOWED_ORIGINS_MODE=additive
+```
+
+Never use `ALLOWED_ORIGINS=*` in production. CORS is a browser abuse boundary, not authentication;
+server-to-server clients without an `Origin` header still rely on their own token/capability controls.
+
+#### Secrets — private / server-only
+
+| Name | Required? | Purpose |
+|---|---:|---|
+| `HF_TOKEN` | Path 3 inference | Hugging Face inference credential. Prefer least privilege; it should not also be your broad repository-write token. |
+| `AI_RECORD_STORAGE_TOKEN_HF_PRIMARY` | When referenced by `RECORD_STORAGE_TARGETS` | Example HF Primary write credential. The exact name is configurable through each target's `token_env`. |
+| `AI_RECORD_STORAGE_TOKEN_GITHUB_MIRROR` | When referenced by `RECORD_STORAGE_TARGETS` | Example GitHub Mirror write credential. Use an independent least-privilege token. |
+| `AI_RECORD_STORAGE_TOKEN_*` | Per configured target | Provider-specific HF/GitHub/GitLab/Bitbucket write credential. Only names with this prefix are accepted by storage target configuration. |
+| `HF_DATASET_TOKEN` | Legacy HF-only persistence | Preferred legacy dataset token; fine-grained to the target dataset repository. |
+| `CONTRIBUTION_REVIEW_TOKEN` | Optional | API-driven review/promotion capability. Not required when maintainers review entirely through provider-native PR/MR UI. |
+| `RATE_LIMIT_IDENTITY_SECRET` | Redis rate limiting | HMAC key used to pseudonymize shared rate-limit identities. |
+| `CONTRIBUTION_LEDGER_KEY_SECRET` | Redis contribution ledger | HMAC key used to pseudonymize receipt identifiers. |
+| Redis URLs containing credentials | When Redis is used | Keep `RATE_LIMIT_REDIS_URL`, `SHARE_STORE_REDIS_URL`, and `CONTRIBUTION_LEDGER_REDIS_URL` private when they contain usernames/passwords/tokens. |
+
+A practical Scikit-plots Space layout is therefore:
+
+```text
+# Variables
+RECORD_STORAGE_TARGETS=<provider-neutral JSON topology>
+ALLOWED_MODELS=openai/gpt-oss-20b,Qwen/Qwen2.5-Coder-7B-Instruct,Qwen/Qwen2.5-Coder-32B-Instruct,scikit-plots/gpt-oss-20b,scikit-plots/Qwen2.5-Coder-7B-Instruct,scikit-plots/Qwen2.5-Coder-32B-Instruct
+HF_SPACES_MODEL_NAMESPACES=scikit-plots
+ALLOWED_ORIGINS_MODE=additive
+# ALLOWED_ORIGINS may remain empty because both current Scikit-plots sites are built in.
+
+# Legacy-only variable (not needed as the active topology when RECORD_STORAGE_TARGETS is used)
+TRAINING_DATASET_REPO=scikit-plots/ai-assistant-contributions
+
+# Secrets
+HF_TOKEN=<inference-token>
+AI_RECORD_STORAGE_TOKEN_HF_PRIMARY=<repo-scoped-write-token>
+AI_RECORD_STORAGE_TOKEN_GITHUB_MIRROR=<repo-scoped-write-token>
+```
+
+The proxy never reads provider token values from `RECORD_STORAGE_TARGETS`; it reads only the
+configured `token_env` name and then resolves that environment variable server-side. Keep token
+values out of `conf.py`, generated Sphinx HTML, JavaScript, logs, repository URLs, and commit metadata.
 
 See [DATASET_COLLECTION_GUIDANCE.md](./DATASET_COLLECTION_GUIDANCE.md) for the beginner-to-operator storage guide, including exact HF-only, GitHub-only, Primary+Mirror, migration, testing, and deduplication recipes.
 
@@ -317,7 +402,7 @@ production.
 | `BACKEND_URL` | No | `""` | **Path 1** — Explicit upstream URL.  All requests forwarded here when set.  Use for Docker Model Runner, Ollama, or any custom backend. |
 | `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`). |
-| `ALLOWED_MODELS` | No | bundled public model set | Exact Path-3 provider model IDs accepted by the strict chat contract. The default matches the public models shown by `_example_conf.py`: `Qwen/Qwen2.5-Coder-7B-Instruct`, `Qwen/Qwen2.5-Coder-32B-Instruct`, and `openai/gpt-oss-20b`. |
+| `ALLOWED_MODELS` | No | `DEFAULT_MODEL` + bundled provider models | Exact model IDs accepted by the strict chat contract before routing. The bundled defaults include the configured `DEFAULT_MODEL` plus `Qwen/Qwen2.5-Coder-7B-Instruct`, `Qwen/Qwen2.5-Coder-32B-Instruct`, and `openai/gpt-oss-20b`; Path-2 namespaces remain an additional explicit admission rule. |
 | `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-7B-Instruct` | Fallback model when the request body omits `"model"`. |
 
@@ -386,7 +471,8 @@ All values are in seconds.  Non-integer values silently fall back to the default
 
 | Variable | Default | Description |
 |---|---|---|
-| `ALLOWED_ORIGINS` | empty | Comma-separated **additional** exact browser origins. The official `https://scikit-plots.github.io` origin is always retained so an environment override cannot accidentally break the shipped documentation. Missing `Origin` remains valid for server-to-server clients. `*` is an explicit insecure compatibility escape hatch and is not authentication. |
+| `ALLOWED_ORIGINS` | empty | Comma-separated exact browser origins. In `additive` mode they are appended to the two bundled defaults (`https://scikit-plots.github.io`, `https://scikit-plots-learn.readthedocs.io`). In `replace` mode they are the complete browser allow-list. Missing `Origin` remains valid for server-to-server clients. `*` is an explicit insecure compatibility escape hatch and is not authentication. |
+| `ALLOWED_ORIGINS_MODE` | `additive` | `additive` retains the bundled project origins; `replace` starts from an empty allow-list and trusts only valid entries from `ALLOWED_ORIGINS`. Invalid values fail safely back to `additive`. |
 | `DEPLOYMENT_PROFILE` | `compat` | `compat` preserves explicit legacy deployment choices. The hardened Dockerfile sets `strict`, which fails startup as root, rejects wildcard origins and opaque-origin **writes**, and requires verified TLS for all configured Redis authorities. Read-only opaque Share compatibility remains a separate explicit opt-in because local `file://` viewers may need it. |
 | `REDIS_REQUIRE_TLS` | `false` (`true` in strict) | Requires `rediss://`; URL query parameters are rejected so callers cannot disable certificate verification through redis-py URL options. |
 | `REQUIRE_NON_ROOT` | `false` (`true` in strict) | Fails application startup when the process is UID 0 on POSIX. |
@@ -694,8 +780,15 @@ HF_DATASET_TOKEN           = hf_<fine-grained-dataset-token>
 # For Primary + Mirrors, use RECORD_STORAGE_TARGETS instead; see DATASET_COLLECTION_GUIDANCE.md.
 
 # Security
-# Optional extra origins; official https://scikit-plots.github.io is built in.
+# Both current Scikit-plots origins are built in:
+#   https://scikit-plots.github.io
+#   https://scikit-plots-learn.readthedocs.io
+# Leave empty to use only those defaults, or add exact custom origins.
 ALLOWED_ORIGINS            =
+ALLOWED_ORIGINS_MODE       = additive
+# Fork/downstream alternative:
+# ALLOWED_ORIGINS=https://docs.example.org,https://learn.example.org
+# ALLOWED_ORIGINS_MODE=replace
 # Optional read-only local-file (Origin:null) Share compatibility.
 # Keep false unless you explicitly need Global Share viewing from file:// pages.
 SHARE_ALLOW_OPAQUE_ORIGIN       = false
@@ -712,7 +805,7 @@ BASE=https://scikit-plots-ai.hf.space
 
 # 1. Liveness probe
 curl $BASE/health
-# {"status":"ok","version":"6.8.0"}
+# {"status":"ok","version":"7.3.0"}
 
 # Optional deterministic stub rig status
 curl -s $BASE/health | python3 -m json.tool

_utils/_shared_logic.py

@@ -1413,6 +1413,8 @@ def load_proxy_env() -> dict[str, Any]:
             Path 3 read timeout (env ``PATH3_TIMEOUT``).
         ``max_body_bytes`` : int
         ``allowed_origins`` : str
+        ``allowed_origins_mode`` : str
+            Raw deployment composition mode (``additive`` or ``replace``).
         ``hf_token_type`` : str
             Classified token type for *hf_token* (env ``HF_TOKEN_TYPE``).
             One of ``"fine-grained"``, ``"read"``, ``"write"``, ``"unknown"``.
@@ -1504,4 +1506,8 @@ def load_proxy_env() -> dict[str, Any]:
             DEFAULT_MAX_BODY_BYTES,
         ),
         "allowed_origins": os.environ.get("ALLOWED_ORIGINS", "").strip(),
+        "allowed_origins_mode": (
+            os.environ.get("ALLOWED_ORIGINS_MODE", "additive").strip().lower()
+            or "additive"
+        ),
     }

app.py

@@ -87,7 +87,8 @@
 #                       persistence; fine-grained repo-write is preferred.
 #   HF_WRITE_TOKEN_TYPE Legacy type declaration for HF_WRITE_TOKEN.
 #                       Accepted values: fine-grained | read | write.
-#   ALLOWED_ORIGINS     Comma-separated additional exact CORS origins. The official docs origin is always included; set * only as an explicit insecure compatibility escape hatch.
+#   ALLOWED_ORIGINS     Comma-separated exact CORS origins. Additive by default; use ALLOWED_ORIGINS_MODE=replace for downstream sites.
+#   ALLOWED_ORIGINS_MODE additive (default) keeps built-in Scikit-plots origins; replace trusts only ALLOWED_ORIGINS.
 #   RECORD_STORAGE_TARGETS  Optional JSON array defining one primary record
 #                       store plus mirrors (huggingface/github/gitlab/bitbucket).
 #                       Credentials are referenced only through env names with
@@ -993,8 +994,11 @@ _protocol_retries: int = max(
 # CORS
 # ─────────────────────────────────────────────────────────────────────────────
 
-_DEFAULT_ALLOWED_ORIGINS = "https://scikit-plots.github.io"
-_OFFICIAL_ALLOWED_ORIGINS: tuple[str, ...] = (_DEFAULT_ALLOWED_ORIGINS,)
+_DEFAULT_ALLOWED_ORIGINS: tuple[str, ...] = (
+    "https://scikit-plots.github.io",
+    "https://scikit-plots-learn.readthedocs.io",
+)
+_ALLOWED_ORIGIN_MODES: frozenset[str] = frozenset({"additive", "replace"})
 
 
 def _normalise_browser_origin(value: str) -> str:
@@ -1017,18 +1021,32 @@ def _normalise_browser_origin(value: str) -> str:
     return f"{parsed.scheme.lower()}://{parsed.netloc.lower()}"
 
 
-def _build_allowed_origins(raw: str) -> list[str]:
+def _normalise_allowed_origins_mode(value: str) -> str:
+    """Return the supported CORS composition mode without echoing bad input."""
+    mode = str(value or "additive").strip().lower() or "additive"
+    if mode not in _ALLOWED_ORIGIN_MODES:
+        logger.warning(
+            "AI proxy [CORS_MODE_INVALID]: invalid ALLOWED_ORIGINS_MODE; using additive defaults."
+        )
+        return "additive"
+    return mode
+
+
+def _build_allowed_origins(raw: str, *, mode: str = "additive") -> list[str]:
     """Build the exact browser-origin allowlist.
 
-    The official Scikit-Plots documentation origin is a package-owned trust
-    anchor and cannot be accidentally removed by an ``ALLOWED_ORIGINS``
-    deployment override.  The environment variable adds exact origins.  Only
-    an explicit ``*`` selects wildcard compatibility mode.
+    ``additive`` retains the package defaults and appends deployment-specific
+    exact origins. ``replace`` starts empty so downstream/open-source deployments
+    can own their complete browser-origin trust boundary without editing source.
+    Only an explicit ``*`` selects wildcard compatibility mode.
     """
     text = str(raw or "").strip()
     if text == "*":
         return ["*"]
-    merged: list[str] = list(_OFFICIAL_ALLOWED_ORIGINS)
+    selected_mode = _normalise_allowed_origins_mode(mode)
+    merged: list[str] = (
+        list(_DEFAULT_ALLOWED_ORIGINS) if selected_mode == "additive" else []
+    )
     for item in text.split(","):
         item = item.strip()  # ruff: ignore[redefined-loop-name]
         if not item:
@@ -1045,7 +1063,12 @@ def _build_allowed_origins(raw: str) -> list[str]:
 
 
 _raw_origins: str = os.environ.get("ALLOWED_ORIGINS", "").strip()
-_allowed_origins: list[str] = _build_allowed_origins(_raw_origins)
+ALLOWED_ORIGINS_MODE: str = _normalise_allowed_origins_mode(
+    os.environ.get("ALLOWED_ORIGINS_MODE", "additive")
+)
+_allowed_origins: list[str] = _build_allowed_origins(
+    _raw_origins, mode=ALLOWED_ORIGINS_MODE
+)
 
 #: Optional Share-only compatibility for browser opaque origins such as
 #: ``file://`` documents, which browsers serialize as ``Origin: null``.  This is
@@ -1076,9 +1099,13 @@ if _allowed_origins == ["*"]:
         "AI proxy [CORS_WILDCARD]: ALLOWED_ORIGINS=* explicitly enables every browser origin; "
         "use an exact comma-separated origin list in production."
     )
+elif ALLOWED_ORIGINS_MODE == "replace":
+    logger.info(
+        "AI proxy CORS: replacement mode active; only exact ALLOWED_ORIGINS entries are trusted."
+    )
 elif _raw_origins:
     logger.info(
-        "AI proxy CORS: official docs origin retained; ALLOWED_ORIGINS contributes additional exact origins."
+        "AI proxy CORS: built-in documentation origins retained; ALLOWED_ORIGINS contributes additional exact origins."
     )
 
 #: Trust ``X-Forwarded-For`` only when a known ingress proxy strips/overwrites
@@ -2706,14 +2733,20 @@ def _canonical_payload_digest(value: Any) -> str:
 def _cors_public_status() -> dict[str, Any]:
     """Return public CORS diagnostics without exposing custom/private origins."""
     wildcard = _allowed_origins == ["*"]
+    primary_default = _DEFAULT_ALLOWED_ORIGINS[0]
     return {
-        "official_docs_origin": _DEFAULT_ALLOWED_ORIGINS,
+        # Backward-compatible singular fields refer to the primary project origin.
+        "official_docs_origin": primary_default,
         "official_docs_origin_allowed": (
-            wildcard or _DEFAULT_ALLOWED_ORIGINS in _allowed_origins
+            wildcard or primary_default in _allowed_origins
+        ),
+        "default_allowed_origin_count": len(_DEFAULT_ALLOWED_ORIGINS),
+        "default_allowed_origins_allowed": (
+            wildcard or all(origin in _allowed_origins for origin in _DEFAULT_ALLOWED_ORIGINS)
         ),
         "wildcard": wildcard,
         "allowed_origin_count": None if wildcard else len(_allowed_origins),
-        "env_semantics": "additive",
+        "env_semantics": ALLOWED_ORIGINS_MODE,
         "share_opaque_origin_allowed": SHARE_ALLOW_OPAQUE_ORIGIN,
         "share_opaque_origin_write_allowed": bool(
             SHARE_ALLOW_OPAQUE_ORIGIN and SHARE_ALLOW_OPAQUE_ORIGIN_WRITE