Restrict environment names to a strict identifier

Names are trimmed, then must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.
Anything else is unspecified and never rewritten.

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

Author: ejsmith

.agents/skills/exceptionless-javascript/SKILL.md

@@ -9,7 +9,7 @@ Use this skill to produce source-accurate setup code, integration guidance, and
 
 Keep answers compact. Prefer pointing to official docs for broad product behavior, and use local package READMEs/source to correct stale snippets or repo-specific package details.
 
-Deployment environments use `config.environment` or `config.setEnvironment(name)` as the default, and `builder.setEnvironment(name)` for overrides. They serialize as top-level `environment`, separately from `data.@environment`, preserving the supplied casing after trimming. See [configuration.md](references/configuration.md).
+Deployment environments use `config.environment` or `config.setEnvironment(name)` as the default, and `builder.setEnvironment(name)` for overrides. They serialize as top-level `environment`, separately from `data.@environment`, preserving the supplied casing after trimming; names must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` or stay unspecified. See [configuration.md](references/configuration.md).
 
 ## Pick References
 

.agents/skills/exceptionless-javascript/references/configuration.md

@@ -31,7 +31,7 @@ await Exceptionless.startup((config) => {
 
 ## Deployment environment
 
-Set `config.environment = "production"` or call `config.setEnvironment("production")`. Per-event `setEnvironment("staging")` overrides the default. Names are trimmed and retain their supplied casing; empty names, names longer than 64 characters, and names with control characters are unspecified. An invalid per-event name stays unspecified instead of using the default; pass `null` or `undefined` to `setEnvironment` to use the default. Missing values remain unspecified. The server filters case-insensitively and normalizes aggregation keys. This property is independent of `data.@environment` runtime metadata and of the application version. It does not change server stack grouping or create per-environment status.
+Set `config.environment = "production"` or call `config.setEnvironment("production")`. Per-event `setEnvironment("staging")` overrides the default. Names are trimmed and retain their supplied casing, then must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` (ASCII letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 64 characters). Anything else, such as `Staging West`, `prod/eu`, `produção`, empty or over-long names, is unspecified and never rewritten. An invalid per-event name stays unspecified instead of using the default; pass `null` or `undefined` to `setEnvironment` to use the default. Missing values remain unspecified. The server filters case-insensitively and normalizes aggregation keys. This property is independent of `data.@environment` runtime metadata and of the application version. It does not change server stack grouping or create per-environment status.
 
 ## Privacy
 

README.md

@@ -158,7 +158,7 @@ more information on configuring the client.
 
 #### Deployment environments
 
-Set a deployment environment in startup configuration with `config.environment = "production"` (or `config.setEnvironment("production")`). Override it on an event with `Exceptionless.createLog("Example").setEnvironment("staging").submit()`. Names are trimmed and limited to 64 characters, preserving the supplied casing. The server filters case-insensitively and normalizes aggregation keys. Missing or invalid names remain unspecified, and an invalid per-event name does not fall back to the configured default; pass `null` or `undefined` to `setEnvironment` to use the default. The top-level `environment` is separate from machine/runtime diagnostics in `data.@environment`; stacks and fixed versions remain shared across environments.
+Set a deployment environment in startup configuration with `config.environment = "production"` (or `config.setEnvironment("production")`). Override it on an event with `Exceptionless.createLog("Example").setEnvironment("staging").submit()`. Names are trimmed, then must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`: ASCII letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 64 characters. Casing is preserved and names are never rewritten, so values such as `Staging West`, `prod/eu` or `produção` are invalid. The server filters case-insensitively and normalizes aggregation keys. Missing or invalid names remain unspecified, and an invalid per-event name does not fall back to the configured default; pass `null` or `undefined` to `setEnvironment` to use the default. The top-level `environment` is separate from machine/runtime diagnostics in `data.@environment`; stacks and fixed versions remain shared across environments.
 
 ### Submitting Events and Errors
 

packages/core/src/Utils.ts

@@ -561,13 +561,18 @@ export function allowProcessToExitWithoutWaitingForTimerOrInterval(timeoutOrInte
     (timeoutOrIntervalId as { unref: () => ReturnType<typeof setTimeout> }).unref();
   }
 }
+const validEnvironment = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/**
+ * Trims the name and returns it with its casing preserved, or undefined when it is not a valid
+ * deployment environment name: ASCII letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 64 characters.
+ */
 export function normalizeEnvironment(value: string | null | undefined): string | undefined {
   if (typeof value !== "string") {
     return undefined;
   }
   const name = value.trim();
-  // eslint-disable-next-line no-control-regex -- Deployment names cannot contain control characters.
-  return name && name.length <= 64 && !/[\u0000-\u001f\u007f-\u009f]/u.test(name) ? name : undefined;
+  return validEnvironment.test(name) ? name : undefined;
 }
 
 /**

packages/core/test/ExceptionlessClient.test.ts

@@ -39,7 +39,9 @@ describe("ExceptionlessClient", () => {
 
   test.each([
     [" QA\t", "QA"],
-    ["x".repeat(65), undefined]
+    ["x".repeat(65), undefined],
+    ["Staging West", undefined],
+    ["prod/eu", undefined]
   ])("should normalize environment %j assigned by a later plugin", async (environment, expected) => {
     const client = new ExceptionlessClient();
     client.config.apiKey = "UNIT_TEST_API_KEY";

packages/core/test/Utils.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test, vi } from "vitest";
 
-import { endsWith, guid, isEmpty, isMatch, parseVersion, prune, randomNumber, startsWith, stringify, toBoolean } from "../src/Utils.js";
+import { endsWith, guid, isEmpty, isMatch, normalizeEnvironment, parseVersion, prune, randomNumber, startsWith, stringify, toBoolean } from "../src/Utils.js";
 
 describe("Utils", () => {
   function getObjectWithInheritedProperties(): unknown {
@@ -1237,4 +1237,48 @@ describe("Utils", () => {
       expect(toBoolean(true)).toBe(true);
     });
   });
+
+  describe("normalizeEnvironment", () => {
+    test.each([
+      ["production", "production"],
+      ["Staging-EU", "Staging-EU"],
+      ["qa.2", "qa.2"],
+      ["dev_local", "dev_local"],
+      ["a", "a"],
+      ["0", "0"],
+      ["  Production \t", "Production"],
+      ["\u00a0Production\u2003", "Production"],
+      ["a" + "b".repeat(63), "a" + "b".repeat(63)],
+      ["  " + "a".repeat(64) + "  ", "a".repeat(64)]
+    ])("should accept %j", (value, expected) => {
+      expect(normalizeEnvironment(value)).toBe(expected);
+    });
+
+    test.each([
+      null,
+      undefined,
+      "",
+      " ",
+      " \t\r\n ",
+      "Staging West",
+      "prod/eu",
+      "prod:eu",
+      "-prod",
+      ".prod",
+      "_prod",
+      "produção",
+      "İ".repeat(64),
+      "a".repeat(65),
+      "  " + "a".repeat(65) + "  ",
+      "prod\ninvalid",
+      "prod\tinvalid",
+      "pro\u0000d",
+      "prod\u007f",
+      "pro\u0085d",
+      "prod\u200b",
+      "prod\n\u2028x"
+    ])("should reject %j", (value) => {
+      expect(normalizeEnvironment(value)).toBeUndefined();
+    });
+  });
 });

packages/core/test/configuration/Configuration.test.ts

@@ -10,14 +10,18 @@ describe("Configuration", () => {
     expect(config.environment).toBe("Production");
     config.environment = "Staging";
     expect(config.environment).toBe("Staging");
-    config.environment = "İ".repeat(64);
-    expect(config.environment).toBe("İ".repeat(64));
+    config.environment = "a".repeat(64);
+    expect(config.environment).toBe("a".repeat(64));
     config.setEnvironment("");
     expect(config.environment).toBeUndefined();
     config.setEnvironment("x".repeat(65));
     expect(config.environment).toBeUndefined();
     config.setEnvironment("prod\ninvalid");
     expect(config.environment).toBeUndefined();
+    config.setEnvironment("Staging-EU");
+    expect(config.environment).toBe("Staging-EU");
+    config.setEnvironment("Staging West");
+    expect(config.environment).toBeUndefined();
     config.setEnvironment("\tProduction\n");
     expect(config.environment).toBe("Production");
   });

packages/core/test/plugins/default/ConfigurationDefaultsPlugin.test.ts

@@ -31,13 +31,16 @@ describe("ConfigurationDefaultsPlugin", () => {
     expect(JSON.parse(JSON.stringify(builder.target)).environment).toBe("Staging");
   });
 
-  test.each(["", " ", "x".repeat(65), "prod\ninvalid"])("should keep invalid override %j unspecified", async (environment) => {
-    const client = new ExceptionlessClient();
-    client.config.environment = "production";
-    const builder = client.createLog("test", "message").setEnvironment(environment);
-    await new ConfigurationDefaultsPlugin().run(new EventPluginContext(client, builder.target, new EventContext()));
-    expect(builder.target.environment).toBeUndefined();
-  });
+  test.each(["", " ", "x".repeat(65), "prod\ninvalid", "Staging West", "prod/eu", "prod:eu", "-prod", ".prod", "produção"])(
+    "should keep invalid override %j unspecified",
+    async (environment) => {
+      const client = new ExceptionlessClient();
+      client.config.environment = "production";
+      const builder = client.createLog("test", "message").setEnvironment(environment);
+      await new ConfigurationDefaultsPlugin().run(new EventPluginContext(client, builder.target, new EventContext()));
+      expect(builder.target.environment).toBeUndefined();
+    }
+  );
 
   test.each([null, undefined])("should apply the default when the override is cleared with %j", async (environment) => {
     const client = new ExceptionlessClient();