@endo/compartment-mapper 1.6.2 → 2.0.0

package/src/policy.js

@@ -4,39 +4,46 @@
  * @module
  */
 
-// @ts-check
-
 /**
  * @import {
  *   Policy,
  *   PackagePolicy,
  *   AttenuationDefinition,
- *   PackageNamingKit,
  *   DeferredAttenuatorsProvider,
  *   CompartmentDescriptor,
  *   Attenuator,
  *   SomePolicy,
+ *   PolicyEnforcementField,
  *   SomePackagePolicy,
+ *   CompartmentDescriptorWithPolicy,
+ *   ModuleConfiguration,
+ *   CanonicalName,
  * } from './types.js'
+ * @import {ThirdPartyStaticModuleInterface} from 'ses'
  */
 
 import {
+  ATTENUATORS_COMPARTMENT,
+  ENTRY_COMPARTMENT,
   getAttenuatorFromDefinition,
   isAllowingEverything,
   isAttenuationDefinition,
   policyLookupHelper,
+  WILDCARD_POLICY_VALUE,
 } from './policy-format.js';
 
-const { create, entries, values, assign, freeze, getOwnPropertyDescriptors } =
-  Object;
+const {
+  keys,
+  create,
+  entries,
+  values,
+  assign,
+  freeze,
+  getOwnPropertyDescriptors,
+} = Object;
 const { ownKeys } = Reflect;
 const q = JSON.stringify;
 
-/**
- * Const string to identify the internal attenuators compartment
- */
-export const ATTENUATORS_COMPARTMENT = '<ATTENUATORS>';
-
 /**
  * Copies properties (optionally limited to a specific list) from one object to another.
  * @template {Record<PropertyKey, any>} T
@@ -107,80 +114,55 @@ export const detectAttenuators = policy => {
   return attenuatorsCache.get(policy);
 };
 
-/**
- * Generates a string identifying a package for policy lookup purposes.
- *
- * @param {PackageNamingKit} namingKit
- * @returns {string}
- */
-const generateCanonicalName = ({ isEntry = false, name, path }) => {
-  if (isEntry) {
-    throw Error('Entry module cannot be identified with a canonicalName');
-  }
-  if (name === ATTENUATORS_COMPARTMENT) {
-    return ATTENUATORS_COMPARTMENT;
-  }
-  return path.join('>');
-};
-
 /**
  * Verifies if a module identified by `namingKit` can be a dependency of a package per `packagePolicy`.
  * `packagePolicy` is required, when policy is not set, skipping needs to be handled by the caller.
  *
- * @param {PackageNamingKit} namingKit
+ * @param {CanonicalName} canonicalName
  * @param {PackagePolicy} packagePolicy
  * @returns {boolean}
  */
-export const dependencyAllowedByPolicy = (namingKit, packagePolicy) => {
-  if (namingKit.isEntry) {
-    // dependency on entry compartment should never be allowed
-    return false;
-  }
-  const canonicalName = generateCanonicalName(namingKit);
+export const dependencyAllowedByPolicy = (canonicalName, packagePolicy) => {
   return !!policyLookupHelper(packagePolicy, 'packages', canonicalName);
 };
 
 /**
- * Returns the policy applicable to the canonicalName of the package
- *
- * @overload
- * @param {PackageNamingKit} namingKit - a key in the policy resources spec is derived from these
- * @param {SomePolicy} policy - user supplied policy
- * @returns {SomePackagePolicy} packagePolicy if policy was specified
- */
-
-/**
- * Returns `undefined`
- *
- * @overload
- * @param {PackageNamingKit} namingKit - a key in the policy resources spec is derived from these
- * @param {SomePolicy} [policy] - user supplied policy
- * @returns {SomePackagePolicy|undefined} packagePolicy if policy was specified
- */
-
-/**
- * Returns the policy applicable to the canonicalName of the package
+ * Generates the {@link SomePackagePolicy} value to be used in
+ * {@link CompartmentDescriptor.policy}
  *
- * @param {PackageNamingKit} namingKit - a key in the policy resources spec is derived from these
- * @param {SomePolicy} [policy] - user supplied policy
+ * @param {CanonicalName | typeof ATTENUATORS_COMPARTMENT | typeof ENTRY_COMPARTMENT} label
+ * @param {object} [options] Options
+ * @param {SomePolicy} [options.policy] User-supplied policy
+ * @returns {SomePackagePolicy|undefined} Package policy from `policy` or empty
+ * object; returns `params.packagePolicy` if provided. If entry compartment,
+ * returns the `entry` property of the policy verbatim.
  */
-export const getPolicyForPackage = (namingKit, policy) => {
-  if (!policy) {
-    return undefined;
-  }
-  if (namingKit.isEntry) {
-    return policy.entry;
-  }
-  const canonicalName = generateCanonicalName(namingKit);
-  if (canonicalName === ATTENUATORS_COMPARTMENT) {
-    return { defaultAttenuator: policy.defaultAttenuator, packages: 'any' };
+export const makePackagePolicy = (label, { policy } = {}) => {
+  /** @type {SomePackagePolicy|undefined} */
+  let packagePolicy;
+  if (!label) {
+    throw new TypeError(
+      `Invalid arguments: label must be a non-empty string; got ${q(label)}`,
+    );
   }
-  if (policy.resources && policy.resources[canonicalName] !== undefined) {
-    return policy.resources[canonicalName];
-  } else {
-    // Allow skipping policy entries for packages with no powers.
-    return create(null);
+  if (policy) {
+    if (label === ATTENUATORS_COMPARTMENT) {
+      packagePolicy = {
+        defaultAttenuator: policy.defaultAttenuator,
+        packages: WILDCARD_POLICY_VALUE,
+      };
+    } else if (label === ENTRY_COMPARTMENT) {
+      packagePolicy = policy.entry;
+      // If policy.entry is `undefined`, we return `undefined` which is
+      // equivalent to "allow everything".
+      return packagePolicy;
+    } else if (label) {
+      packagePolicy = policy.resources?.[label];
+    }
+    // An empty object for a package policy is equivalent to "allow nothing"
+    return packagePolicy ?? create(null);
   }
+  return undefined;
 };
 
 /**
@@ -249,6 +231,11 @@ export const makeDeferredAttenuatorsProvider = (
       throw Error(`No attenuators specified in policy`);
     };
   } else {
+    if (!compartmentDescriptors[ATTENUATORS_COMPARTMENT].policy) {
+      throw Error(
+        `${q(ATTENUATORS_COMPARTMENT)} is missing the required policy; this is likely a bug`,
+      );
+    }
     defaultAttenuator =
       compartmentDescriptors[ATTENUATORS_COMPARTMENT].policy.defaultAttenuator;
 
@@ -321,7 +308,7 @@ async function attenuateGlobalThis({
  *
  * @param {object} globalThis
  * @param {object} globals
- * @param {PackagePolicy} packagePolicy
+ * @param {PackagePolicy|undefined} packagePolicy
  * @param {DeferredAttenuatorsProvider} attenuators
  * @param {Array<Promise>} pendingJobs
  * @param {string} name
@@ -376,18 +363,46 @@ export const attenuateGlobals = (
 };
 
 /**
- * @param {string} [errorHint]
+ * Generates a helpful error message for a policy enforcement failure
+ *
+ * @param {string} specifier
+ * @param {CompartmentDescriptorWithPolicy} referrerCompartmentDescriptor
+ * @param {object} options
+ * @param {string} [options.resourceCanonicalName]
+ * @param {string} [options.errorHint]
+ * @param {PolicyEnforcementField} [options.policyField]
  * @returns {string}
  */
-const diagnoseModulePolicy = errorHint => {
-  if (!errorHint) {
-    return '';
+const policyEnforcementFailureMessage = (
+  specifier,
+  { label, policy },
+  { resourceCanonicalName, errorHint, policyField = 'packages' } = {},
+) => {
+  let message = `Importing ${q(specifier)}`;
+  if (resourceCanonicalName) {
+    message += ` in resource ${q(resourceCanonicalName)}`;
   }
-  return ` (info: ${errorHint})`;
+  message += ` in ${q(label)} was not allowed by`;
+  if (keys(policy[policyField] ?? {}).length > 0) {
+    message += ` ${q(policyField)} policy: ${q(policy[policyField])}`;
+  } else {
+    message += ` empty ${q(policyField)} policy`;
+  }
+  if (errorHint) {
+    message += ` (info: ${errorHint})`;
+  }
+  return message;
 };
 
 /**
- * Options for {@link enforceModulePolicy}
+ * @template {ModuleConfiguration} T
+ * @param {CompartmentDescriptor<T>} compartmentDescriptor
+ * @returns {compartmentDescriptor is CompartmentDescriptorWithPolicy<T>}
+ */
+const hasPolicy = compartmentDescriptor => !!compartmentDescriptor.policy;
+
+/**
+ * Options for {@link enforcePolicyByModule}
  * @typedef EnforceModulePolicyOptions
  * @property {boolean} [exit] - Whether it is an exit module
  * @property {string} [errorHint] - Error hint message
@@ -400,34 +415,69 @@ const diagnoseModulePolicy = errorHint => {
  * @param {CompartmentDescriptor} compartmentDescriptor
  * @param {EnforceModulePolicyOptions} [options]
  */
-export const enforceModulePolicy = (
+export const enforcePolicyByModule = (
   specifier,
   compartmentDescriptor,
   { exit, errorHint } = {},
 ) => {
-  const { policy, modules, label } = compartmentDescriptor;
-  if (!policy) {
+  if (!hasPolicy(compartmentDescriptor)) {
+    // No policy, no enforcement
     return;
   }
+  const { policy, modules } = compartmentDescriptor;
 
   if (!exit) {
     if (!modules[specifier]) {
       throw Error(
-        `Importing ${q(specifier)} in ${q(
-          label,
-        )} was not allowed by packages policy ${q(
-          policy.packages,
-        )}${diagnoseModulePolicy(errorHint)}`,
+        policyEnforcementFailureMessage(specifier, compartmentDescriptor, {
+          errorHint,
+        }),
       );
     }
+
     return;
   }
 
   if (!policyLookupHelper(policy, 'builtins', specifier)) {
     throw Error(
-      `Importing ${q(specifier)} was not allowed by policy builtins:${q(
-        policy.builtins,
-      )}${diagnoseModulePolicy(errorHint)}`,
+      policyEnforcementFailureMessage(specifier, compartmentDescriptor, {
+        errorHint,
+        policyField: 'builtins',
+      }),
+    );
+  }
+};
+
+/**
+ * Throws if importing `compartmentDescriptor` from `referrerCompartmentDescriptor` is not allowed per package policy
+ *
+ * @param {CompartmentDescriptor} compartmentDescriptor
+ * @param {CompartmentDescriptor} referrerCompartmentDescriptor
+ * @param {EnforceModulePolicyOptions} [options]
+ */
+export const enforcePackagePolicyByCanonicalName = (
+  compartmentDescriptor,
+  referrerCompartmentDescriptor,
+  { errorHint } = {},
+) => {
+  if (!hasPolicy(referrerCompartmentDescriptor)) {
+    throw new Error(
+      `Cannot enforce policy via ${q(referrerCompartmentDescriptor.label)}: no package policy defined`,
+    );
+  }
+  const { policy: referrerPolicy } = referrerCompartmentDescriptor;
+  const { label: resourceCanonicalName } = compartmentDescriptor;
+
+  if (!policyLookupHelper(referrerPolicy, 'packages', resourceCanonicalName)) {
+    throw new Error(
+      policyEnforcementFailureMessage(
+        resourceCanonicalName,
+        referrerCompartmentDescriptor,
+        {
+          errorHint,
+          resourceCanonicalName,
+        },
+      ),
     );
   }
 };
@@ -437,8 +487,8 @@ export const enforceModulePolicy = (
  * @param {object} options
  * @param {DeferredAttenuatorsProvider} options.attenuators
  * @param {AttenuationDefinition} options.attenuationDefinition
- * @param {import('ses').ThirdPartyStaticModuleInterface} options.originalModuleRecord
- * @returns {Promise<import('ses').ThirdPartyStaticModuleInterface>}
+ * @param {ThirdPartyStaticModuleInterface} options.originalModuleRecord
+ * @returns {Promise<ThirdPartyStaticModuleInterface>}
  */
 async function attenuateModule({
   attenuators,
@@ -454,29 +504,31 @@ async function attenuateModule({
   // An async attenuator maker could be introduced here to return a synchronous attenuator.
   // For async attenuators see PR https://github.com/endojs/endo/pull/1535
 
-  return freeze({
-    imports: originalModuleRecord.imports,
-    // It seems ok to declare the exports but then let the attenuator trim the values.
-    // Seems ok for attenuation to leave them undefined - accessing them is malicious behavior.
-    exports: originalModuleRecord.exports,
-    execute: (moduleExports, compartment, resolvedImports) => {
-      const ns = {};
-      originalModuleRecord.execute(ns, compartment, resolvedImports);
-      const attenuated = attenuate(ns);
-      moduleExports.default = attenuated;
-      assign(moduleExports, attenuated);
-    },
-  });
+  return freeze(
+    /** @type {ThirdPartyStaticModuleInterface} */ ({
+      imports: originalModuleRecord.imports,
+      // It seems ok to declare the exports but then let the attenuator trim the values.
+      // Seems ok for attenuation to leave them undefined - accessing them is malicious behavior.
+      exports: originalModuleRecord.exports,
+      execute: (moduleExports, compartment, resolvedImports) => {
+        const ns = {};
+        originalModuleRecord.execute(ns, compartment, resolvedImports);
+        const attenuated = attenuate(ns);
+        moduleExports.default = attenuated;
+        assign(moduleExports, attenuated);
+      },
+    }),
+  );
 }
 
 /**
  * Throws if importing of the specifier is not allowed by the policy
  *
  * @param {string} specifier - exit module name
- * @param {import('ses').ThirdPartyStaticModuleInterface} originalModuleRecord - reference to the exit module
- * @param {PackagePolicy} policy - local compartment policy
+ * @param {ThirdPartyStaticModuleInterface} originalModuleRecord - reference to the exit module
+ * @param {PackagePolicy|undefined} policy - local compartment policy
  * @param {DeferredAttenuatorsProvider} attenuators - a key-value where attenuations can be found
- * @returns {Promise<import('ses').ThirdPartyStaticModuleInterface>} - the attenuated module
+ * @returns {Promise<ThirdPartyStaticModuleInterface>} - the attenuated module
  */
 export const attenuateModuleHook = async (
   specifier,
@@ -484,8 +536,11 @@ export const attenuateModuleHook = async (
   policy,
   attenuators,
 ) => {
+  if (!policy) {
+    return originalModuleRecord;
+  }
   const policyValue = policyLookupHelper(policy, 'builtins', specifier);
-  if (!policy || policyValue === true) {
+  if (policyValue === true) {
     return originalModuleRecord;
   }
 

package/src/types/canonical-name.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Fairly exhaustive, excruciatingly pedantic _type-level_ helpers for
+ * representing and validating **Canonical Names** and npm package names.
+ *
+ * A {@link CanonicalName | Canonical Name} is a string containing one or more
+ * npm package names (scoped or unscoped) delimited by a `>` character.
+ *
+ * The following rules about npm package names are enforced:
+ *
+ * - ✅ Length > 0
+ * - ✅ Can contain hyphens
+ * - ✅ No leading `.` or `_`
+ * - ✅ No spaces
+ * - ✅ No `~)('!*` characters
+ *
+ * The following rules are not enforced:
+ *
+ * - ❌ All lowercase - Not feasible due to recursion limits & legacy package
+ *   names
+ * - ❌ Not a reserved name - unmaintainable list of node builtin module names
+ * - ❌ Length ≤ 214 - Not feasible due to recursion limits & legacy package
+ *   names
+ *
+ * "Legacy" package names may contain uppercase letters and be longer than 214
+ * characters.
+ *
+ * @module
+ * @see {@link https://www.npmjs.com/package/validate-npm-package-name}
+ */
+/**
+ * Characters that are explicitly forbidden in npm package names. These include:
+ * ` `, `~`, `)`, `(`, `'`, `!`, `*`
+ *
+ * We check each one individually because TypeScript's template literal types
+ * can detect if a string contains a specific substring.
+ *
+ * Returns `true` if the string contains a forbidden character, `false`
+ * otherwise.
+ */
+type ContainsForbiddenChar<S extends string> = S extends `${string} ${string}` | `${string}~${string}` | `${string})${string}` | `${string}(${string}` | `${string}'${string}` | `${string}!${string}` | `${string}*${string}` ? true : false;
+/**
+ * Validates that a string doesn't start with `.` or `_`.
+ *
+ * Returns `true` if the string doesn't start with `.` or `_`, `false`
+ * otherwise.
+ */
+type HasValidStart<S extends string> = S extends `.${string}` | `_${string}` ? false : true;
+/**
+ * Validates that a string is non-empty.
+ *
+ * Returns `true` if the string is non-empty, `false` otherwise.
+ */
+type IsNonEmpty<S extends string> = S extends '' ? false : true;
+/**
+ * Combines all validation checks for a package name segment.
+ *
+ * Returns `true` if the string passes all checks, `false` otherwise.
+ */
+type IsValidPackageNameSegment<S extends string> = IsNonEmpty<S> extends false ? false : HasValidStart<S> extends false ? false : ContainsForbiddenChar<S> extends true ? false : true;
+/** A scoped npm package name, like "@scope/pkg" */
+export type ScopedPackageName<S extends string = string> = S extends `@${infer Scope}/${infer Name}` ? IsValidPackageNameSegment<Scope> extends true ? IsValidPackageNameSegment<Name> extends true ? S : never : never : never;
+/**
+ * An unscoped npm package name.
+ *
+ * Must pass all validation checks and must not contain a `/` (which would
+ * indicate a scoped package or a subpath).
+ *
+ * Note: Package names containing uppercase letters are technically invalid per
+ * npm rules, but they exist in the wild. TypeScript cannot reliably validate
+ * case at the type level, so we don't enforce this.
+ */
+export type UnscopedPackageName<S extends string = string> = S extends `${string}/${string}` ? never : IsValidPackageNameSegment<S> extends true ? S : never;
+/**
+ * A scoped or unscoped npm package name.
+ */
+export type NpmPackageName<S extends string = string> = S extends `@${string}/${string}` ? ScopedPackageName<S> : UnscopedPackageName<S>;
+/**
+ * Split a string on `>`—the canonical name delimiter—into a tuple of segments.
+ */
+export type SplitOnDelimiter<S extends string> = S extends `${infer Head}>${infer Tail}` ? [Head, ...SplitOnDelimiter<Tail>] : [S];
+/**
+ * Validate that every element in a tuple of strings is a valid npm package
+ * name.
+ */
+export type AllValidPackageNames<Parts extends readonly string[]> = Parts extends [
+    infer Head extends string,
+    ...infer Tail extends readonly string[]
+] ? NpmPackageName<Head> extends never ? never : AllValidPackageNames<Tail> : Parts;
+/**
+ * A Canonical Name string comprised of one or more npm package names separated
+ * by `>` (e.g., `foo`, `@scope/foo>bar`, `foo>@scope/bar>baz`).
+ *
+ * When given a string literal type, invalid shapes narrow to `never`.
+ */
+export type CanonicalName<S extends string = string> = AllValidPackageNames<SplitOnDelimiter<S>> extends never ? never : S;
+export {};
+//# sourceMappingURL=canonical-name.d.ts.map

package/src/types/canonical-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-name.d.ts","sourceRoot":"","sources":["canonical-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;GASG;AACH,KAAK,qBAAqB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAC5C,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,IAAI,GACJ,KAAK,CAAC;AAEV;;;;;GAKG;AACH,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,IAAI,MAAM,EAAE,GAAG,IAAI,MAAM,EAAE,GACxE,KAAK,GACL,IAAI,CAAC;AAET;;;;GAIG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,KAAK,GAAG,IAAI,CAAC;AAEhE;;;;GAIG;AACH,KAAK,yBAAyB,CAAC,CAAC,SAAS,MAAM,IAC7C,UAAU,CAAC,CAAC,CAAC,SAAS,KAAK,GACvB,KAAK,GACL,aAAa,CAAC,CAAC,CAAC,SAAS,KAAK,GAC5B,KAAK,GACL,qBAAqB,CAAC,CAAC,CAAC,SAAS,IAAI,GACnC,KAAK,GACL,IAAI,CAAC;AAMf,mDAAmD;AACnD,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IACrD,CAAC,SAAS,IAAI,MAAM,KAAK,IAAI,MAAM,IAAI,EAAE,GACrC,yBAAyB,CAAC,KAAK,CAAC,SAAS,IAAI,GAC3C,yBAAyB,CAAC,IAAI,CAAC,SAAS,IAAI,GAC1C,CAAC,GACD,KAAK,GACP,KAAK,GACP,KAAK,CAAC;AAEZ;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IACvD,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,GAC3B,KAAK,GACL,yBAAyB,CAAC,CAAC,CAAC,SAAS,IAAI,GACvC,CAAC,GACD,KAAK,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAClD,CAAC,SAAS,IAAI,MAAM,IAAI,MAAM,EAAE,GAC5B,iBAAiB,CAAC,CAAC,CAAC,GACpB,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAE7B;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAC3C,CAAC,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GACnC,CAAC,IAAI,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC,GACjC,CAAC,CAAC,CAAC,CAAC;AAEV;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,SAAS,MAAM,EAAE,IAC9D,KAAK,SAAS;IACZ,MAAM,IAAI,SAAS,MAAM;IACzB,GAAG,MAAM,IAAI,SAAS,SAAS,MAAM,EAAE;CACxC,GACG,cAAc,CAAC,IAAI,CAAC,SAAS,KAAK,GAChC,KAAK,GACL,oBAAoB,CAAC,IAAI,CAAC,GAC5B,KAAK,CAAC;AAEZ;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IACjD,oBAAoB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,GAAG,CAAC,CAAC"}

package/src/types/canonical-name.ts

@@ -0,0 +1,151 @@
+/**
+ * Fairly exhaustive, excruciatingly pedantic _type-level_ helpers for
+ * representing and validating **Canonical Names** and npm package names.
+ *
+ * A {@link CanonicalName | Canonical Name} is a string containing one or more
+ * npm package names (scoped or unscoped) delimited by a `>` character.
+ *
+ * The following rules about npm package names are enforced:
+ *
+ * - ✅ Length > 0
+ * - ✅ Can contain hyphens
+ * - ✅ No leading `.` or `_`
+ * - ✅ No spaces
+ * - ✅ No `~)('!*` characters
+ *
+ * The following rules are not enforced:
+ *
+ * - ❌ All lowercase - Not feasible due to recursion limits & legacy package
+ *   names
+ * - ❌ Not a reserved name - unmaintainable list of node builtin module names
+ * - ❌ Length ≤ 214 - Not feasible due to recursion limits & legacy package
+ *   names
+ *
+ * "Legacy" package names may contain uppercase letters and be longer than 214
+ * characters.
+ *
+ * @module
+ * @see {@link https://www.npmjs.com/package/validate-npm-package-name}
+ */
+
+/**
+ * Characters that are explicitly forbidden in npm package names. These include:
+ * ` `, `~`, `)`, `(`, `'`, `!`, `*`
+ *
+ * We check each one individually because TypeScript's template literal types
+ * can detect if a string contains a specific substring.
+ *
+ * Returns `true` if the string contains a forbidden character, `false`
+ * otherwise.
+ */
+type ContainsForbiddenChar<S extends string> = S extends
+  | `${string} ${string}`
+  | `${string}~${string}`
+  | `${string})${string}`
+  | `${string}(${string}`
+  | `${string}'${string}`
+  | `${string}!${string}`
+  | `${string}*${string}`
+  ? true
+  : false;
+
+/**
+ * Validates that a string doesn't start with `.` or `_`.
+ *
+ * Returns `true` if the string doesn't start with `.` or `_`, `false`
+ * otherwise.
+ */
+type HasValidStart<S extends string> = S extends `.${string}` | `_${string}`
+  ? false
+  : true;
+
+/**
+ * Validates that a string is non-empty.
+ *
+ * Returns `true` if the string is non-empty, `false` otherwise.
+ */
+type IsNonEmpty<S extends string> = S extends '' ? false : true;
+
+/**
+ * Combines all validation checks for a package name segment.
+ *
+ * Returns `true` if the string passes all checks, `false` otherwise.
+ */
+type IsValidPackageNameSegment<S extends string> =
+  IsNonEmpty<S> extends false
+    ? false
+    : HasValidStart<S> extends false
+      ? false
+      : ContainsForbiddenChar<S> extends true
+        ? false
+        : true;
+
+// ============================================================================
+// Scoped and Unscoped Package Names
+// ============================================================================
+
+/** A scoped npm package name, like "@scope/pkg" */
+export type ScopedPackageName<S extends string = string> =
+  S extends `@${infer Scope}/${infer Name}`
+    ? IsValidPackageNameSegment<Scope> extends true
+      ? IsValidPackageNameSegment<Name> extends true
+        ? S
+        : never
+      : never
+    : never;
+
+/**
+ * An unscoped npm package name.
+ *
+ * Must pass all validation checks and must not contain a `/` (which would
+ * indicate a scoped package or a subpath).
+ *
+ * Note: Package names containing uppercase letters are technically invalid per
+ * npm rules, but they exist in the wild. TypeScript cannot reliably validate
+ * case at the type level, so we don't enforce this.
+ */
+export type UnscopedPackageName<S extends string = string> =
+  S extends `${string}/${string}`
+    ? never
+    : IsValidPackageNameSegment<S> extends true
+      ? S
+      : never;
+
+/**
+ * A scoped or unscoped npm package name.
+ */
+export type NpmPackageName<S extends string = string> =
+  S extends `@${string}/${string}`
+    ? ScopedPackageName<S>
+    : UnscopedPackageName<S>;
+
+/**
+ * Split a string on `>`—the canonical name delimiter—into a tuple of segments.
+ */
+export type SplitOnDelimiter<S extends string> =
+  S extends `${infer Head}>${infer Tail}`
+    ? [Head, ...SplitOnDelimiter<Tail>]
+    : [S];
+
+/**
+ * Validate that every element in a tuple of strings is a valid npm package
+ * name.
+ */
+export type AllValidPackageNames<Parts extends readonly string[]> =
+  Parts extends [
+    infer Head extends string,
+    ...infer Tail extends readonly string[],
+  ]
+    ? NpmPackageName<Head> extends never
+      ? never
+      : AllValidPackageNames<Tail>
+    : Parts;
+
+/**
+ * A Canonical Name string comprised of one or more npm package names separated
+ * by `>` (e.g., `foo`, `@scope/foo>bar`, `foo>@scope/bar>baz`).
+ *
+ * When given a string literal type, invalid shapes narrow to `never`.
+ */
+export type CanonicalName<S extends string = string> =
+  AllValidPackageNames<SplitOnDelimiter<S>> extends never ? never : S;