[HWORKS-2802 / -2807] partitioned_by — Python client grain materialization (Delta/Iceberg/Hudi) + predicate translator + MCP/CLI hardening (#961)

This PR series extends **HWORKS-2802 / HWORKS-2807** from UI-only partitioning visibility into the full backend/client implementation of `partitioned_by` across Delta, Hudi, and Iceberg. 

It adds `partitioned_by` and `online_partition_columns` to the Python client API, with validation for allowed grains, duplicates, conflicts with `partition_key`, required `event_time`, and name collisions. The fields round-trip through REST, are exposed as read-only properties, and synthetic grain features are marked `offline_only`.

The implementation evolved from an initial **Delta GENERATED ALWAYS AS** design to a simpler cross-engine model where grain columns are real materialized partition columns. The client now derives `year`, `month`, `week`, `day`, and `hour` from `event_time` before writes, using Arrow for delta-rs/PyIceberg paths and Spark functions for Spark paths. This applies to Delta, Hudi, and Iceberg, including deletes.

Hudi support adds a `PartitionedByTransformer` for materialization jobs and later moves direct writes to the same real-column model, using ordinary SIMPLE partition columns with Hive-style partitioning. Iceberg gets the same grain materialization on both Spark and PyIceberg write paths.

Read pruning is handled by a partition predicate translator. It adds grain-column predicates from `event_time` ranges so partition pruning works consistently across engines and formats. The translator was simplified to one direction only: **event_time range → derived grain predicates**. It also handles UTC normalization, avoids unsafe OR translations, and improves pruning by descending into finer grains when the range shares coarser prefixes.

Several correctness fixes are included: per-row seconds-vs-milliseconds handling for integer `event_time`, DATE + hour materialization, partitioned deletes, repeated `Query.read()` mutation, post-merge private API renames, and CI compatibility when `deltalake` is unavailable.

The series also exposes `FeatureGroup.online_config` so users can inspect RonDB secondary indexes, documents `time_travel_format` and `partitioned_by` in the hops-fg skill, and guards online serving by warning or failing when offline-only partition grain columns are selected in online feature views.

Separately, it hardens the Hopsworks MCP server and CLI after a security audit: shell tools are now opt-in, HTTP defaults to localhost, bearer-token auth is supported, unauthenticated network binds are blocked unless explicitly overridden, terminal sessions use unguessable tokens, credential exposure is reduced, hostname verification defaults to true, and the CLI supports reading API keys from stdin.

---------

Signed-off-by: Jim Dowling <jim@logicalclocks.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jimdowling

python/hopsworks/cli/commands/transformation.py

@@ -79,6 +79,12 @@ def transformation_create(
     The decorated function is imported in-process and passed to
     ``fs.create_transformation_function()``.
 
+    Security: the source is executed in-process (``_load_udf``) — this is
+    arbitrary code execution by design, as the same UDF runs server-side.
+    Treat ``--code``/``--file`` as trusted input; never assemble a
+    ``hops transformation create --code ...`` invocation from an untrusted
+    source (an agent prompt, a CI variable, a web request).
+
     Args:
         ctx: Click context.
         file_path: Python source path.

python/hopsworks/cli/main.py

@@ -11,6 +11,7 @@
 from __future__ import annotations
 
 import importlib
+import sys
 from typing import TYPE_CHECKING
 
 import click
@@ -186,7 +187,20 @@ def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
 )
 @click.version_option(_VERSION, "-v", "--version", prog_name="hops")
 @click.option("--host", "host_flag", help="Hopsworks host URL (overrides config).")
-@click.option("--api-key", "api_key_flag", help="API key (overrides config).")
+@click.option(
+    "--api-key",
+    "api_key_flag",
+    help="API key (overrides config). Avoid in shared shells — a key in argv "
+    "is visible in the process list and shell history. Prefer the "
+    "HOPSWORKS_API_KEY env var or --api-key-stdin.",
+)
+@click.option(
+    "--api-key-stdin",
+    "api_key_stdin",
+    is_flag=True,
+    help="Read the API key from the first line of stdin instead of argv "
+    "(keeps the secret out of the process list and shell history).",
+)
 @click.option("--project", "project_flag", help="Project name (overrides config).")
 @click.option(
     "--verify/--no-verify",
@@ -206,6 +220,7 @@ def cli(
     ctx: click.Context,
     host_flag: str | None,
     api_key_flag: str | None,
+    api_key_stdin: bool,
     project_flag: str | None,
     verify_flag: bool | None,
     json_flag: bool,
@@ -216,11 +231,16 @@ def cli(
         ctx: Click context; we stash the resolved ``HopsConfig`` on ``ctx.obj``.
         host_flag: Value of ``--host`` if provided.
         api_key_flag: Value of ``--api-key`` if provided.
+        api_key_stdin: When True, read the API key from stdin.
         project_flag: Value of ``--project`` if provided.
         verify_flag: True for ``--verify``, False for ``--no-verify``, None if neither was passed.
         json_flag: When True, every output helper switches to JSON mode.
     """
     output.set_json_mode(json_flag)
+    if api_key_stdin:
+        if api_key_flag:
+            raise click.UsageError("Pass --api-key or --api-key-stdin, not both.")
+        api_key_flag = sys.stdin.readline().strip() or None
     ctx.ensure_object(dict)
     ctx.obj["config"] = config.load(
         flag_host=host_flag,

python/hopsworks/mcp/run_server.py

@@ -25,10 +25,16 @@
 import hopsworks
 import uvicorn
 
-from .server import mcp
+from .server import AUTH_TOKEN_ENV, build_mcp, static_bearer_auth
 from .utils.auth import login
 
 
+# Hosts that keep the server off the network. Binding anything else over an
+# HTTP transport without an auth token is refused (fail closed).
+_LOOPBACK_HOSTS = {"127.0.0.1", "::1", "localhost"}
+_NETWORK_TRANSPORTS = {"http", "sse", "streamable-http"}
+
+
 # Configure logging to handle closed streams gracefully
 class SafeStreamHandler(logging.StreamHandler):
     def emit(self, record):
@@ -50,14 +56,43 @@ def handle_shutdown(signum, frame):
 
 
 @click.option(
-    "--host", default="0.0.0.0", help="Host to run the server on. (default: 0.0.0.0)"
+    "--host",
+    default="127.0.0.1",
+    help="Host to bind the server to. (default: 127.0.0.1, loopback only). "
+    "Binding a routable address exposes the server to the network — see "
+    "--auth-token and --enable-shell-tools.",
 )
 @click.option("--port", default=8000, help="Port to run the server on. (default: 8000)")
 @click.option(
     "--transport",
     default="http",
     help="Transport method to use. (default: http). Options: 'stdio', 'http', 'sse', 'streamable-http'",
 )
+@click.option(
+    "--auth-token",
+    "auth_token",
+    default=None,
+    help="Bearer token required on the HTTP transport (clients send "
+    f"'Authorization: Bearer <token>'). Falls back to ${AUTH_TOKEN_ENV}. "
+    "Required to bind a non-loopback host unless --insecure-no-auth is set.",
+)
+@click.option(
+    "--insecure-no-auth",
+    "insecure_no_auth",
+    is_flag=True,
+    default=False,
+    help="Allow binding a non-loopback host with no --auth-token. "
+    "Unauthenticated network access — only for an isolated network you trust.",
+)
+@click.option(
+    "--enable-shell-tools",
+    "enable_shell_tools",
+    is_flag=True,
+    default=False,
+    help="Register the terminal/brewer tools. These execute arbitrary commands "
+    "as the server process; off by default. Never combine with an "
+    "unauthenticated network bind.",
+)
 @click.option(
     "--create_session",
     default=True,
@@ -77,9 +112,10 @@ def handle_shutdown(signum, frame):
     help="Path to a file containing the API key for Hopsworks authentication",
 )
 @click.option(
-    "--hostname_verification",
-    default=False,
-    help="Enable hostname verification for Hopsworks authentication",
+    "--hostname_verification/--no-hostname-verification",
+    default=True,
+    help="Verify the Hopsworks TLS hostname (default: on). Disable only for a "
+    "trusted private cluster with a self-signed certificate.",
 )
 @click.option(
     "--trust_store_path",
@@ -92,16 +128,19 @@ def handle_shutdown(signum, frame):
     help="Engine to use (python, spark, training, spark-no-metastore, spark-delta) (default: python)",
 )
 def run_server(
-    host: str = "0.0.0.0",
+    host: str = "127.0.0.1",
     port: int | None = None,
     transport: Literal["stdio", "http", "sse", "streamable-http"] = "http",
+    auth_token: str | None = None,
+    insecure_no_auth: bool = False,
+    enable_shell_tools: bool = False,
     create_session: bool = True,
     hopsworks_host: str | None = None,
     hopsworks_port: int = 443,
     project: str | None = None,
     api_key_value: str | None = None,
     api_key_file: str | None = None,
-    hostname_verification: bool = False,
+    hostname_verification: bool = True,
     trust_store_path: str | None = None,
     engine: Literal[
         "spark", "python", "training", "spark-no-metastore", "spark-delta"
@@ -110,18 +149,24 @@ def run_server(
     """Run the Hopsworks MCP server.
 
     Parameters:
-        host: Host to run the server on.
+        host: Address to bind to. Defaults to loopback; a routable address
+            exposes the server to the network.
         port:
             Port to run the server on.
             If not provided, it will default to the value of the UVICORN_PORT environment variable or 8000 if that is not set.
         transport: Transport method to use.
+        auth_token: Bearer token required on the HTTP transport (or via the
+            environment variable). Required for a non-loopback bind.
+        insecure_no_auth: Permit a non-loopback bind with no auth token.
+        enable_shell_tools: Register the command-executing terminal/brewer tools
+            (off by default).
         create_session: Whether to create a Hopsworks session for the MCP server.
         hopsworks_host: Hopsworks host URL.
         hopsworks_port: Hopsworks port.
         project: Project name to use as default.
         api_key_value: API key value for Hopsworks authentication.
         api_key_file: Path to a file containing the API key for Hopsworks authentication.
-        hostname_verification: Enable hostname verification for Hopsworks authentication.
+        hostname_verification: Verify the Hopsworks TLS hostname (default on).
         trust_store_path: Path to the trust store for Hopsworks authentication.
         engine: Hopsworks engine to use.
     """
@@ -133,6 +178,28 @@ def run_server(
     if port is None:
         port = int(os.getenv("UVICORN_PORT", "8000"))
 
+    auth_token = auth_token or os.getenv(AUTH_TOKEN_ENV)
+
+    # Fail closed: a network transport on a routable host with no auth token is
+    # the exact shape that turns this server into an open endpoint. Refuse it
+    # unless the operator explicitly accepts the risk.
+    on_network = transport in _NETWORK_TRANSPORTS and host not in _LOOPBACK_HOSTS
+    if on_network and not auth_token and not insecure_no_auth:
+        raise click.ClickException(
+            f"Refusing to bind {host!r} over '{transport}' without authentication. "
+            f"Pass --auth-token (or set ${AUTH_TOKEN_ENV}), bind 127.0.0.1, or "
+            "pass --insecure-no-auth if this is an isolated, trusted network."
+        )
+    if enable_shell_tools and on_network and not auth_token:
+        raise click.ClickException(
+            "--enable-shell-tools exposes arbitrary command execution; it cannot "
+            "be combined with an unauthenticated network bind. Add --auth-token "
+            "or bind 127.0.0.1."
+        )
+
+    auth = static_bearer_auth(auth_token) if auth_token else None
+    mcp = build_mcp(enable_shell_tools=enable_shell_tools, auth=auth)
+
     if create_session:
         # Set the API key for the Hopsworks client
         login(

python/hopsworks/mcp/server.py

@@ -14,9 +14,25 @@
 #   limitations under the License.
 #
 
-"""MCP server for Hopsworks."""
+"""MCP server for Hopsworks.
+
+`build_mcp()` is the factory. Shell-capable tools (`TerminalTools`,
+`BrewerTools`) execute arbitrary commands as the server process, so they are
+**opt-in** (`enable_shell_tools=True`) rather than always registered. Transport
+authentication is also opt-in via an `auth` provider; `run_server` refuses to
+expose a non-loopback HTTP transport without one.
+
+The module-level `mcp`/`app` are a safe default for ASGI deployments that import
+`hopsworks.mcp.server:app`: shell tools are off, and a bearer token verifier is
+attached when `HOPSWORKS_MCP_AUTH_TOKEN` is set in the environment.
+"""
+
+from __future__ import annotations
+
+import os
 
 from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
 from starlette import status
 from starlette.responses import Response
 
@@ -33,25 +49,76 @@
 )
 
 
-# Create a FastMCP server instance
-mcp = FastMCP(name="Hopsworks MCP")
+# Env var an operator can set to require a bearer token on the HTTP transport.
+# `run_server` also accepts it via --auth-token.
+AUTH_TOKEN_ENV = "HOPSWORKS_MCP_AUTH_TOKEN"
+
+
+def static_bearer_auth(token: str) -> StaticTokenVerifier:
+    """Build a single-token bearer verifier for the HTTP transport.
+
+    Clients must send ``Authorization: Bearer <token>``. This is a shared-secret
+    gate, not per-user identity; pair it with a loopback bind or a fronting proxy
+    for anything beyond a single trusted operator.
+
+    Parameters:
+        token: The bearer token clients must present.
 
-# Initialize tools and resources
-AuthTools(mcp)
-ProjectTools(mcp)
-ProjectResources(mcp)
-ProjectPrompts(mcp)
-SystemPrompts(mcp)
-JobTools(mcp)
-DatasetTools(mcp)
-FeatureGroupTools(mcp)
-TerminalTools(mcp)
-BrewerTools(mcp)
+    Returns:
+        A verifier suitable for ``FastMCP(auth=...)``.
+    """
+    return StaticTokenVerifier(
+        tokens={token: {"client_id": "hopsworks-mcp", "scopes": []}}
+    )
 
 
-@mcp.custom_route("/health", methods=["GET"])
-async def health(_):
-    return Response(status_code=status.HTTP_204_NO_CONTENT)
+def build_mcp(
+    *,
+    enable_shell_tools: bool = False,
+    auth: StaticTokenVerifier | None = None,
+) -> FastMCP:
+    """Construct a Hopsworks MCP server.
 
+    Parameters:
+        enable_shell_tools: Register the command-executing tools
+            (``TerminalTools``, ``BrewerTools``). Off by default — these grant
+            arbitrary code execution as the server process and must be turned on
+            deliberately.
+        auth: Optional transport auth provider. When set, the HTTP transport
+            rejects unauthenticated requests.
+
+    Returns:
+        The configured ``FastMCP`` instance.
+    """
+    server = FastMCP(name="Hopsworks MCP", auth=auth)
+
+    AuthTools(server)
+    ProjectTools(server)
+    ProjectResources(server)
+    ProjectPrompts(server)
+    SystemPrompts(server)
+    JobTools(server)
+    DatasetTools(server)
+    FeatureGroupTools(server)
+
+    if enable_shell_tools:
+        TerminalTools(server)
+        BrewerTools(server)
+
+    @server.custom_route("/health", methods=["GET"])
+    async def health(_):
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+    return server
+
+
+# Safe default for `hopsworks.mcp.server:app` importers: no shell tools, and a
+# bearer gate when HOPSWORKS_MCP_AUTH_TOKEN is set. Operators who need the shell
+# tools or a custom auth provider should run via `hopsworks-mcp` (run_server.py).
+_env_token = os.environ.get(AUTH_TOKEN_ENV)
+mcp = build_mcp(
+    enable_shell_tools=False,
+    auth=static_bearer_auth(_env_token) if _env_token else None,
+)
 
 app = mcp.http_app()

python/hopsworks/mcp/tools/auth.py

@@ -54,7 +54,7 @@ async def login(
         project: str = None,
         api_key_value: str = None,
         api_key_file: str = None,
-        hostname_verification: bool = False,
+        hostname_verification: bool = True,
         trust_store_path: str = None,
         engine: str = "python",
         ctx: Context | None = None,