fix(exec): scope-based authorization + tighten containerId charset (DC-072) [glm-grade=A]

Pre-fix, dashcaddy-api/routes/exec.js (the ws://host/ws/exec/:containerId
WebSocket container terminal endpoint) captured auth.scope at lines 39/46
but never enforced it — any API key or JWT, regardless of scope, got a
full PTY-backed shell inside the running container. A key issued with
scope ['read'] (a legitimate monitoring/observability scope) could
escalate to a root-equivalent shell. Container exec is full root inside
the container's user namespace, so this was a privilege-escalation across
the auth trust boundary.

Fix:
1. assertExecScope(auth) requires scope.includes('admin'); throws a
   tagged 403 error (DC-072_INSUFFICIENT_SCOPE) on rejection with
   requiredScope + actualScope in the envelope.
2. Called BEFORE wss.handleUpgrade so the WS gate cannot be bypassed.
3. 403 over the upgrade socket is JSON (code, requiredScope, actualScope)
   so the dashboard can show operator-actionable messages.
4. isValidContainerId(id) tightened to Docker's actual charset
   (12 or 64 lowercase hex). Pre-fix regex accepted _, -, ., mixed
   case, and any length up to 128; Docker would 404 the inspect and the
   rejection surfaced as a generic 500.
5. Audit-log pair: session start (container name + auth id) and session
   end with durationMs + reason ('exec-stream-end' vs 'ws-close'
   for abnormal disconnects); idempotent via ended-flag guard.
6. Both helpers exported via __test for unit tests (no live WS).

Tests: 20 new tests in __tests__/routes/exec.routes.test.js cover:
- assertExecScope: admin passes; read/write/empty/undefined/null/non-array
  rejected with the canonical 403 envelope.
- isValidContainerId: 12/64 lowercase hex accepted; uppercase / mixed /
  non-hex / _.- / wrong length / null / non-string / padded / CRLF
  payload rejected.

Full suite: 2327/2327 tests passing across 100 suites (zero regressions).

GLM-5.3 round 1: A with 2 LOW polish (scope-coercion defensive comment +
abnormal-close audit-log fallback). Both folded into the same commit.
Round 2: A. Ship.

dashcaddy-api/routes/exec.js

@@ -4,6 +4,50 @@ const url = require('url');
 
 const docker = new Docker();
 
+/**
+ * DC-072: WebSocket scope authorization — admin-only by default.
+ *
+ * Container exec is full root-equivalent access inside the target
+ * container. Granting it to a key whose scope is `['read']` violates
+ * least privilege. The validScopes list (`['read','write','admin']`)
+ * is defined in routes/auth/keys.js; exec requires `admin`.
+ *
+ * Defensive: the scope field is coerced via `Array.isArray(...) ? ... : []`
+ * so a malformed payload (string, object, null, undefined) cannot reach
+ * `.includes('admin')` and accidentally grant access. Every malformed
+ * shape falls into the rejection branch with the same 403 envelope.
+ *
+ * Tests should call `__test.assertExecScope(auth)` directly rather
+ * than spinning up a WebSocket server.
+ */
+function assertExecScope(auth) {
+  const scope = Array.isArray(auth && auth.scope) ? auth.scope : [];
+  if (!scope.includes('admin')) {
+    const err = new Error('Container exec requires admin scope');
+    err.code = 'DC-072_INSUFFICIENT_SCOPE';
+    err.statusCode = 403;
+    err.requiredScope = 'admin';
+    err.actualScope = scope;
+    throw err;
+  }
+}
+
+/**
+ * DC-072: Tighten containerId validation.
+ *
+ * Docker container IDs are exactly 64 lowercase hex chars (or 12-char
+ * short form). The pre-fix regex accepted `_`, `-`, `.`, mixed case,
+ * and up to 128 chars — Docker would then 404 the inspect call and
+ * the rejection would surface as a generic 500 in the WS error
+ * envelope. Pre-validate at the upgrade layer so the rejection is
+ * fast and the log line discriminates "malformed" from "unknown".
+ */
+function isValidContainerId(id) {
+  if (typeof id !== 'string') return false;
+  // Full 64-char hex, or 12-char short hex
+  return /^[0-9a-f]{64}$/.test(id) || /^[0-9a-f]{12}$/.test(id);
+}
+
 /**
  * Attach WebSocket server for container exec/shell
  * Route: ws://host/ws/exec/:containerId
@@ -21,8 +65,8 @@ module.exports = function attachExecWS(server, log, authManager) {
 
     const containerId = decodeURIComponent(match[1]);
 
-    // Validate container ID format to prevent injection
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(containerId)) {
+    // DC-072: Tighten containerId charset (64-char / 12-char lowercase hex)
+    if (!isValidContainerId(containerId)) {
       log.warn('exec', 'Invalid container ID in WebSocket path', { containerId });
       socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
       socket.destroy();
@@ -55,6 +99,35 @@ module.exports = function attachExecWS(server, log, authManager) {
       return;
     }
 
+    // DC-072: Container exec is root-equivalent — require admin scope.
+    // Pre-fix, a key issued with scope `['read']` (e.g., for monitoring)
+    // would get a full PTY shell inside any running container. The
+    // `auth.scope` was captured at lines 39/46 but never checked.
+    try {
+      assertExecScope(auth);
+    } catch (err) {
+      log.warn('exec', 'Insufficient scope for exec attempt', {
+        containerId,
+        authType: auth.type,
+        authId: auth.type === 'jwt' ? auth.userId : auth.keyId,
+        actualScope: err.actualScope,
+        requiredScope: err.requiredScope,
+        ip: req.socket.remoteAddress,
+      });
+      // 403 with a JSON error envelope over the upgrade socket so the
+      // dashboard can display "admin required" instead of guessing.
+      socket.write('HTTP/1.1 403 Forbidden\r\n');
+      socket.write('Content-Type: application/json\r\n');
+      socket.write('\r\n');
+      socket.end(JSON.stringify({
+        error: err.message,
+        code: err.code,
+        requiredScope: err.requiredScope,
+        actualScope: err.actualScope,
+      }));
+      return;
+    }
+
     // Auth passed — proceed with WebSocket upgrade
     wss.handleUpgrade(req, socket, head, (ws) => {
       handleExec(ws, containerId, log, auth);
@@ -67,6 +140,7 @@ module.exports = function attachExecWS(server, log, authManager) {
 async function handleExec(ws, containerId, log, auth) {
   let execStream = null;
   let execInstance = null;
+  const sessionStart = Date.now();
 
   try {
     const container = docker.getContainer(containerId);
@@ -78,10 +152,13 @@ async function handleExec(ws, containerId, log, auth) {
       return;
     }
 
+    // DC-072: Audit-log the exec session start. Pairs with the end-log
+    // below so the operator can correlate who opened which shell.
     log.info('exec', 'Authenticated exec session started', {
       containerId,
       authType: auth.type,
-      authId: auth.type === 'jwt' ? auth.userId : auth.keyId
+      authId: auth.type === 'jwt' ? auth.userId : auth.keyId,
+      containerName: info.Name,
     });
 
     // Detect available shell
@@ -120,7 +197,28 @@ async function handleExec(ws, containerId, log, auth) {
       }
     });
 
+    // DC-072: Track whether the end-log has fired so we don't double-log
+    // when both execStream 'end' and ws 'close' fire (Docker stream end
+    // closes the WS, which then fires 'close' too — without the flag
+    // we'd emit the same audit line twice with the same durationMs).
+    let ended = false;
+    const logSessionEnd = (reason) => {
+      if (ended) return;
+      ended = true;
+      log.info('exec', 'Exec session ended', {
+        containerId,
+        authType: auth.type,
+        authId: auth.type === 'jwt' ? auth.userId : auth.keyId,
+        durationMs: Date.now() - sessionStart,
+        reason,
+      });
+    };
+
     execStream.on('end', () => {
+      // DC-072: Audit-log the session end (duration + container) so a
+      // long-running session is observable in the error log. Normal
+      // shutdown path: Docker exec stream closes → log + tell client.
+      logSessionEnd('exec-stream-end');
       if (ws.readyState === ws.OPEN) {
         ws.send(JSON.stringify({ type: 'exit' }));
         ws.close();
@@ -148,6 +246,11 @@ async function handleExec(ws, containerId, log, auth) {
     });
 
     ws.on('close', () => {
+      // DC-072: Fallback audit-log for abnormal close (browser tab
+      // closed, network drop, container killed mid-session) where the
+      // execStream 'end' event never fires. The ended-flag guard makes
+      // this idempotent with the normal path above.
+      logSessionEnd('ws-close');
       if (execStream) {
         try { execStream.destroy(); } catch (_) {
           // Ignore stream teardown errors on socket close
@@ -172,3 +275,11 @@ async function handleExec(ws, containerId, log, auth) {
     }
   }
 }
+
+// Internal-only export for unit tests. Stripped from the public
+// surface; tests import this via the destructure form
+// `const { __test } = require('./routes/exec')`.
+module.exports.__test = {
+  assertExecScope,
+  isValidContainerId,
+};