@endo/compartment-mapper 1.3.1 → 1.5.0

package/src/types/internal.ts

@@ -0,0 +1,217 @@
+/**
+ * @module Internal types of the compartment mapper that need not be visible to
+ * consumers.
+ */
+
+/* eslint-disable no-use-before-define */
+
+import type { ImportHook, ImportNowHook } from 'ses';
+import type {
+  CompartmentDescriptor,
+  Language,
+  LanguageForExtension,
+  LanguageForModuleSpecifier,
+  ModuleDescriptor,
+} from './compartment-map-schema.js';
+import type {
+  HashFn,
+  MaybeReadFn,
+  MaybeReadNowFn,
+  ReadFn,
+  ReadPowers,
+} from './powers.js';
+import type { DeferredAttenuatorsProvider } from './policy.js';
+import type {
+  AsyncParseFn,
+  CompartmentSources,
+  ExecuteOptions,
+  ExitModuleImportNowHook,
+  ModuleTransforms,
+  ParseFn,
+  ParserForLanguage,
+  SearchSuffixesOption,
+  SourceMapHook,
+  SourceMapHookOption,
+  Sources,
+  SyncModuleTransforms,
+} from './external.js';
+
+export type LinkOptions = {
+  resolve?: ResolveHook;
+  makeImportHook: ImportHookMaker;
+  makeImportNowHook?: ImportNowHookMaker;
+  parserForLanguage?: ParserForLanguage;
+  moduleTransforms?: ModuleTransforms;
+  syncModuleTransforms?: SyncModuleTransforms;
+  archiveOnly?: boolean;
+  __native__?: boolean;
+} & ExecuteOptions;
+
+export type LinkResult = {
+  compartment: Compartment;
+  compartments: Record<string, Compartment>;
+  attenuatorsCompartment: Compartment;
+  pendingJobsPromise: Promise<void>;
+};
+
+export type ResolveHook = (
+  importSpecifier: string,
+  referrerSpecifier: string,
+) => string;
+
+export type ShouldDeferError = (language: Language | undefined) => boolean;
+
+export type MakeImportNowHookMakerOptions = Partial<{
+  sources: Sources;
+  compartmentDescriptors: Record<string, CompartmentDescriptor>;
+  computeSha512: HashFn;
+  exitModuleImportNowHook: ExitModuleImportNowHook;
+}> &
+  SearchSuffixesOption &
+  SourceMapHookOption;
+
+export type ImportHookMaker = (params: {
+  packageLocation: string;
+  packageName: string;
+  attenuators: DeferredAttenuatorsProvider;
+  parse: ParseFn | AsyncParseFn;
+  shouldDeferError: ShouldDeferError;
+  compartments: Record<string, Compartment>;
+}) => ImportHook;
+
+export type ImportNowHookMaker = (params: {
+  packageLocation: string;
+  packageName: string;
+  parse: ParseFn | AsyncParseFn;
+  compartments: Record<string, Compartment>;
+  // Unlike analogous prameters of ImportHookMaker, the Compartment Mapper
+  // ignores these two parameters, so they are expressly disallowed to avoid
+  // confusion about whether they would be respected.
+  attenuators?: never;
+  shouldDeferError?: never;
+}) => ImportNowHook;
+
+/**
+ * The value returned by `makeMapParsers()`
+ */
+export type MapParsersFn<ParseT = AsyncParseFn | ParseFn> = (
+  /** Mapping from file extension to Language (like `js` to `mjs`). */
+  languageForExtension: LanguageForExtension,
+  /** Mapping from module specifier to Language. */
+  languageForModuleSpecifier: LanguageForModuleSpecifier,
+) => ParseT;
+
+/**
+ * As used in `import-hook.js`
+ */
+export type ChooseModuleDescriptorParams = {
+  /** Module specifiers with each search suffix appended */
+  candidates: string[];
+  moduleSpecifier: string;
+  packageLocation: string;
+  /** Compartment descriptor from the compartment map */
+  compartmentDescriptor: CompartmentDescriptor;
+  /** All compartment descriptors from the compartment map */
+  compartmentDescriptors: Record<string, CompartmentDescriptor>;
+  /** All module descriptors in same compartment */
+  moduleDescriptors: Record<string, ModuleDescriptor>;
+  /** All compartments */
+  compartments: Record<string, Compartment>;
+  packageSources: CompartmentSources;
+  /** Function to compute SHA-512 hash */
+  computeSha512?: HashFn;
+  readPowers: ReadPowers | ReadFn;
+  sourceMapHook?: SourceMapHook;
+  /**
+   * Function returning a set of module names (scoped to the compartment) whose
+   * parser is not using heuristics to determine imports.
+   */
+  strictlyRequiredForCompartment: (compartmentName: string) => Set<string>;
+};
+
+type SyncChooseModuleDescriptorOperators = {
+  /**
+   * A function that reads a file, returning its binary contents _or_
+   * `undefined` if the file is not found
+   */
+  maybeRead: MaybeReadNowFn;
+  /**
+   * A function that parses the (defined) binary contents from `maybeRad` into
+   * a `ParseResult`
+   */
+  parse: ParseFn;
+  /** Should be omitted */
+  shouldDeferError?: never;
+};
+
+/**
+ * Operators for `chooseModuleDescriptor` representing asynchronous operation.
+ */
+export type AsyncChooseModuleDescriptorOperators = {
+  /**
+   * A function that reads a file, resolving with its binary contents _or_
+   * `undefined` if the file is not found
+   */
+  maybeRead: MaybeReadFn;
+  /**
+   * A function that parses the (defined) binary contents from `maybeRead` into
+   * a `ParseResult`
+   */
+  parse: AsyncParseFn | ParseFn;
+  /**
+   * A function that returns `true` if the language returned by `parse` should
+   * defer errors.
+   */
+  shouldDeferError: (language: Language) => boolean;
+};
+
+/**
+ * Either synchronous or asynchronous operators for `chooseModuleDescriptor`.
+ */
+export type ChooseModuleDescriptorOperators =
+  | AsyncChooseModuleDescriptorOperators
+  | SyncChooseModuleDescriptorOperators;
+
+/**
+ * The agglomeration of things that the `chooseModuleDescriptor` generator can
+ * yield.
+ *
+ * The generator does not necessarily yield _all_ of these; it depends on
+ * whether the operators are {@link AsyncChooseModuleDescriptorOperators} or
+ * {@link SyncChooseModuleDescriptorOperators}.
+ */
+export type ChooseModuleDescriptorYieldables =
+  | ReturnType<ChooseModuleDescriptorOperators['maybeRead']>
+  | ReturnType<ChooseModuleDescriptorOperators['parse']>;
+
+/**
+ * Parameters for `findRedirect()`.
+ */
+export type FindRedirectParams = {
+  compartmentDescriptor: CompartmentDescriptor;
+  compartmentDescriptors: Record<string, CompartmentDescriptor>;
+  compartments: Record<string, Compartment>;
+  /* A module specifier which is an absolute path. NOT a `file://` URL. */
+  absoluteModuleSpecifier: string;
+  /** Location of the compartment descriptor's package. */
+  packageLocation: string;
+};
+
+/**
+ * Options for `makeMapParsers()`
+ */
+export type MakeMapParsersOptions = {
+  /** Mapping of language to `ParserImplementation` */
+  parserForLanguage: ParserForLanguage;
+  /**
+   * Async or sync module transforms.
+   * If non-empty, synchronous import (specifically dynamic `require` in
+   * CommonJS or `compartment.importNow`) are unsupported.
+   */
+  moduleTransforms?: ModuleTransforms;
+  /**
+   * Sync module transforms.
+   * Always supported.
+   */
+  syncModuleTransforms?: SyncModuleTransforms;
+};

package/src/types/node-powers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module These interfaces describe the powers needed in `node-powers.js` to
+ * adapt host capabilities for the compartment mapper.
+ */
+/** For creating `ReadPowers` */
+export type FsInterface = {
+    promises: {
+        realpath: (filepath: string) => Promise<string>;
+        writeFile: (location: string, bytes: Uint8Array) => Promise<void>;
+        readFile: (location: string) => Promise<Uint8Array>;
+    };
+    readFileSync: (location: string) => Uint8Array;
+};
+/**
+ * The portion of the "node:url" module needed to normalize paths to fully
+ * qualified file URLs, as used by the compartment mapper internally.
+ */
+export type UrlInterface = {
+    fileURLToPath: (location: string | URL) => string;
+    pathToFileURL: (location: string) => URL;
+};
+/**
+ * The portion of the "node:path" module needed to support dynamic-require for
+ * a module specifier that is an absolute path.
+ */
+export type PathInterface = {
+    isAbsolute: (location: string) => boolean;
+};
+/**
+ * The portion of the "node:crypto" module needed for generating and verifying
+ * integrity hashes, optionally consumed to make "read powers".
+ */
+export type CryptoInterface = {
+    createHash: (algorithm: 'sha512') => Hash;
+};
+/**
+ * Object returned by function in `CryptoInterface`
+ */
+type Hash = {
+    update: (data: Uint8Array | string) => Hash;
+    digest: () => {
+        toString: (radix: 'hex') => string;
+    };
+};
+export {};
+//# sourceMappingURL=node-powers.d.ts.map

package/src/types/node-powers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-powers.d.ts","sourceRoot":"","sources":["node-powers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,gCAAgC;AAChC,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE;QACR,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;QAChD,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QAClE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;KACrD,CAAC;IACF,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,CAAC;CAChD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,KAAK,MAAM,CAAC;IAClD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,GAAG,CAAC;CAC1C,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3C,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,CAAC,SAAS,EAAE,QAAQ,KAAK,IAAI,CAAC;CAC3C,CAAC;AAEF;;GAEG;AACH,KAAK,IAAI,GAAG;IACV,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,KAAK,IAAI,CAAC;IAC5C,MAAM,EAAE,MAAM;QAEZ,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;KACpC,CAAC;CACH,CAAC"}

package/src/types/node-powers.ts

@@ -0,0 +1,52 @@
+/**
+ * @module These interfaces describe the powers needed in `node-powers.js` to
+ * adapt host capabilities for the compartment mapper.
+ */
+
+/* eslint-disable no-use-before-define */
+
+/** For creating `ReadPowers` */
+export type FsInterface = {
+  promises: {
+    realpath: (filepath: string) => Promise<string>;
+    writeFile: (location: string, bytes: Uint8Array) => Promise<void>;
+    readFile: (location: string) => Promise<Uint8Array>;
+  };
+  readFileSync: (location: string) => Uint8Array;
+};
+
+/**
+ * The portion of the "node:url" module needed to normalize paths to fully
+ * qualified file URLs, as used by the compartment mapper internally.
+ */
+export type UrlInterface = {
+  fileURLToPath: (location: string | URL) => string;
+  pathToFileURL: (location: string) => URL;
+};
+
+/**
+ * The portion of the "node:path" module needed to support dynamic-require for
+ * a module specifier that is an absolute path.
+ */
+export type PathInterface = {
+  isAbsolute: (location: string) => boolean;
+};
+
+/**
+ * The portion of the "node:crypto" module needed for generating and verifying
+ * integrity hashes, optionally consumed to make "read powers".
+ */
+export type CryptoInterface = {
+  createHash: (algorithm: 'sha512') => Hash;
+};
+
+/**
+ * Object returned by function in `CryptoInterface`
+ */
+type Hash = {
+  update: (data: Uint8Array | string) => Hash;
+  digest: () => {
+    // This is the exact subset of Node.js Buffer that we need.
+    toString: (radix: 'hex') => string;
+  };
+};

package/src/types/policy-schema.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module Describes the portion of a compartment map dedicated to narrowing
+ * or attenuating the powers available to each compartment.
+ */
+/**
+ * An object representing a full attenuation definition.
+ */
+export type FullAttenuationDefinition = {
+    /** The type of attenuation. */
+    attenuate: string;
+    /** The parameters for the attenuation. */
+    params: ImplicitAttenuationDefinition;
+};
+/**
+ * An array of any type representing an implicit attenuation definition.
+ */
+export type ImplicitAttenuationDefinition = [any, ...any[]];
+/**
+ * A type representing an attenuation definition, which can be either a full or
+ * implicit definition.
+ */
+export type AttenuationDefinition = FullAttenuationDefinition | ImplicitAttenuationDefinition;
+export type UnifiedAttenuationDefinition = {
+    displayName: string;
+    specifier: string | null;
+    params?: any[] | undefined;
+};
+/**
+ * A type representing a wildcard policy, which can be 'any'.
+ */
+export type WildcardPolicy = 'any';
+/**
+ * A type representing a property policy, which is a record of string keys and
+ * boolean values
+ */
+export type PropertyPolicy = Record<string, boolean>;
+/**
+ * A type representing a policy item, which can be a {@link WildcardPolicy
+ * wildcard policy}, a property policy, `undefined`, or defined by an
+ * attenuator
+ */
+export type PolicyItem<T = void> = WildcardPolicy | PropertyPolicy | T;
+/**
+ * An object representing a nested attenuation definition.
+ */
+export type NestedAttenuationDefinition = Record<string, AttenuationDefinition | boolean>;
+/**
+ * An object representing a base package policy.
+ */
+export type PackagePolicy<PackagePolicyItem = void, GlobalsPolicyItem = void, BuiltinsPolicyItem = void, ExtraOptions = unknown> = {
+    /** The default attenuator. */
+    defaultAttenuator?: string | undefined;
+    /** The policy item for packages. */
+    packages?: PolicyItem<PackagePolicyItem> | undefined;
+    /** The policy item or full attenuation definition for globals. */
+    globals?: AttenuationDefinition | PolicyItem<GlobalsPolicyItem> | undefined;
+    /** The policy item or nested attenuation definition for builtins. */
+    builtins?: NestedAttenuationDefinition | PolicyItem<BuiltinsPolicyItem> | undefined;
+    /** Whether to disable global freeze. */
+    noGlobalFreeze?: boolean | undefined;
+    /** Whether to allow dynamic imports */
+    dynamic?: boolean | undefined;
+    /** Any additional user-defined options can be added to the policy here */
+    options?: ExtraOptions | undefined;
+};
+/**
+ * An object representing a base policy.
+ */
+export type Policy<PackagePolicyItem = void, GlobalsPolicyItem = void, BuiltinsPolicyItem = void, ExtraOptions = unknown> = {
+    /** The package policies for the resources. */
+    resources: Record<string, PackagePolicy<PackagePolicyItem, GlobalsPolicyItem, BuiltinsPolicyItem, ExtraOptions>>;
+    /** The default attenuator. */
+    defaultAttenuator?: string | undefined;
+    /** The package policy for the entry. */
+    entry?: PackagePolicy<PackagePolicyItem, GlobalsPolicyItem, BuiltinsPolicyItem, ExtraOptions> | undefined;
+};
+/** Any {@link Policy} */
+export type SomePolicy = Policy<any, any, any, any>;
+/** Any {@link PackagePolicy} */
+export type SomePackagePolicy = PackagePolicy<PolicyItem, PolicyItem, PolicyItem, unknown>;
+//# sourceMappingURL=policy-schema.d.ts.map

package/src/types/policy-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-schema.d.ts","sourceRoot":"","sources":["policy-schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,MAAM,EAAE,6BAA6B,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAC7B,yBAAyB,GACzB,6BAA6B,CAAC;AAClC,MAAM,MAAM,4BAA4B,GAAG;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC;AAEnC;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,IAAI,IAAI,cAAc,GAAG,cAAc,GAAG,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC9C,MAAM,EACN,qBAAqB,GAAG,OAAO,CAChC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,CACvB,iBAAiB,GAAG,IAAI,EACxB,iBAAiB,GAAG,IAAI,EACxB,kBAAkB,GAAG,IAAI,EACzB,YAAY,GAAG,OAAO,IACpB;IACF,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,oCAAoC;IACpC,QAAQ,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,GAAG,SAAS,CAAC;IACrD,kEAAkE;IAClE,OAAO,CAAC,EAAE,qBAAqB,GAAG,UAAU,CAAC,iBAAiB,CAAC,GAAG,SAAS,CAAC;IAC5E,qEAAqE;IACrE,QAAQ,CAAC,EACL,2BAA2B,GAC3B,UAAU,CAAC,kBAAkB,CAAC,GAC9B,SAAS,CAAC;IACd,wCAAwC;IACxC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,MAAM,CAChB,iBAAiB,GAAG,IAAI,EACxB,iBAAiB,GAAG,IAAI,EACxB,kBAAkB,GAAG,IAAI,EACzB,YAAY,GAAG,OAAO,IACpB;IACF,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CACf,MAAM,EACN,aAAa,CACX,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,CACb,CACF,CAAC;IACF,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,wCAAwC;IACxC,KAAK,CAAC,EACF,aAAa,CACX,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,CACb,GACD,SAAS,CAAC;CACf,CAAC;AAEF,yBAAyB;AACzB,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAEpD,gCAAgC;AAChC,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAC3C,UAAU,EACV,UAAU,EACV,UAAU,EACV,OAAO,CACR,CAAC"}

package/src/types/policy-schema.ts

@@ -0,0 +1,131 @@
+/**
+ * @module Describes the portion of a compartment map dedicated to narrowing
+ * or attenuating the powers available to each compartment.
+ */
+
+/* eslint-disable no-use-before-define */
+
+/**
+ * An object representing a full attenuation definition.
+ */
+export type FullAttenuationDefinition = {
+  /** The type of attenuation. */
+  attenuate: string;
+  /** The parameters for the attenuation. */
+  params: ImplicitAttenuationDefinition;
+};
+
+/**
+ * An array of any type representing an implicit attenuation definition.
+ */
+export type ImplicitAttenuationDefinition = [any, ...any[]];
+
+/**
+ * A type representing an attenuation definition, which can be either a full or
+ * implicit definition.
+ */
+export type AttenuationDefinition =
+  | FullAttenuationDefinition
+  | ImplicitAttenuationDefinition;
+export type UnifiedAttenuationDefinition = {
+  displayName: string;
+  specifier: string | null;
+  params?: any[] | undefined;
+};
+
+/**
+ * A type representing a wildcard policy, which can be 'any'.
+ */
+export type WildcardPolicy = 'any';
+
+/**
+ * A type representing a property policy, which is a record of string keys and
+ * boolean values
+ */
+export type PropertyPolicy = Record<string, boolean>;
+
+/**
+ * A type representing a policy item, which can be a {@link WildcardPolicy
+ * wildcard policy}, a property policy, `undefined`, or defined by an
+ * attenuator
+ */
+export type PolicyItem<T = void> = WildcardPolicy | PropertyPolicy | T;
+
+/**
+ * An object representing a nested attenuation definition.
+ */
+export type NestedAttenuationDefinition = Record<
+  string,
+  AttenuationDefinition | boolean
+>;
+
+/**
+ * An object representing a base package policy.
+ */
+export type PackagePolicy<
+  PackagePolicyItem = void,
+  GlobalsPolicyItem = void,
+  BuiltinsPolicyItem = void,
+  ExtraOptions = unknown,
+> = {
+  /** The default attenuator. */
+  defaultAttenuator?: string | undefined;
+  /** The policy item for packages. */
+  packages?: PolicyItem<PackagePolicyItem> | undefined;
+  /** The policy item or full attenuation definition for globals. */
+  globals?: AttenuationDefinition | PolicyItem<GlobalsPolicyItem> | undefined;
+  /** The policy item or nested attenuation definition for builtins. */
+  builtins?:
+    | NestedAttenuationDefinition
+    | PolicyItem<BuiltinsPolicyItem>
+    | undefined;
+  /** Whether to disable global freeze. */
+  noGlobalFreeze?: boolean | undefined;
+  /** Whether to allow dynamic imports */
+  dynamic?: boolean | undefined;
+  /** Any additional user-defined options can be added to the policy here */
+  options?: ExtraOptions | undefined;
+};
+
+/**
+ * An object representing a base policy.
+ */
+export type Policy<
+  PackagePolicyItem = void,
+  GlobalsPolicyItem = void,
+  BuiltinsPolicyItem = void,
+  ExtraOptions = unknown,
+> = {
+  /** The package policies for the resources. */
+  resources: Record<
+    string,
+    PackagePolicy<
+      PackagePolicyItem,
+      GlobalsPolicyItem,
+      BuiltinsPolicyItem,
+      ExtraOptions
+    >
+  >;
+  /** The default attenuator. */
+  defaultAttenuator?: string | undefined;
+  /** The package policy for the entry. */
+  entry?:
+    | PackagePolicy<
+        PackagePolicyItem,
+        GlobalsPolicyItem,
+        BuiltinsPolicyItem,
+        ExtraOptions
+      >
+    | undefined;
+};
+
+/** Any {@link Policy} */
+export type SomePolicy = Policy<any, any, any, any>;
+
+/** Any {@link PackagePolicy} */
+export type SomePackagePolicy = PackagePolicy<
+  PolicyItem,
+  PolicyItem,
+  PolicyItem,
+  unknown
+>;

package/src/types/policy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module Types required for policy enforcement.
+ */
+import type { SomeObject } from './typescript.js';
+export type PackageNamingKit = {
+    /** true if location is the entry compartment */
+    isEntry?: boolean | undefined;
+    name: string;
+    path: Array<string>;
+};
+export type Attenuator<GlobalParams extends [any, ...any[]] = [any, ...any[]], ModuleParams extends [any, ...any[]] = [any, ...any[]]> = {
+    attenuateGlobals?: GlobalAttenuatorFn<GlobalParams> | undefined;
+    attenuateModule?: ModuleAttenuatorFn<ModuleParams, SomeObject, SomeObject> | undefined;
+};
+export type GlobalAttenuatorFn<Params extends [any, ...any[]] = [any, ...any[]]> = (params: Params, originalObject: Record<PropertyKey, any>, globalThis: Record<PropertyKey, any>) => void;
+export type ModuleAttenuatorFn<Params extends [any, ...any[]] = [any, ...any[]], T = SomeObject, U = T> = (params: Params, ns: T) => U;
+export type DeferredAttenuatorsProvider = {
+    import: (attenuatorSpecifier: string | null) => Promise<Attenuator>;
+};
+//# sourceMappingURL=policy.d.ts.map

package/src/types/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["policy.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,UAAU,CACpB,YAAY,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,EACtD,YAAY,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,IACpD;IACF,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;IAChE,eAAe,CAAC,EACZ,kBAAkB,CAAC,YAAY,EAAE,UAAU,EAAE,UAAU,CAAC,GACxD,SAAS,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAC5B,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,IAC9C,CACF,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,EACxC,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,KACjC,IAAI,CAAC;AAEV,MAAM,MAAM,kBAAkB,CAC5B,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,EAChD,CAAC,GAAG,UAAU,EACd,CAAC,GAAG,CAAC,IACH,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;AAEjC,MAAM,MAAM,2BAA2B,GAAG;IACxC,MAAM,EAAE,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACrE,CAAC"}

package/src/types/policy.ts

@@ -0,0 +1,42 @@
+/**
+ * @module Types required for policy enforcement.
+ */
+
+/* eslint-disable no-use-before-define */
+
+import type { SomeObject } from './typescript.js';
+
+export type PackageNamingKit = {
+  /** true if location is the entry compartment */
+  isEntry?: boolean | undefined;
+  name: string;
+  path: Array<string>;
+};
+
+export type Attenuator<
+  GlobalParams extends [any, ...any[]] = [any, ...any[]],
+  ModuleParams extends [any, ...any[]] = [any, ...any[]],
+> = {
+  attenuateGlobals?: GlobalAttenuatorFn<GlobalParams> | undefined;
+  attenuateModule?:
+    | ModuleAttenuatorFn<ModuleParams, SomeObject, SomeObject>
+    | undefined;
+};
+
+export type GlobalAttenuatorFn<
+  Params extends [any, ...any[]] = [any, ...any[]],
+> = (
+  params: Params,
+  originalObject: Record<PropertyKey, any>,
+  globalThis: Record<PropertyKey, any>,
+) => void;
+
+export type ModuleAttenuatorFn<
+  Params extends [any, ...any[]] = [any, ...any[]],
+  T = SomeObject,
+  U = T,
+> = (params: Params, ns: T) => U;
+
+export type DeferredAttenuatorsProvider = {
+  import: (attenuatorSpecifier: string | null) => Promise<Attenuator>;
+};

package/src/types/powers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module The compartment mapper requires certain host capabilities.
+ * These are the platform-neutral types for those capabilities.
+ * For example, {@file node-powers.js} adapts Node.js how modules
+ * to various subsets of these capabilities.
+ */
+import type { SomeObject } from './typescript.js';
+export type ReadPowers = {
+    canonical: CanonicalFn;
+    read: ReadFn;
+    maybeRead?: MaybeReadFn;
+    readNow?: ReadNowFn;
+    maybeReadNow?: MaybeReadNowFn;
+    computeSha512?: HashFn;
+    fileURLToPath?: FileURLToPathFn;
+    pathToFileURL?: PathToFileURLFn;
+    requireResolve?: RequireResolveFn;
+    isAbsolute?: IsAbsoluteFn;
+};
+export type MaybeReadPowers = ReadPowers & {
+    maybeRead: MaybeReadFn;
+};
+/**
+ * The extension of {@link ReadPowers} necessary for dynamic require support
+ *
+ * For a `ReadPowers` to be a `ReadNowPowers`:
+ *
+ * 1. It must be an object (not a {@link ReadFn})
+ * 2. Prop `maybeReadNow` is a function
+ * 3. Prop `fileURLToPath` is a function
+ * 4. Prop `isAbsolute` is a function
+ */
+export type ReadNowPowers = Omit<ReadPowers, ReadNowPowersProp> & Required<Pick<ReadPowers, ReadNowPowersProp>>;
+/**
+ * These properties are necessary for dynamic require support
+ */
+export type ReadNowPowersProp = 'fileURLToPath' | 'isAbsolute' | 'maybeReadNow';
+/**
+ * Returns a canonical URL for a given URL, following redirects or symbolic
+ * links if any exist along the path.
+ * Must return the given logical location if the real location does not exist.
+ */
+export type CanonicalFn = (location: string) => Promise<string>;
+export type ReadFn = (location: string) => Promise<Uint8Array>;
+/**
+ * A resolution of `undefined` indicates `ENOENT` or the equivalent.
+ */
+export type MaybeReadFn = (location: string) => Promise<Uint8Array | undefined>;
+export type ReadNowFn = (location: string) => Uint8Array;
+/**
+ * A resolution of `undefined` indicates `ENOENT` or the equivalent.
+ */
+export type MaybeReadNowFn = (location: string) => Uint8Array | undefined;
+export type HashFn = (bytes: Uint8Array) => string;
+export type FileURLToPathFn = (location: string | URL) => string;
+export type PathToFileURLFn = (location: string) => URL;
+export type RequireResolveFn = (fromLocation: string, specifier: string, options?: {
+    paths?: string[];
+} | undefined) => any;
+export type IsAbsoluteFn = (location: string) => boolean;
+export type ArchiveReader = {
+    read: ReadFn;
+};
+export type HashPowers = {
+    read: ReadFn;
+    canonical: CanonicalFn;
+    computeSha512: HashFn;
+};
+export type WritePowers = {
+    write: WriteFn;
+};
+export type WriteFn = (location: string, bytes: Uint8Array) => Promise<void>;
+export type ArchiveWriter = {
+    write: WriteFn;
+    snapshot: SnapshotFn;
+};
+export type SnapshotFn = () => Promise<Uint8Array>;
+export type Application = {
+    import: ExecuteFn;
+    sha512?: string | undefined;
+};
+export type ExecuteFn = (options?: any) => Promise<SomeObject>;
+//# sourceMappingURL=powers.d.ts.map