@pulse-compute/wasm-guest-link 0.0.0 → 1.0.0-beta.1

package/src/errors.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const sensitiveKey = /(?:secret|credential|private|token|raw|buffer|payload|contents?|environment)/i;
+const sensitiveEnvironmentName = /(?:secret|token|key|credential|password|passphrase|authorization|cookie)/i;
+const pemBlock = /-----BEGIN [^-]*(?:PRIVATE|SECRET|ENCRYPTED)[^-]*-----[\s\S]*?-----END [^-]*-----/gi;
+const authorizationValue = /\b(?:bearer|basic)\s+[A-Za-z0-9._~+/=-]+/gi;
+const credentialAssignment = /\b(?:secret|token|password|passphrase|credential|private[_-]?key)\s*[=:]\s*[^\s,;]+/gi;
+
+function sensitiveValues() {
+  return Object.entries(process.env)
+    .filter(([name, value]) => sensitiveEnvironmentName.test(name) && typeof value === 'string' && value.length >= 4)
+    .map(([, value]) => value)
+    .sort((left, right) => right.length - left.length);
+}
+
+function safeString(value, secrets = sensitiveValues()) {
+  let result = String(value)
+    .replace(pemBlock, '<redacted-private-material>')
+    .replace(authorizationValue, '<redacted-authorization>')
+    .replace(credentialAssignment, '<redacted-credential>');
+  for (const secret of secrets) result = result.split(secret).join('<redacted-environment-value>');
+  return result.slice(0, 2048);
+}
+
+function safeDetails(value, depth = 0, secrets = sensitiveValues()) {
+  if (depth > 5) return '<omitted>';
+  if (Buffer.isBuffer(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return '<redacted-bytes>';
+  if (Array.isArray(value)) return Object.freeze(value.slice(0, 32).map((entry) => safeDetails(entry, depth + 1, secrets)));
+  if (!value || typeof value !== 'object') {
+    if (typeof value === 'string') return safeString(value, secrets);
+    return value;
+  }
+  const result = {};
+  for (const [key, child] of Object.entries(value)) {
+    result[key] = sensitiveKey.test(key) ? '<redacted>' : safeDetails(child, depth + 1, secrets);
+  }
+  return Object.freeze(result);
+}
+
+class GuestLinkError extends Error {
+  constructor(code, message, details) {
+    super(safeString(message));
+    this.name = 'GuestLinkError';
+    this.code = code;
+    if (details !== undefined) {
+      const detail = safeDetails(details);
+      this.detail = detail;
+      Object.defineProperty(this, 'details', {
+        enumerable: false,
+        configurable: false,
+        writable: false,
+        value: detail
+      });
+    }
+  }
+}
+
+function fail(code, message, details) {
+  throw new GuestLinkError(code, message, details);
+}
+
+function wrap(error, code, message, details = {}) {
+  if (error instanceof GuestLinkError) throw error;
+  fail(code, message, {
+    ...details,
+    cause: error && error.message ? error.message : String(error)
+  });
+}
+
+module.exports = Object.freeze({
+  GuestLinkError,
+  fail,
+  wrap,
+  safeDetails,
+  safeString
+});

package/src/files.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { diagnosticCodes } = require('./constants.js');
+const { fail } = require('./errors.js');
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function slash(value) {
+  return String(value).replace(/\\/g, '/');
+}
+
+function assertRelativePath(value, field) {
+  if (typeof value !== 'string' || value.length === 0) {
+    fail(diagnosticCodes.invalid, `${field} must be a non-empty package-relative path.`);
+  }
+  if (path.posix.isAbsolute(value) || path.win32.isAbsolute(value) || value.includes('\\')) {
+    fail(diagnosticCodes.invalid, `${field} must use portable package-relative syntax.`);
+  }
+  const parts = value.split('/');
+  if (parts.some((part) => part === '' || part === '.' || part === '..')) {
+    fail(diagnosticCodes.invalid, `${field} must not contain empty, current, or parent path segments.`);
+  }
+  return value;
+}
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function resolveExistingContained(root, relative, field, expectedKind = 'file') {
+  const normalized = assertRelativePath(relative, field);
+  const realRoot = fs.realpathSync(root);
+  const candidate = path.resolve(realRoot, normalized);
+  if (!inside(realRoot, candidate) || !fs.existsSync(candidate)) {
+    fail(diagnosticCodes.invalid, `${field} does not resolve to an existing contained ${expectedKind}.`);
+  }
+  const real = fs.realpathSync(candidate);
+  if (!inside(realRoot, real)) {
+    fail(diagnosticCodes.invalid, `${field} escapes its package root.`);
+  }
+  const stat = fs.statSync(real);
+  if ((expectedKind === 'file' && !stat.isFile()) || (expectedKind === 'directory' && !stat.isDirectory())) {
+    fail(diagnosticCodes.invalid, `${field} must resolve to a ${expectedKind}.`);
+  }
+  return real;
+}
+
+function fileRecord(file) {
+  const bytes = fs.readFileSync(file);
+  return Object.freeze({ bytes: bytes.length, sha256: sha256(bytes) });
+}
+
+function sourceEntries(directory, root = directory, entries = []) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => (
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+  ))) {
+    const file = path.join(directory, entry.name);
+    const relative = slash(path.relative(root, file));
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) {
+      fail(diagnosticCodes.invalid, `Guest source provenance rejects symbolic link ${relative}.`);
+    }
+    if (stat.isDirectory()) {
+      sourceEntries(file, root, entries);
+      continue;
+    }
+    if (!stat.isFile()) {
+      fail(diagnosticCodes.invalid, `Guest source provenance rejects non-file ${relative}.`);
+    }
+    entries.push(Object.freeze({ relative, file, bytes: stat.size }));
+  }
+  return entries;
+}
+
+function sourceTreeRecord(directory) {
+  const entries = sourceEntries(directory);
+  if (entries.length === 0) fail(diagnosticCodes.invalid, 'Guest source provenance directory must not be empty.');
+  const hash = crypto.createHash('sha256');
+  const files = [];
+  for (const entry of entries) {
+    const bytes = fs.readFileSync(entry.file);
+    hash.update(entry.relative, 'utf8');
+    hash.update('\0');
+    hash.update(String(bytes.length), 'utf8');
+    hash.update('\0');
+    hash.update(bytes);
+    hash.update('\0');
+    files.push(Object.freeze({
+      file: entry.relative,
+      bytes: bytes.length,
+      sha256: sha256(bytes)
+    }));
+  }
+  return Object.freeze({
+    algorithm: 'path-size-bytes-sha256-v1',
+    files: Object.freeze(files),
+    bytes: files.reduce((sum, entry) => sum + entry.bytes, 0),
+    sha256: hash.digest('hex')
+  });
+}
+
+function ensureContainedDirectory(projectRoot, relative) {
+  const realProject = fs.realpathSync(projectRoot);
+  const target = path.resolve(realProject, relative);
+  if (!inside(realProject, target)) {
+    fail(diagnosticCodes.materializationFailed, 'Guest workspace escapes the project root.');
+  }
+  fs.mkdirSync(target, { recursive: true });
+  const realTarget = fs.realpathSync(target);
+  if (!inside(realProject, realTarget)) {
+    fail(diagnosticCodes.materializationFailed, 'Guest workspace resolves outside the project root.');
+  }
+  return realTarget;
+}
+
+function writeAtomic(file, bytes) {
+  const directory = path.dirname(file);
+  fs.mkdirSync(directory, { recursive: true });
+  const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(temporary, bytes);
+    fs.renameSync(temporary, file);
+  } finally {
+    if (fs.existsSync(temporary)) fs.rmSync(temporary, { force: true });
+  }
+}
+
+module.exports = Object.freeze({
+  sha256,
+  stableJson,
+  slash,
+  assertRelativePath,
+  inside,
+  resolveExistingContained,
+  fileRecord,
+  sourceTreeRecord,
+  ensureContainedDirectory,
+  writeAtomic
+});

package/src/index.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const constants = require('./constants.js');
+const contracts = require('./contracts.js');
+const errors = require('./errors.js');
+const files = require('./files.js');
+const inspect = require('./inspect.js');
+const materialize = require('./materialize.js');
+const memoryOwner = require('./memory-owner.js');
+const pipeline = require('./pipeline.js');
+const toolchain = require('./toolchain.js');
+
+module.exports = Object.freeze({
+  versions: constants.versions,
+  memoryAbi: constants.memoryAbi,
+  memoryAbiV2: constants.memoryAbiV2,
+  es256FrameV2: constants.es256FrameV2,
+  es256GuestUnit: constants.es256GuestUnit,
+  diagnosticCodes: constants.diagnosticCodes,
+  binaryenVersion: constants.binaryenVersion,
+  GuestLinkError: errors.GuestLinkError,
+  safeDiagnosticDetails: errors.safeDetails,
+  safeDiagnosticString: errors.safeString,
+  normalizeGuestUnitManifest: contracts.normalizeGuestUnitManifest,
+  normalizeGuestUnitPlan: contracts.normalizeGuestUnitPlan,
+  sourceTreeRecord: files.sourceTreeRecord,
+  inspectWasmFile: inspect.inspectWasmFile,
+  materializePackagePrebuilt: materialize.materializePackagePrebuilt,
+  writeMemoryOwnerModule: memoryOwner.writeMemoryOwnerModule,
+  realizeGuestLinkPlan: pipeline.realizeGuestLinkPlan,
+  assertFinalArtifactIdentity: pipeline.assertFinalArtifactIdentity,
+  binaryenIdentity: toolchain.binaryenIdentity
+});