fix(#338): Validate DEFAULT_WORKSPACE_ID as UUID

- Add federation.config.ts with UUID v4 validation for DEFAULT_WORKSPACE_ID
- Validate at module initialization (fail fast if misconfigured)
- Replace hardcoded "default" fallback with proper validation
- Add 18 tests covering valid UUIDs, invalid formats, and missing values
- Clear error messages with expected UUID format

Refs #338

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

apps/api/src/federation/federation.config.ts

@@ -0,0 +1,58 @@
+/**
+ * Federation Configuration
+ *
+ * Validates federation-related environment variables at startup.
+ * Issue #338: Validate DEFAULT_WORKSPACE_ID is a valid UUID
+ */
+
+/**
+ * UUID v4 regex pattern
+ * Matches standard UUID format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ * where y is 8, 9, a, or b
+ */
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/**
+ * Check if a string is a valid UUID v4
+ */
+export function isValidUuidV4(value: string): boolean {
+  return UUID_V4_REGEX.test(value);
+}
+
+/**
+ * Get the configured default workspace ID for federation
+ * @throws Error if DEFAULT_WORKSPACE_ID is not set or is not a valid UUID
+ */
+export function getDefaultWorkspaceId(): string {
+  const workspaceId = process.env.DEFAULT_WORKSPACE_ID;
+
+  if (!workspaceId || workspaceId.trim() === "") {
+    throw new Error(
+      "DEFAULT_WORKSPACE_ID environment variable is required for federation but is not set. " +
+        "Please configure a valid UUID v4 workspace ID for handling incoming federation connections."
+    );
+  }
+
+  const trimmedId = workspaceId.trim();
+
+  if (!isValidUuidV4(trimmedId)) {
+    throw new Error(
+      `DEFAULT_WORKSPACE_ID must be a valid UUID v4. ` +
+        `Current value "${trimmedId}" is not a valid UUID format. ` +
+        `Expected format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (where y is 8, 9, a, or b)`
+    );
+  }
+
+  return trimmedId;
+}
+
+/**
+ * Validates federation configuration at startup.
+ * Call this during module initialization to fail fast if misconfigured.
+ *
+ * @throws Error if DEFAULT_WORKSPACE_ID is not set or is not a valid UUID
+ */
+export function validateFederationConfig(): void {
+  // Validate DEFAULT_WORKSPACE_ID - this will throw if invalid
+  getDefaultWorkspaceId();
+}