mustardscript 0.1.0

package/dist/lib/policy.js

@@ -0,0 +1,292 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { types } = require('node:util');
+const { loadNative } = require('../native-loader.js');
+
+const { MustardError, callNative } = require('./errors.js');
+const { defineEnumerableProperty, hasOwnProperty, isAccessorDescriptor } = require('./structured.js');
+
+const CONSOLE_CAPABILITY_NAMES = {
+  log: 'console.log',
+  warn: 'console.warn',
+  error: 'console.error',
+};
+const DEFAULT_SNAPSHOT_KEY = crypto.randomBytes(32);
+let nativeSnapshotHelpers;
+
+function snapshotNative() {
+  nativeSnapshotHelpers ??= loadNative();
+  return nativeSnapshotHelpers;
+}
+
+function validatePlainHandlerContainer(value, label) {
+  if (value === undefined) {
+    return null;
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value) || types.isProxy(value)) {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  return value;
+}
+
+function enumerateHandlerProperties(value, label) {
+  const container = validatePlainHandlerContainer(value, label);
+  if (container === null) {
+    return [];
+  }
+  return Object.entries(Object.getOwnPropertyDescriptors(container)).filter(([, descriptor]) => {
+    if (!descriptor.enumerable) {
+      return false;
+    }
+    if (isAccessorDescriptor(descriptor)) {
+      throw new TypeError(`${label} cannot define accessor properties`);
+    }
+    return true;
+  });
+}
+
+function collectHostHandlers({ capabilities = {}, console = {} } = {}) {
+  const handlers = {};
+  for (const [name, descriptor] of enumerateHandlerProperties(
+    capabilities,
+    'options.capabilities',
+  )) {
+    defineEnumerableProperty(handlers, name, descriptor.value);
+  }
+
+  const consoleDescriptors = new Map(
+    enumerateHandlerProperties(console, 'options.console'),
+  );
+  for (const [method, capabilityName] of Object.entries(CONSOLE_CAPABILITY_NAMES)) {
+    const descriptor = consoleDescriptors.get(method);
+    if (!descriptor) {
+      continue;
+    }
+    const handler = descriptor.value;
+    if (typeof handler !== 'function') {
+      throw new TypeError(`console.${method} must be a function`);
+    }
+    if (handlers[capabilityName] !== undefined) {
+      throw new TypeError(
+        `Duplicate handler for ${capabilityName}; use either options.console or options.capabilities`,
+      );
+    }
+    handlers[capabilityName] = handler;
+  }
+  return handlers;
+}
+
+function encodeRuntimeLimits(limits = {}) {
+  const encodedLimits = {};
+  if (limits.instructionBudget !== undefined) {
+    encodedLimits.instruction_budget = limits.instructionBudget;
+  }
+  if (limits.heapLimitBytes !== undefined) {
+    encodedLimits.heap_limit_bytes = limits.heapLimitBytes;
+  }
+  if (limits.allocationBudget !== undefined) {
+    encodedLimits.allocation_budget = limits.allocationBudget;
+  }
+  if (limits.callDepthLimit !== undefined) {
+    encodedLimits.call_depth_limit = limits.callDepthLimit;
+  }
+  if (limits.maxOutstandingHostCalls !== undefined) {
+    encodedLimits.max_outstanding_host_calls = limits.maxOutstandingHostCalls;
+  }
+  return encodedLimits;
+}
+
+function validateRuntimeLimitsObject(limits, label) {
+  if (limits === undefined || limits === null || typeof limits !== 'object') {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  if (Array.isArray(limits) || types.isProxy(limits)) {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  const prototype = Object.getPrototypeOf(limits);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  return limits;
+}
+
+function cloneSnapshotPolicy(policy) {
+  return {
+    capabilities: policy.capabilities.slice(),
+    limits: { ...policy.limits },
+  };
+}
+
+function cloneSnapshotKey(snapshotKey) {
+  return Buffer.from(snapshotKey);
+}
+
+function encodeSnapshotPolicy(policy, options = undefined) {
+  const encoded = cloneSnapshotPolicy(policy);
+  if (typeof options?.snapshotId === 'string' && options.snapshotId.length > 0) {
+    encoded.snapshot_id = options.snapshotId;
+  }
+  if (options?.snapshotKey !== undefined) {
+    const snapshotKey = cloneSnapshotKey(options.snapshotKey);
+    encoded.snapshot_key_base64 = snapshotKey.toString('base64');
+    encoded.snapshot_key_digest = snapshotKeyDigest(snapshotKey);
+  }
+  if (typeof options?.snapshotToken === 'string' && options.snapshotToken.length > 0) {
+    encoded.snapshot_token = options.snapshotToken;
+  }
+  return JSON.stringify(encoded);
+}
+
+function normalizeSnapshotKey(snapshotKey, label) {
+  if (snapshotKey === undefined) {
+    return cloneSnapshotKey(DEFAULT_SNAPSHOT_KEY);
+  }
+  if (typeof snapshotKey === 'string') {
+    return Buffer.from(snapshotKey, 'utf8');
+  }
+  if (Buffer.isBuffer(snapshotKey) || snapshotKey instanceof Uint8Array) {
+    return Buffer.from(snapshotKey);
+  }
+  throw new TypeError(`${label} must be a string, Buffer, or Uint8Array`);
+}
+
+function snapshotToken(snapshot, snapshotKey, snapshotId = undefined) {
+  const identity = snapshotId ?? snapshotIdentity(snapshot);
+  return crypto.createHmac('sha256', snapshotKey).update(identity, 'utf8').digest('hex');
+}
+
+function snapshotIdentity(snapshot) {
+  return callNative(snapshotNative().snapshotIdentity, Buffer.from(snapshot));
+}
+
+function snapshotKeyDigest(snapshotKey) {
+  return crypto.createHash('sha256').update(snapshotKey).digest('hex');
+}
+
+function assertSnapshotToken(
+  snapshot,
+  token,
+  snapshotKey,
+  expectedSnapshotId = undefined,
+  expectedSnapshotKeyDigest = undefined,
+) {
+  if (typeof token !== 'string' || token.length === 0) {
+    throw new TypeError('Progress.load() requires a dumped progress token');
+  }
+  const actualSnapshotId = snapshotIdentity(snapshot);
+  if (expectedSnapshotId !== undefined && actualSnapshotId !== expectedSnapshotId) {
+    throw new MustardError(
+      'Serialization',
+      'Progress.load() rejected a tampered or unauthenticated snapshot',
+    );
+  }
+  if (
+    expectedSnapshotKeyDigest !== undefined &&
+    snapshotKeyDigest(snapshotKey) !== expectedSnapshotKeyDigest
+  ) {
+    throw new MustardError(
+      'Serialization',
+      'Progress.load() rejected a mismatched snapshot key digest',
+    );
+  }
+  const expected = snapshotToken(snapshot, snapshotKey, actualSnapshotId);
+  if (
+    token.length !== expected.length ||
+    !crypto.timingSafeEqual(Buffer.from(token, 'utf8'), Buffer.from(expected, 'utf8'))
+  ) {
+    throw new MustardError(
+      'Serialization',
+      'Progress.load() rejected a tampered or unauthenticated snapshot',
+    );
+  }
+}
+
+function createExecutionPolicy({ limits = {}, snapshotKey, ...handlers } = {}) {
+  const hostHandlers = collectHostHandlers(handlers);
+  return {
+    hostHandlers,
+    policy: {
+      capabilities: Object.keys(hostHandlers),
+      limits: encodeRuntimeLimits(limits),
+    },
+    snapshotKey: normalizeSnapshotKey(snapshotKey, 'options.snapshotKey'),
+  };
+}
+
+function resolveProgressLoadContext(state, snapshot, options) {
+  const expectedSnapshotId =
+    typeof state.snapshot_id === 'string' && state.snapshot_id.length > 0
+      ? state.snapshot_id
+      : undefined;
+  const expectedSnapshotKeyDigest =
+    typeof state.snapshot_key_digest === 'string' && state.snapshot_key_digest.length > 0
+      ? state.snapshot_key_digest
+      : undefined;
+  if (expectedSnapshotId === undefined) {
+    throw new TypeError('Progress.load() requires dumped snapshot_id metadata');
+  }
+  if (expectedSnapshotKeyDigest === undefined) {
+    throw new TypeError('Progress.load() requires dumped snapshot_key_digest metadata');
+  }
+  if (options === undefined || options === null || typeof options !== 'object') {
+    throw new TypeError(
+      'Progress.load() requires explicit capabilities, limits, and snapshotKey',
+    );
+  }
+  if (
+    !hasOwnProperty(options, 'capabilities') &&
+    !hasOwnProperty(options, 'console')
+  ) {
+    throw new TypeError(
+      'Progress.load() requires explicit capabilities when restoring progress',
+    );
+  }
+  if (!hasOwnProperty(options, 'limits')) {
+    throw new TypeError(
+      'Progress.load() requires explicit limits when restoring progress',
+    );
+  }
+  const limits = validateRuntimeLimitsObject(
+    options.limits,
+    'Progress.load() options.limits',
+  );
+  if (options.snapshotKey === undefined) {
+    throw new TypeError(
+      'Progress.load() requires explicit snapshotKey when restoring progress',
+    );
+  }
+  const snapshotKey = normalizeSnapshotKey(
+    options.snapshotKey,
+    'Progress.load() options.snapshotKey',
+  );
+  assertSnapshotToken(
+    snapshot,
+    state.token,
+    snapshotKey,
+    expectedSnapshotId,
+    expectedSnapshotKeyDigest,
+  );
+  return {
+    policy: createExecutionPolicy({ ...options, limits }).policy,
+    snapshotKey: cloneSnapshotKey(snapshotKey),
+  };
+}
+
+module.exports = {
+  cloneSnapshotPolicy,
+  cloneSnapshotKey,
+  collectHostHandlers,
+  createExecutionPolicy,
+  encodeRuntimeLimits,
+  encodeSnapshotPolicy,
+  normalizeSnapshotKey,
+  resolveProgressLoadContext,
+  snapshotIdentity,
+  snapshotKeyDigest,
+  snapshotToken,
+};

package/dist/lib/progress.js

@@ -0,0 +1,356 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { performance } = require('node:perf_hooks');
+
+const { MustardError, callNative } = require('./errors.js');
+const { getAbortSignal, withCancellationSignal } = require('./cancellation.js');
+const {
+  cloneSnapshotPolicy,
+  cloneSnapshotKey,
+  encodeSnapshotPolicy,
+  resolveProgressLoadContext,
+  snapshotIdentity,
+  snapshotKeyDigest,
+  snapshotToken,
+} = require('./policy.js');
+const {
+  decodeStructured,
+  encodeResumePayloadCancel,
+  encodeResumePayloadError,
+  encodeResumePayloadValue,
+} = require('./structured.js');
+
+const SHARED_PROGRESS_REGISTRY_ROOT = path.join(
+  os.tmpdir(),
+  'mustard-progress-registry',
+  `${process.pid}-${Math.round(performance.timeOrigin)}`,
+);
+
+function sharedProgressSnapshotPath(snapshotIdentityValue) {
+  return path.join(SHARED_PROGRESS_REGISTRY_ROOT, snapshotIdentityValue);
+}
+
+function ensureSharedProgressRegistryRoot() {
+  fs.mkdirSync(SHARED_PROGRESS_REGISTRY_ROOT, { recursive: true });
+}
+
+function isSharedProgressSnapshotUsed(snapshotIdentityValue) {
+  ensureSharedProgressRegistryRoot();
+  return fs.existsSync(sharedProgressSnapshotPath(snapshotIdentityValue));
+}
+
+function releaseSharedProgressSnapshot(snapshotIdentityValue) {
+  try {
+    fs.rmSync(sharedProgressSnapshotPath(snapshotIdentityValue));
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
+function claimSharedProgressSnapshot(snapshotIdentityValue) {
+  ensureSharedProgressRegistryRoot();
+  try {
+    const fd = fs.openSync(sharedProgressSnapshotPath(snapshotIdentityValue), 'wx', 0o600);
+    fs.closeSync(fd);
+    return true;
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'EEXIST') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function singleUseRuntimeError() {
+  return new MustardError(
+    'Runtime',
+    'Progress objects are single-use; this suspended execution was already resumed',
+  );
+}
+
+function releaseClaimedSnapshot(native, snapshotIdentityValue) {
+  try {
+    callNative(native.releaseProgressSnapshot, snapshotIdentityValue);
+  } finally {
+    releaseSharedProgressSnapshot(snapshotIdentityValue);
+  }
+}
+
+function claimSnapshotForLoad(native, snapshotIdentityValue) {
+  if (!claimSharedProgressSnapshot(snapshotIdentityValue)) {
+    throw singleUseRuntimeError();
+  }
+  try {
+    if (!callNative(native.claimProgressSnapshot, snapshotIdentityValue)) {
+      releaseSharedProgressSnapshot(snapshotIdentityValue);
+      throw singleUseRuntimeError();
+    }
+  } catch (error) {
+    if (!(error instanceof MustardError)) {
+      releaseSharedProgressSnapshot(snapshotIdentityValue);
+    }
+    throw error;
+  }
+
+  return () => {
+    releaseClaimedSnapshot(native, snapshotIdentityValue);
+  };
+}
+
+function assertSnapshotNotUsed(native, snapshotIdentityValue) {
+  if (
+    isSharedProgressSnapshotUsed(snapshotIdentityValue) ||
+    callNative(native.isProgressSnapshotUsed, snapshotIdentityValue)
+  ) {
+    throw singleUseRuntimeError();
+  }
+}
+
+function createProgressApi(native) {
+  class Progress {
+    constructor(
+      snapshot,
+      capability,
+      args,
+      policy,
+      snapshotKey,
+      token = undefined,
+      claimState = 'unclaimed',
+    ) {
+      this.capability = capability;
+      this.args = args;
+      this.#snapshot = Buffer.from(snapshot);
+      this.#snapshotIdentity = snapshotIdentity(this.#snapshot);
+      this.#snapshotKey = cloneSnapshotKey(snapshotKey);
+      this.#snapshotKeyDigest = snapshotKeyDigest(this.#snapshotKey);
+      this.#snapshotToken = token ?? snapshotToken(this.#snapshot, this.#snapshotKey);
+      this.#policy = cloneSnapshotPolicy(policy);
+      this.#claimState = claimState;
+    }
+
+    #snapshot;
+    #snapshotIdentity;
+    #snapshotKey;
+    #snapshotKeyDigest;
+    #snapshotToken;
+    #policy;
+    #claimState;
+
+    #consumeSnapshot() {
+      if (this.#claimState === 'consumed') {
+        throw singleUseRuntimeError();
+      }
+      if (this.#claimState === 'claimed') {
+        this.#claimState = 'consumed';
+        return Buffer.from(this.#snapshot);
+      }
+      if (!claimSharedProgressSnapshot(this.#snapshotIdentity)) {
+        throw singleUseRuntimeError();
+      }
+      try {
+        if (!callNative(native.claimProgressSnapshot, this.#snapshotIdentity)) {
+          releaseSharedProgressSnapshot(this.#snapshotIdentity);
+          throw singleUseRuntimeError();
+        }
+      } catch (error) {
+        if (!(error instanceof MustardError)) {
+          releaseSharedProgressSnapshot(this.#snapshotIdentity);
+        }
+        throw error;
+      }
+      this.#claimState = 'consumed';
+      return Buffer.from(this.#snapshot);
+    }
+
+    get snapshot() {
+      return Buffer.from(this.#snapshot);
+    }
+
+    dump() {
+      return {
+        capability: this.capability,
+        args: this.args.slice(),
+        snapshot: this.snapshot,
+        snapshot_id: this.#snapshotIdentity,
+        snapshot_key_digest: this.#snapshotKeyDigest,
+        token: this.#snapshotToken,
+      };
+    }
+
+    resume(value, options = undefined) {
+      const signal = getAbortSignal(options, 'resume options');
+      if (signal?.aborted) {
+        return this.cancel();
+      }
+      const payload = encodeResumePayloadValue(value);
+      const policyJson = encodeSnapshotPolicy(this.#policy, {
+        snapshotId: this.#snapshotIdentity,
+        snapshotKey: this.#snapshotKey,
+        snapshotToken: this.#snapshotToken,
+      });
+      const step = parseStep(
+        withCancellationSignal(
+          native,
+          native.resumeProgram,
+          [this.#consumeSnapshot(), payload, policyJson],
+          signal,
+        ),
+      );
+      return materializeStep(step, this.#policy, this.#snapshotKey);
+    }
+
+    resumeError(error, options = undefined) {
+      const signal = getAbortSignal(options, 'resume options');
+      if (signal?.aborted) {
+        return this.cancel();
+      }
+      const payload = encodeResumePayloadError(error);
+      const policyJson = encodeSnapshotPolicy(this.#policy, {
+        snapshotId: this.#snapshotIdentity,
+        snapshotKey: this.#snapshotKey,
+        snapshotToken: this.#snapshotToken,
+      });
+      const step = parseStep(
+        withCancellationSignal(
+          native,
+          native.resumeProgram,
+          [this.#consumeSnapshot(), payload, policyJson],
+          signal,
+        ),
+      );
+      return materializeStep(step, this.#policy, this.#snapshotKey);
+    }
+
+    cancel() {
+      const policyJson = encodeSnapshotPolicy(this.#policy, {
+        snapshotId: this.#snapshotIdentity,
+        snapshotKey: this.#snapshotKey,
+        snapshotToken: this.#snapshotToken,
+      });
+      const step = parseStep(
+        callNative(
+          native.resumeProgram,
+          this.#consumeSnapshot(),
+          encodeResumePayloadCancel(),
+          policyJson,
+        ),
+      );
+      return materializeStep(step, this.#policy, this.#snapshotKey);
+    }
+
+    static load(state, options = undefined) {
+      if (!state || typeof state !== 'object') {
+        throw new TypeError('Progress.load() expects a dumped progress object');
+      }
+      if (!state.snapshot) {
+        throw new TypeError('Progress.load() requires snapshot bytes');
+      }
+      if (typeof state.snapshot_id !== 'string' || state.snapshot_id.length === 0) {
+        throw new TypeError('Progress.load() requires dumped snapshot_id metadata');
+      }
+      if (
+        typeof state.snapshot_key_digest !== 'string' ||
+        state.snapshot_key_digest.length === 0
+      ) {
+        throw new TypeError('Progress.load() requires dumped snapshot_key_digest metadata');
+      }
+      if (typeof state.token !== 'string' || state.token.length === 0) {
+        throw new TypeError('Progress.load() requires a dumped progress token');
+      }
+      const snapshot = Buffer.from(state.snapshot);
+      let snapshotIdentityValue;
+      try {
+        snapshotIdentityValue = snapshotIdentity(snapshot);
+      } catch (error) {
+        if (error instanceof MustardError && error.kind === 'Serialization') {
+          throw new MustardError(
+            'Serialization',
+            'Progress.load() rejected a tampered or unauthenticated snapshot',
+            error,
+          );
+        }
+        throw error;
+      }
+      if (state.snapshot_id !== snapshotIdentityValue) {
+        throw new MustardError(
+          'Serialization',
+          'Progress.load() rejected a tampered or unauthenticated snapshot',
+        );
+      }
+      assertSnapshotNotUsed(native, snapshotIdentityValue);
+      const context = resolveProgressLoadContext(state, snapshot, options);
+      const releaseClaim = claimSnapshotForLoad(native, snapshotIdentityValue);
+      try {
+        const inspection = parseSnapshotInspection(
+          callNative(
+            native.inspectSnapshot,
+            snapshot,
+            encodeSnapshotPolicy(context.policy, {
+              snapshotId: state.snapshot_id,
+              snapshotKey: context.snapshotKey,
+              snapshotToken: state.token,
+            }),
+          ),
+        );
+        return new Progress(
+          snapshot,
+          inspection.capability,
+          inspection.args,
+          context.policy,
+          context.snapshotKey,
+          state.token,
+          'claimed',
+        );
+      } catch (error) {
+        releaseClaim();
+        throw error;
+      }
+    }
+  }
+
+  function parseStep(stepJson) {
+    const step = JSON.parse(stepJson);
+    if (step.type === 'completed') {
+      return {
+        type: 'completed',
+        value: decodeStructured(step.value),
+      };
+    }
+    return {
+      type: 'suspended',
+      capability: step.capability,
+      args: step.args.map(decodeStructured),
+      snapshot: Buffer.from(step.snapshot_base64, 'base64'),
+    };
+  }
+
+  function parseSnapshotInspection(inspectionJson) {
+    const inspection = JSON.parse(inspectionJson);
+    return {
+      capability: inspection.capability,
+      args: inspection.args.map(decodeStructured),
+    };
+  }
+
+  function materializeStep(step, policy, snapshotKey) {
+    if (step.type === 'completed') {
+      return step.value;
+    }
+    return new Progress(step.snapshot, step.capability, step.args, policy, snapshotKey);
+  }
+
+  return {
+    Progress,
+    materializeStep,
+    parseStep,
+  };
+}
+
+module.exports = {
+  createProgressApi,
+};