@cytario/web 2.2.5 → 2.2.6

package/README.md

@@ -230,6 +230,21 @@ cp .env.template .env    # Pre-configured for the Podman cluster
 npm run dev
 ```
 
+### Session Cache (Redis/Valkey)
+
+Sessions hold OAuth access/refresh/ID tokens and short-lived STS credentials. **TLS is required in production.** The app refuses to boot when `NODE_ENV !== "development"` unless one of the following is true:
+
+| Env var                          | Value    | Meaning                                                                                              |
+| -------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `REDIS_TLS`                      | `"true"` | Wrap the ioredis connection in TLS (recommended).                                                    |
+| `REDIS_CA_CERT`                  | PEM      | Optional CA bundle for self-signed deployments. Multi-line PEM string.                               |
+| `REDIS_TLS_SERVER_NAME`          | hostname | Optional SNI / certificate hostname override.                                                        |
+| `REDIS_INSECURE_ALLOW_PLAINTEXT` | `"true"` | Explicit opt-out for trusted private networks. Logs a warning. Not for use on shared infrastructure. |
+
+The local Podman cluster runs Valkey without TLS, which is allowed because `NODE_ENV=development`. Managed Valkey deployments (helm chart, AWS ElastiCache, etc.) should set `REDIS_TLS=true`. Valkey reuses the standard `6379` port for TLS when `tls.enabled` is set — it does not move the listener to `6380` and refuses plaintext on the same port — so leave `REDIS_PORT` at `6379` unless your provider explicitly publishes a separate TLS endpoint.
+
+In the production cluster (see `cytario-infrastructure`, C-212) the Valkey leaf cert is signed by a cluster-internal CA managed by cert-manager. The CA's public cert is distributed to every namespace as a `cytario-internal-ca` ConfigMap by trust-manager, and the `cytario-web` helm chart's `redis.caCertConfigMap.{name,key}` wires it into the pod as `REDIS_CA_CERT` via `valueFrom.configMapKeyRef`. The app sees the PEM through the normal env var path — no code-side knowledge of the trust source is required.
+
 ### Database
 
 PostgreSQL with [Prisma ORM](https://www.prisma.io/). Connection configured via `DATABASE_URL` in `.env`.

package/app/.server/db/redis.ts

@@ -1,6 +1,6 @@
 import Redis from "ioredis";
 
-import { cytarioConfig } from "~/config";
+import { buildRedisOptions } from "./redisOptions";
 
 /**
  * Redis/Valkey client instance
@@ -14,55 +14,39 @@ import { cytarioConfig } from "~/config";
  * - REDIS_PORT: Server port (default: 6379)
  * - REDIS_USERNAME: Optional username for authenticated connections (Redis 6+ / Valkey)
  * - REDIS_PASSWORD: Optional password for authenticated connections
+ * - REDIS_TLS: Set to "true" to wrap the connection in TLS (required in production)
+ * - REDIS_CA_CERT: Optional PEM-encoded CA certificate (string) for self-signed deployments
+ * - REDIS_TLS_SERVER_NAME: Optional SNI / certificate hostname override
+ * - REDIS_INSECURE_ALLOW_PLAINTEXT: Set to "true" to opt out of the production TLS requirement
  *
  * @example
- * // Use with Redis without authentication
- * REDIS_HOST=redis.example.com
- * REDIS_PORT=6379
- *
- * @example
- * // Use with Valkey with authentication
+ * // Use with managed Valkey over TLS — Valkey reuses 6379 for TLS when tls.enabled is set
  * REDIS_HOST=valkey.example.com
  * REDIS_PORT=6379
  * REDIS_USERNAME=myuser
  * REDIS_PASSWORD=mypassword
+ * REDIS_TLS=true
  *
  * @example
- * // Use with Redis/Valkey with password-only authentication (legacy)
- * REDIS_HOST=redis.example.com
+ * // Local development without TLS (only allowed when NODE_ENV=development)
+ * REDIS_HOST=localhost
  * REDIS_PORT=6379
- * REDIS_PASSWORD=mypassword
  */
 
-const {
-  redis: { host, port, username, password },
-} = cytarioConfig;
+const options = buildRedisOptions(process.env);
 
-export const redis = new Redis({
-  host,
-  port,
-  // Only include username if provided (Redis 6+ ACL support)
-  ...(username && { username }),
-  // Only include password if provided (backwards compatible)
-  ...(password && { password }),
-  maxRetriesPerRequest: 3,
-  retryStrategy(times) {
-    const delay = Math.min(times * 50, 2000);
-    return delay;
-  },
-  lazyConnect: false,
-});
+export const redis = new Redis(options);
 
-// Log connection errors
 redis.on("error", (err) => {
   console.error("Redis/Valkey connection error:", err);
 });
 
 redis.on("connect", () => {
-  const authInfo = username
-    ? ` (authenticated as ${username})`
-    : password
+  const authInfo = options.username
+    ? ` (authenticated as ${options.username})`
+    : options.password
       ? " (authenticated)"
       : "";
-  console.log(`Connected to Redis/Valkey at ${host}:${port}${authInfo}`);
+  const tlsInfo = options.tls ? " over TLS" : "";
+  console.log(`Connected to Redis/Valkey at ${options.host}:${options.port}${authInfo}${tlsInfo}`);
 });

package/app/.server/db/redisOptions.ts

@@ -0,0 +1,72 @@
+import type { RedisOptions } from "ioredis";
+
+/**
+ * Build ioredis connection options from environment variables.
+ *
+ * Recognised env vars:
+ * - `REDIS_HOST` (default: `localhost`)
+ * - `REDIS_PORT` (default: `6379`)
+ * - `REDIS_USERNAME` — optional ACL username
+ * - `REDIS_PASSWORD` — optional password
+ * - `REDIS_TLS` — `"true"` to wrap the connection in TLS
+ * - `REDIS_CA_CERT` — PEM-encoded CA certificate (string) used to verify
+ *   the server when the cert chain is not in the system trust store
+ * - `REDIS_TLS_SERVER_NAME` — SNI / certificate hostname override
+ * - `REDIS_INSECURE_ALLOW_PLAINTEXT` — `"true"` to opt out of the
+ *   production TLS requirement (escape hatch for trusted in-cluster
+ *   networks; logs a warning)
+ *
+ * Fails fast outside development if TLS is off and the opt-out flag is
+ * not set — session blobs contain OAuth tokens and STS credentials and
+ * must not traverse plaintext links in production. See C-204.
+ */
+export function buildRedisOptions(env: Record<string, string | undefined>): RedisOptions {
+  const host = env.REDIS_HOST || "localhost";
+  const port = Number(env.REDIS_PORT) || 6379;
+  const username = env.REDIS_USERNAME;
+  const password = env.REDIS_PASSWORD;
+  const tlsEnabled = env.REDIS_TLS === "true";
+  const caCert = env.REDIS_CA_CERT;
+  const tlsServerName = env.REDIS_TLS_SERVER_NAME;
+  const allowPlaintext = env.REDIS_INSECURE_ALLOW_PLAINTEXT === "true";
+  const nodeEnv = env.NODE_ENV;
+
+  const isLocalEnv = nodeEnv === "development" || nodeEnv === "test";
+
+  if (!tlsEnabled && !isLocalEnv && !allowPlaintext) {
+    throw new Error(
+      "Refusing to start: Redis/Valkey TLS is disabled. Set REDIS_TLS=true " +
+        "(recommended) or REDIS_INSECURE_ALLOW_PLAINTEXT=true to opt out. " +
+        "See C-204 / OWASP A02:2021.",
+    );
+  }
+
+  if (!tlsEnabled && allowPlaintext && !isLocalEnv) {
+    console.warn(
+      "REDIS_INSECURE_ALLOW_PLAINTEXT=true — session tokens will traverse " +
+        "an unencrypted connection. Only safe on a trusted private network.",
+    );
+  }
+
+  const options: RedisOptions = {
+    host,
+    port,
+    ...(username && { username }),
+    ...(password && { password }),
+    maxRetriesPerRequest: 3,
+    retryStrategy(times) {
+      const delay = Math.min(times * 50, 2000);
+      return delay;
+    },
+    lazyConnect: false,
+  };
+
+  if (tlsEnabled) {
+    options.tls = {
+      ...(caCert && { ca: caCert }),
+      ...(tlsServerName && { servername: tlsServerName }),
+    };
+  }
+
+  return options;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cytario/web",
-  "version": "2.2.5",
+  "version": "2.2.6",
   "description": "Cytario Web — scientific imaging data browser and viewer for OME-TIFF, OME-Zarr, Parquet and GeoTIFF on S3-compatible storage.",
   "license": "AGPL-3.0",
   "sideEffects": false,