feat(security): add injection character validation to all purl type validators (#16)

* fix(test): increase timeout for network-dependent purlExists tests

The conda and docker purlExists tests make real HTTP requests to external
registries. The conda test was timing out on CI at the default 10s limit.
Increase timeout to 30s for both network-calling tests.

* fix(test): reduce timeout to 15s

* feat(security): add injection character validation to all purl type validators

Add containsInjectionCharacters() checks to all 28 per-type validators,
rejecting shell/URL metacharacters (|, &, ;, `, $, <, >, (, ), {, }, #,
\, space, tab, newline, CR) in name and namespace components.

Previously only vscode-extension had these checks. Now every ecosystem
type validates against injection characters while respecting the purl
spec (which allows special characters in the generic type via
percent-encoding — so checks are per-type, not in the base validator).

- Enhanced 19 existing validators with injection checks
- Added new validate functions to 6 types (docker, github, gitlab,
  bitbucket, hex, pypi) that previously only had normalize
- Registered all new validators in purl-type.ts
- Cocoapods: replaced \s regex with containsInjectionCharacters
  (subsumes whitespace + adds shell metachar detection)
- npm/pub: already covered by URL-encoding and [a-z0-9_] checks
- Version strings intentionally NOT checked (Python epoch ! and
  Maven space/& are legitimate)
- 47 new tests covering all types

* refactor(security): centralize injection validation, harden scanner, add PurlInjectionError

Architecture improvements:
- Default validator in purl-type.ts now runs injection checks for all
  registered types — security is opt-out, not opt-in. Unregistered types
  (used by purl spec tests) bypass the default, preserving spec compliance.
- New shared validateNoInjectionByType() helper in validate.ts eliminates
  6-line injection check boilerplate from 26 per-type validators.
- Per-type validators now only contain ecosystem-specific rules.

Hardened scanner (containsInjectionCharacters):
- Added single quote (') and double quote (") detection — prevents
  quote-breaking attacks in shell, SQL, and URL contexts
- Added full C0 control character range (0x00-0x1f) — catches ESC
  (terminal escape sequences), BEL, vertical tab, form feed, and all
  other control chars used for log/terminal injection
- Added DEL (0x7f) detection — control character used in terminal attacks
- Extracted isInjectionCharCode() for the core detection logic
- Added findInjectionCharCode() returning the offending char code
- Added formatInjectionChar() for human-readable error labels

New PurlInjectionError class:
- Subclass of PurlError — catchable as either type for flexible handling
- Exposes charCode, component, and purlType properties for programmatic
  inspection by security tooling
- Error messages include the specific character found, e.g.:
  'maven "namespace" component contains injection character ";" (0x3b)'
- Control characters formatted as hex: '0x1b' (not the raw ESC byte)

* fix(security): freeze PurlInjectionError, use primordials, add unit tests

- Freeze PurlInjectionError instances (ObjectFreeze in constructor) and
  prototype — prevents property tampering on caught error objects
- Replace raw String.fromCharCode, Number.prototype.toString, and
  String.prototype.padStart with captured primordials
  (StringFromCharCode, NumberPrototypeToString, StringPrototypePadStart)
- Add unit tests verifying frozen instance, frozen prototype, and
  rejection of property writes/additions on error objects

* fix: replace 8 raw built-in calls with captured primordials

- validate.ts: Array.isArray → ArrayIsArray, Object.keys → ObjectKeys
- normalize.ts: Object.entries → ObjectEntries
- vscode-extension.ts: JSON.stringify → JSONStringify
- gem.ts: Array.isArray → ArrayIsArray
- npm.ts: new Set() → new SetCtor() (2 instances)
- primordials.ts: add NumberPrototypeToString, StringFromCharCode,
  StringPrototypePadStart exports

Author: jdalton

src/error.ts

@@ -1,4 +1,5 @@
 import {
+  ObjectFreeze,
   StringPrototypeCharCodeAt,
   StringPrototypeSlice,
   StringPrototypeToLowerCase,
@@ -46,4 +47,37 @@ class PurlError extends Error {
   }
 }
 
-export { formatPurlErrorMessage, PurlError }
+/**
+ * Specialized error for injection character detection.
+ * Developers can catch this specifically to distinguish injection rejections
+ * from other PURL validation errors and handle them at an elevated level
+ * (e.g., logging, alerting, blocking).
+ *
+ * Properties:
+ * - `component` — which PURL component was rejected ("name", "namespace")
+ * - `charCode` — the character code of the injection character found
+ * - `purlType` — the package type (e.g., "npm", "maven")
+ */
+class PurlInjectionError extends PurlError {
+  readonly charCode: number
+  readonly component: string
+  readonly purlType: string
+
+  constructor(
+    purlType: string,
+    component: string,
+    charCode: number,
+    charLabel: string,
+  ) {
+    super(
+      `${purlType} "${component}" component contains injection character ${charLabel}`,
+    )
+    this.charCode = charCode
+    this.component = component
+    this.purlType = purlType
+    ObjectFreeze(this)
+  }
+}
+ObjectFreeze(PurlInjectionError.prototype)
+
+export { formatPurlErrorMessage, PurlError, PurlInjectionError }

src/index.ts

@@ -86,7 +86,7 @@ export {
   UrlConverter,
 } from './package-url.js'
 export { PurlBuilder } from './package-url-builder.js'
-export { PurlError } from './error.js'
+export { PurlError, PurlInjectionError } from './error.js'
 // ============================================================================
 // Modular Utilities
 // ============================================================================
@@ -96,7 +96,11 @@ export { parseNpmSpecifier } from './purl-types/npm.js'
 // separate entry point: import { npmExists } from '@socketregistry/packageurl-js/exists'
 // This keeps the core bundle lean (~200 KB vs 3.3 MB with HTTP deps).
 export type { ExistsOptions, ExistsResult } from './purl-types/npm.js'
-export { containsInjectionCharacters } from './strings.js'
+export {
+  containsInjectionCharacters,
+  findInjectionCharCode,
+  formatInjectionChar,
+} from './strings.js'
 export { stringify, stringifySpec } from './stringify.js'
 export { Vers } from './vers.js'
 export type { VersComparator, VersConstraint, VersWildcard } from './vers.js'

src/normalize.ts

@@ -5,6 +5,7 @@
 import { isObject } from './objects.js'
 import {
   ObjectCreate,
+  ObjectEntries,
   ObjectFreeze,
   ReflectApply,
   StringPrototypeCharCodeAt,
@@ -152,7 +153,7 @@ function qualifiersToEntries(
       ? (ReflectApply(entriesProperty, rawQualifiersObj, []) as Iterable<
           [string, string]
         >)
-      : (Object.entries(rawQualifiers as Record<string, string>) as Iterable<
+      : (ObjectEntries(rawQualifiers as Record<string, string>) as Iterable<
           [string, string]
         >)
   }

src/primordials.ts

@@ -80,11 +80,15 @@ const ReflectGetOwnPropertyDescriptor = Reflect.getOwnPropertyDescriptor
 const ReflectOwnKeys = Reflect.ownKeys
 const ReflectSetPrototypeOf = Reflect.setPrototypeOf
 
+// ─── Number ───────────────────────────────────────────────────────────
+const NumberPrototypeToString = uncurryThis(Number.prototype.toString)
+
 // ─── RegExp ────────────────────────────────────────────────────────────
 const RegExpPrototypeExec = uncurryThis(RegExp.prototype.exec)
 const RegExpPrototypeTest = uncurryThis(RegExp.prototype.test)
 
 // ─── String ────────────────────────────────────────────────────────────
+const StringFromCharCode = String.fromCharCode
 const StringPrototypeCharCodeAt = uncurryThis(String.prototype.charCodeAt)
 const StringPrototypeEndsWith = uncurryThis(String.prototype.endsWith)
 const StringPrototypeIncludes = uncurryThis(String.prototype.includes)
@@ -98,6 +102,7 @@ const StringPrototypeReplaceAll = uncurryThis(
     replaceValue: string,
   ) => string,
 )
+const StringPrototypePadStart = uncurryThis(String.prototype.padStart)
 const StringPrototypeSlice = uncurryThis(String.prototype.slice)
 const StringPrototypeSplit = uncurryThis(String.prototype.split)
 const StringPrototypeStartsWith = uncurryThis(String.prototype.startsWith)
@@ -125,6 +130,7 @@ export {
   MapCtor,
   ObjectCreate,
   ObjectEntries,
+  NumberPrototypeToString,
   ObjectFreeze,
   ObjectIsFrozen,
   ObjectKeys,
@@ -137,13 +143,15 @@ export {
   RegExpPrototypeExec,
   RegExpPrototypeTest,
   SetCtor,
+  StringFromCharCode,
   StringPrototypeCharCodeAt,
   StringPrototypeEndsWith,
   StringPrototypeIncludes,
   StringPrototypeIndexOf,
   StringPrototypeLastIndexOf,
   StringPrototypeReplace,
   StringPrototypeReplaceAll,
+  StringPrototypePadStart,
   StringPrototypeSlice,
   StringPrototypeSplit,
   StringPrototypeStartsWith,

src/purl-type.ts

@@ -6,14 +6,19 @@
  * module in the purl-types/ directory with specific rules for namespace, name, version
  * normalization and validation.
  */
+import { PurlInjectionError } from './error.js'
 import { createHelpersNamespaceObject } from './helpers.js'
+import { findInjectionCharCode, formatInjectionChar } from './strings.js'
 import { normalize as alpmNormalize } from './purl-types/alpm.js'
 import { normalize as apkNormalize } from './purl-types/apk.js'
 import {
   normalize as bazelNormalize,
   validate as bazelValidate,
 } from './purl-types/bazel.js'
-import { normalize as bitbucketNormalize } from './purl-types/bitbucket.js'
+import {
+  normalize as bitbucketNormalize,
+  validate as bitbucketValidate,
+} from './purl-types/bitbucket.js'
 import { normalize as bitnamiNormalize } from './purl-types/bitnami.js'
 import { validate as cargoValidate } from './purl-types/cargo.js'
 import { validate as cocoaodsValidate } from './purl-types/cocoapods.js'
@@ -26,13 +31,25 @@ import {
 import { validate as cpanValidate } from './purl-types/cpan.js'
 import { validate as cranValidate } from './purl-types/cran.js'
 import { normalize as debNormalize } from './purl-types/deb.js'
-import { normalize as dockerNormalize } from './purl-types/docker.js'
+import {
+  normalize as dockerNormalize,
+  validate as dockerValidate,
+} from './purl-types/docker.js'
 import { validate as gemValidate } from './purl-types/gem.js'
 import { normalize as genericNormalize } from './purl-types/generic.js'
-import { normalize as githubNormalize } from './purl-types/github.js'
-import { normalize as gitlabNormalize } from './purl-types/gitlab.js'
+import {
+  normalize as githubNormalize,
+  validate as githubValidate,
+} from './purl-types/github.js'
+import {
+  normalize as gitlabNormalize,
+  validate as gitlabValidate,
+} from './purl-types/gitlab.js'
 import { validate as golangValidate } from './purl-types/golang.js'
-import { normalize as hexNormalize } from './purl-types/hex.js'
+import {
+  normalize as hexNormalize,
+  validate as hexValidate,
+} from './purl-types/hex.js'
 import { normalize as huggingfaceNormalize } from './purl-types/huggingface.js'
 import {
   normalize as juliaNormalize,
@@ -62,7 +79,10 @@ import {
   normalize as pubNormalize,
   validate as pubValidate,
 } from './purl-types/pub.js'
-import { normalize as pypiNormalize } from './purl-types/pypi.js'
+import {
+  normalize as pypiNormalize,
+  validate as pypiValidate,
+} from './purl-types/pypi.js'
 import { normalize as qpkgNormalize } from './purl-types/qpkg.js'
 import { normalize as rpmNormalize } from './purl-types/rpm.js'
 import { normalize as socketNormalize } from './purl-types/socket.js'
@@ -94,8 +114,40 @@ const PurlTypNormalizer = (purl: PurlObject): PurlObject => purl
 
 /**
  * Default validator for PURL types without specific validation rules.
+ * Rejects injection characters in name and namespace components.
+ * This ensures all types (including newly added ones) get injection
+ * protection by default — security is opt-out, not opt-in.
  */
-const PurlTypeValidator = (_purl: PurlObject, _throws: boolean): boolean => true
+function PurlTypeValidator(purl: PurlObject, throws: boolean): boolean {
+  const type = purl.type ?? 'unknown'
+  if (typeof purl.namespace === 'string') {
+    const nsCode = findInjectionCharCode(purl.namespace)
+    if (nsCode !== -1) {
+      if (throws) {
+        throw new PurlInjectionError(
+          type,
+          'namespace',
+          nsCode,
+          formatInjectionChar(nsCode),
+        )
+      }
+      return false
+    }
+  }
+  const nameCode = findInjectionCharCode(purl.name)
+  if (nameCode !== -1) {
+    if (throws) {
+      throw new PurlInjectionError(
+        type,
+        'name',
+        nameCode,
+        formatInjectionChar(nameCode),
+      )
+    }
+    return false
+  }
+  return true
+}
 
 // PURL types:
 // https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst
@@ -133,14 +185,19 @@ const PurlType = createHelpersNamespaceObject(
     },
     validate: {
       bazel: bazelValidate,
+      bitbucket: bitbucketValidate,
       cargo: cargoValidate,
       cocoapods: cocoaodsValidate,
       conda: condaValidate,
       conan: conanValidate,
       cpan: cpanValidate,
       cran: cranValidate,
+      docker: dockerValidate,
       gem: gemValidate,
+      github: githubValidate,
+      gitlab: gitlabValidate,
       golang: golangValidate,
+      hex: hexValidate,
       julia: juliaValidate,
       maven: mavenValidate,
       mlflow: mlflowValidate,
@@ -150,6 +207,7 @@ const PurlType = createHelpersNamespaceObject(
       opam: opamValidate,
       otp: otpValidate,
       pub: pubValidate,
+      pypi: pypiValidate,
       swift: swiftValidate,
       swid: swidValidate,
       'vscode-extension': vscodeExtensionValidate,

src/purl-types/bazel.ts

@@ -8,6 +8,7 @@
 
 import { PurlError } from '../error.js'
 import { lowerName } from '../strings.js'
+import { validateNoInjectionByType } from '../validate.js'
 
 interface PurlObject {
   name: string
@@ -29,7 +30,8 @@ export function normalize(purl: PurlObject): PurlObject {
 
 /**
  * Validate Bazel package URL.
- * Bazel packages must have a version (for reproducible builds).
+ * Bazel packages must have a version (for reproducible builds). Name must not
+ * contain injection characters.
  */
 export function validate(purl: PurlObject, throws: boolean): boolean {
   if (!purl.version || purl.version.length === 0) {
@@ -38,5 +40,8 @@ export function validate(purl: PurlObject, throws: boolean): boolean {
     }
     return false
   }
+  if (!validateNoInjectionByType('bazel', 'name', purl.name, throws)) {
+    return false
+  }
   return true
 }

src/purl-types/bitbucket.ts

@@ -1,9 +1,10 @@
 /**
- * @fileoverview Bitbucket PURL normalization.
+ * @fileoverview Bitbucket PURL normalization and validation.
  * https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#bitbucket
  */
 
 import { lowerName, lowerNamespace } from '../strings.js'
+import { validateNoInjectionByType } from '../validate.js'
 
 interface PurlObject {
   name: string
@@ -23,3 +24,19 @@ export function normalize(purl: PurlObject): PurlObject {
   lowerName(purl)
   return purl
 }
+
+/**
+ * Validate Bitbucket package URL.
+ * Name and namespace must not contain injection characters.
+ */
+export function validate(purl: PurlObject, throws: boolean): boolean {
+  if (
+    !validateNoInjectionByType('bitbucket', 'namespace', purl.namespace, throws)
+  ) {
+    return false
+  }
+  if (!validateNoInjectionByType('bitbucket', 'name', purl.name, throws)) {
+    return false
+  }
+  return true
+}

src/purl-types/cargo.ts

@@ -6,7 +6,7 @@
 import { httpJson } from '@socketsecurity/lib/http-request'
 
 import { ArrayPrototypeSome, StringPrototypeIncludes } from '../primordials.js'
-import { validateEmptyByType } from '../validate.js'
+import { validateEmptyByType, validateNoInjectionByType } from '../validate.js'
 
 import type { ExistsResult, ExistsOptions } from './npm.js'
 
@@ -137,10 +137,18 @@ export async function cargoExists(
 
 /**
  * Validate Cargo package URL.
- * Cargo packages must not have a namespace.
+ * Cargo packages must not have a namespace. Name must not contain injection characters.
  */
 export function validate(purl: PurlObject, throws: boolean): boolean {
-  return validateEmptyByType('cargo', 'namespace', purl.namespace, {
-    throws,
-  })
+  if (
+    !validateEmptyByType('cargo', 'namespace', purl.namespace, {
+      throws,
+    })
+  ) {
+    return false
+  }
+  if (!validateNoInjectionByType('cargo', 'name', purl.name, throws)) {
+    return false
+  }
+  return true
 }

src/purl-types/cocoapods.ts

@@ -7,11 +7,11 @@ import { httpJson } from '@socketsecurity/lib/http-request'
 
 import { PurlError } from '../error.js'
 import {
-  RegExpPrototypeTest,
   StringPrototypeCharCodeAt,
   StringPrototypeIncludes,
   ArrayPrototypeSome,
 } from '../primordials.js'
+import { validateNoInjectionByType } from '../validate.js'
 
 import type { ExistsResult, ExistsOptions } from './npm.js'
 
@@ -125,17 +125,13 @@ export async function cocoapodsExists(
 
 /**
  * Validate CocoaPods package URL.
- * Name cannot contain whitespace, plus (+) character, or begin with a period (.).
+ * Name cannot contain injection or whitespace characters, plus (+) character,
+ * or begin with a period (.).
  */
 export function validate(purl: PurlObject, throws: boolean): boolean {
   const { name } = purl
-  // Name cannot contain whitespace
-  if (RegExpPrototypeTest(/\s/, name)) {
-    if (throws) {
-      throw new PurlError(
-        'cocoapods "name" component cannot contain whitespace',
-      )
-    }
+  // Name must not contain injection characters
+  if (!validateNoInjectionByType('cocoapods', 'name', name, throws)) {
     return false
   }
   // Name cannot contain a plus (+) character