policy-generator.js

import { createModuleInspector } from 'lavamoat-core'
import { isBuiltin as nodeIsBuiltin } from 'node:module'
import { PolicyGeneratorContext } from '../policy-gen/policy-generator-context.js'
import { defaultReadPower } from '../power.js'
import { LMRCache } from './lmr-cache.js'

const { entries } = Object

/**
 * Options for {@link PolicyGenerator} and {@link PolicyGenerator.generatePolicy}
 *
 * @typedef PolicyGeneratorOptions
 * @property {import('@endo/compartment-mapper').ReadFn} [read]
 * @property {import('lavamoat-core').LavaMoatPolicyOverrides} [policyOverride]
 */

/**
 * Service which generates a LavaMoat policy from a
 */
export class PolicyGenerator {
  /**
   * Cache of `LavamoatModuleRecord` objects
   *
   * @type {Readonly<LMRCache>}
   */
  #lmrCache

  /**
   * Creates {@link PolicyGeneratorContext} instances for each compartment in
   * `compartmentMap`.
   *
   * @param {Readonly<
   *   import('@endo/compartment-mapper').CompartmentMapDescriptor
   * >} compartmentMap
   * @param {Readonly<import('@endo/compartment-mapper').Sources>} sources
   * @param {Readonly<Record<string, string>>} renames
   * @param {PolicyGeneratorOptions} opts
   */
  constructor(
    compartmentMap,
    sources,
    renames,
    { read = defaultReadPower, policyOverride } = {}
  ) {
    /**
     * Compartment sources
     *
     * @type {Readonly<import('@endo/compartment-mapper').Sources>}
     * @internal
     */
    this.sources = sources

    /**
     * Compartment map
     *
     * @type {Readonly<
     *   import('@endo/compartment-mapper').CompartmentMapDescriptor
     * >}
     * @internal
     */
    this.compartmentMap = compartmentMap

    /**
     * Cache of `LavamoatModuleRecord` objects
     */
    this.#lmrCache = new LMRCache()

    const entryCompartment =
      compartmentMap.compartments[compartmentMap.entry.compartment]

    /**
     * Mapping of compartment names to {@link PolicyGeneratorContext} instances
     *
     * @type {Readonly<Map<string, PolicyGeneratorContext>>}
     * @internal
     */
    this.contexts = new Map(
      entries(compartmentMap.compartments).map(
        ([compartmentName, compartment]) => [
          compartmentName,
          new PolicyGeneratorContext(compartment, renames, this.#lmrCache, {
            isEntry: entryCompartment === compartment,
            readFn: read,
          }),
        ]
      )
    )

    /**
     * Override policy, if any
     *
     * @type {Readonly<
     *   import('lavamoat-core').LavaMoatPolicyOverrides | undefined
     * >}
     * @internal
     */
    this.policyOverride = policyOverride
  }

  /**
   * Builds `LavamoatModuleRecord` objects from the `CompartmentMapDescriptor`
   *
   * @returns {Promise<import('lavamoat-core').LavamoatModuleRecord[]>} Module
   *   records
   * @internal
   */
  async buildModuleRecords() {
    await Promise.resolve()

    let moduleRecords =
      /** @type {import('lavamoat-core').LavamoatModuleRecord[]} */ (
        (
          await Promise.all(
            entries(this.sources).map(
              async ([compartmentName, compartmentSources]) => {
                if (!this.contexts.has(compartmentName)) {
                  // this means that the compartment with this name was not actually used
                  return
                }

                const compartment = /** @type {PolicyGeneratorContext} */ (
                  this.contexts.get(compartmentName)
                )

                return compartment.buildModuleRecords(compartmentSources)
              }
            )
          )
        )
          .flat()
          .filter(Boolean)
      )

    moduleRecords = [...new Set(moduleRecords)]

    this.#lmrCache.clear()

    return moduleRecords
  }

  /**
   * Uses `inspector` to inspect a compartment map and sources.
   *
   * @param {import('lavamoat-core').ModuleInspector} inspector Module inspector
   * @param {import('lavamoat-core').LavamoatModuleRecord[]} moduleRecords
   *   Module records
   * @returns {import('lavamoat-core').ModuleInspector} The inspector
   * @internal
   */
  inspectModuleRecords(inspector, moduleRecords) {
    // FIXME: should we sort here?
    for (const record of moduleRecords) {
      inspector.inspectModule(record)
    }

    return inspector
  }

  /**
   * Generates a LavaMoat policy
   *
   * Policy generation occurs in three (3) steps:
   *
   * 1. Build module records from the `CompartmentMapDescriptor` and associated
   *    `Sources`
   * 2. Inspect the module records using LavaMoat's `ModuleInspector`
   * 3. Generate the policy using the `ModuleInspector`
   *
   * @param {boolean} [debug] - If `true`, the result will be a debug policy
   * @returns {Promise<
   *   | import('lavamoat-core').LavaMoatPolicy
   *   | import('lavamoat-core').LavaMoatPolicyDebug
   * >}
   *   Generated policy
   * @internal
   * @todo Overload this to handle the `debug` parameter
   */
  async generatePolicy(debug) {
    const moduleRecords = await this.buildModuleRecords()

    const inspector = createModuleInspector({
      isBuiltin: nodeIsBuiltin,
      includeDebugInfo: debug,
    })

    return this.inspectModuleRecords(inspector, moduleRecords).generatePolicy({
      policyOverride: this.policyOverride,
    })
  }

  /**
   * Instantiates a {@link PolicyGenerator} and generates a policy.
   *
   * @overload
   * @param {Readonly<
   *   import('@endo/compartment-mapper').CompartmentMapDescriptor
   * >} compartmentMap
   * @param {Readonly<import('@endo/compartment-mapper').Sources>} sources
   * @param {Readonly<Record<string, string>>} renames
   * @param {PolicyGeneratorOptions} [opts]
   * @returns {Promise<import('lavamoat-core').LavaMoatPolicy>} Generated policy
   */

  /**
   * Instantiates a {@link PolicyGenerator} and generates a debug policy.
   *
   * @overload
   * @param {Readonly<
   *   import('@endo/compartment-mapper').CompartmentMapDescriptor
   * >} compartmentMap
   * @param {Readonly<import('@endo/compartment-mapper').Sources>} sources
   * @param {Readonly<Record<string, string>>} renames
   * @param {PolicyGeneratorOptions & { debug: true }} opts
   * @returns {Promise<import('lavamoat-core').LavaMoatPolicyDebug>} Generated
   *   debug policy
   * @public
   */

  /**
   * Instantiates a {@link PolicyGenerator} and generates a policy.
   *
   * @param {Readonly<
   *   import('@endo/compartment-mapper').CompartmentMapDescriptor
   * >} compartmentMap
   * @param {Readonly<import('@endo/compartment-mapper').Sources>} sources
   * @param {Readonly<Record<string, string>>} renames
   * @param {PolicyGeneratorOptions & { debug?: boolean }} [opts]
   * @returns {Promise<import('lavamoat-core').LavaMoatPolicy>} Generated policy
   * @public
   */
  static async generatePolicy(compartmentMap, sources, renames, opts) {
    const { debug, ...restOpts } = opts ?? {}
    const generator = new PolicyGenerator(
      compartmentMap,
      sources,
      renames,
      restOpts
    )
    return generator.generatePolicy(debug)
  }
}