enhance environment variable validation for JWT and admin credentials

Author: kittendevv

VERSION

@@ -1 +1 @@
-1.8.1
+1.8.2

backend/README.md

@@ -1,3 +1,27 @@
+## Environment Configuration
+
+The backend requires three critical environment variables to authenticate and issue JWTs:
+
+```
+ADMIN_USER=...
+ADMIN_PASS=...
+JWT_SECRET=...
+```
+
+Starting with v1.8.1 the server checks these values at boot. If any of them are missing **or empty**, the backend will exit with a fatal error.
+
+- `ADMIN_USER` and `ADMIN_PASS` must be non-empty strings. They define the login credentials for the admin dashboard.
+- `JWT_SECRET` must be non-empty and should be at least 16 characters to avoid weak tokens. Longer random strings are strongly recommended.
+
+When running through Docker Compose, define these in a `.env` file and ensure the values are quoted if they contain special characters. Example:
+
+```
+ADMIN_USER="myadmin"
+ADMIN_PASS="super-secret-P@ssw0rd"
+JWT_SECRET="change-this-to-a-long-random-string"
+```
+
+If you rely on Synology’s GUI or other orchestrators, double-check that the variables are actually persisted and not left blank by default.
 # Invio — Backend API
 
 Plain, fast invoicing without enterprise bloat. Create an invoice, share a link,

backend/src/app.ts

@@ -6,7 +6,7 @@ import { adminRoutes } from "./routes/admin.ts";
 import { publicRoutes } from "./routes/public.ts";
 import { authRoutes } from "./routes/auth.ts";
 import { logChromiumAvailability } from "./utils/chromium.ts";
-import { ensureEnv } from "./utils/env.ts";
+import { ensureEnv, getAdminCredentials, getJwtSecret } from "./utils/env.ts";
 
 const SECURE_HEADERS_DISABLED = (Deno.env.get("SECURE_HEADERS_DISABLED") || "").toLowerCase() === "true";
 const HSTS_ENABLED = (Deno.env.get("ENABLE_HSTS") || "").toLowerCase() === "true";
@@ -17,7 +17,20 @@ const app = new Hono();
 
 // Check for required credentials in environment
 try {
-  ensureEnv(["ADMIN_USER", "ADMIN_PASS", "JWT_SECRET"]);
+  ensureEnv(["JWT_SECRET"]);
+
+  const { username: adminUsername, password: adminPassword } = getAdminCredentials();
+  if (!adminUsername || adminUsername.trim().length === 0) {
+    throw new Error("ADMIN_USER must not be empty");
+  }
+  if (!adminPassword || adminPassword.trim().length === 0) {
+    throw new Error("ADMIN_PASS must not be empty");
+  }
+
+  const secret = getJwtSecret();
+  if (!secret || secret.trim().length === 0) {
+    throw new Error("JWT_SECRET must not be empty");
+  }
 } catch (error) {
   console.error(`FATAL: ${error instanceof Error ? error.message : error}`);
   Deno.exit(1);

backend/src/utils/env.ts

@@ -43,14 +43,23 @@ export function ensureEnv(keys: string[]): void {
 }
 
 export function getAdminCredentials() {
-  return {
-    username: requireEnv("ADMIN_USER"),
-    password: requireEnv("ADMIN_PASS"),
-  };
+  const username = requireEnv("ADMIN_USER").trim();
+  const password = requireEnv("ADMIN_PASS").trim();
+  if (username.length === 0) {
+    throw new Error("ADMIN_USER must not be empty");
+  }
+  if (password.length === 0) {
+    throw new Error("ADMIN_PASS must not be empty");
+  }
+  return { username, password };
 }
 
 export function getJwtSecret(): string {
-  return requireEnv("JWT_SECRET");
+  const secret = requireEnv("JWT_SECRET").trim();
+  if (secret.length === 0) {
+    throw new Error("JWT_SECRET must not be empty");
+  }
+  return secret;
 }
 
 export function isDemoMode(): boolean {

backend/src/utils/jwt.ts

@@ -1,12 +1,32 @@
 import { create, decode, verify } from "djwt";
-import { getJwtSecret } from "./env.ts";
+import { getJwtSecret, getAdminCredentials } from "./env.ts";
 
-async function getKey(): Promise<CryptoKey> {
-  const secretKey = getJwtSecret();
-  const secretBytes = new TextEncoder().encode(secretKey);
-  if (secretBytes.length === 0) {
+function validateSecret(secretKey: string) {
+  if (!secretKey || secretKey.trim().length === 0) {
     throw new Error("JWT_SECRET must not be empty");
   }
+
+  const trimmed = secretKey.trim();
+  if (trimmed.length < 16) {
+    console.warn("Warning: JWT_SECRET is shorter than 16 characters. Consider using a longer secret for better security.");
+  }
+}
+
+function validateAdminCredentials() {
+  const { username, password } = getAdminCredentials();
+  if (!username || username.trim().length === 0) {
+    throw new Error("ADMIN_USER must not be empty");
+  }
+  if (!password || password.trim().length === 0) {
+    throw new Error("ADMIN_PASS must not be empty");
+  }
+}
+
+async function getKey(): Promise<CryptoKey> {
+  validateAdminCredentials();
+  const secretKey = getJwtSecret();
+  validateSecret(secretKey);
+  const secretBytes = new TextEncoder().encode(secretKey.trim());
   const key = await crypto.subtle.importKey(
     "raw",
     secretBytes,