wasm-platform-kit 0.0.0-stage → 0.2.0

package/install.d.ts

@@ -0,0 +1,22 @@
+import type {HostOptions} from './index.js';
+
+/** Trusted embedding package installation settings; guest manifests grant no authority. */
+export interface InstallationOptions
+{
+  directory: URL;
+  component: URL;
+  componentSha256: string;
+  prebuiltArtifacts?: HostOptions['nativeArtifacts'];
+  /** Defaults to WASM_PLATFORM_KIT_BUILD_FROM_SOURCE=1. */
+  fromSource?: boolean;
+  signal?: AbortSignal;
+  /** Installation-only deadline, at most 900000ms; guest execution limits are independent. */
+  timeout?: number;
+}
+export function prepareNative(options: InstallationOptions): Promise<{
+  preparation: 'prebuilt' | 'source';
+  componentSha256: string;
+  nativeSha256: string;
+  configuration: string;
+  target: string;
+}>;

package/install.mjs

@@ -0,0 +1,176 @@
+// Installation prepares executable artifacts. Runtime modules never import this module.
+// ref:DEC-wpk-installation-preparation
+import {execFile} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {createReadStream, createWriteStream} from 'node:fs';
+import {pipeline} from 'node:stream/promises';
+import {mkdir, mkdtemp, rename, rm, writeFile} from 'node:fs/promises';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+import {promisify} from 'node:util';
+import {nativeConfiguration, nativeTargets} from './native-registration.mjs';
+
+const require = createRequire(import.meta.url);
+const execute = promisify(execFile);
+
+/** Hashes streams with the same artifact bounds as the native helper. ref:DEC-wpk-installation-preparation */
+async function digest(file, limit)
+{
+  const hash = createHash('sha256');
+  let size = 0;
+  for await (const chunk of createReadStream(file))
+  {
+    size += chunk.length;
+    if (size > limit) throw new Error('Installation artifact size exhausted');
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+
+/** Copies only bounded, pinned input into private installation staging. ref:DEC-wpk-installation-preparation */
+async function snapshot(component, destination, expected, signal)
+{
+  const hash = createHash('sha256');
+  let size = 0;
+  await pipeline(
+    createReadStream(component),
+    async function* (source)
+    {
+      for await (const chunk of source)
+      {
+        size += chunk.length;
+        if (size > 128 * 1024 * 1024)
+          throw new Error('Installation artifact size exhausted');
+        hash.update(chunk);
+        yield chunk;
+      }
+    },
+    createWriteStream(destination, {flags: 'wx', mode: 0o600}),
+    {signal},
+  );
+  if (hash.digest('hex') !== expected)
+    throw new Error('Portable component integrity mismatch');
+}
+
+/** Verifies a prebuilt artifact or compiles a pinned portable component during installation. ref:DEC-wpk-installation-preparation */
+export async function prepareNative({
+  directory,
+  component,
+  componentSha256,
+  prebuiltArtifacts = {},
+  fromSource = process.env.WASM_PLATFORM_KIT_BUILD_FROM_SOURCE === '1',
+  signal,
+  timeout = 15 * 60 * 1000,
+})
+{
+  const platform = `${process.platform}-${process.arch}`;
+  const target = nativeTargets[platform];
+  if (
+    !target ||
+    (process.platform === 'linux' &&
+      !process.report.getReport().header.glibcVersionRuntime)
+  )
+    throw new Error(
+      'Native installation supports macOS and glibc Linux on x64/ARM64; use WSL on Windows',
+    );
+  if (!/^[a-f0-9]{64}$/.test(componentSha256))
+    throw new Error('Trusted component digest required');
+  if (
+    !Number.isSafeInteger(timeout) ||
+    timeout <= 0 ||
+    timeout > 15 * 60 * 1000
+  )
+    throw new Error(
+      'Installation timeout must be between 1 and 900000 milliseconds',
+    );
+  signal?.throwIfAborted();
+  require.resolve(`wasm-platform-kit-${platform}/bin/host-sdk-runtime`);
+  if (!fromSource)
+  {
+    let prebuilt;
+    try
+    {
+      const entry = prebuiltArtifacts[platform];
+      if (entry) prebuilt = {...entry, artifact: entry.artifact};
+    }
+    catch (error)
+    {
+      if (
+        !['MODULE_NOT_FOUND', 'ENOENT'].includes(error.code) &&
+        !['MODULE_NOT_FOUND', 'ENOENT'].includes(error.cause?.code)
+      )
+        throw error;
+    }
+    if (prebuilt)
+    {
+      if (
+        prebuilt.componentSha256 !== componentSha256 ||
+        prebuilt.configuration !== nativeConfiguration ||
+        prebuilt.target !== target ||
+        (await digest(prebuilt.artifact, 512 * 1024 * 1024)) !==
+          prebuilt.nativeSha256
+      )
+        throw new Error('Prebuilt native artifact integrity mismatch');
+      // A rebuild without force-source returns the installation to its packaged artifact.
+      await rm(new URL(`.native/${platform}/registration.json`, directory), {
+        force: true,
+      });
+      return {preparation: 'prebuilt', ...prebuilt};
+    }
+  }
+  const destination = fileURLToPath(new URL(`.native/${platform}/`, directory));
+  await mkdir(destination, {recursive: true, mode: 0o700});
+  await writeFile(new URL('.native/.npmignore', directory), '*\n');
+  const staging = await mkdtemp(path.join(destination, '.prepare-'));
+  try
+  {
+    const source = path.join(staging, 'component.wasm');
+    const output = path.join(staging, 'component.cwasm');
+    await snapshot(component, source, componentSha256, signal);
+    signal?.throwIfAborted();
+    const binary = require.resolve(
+      `wasm-platform-kit-${platform}/bin/host-sdk-source-runtime`,
+    );
+    const {stdout} = await execute(
+      binary,
+      ['--precompile', source, output, target],
+      {
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024,
+        timeout,
+        signal,
+        killSignal: 'SIGKILL',
+        env: {},
+        cwd: staging,
+      },
+    );
+    const receipt = JSON.parse(stdout);
+    if (
+      receipt.componentSha256 !== componentSha256 ||
+      receipt.configuration !== nativeConfiguration ||
+      receipt.target !== target ||
+      (await digest(output, 512 * 1024 * 1024)) !== receipt.nativeSha256
+    )
+      throw new Error('Compiled native artifact registration mismatch');
+    signal?.throwIfAborted();
+    await rename(
+      output,
+      path.join(destination, `${receipt.nativeSha256}.cwasm`),
+    );
+    await writeFile(
+      path.join(staging, 'registration.json'),
+      JSON.stringify(receipt) + '\n',
+      {mode: 0o600},
+    );
+    await rename(
+      path.join(staging, 'registration.json'),
+      path.join(destination, 'registration.json'),
+    );
+    return {preparation: 'source', ...receipt};
+  }
+  finally
+  {
+    await rm(staging, {recursive: true, force: true});
+  }
+}

package/native-registration.mjs

@@ -0,0 +1,70 @@
+// Installation receipts are trusted package-local state, never guest authority.
+// ref:DEC-wpk-installation-preparation
+import {readFileSync} from 'node:fs';
+
+export const nativeConfiguration = 'host-sdk-0.2.0/wasmtime-50.0.1/fuel-v1';
+export const nativeTargets = Object.freeze({
+  'darwin-arm64': 'aarch64-apple-darwin',
+  'darwin-x64': 'x86_64-apple-darwin',
+  'linux-arm64': 'aarch64-unknown-linux-gnu',
+  'linux-x64': 'x86_64-unknown-linux-gnu',
+});
+
+/** Reads only receipts approved by the embedding package's generated registration. ref:DEC-wpk-installation-preparation */
+export function installedNativeArtifacts({
+  directory,
+  componentSha256,
+  prebuiltArtifacts = {},
+})
+{
+  return Object.freeze(
+    Object.defineProperties(
+      {},
+      Object.fromEntries(
+        Object.entries(nativeTargets).map(([platform, target]) => [
+          platform,
+          {
+            enumerable: true,
+            get()
+            {
+              let receipt;
+              try
+              {
+                receipt = JSON.parse(
+                  readFileSync(
+                    new URL(`.native/${platform}/registration.json`, directory),
+                    'utf8',
+                  ),
+                );
+              }
+              catch (error)
+              {
+                if (error.code === 'ENOENT') return prebuiltArtifacts[platform];
+                throw error;
+              }
+              if (
+                receipt.componentSha256 !== componentSha256 ||
+                receipt.configuration !== nativeConfiguration ||
+                receipt.target !== target ||
+                !/^[a-f0-9]{64}$/.test(receipt.nativeSha256)
+              )
+                throw new Error(
+                  'Installed native registration mismatch; reinstall the application',
+                );
+              return Object.freeze({
+                componentSha256,
+                configuration: nativeConfiguration,
+                target,
+                nativeSha256: receipt.nativeSha256,
+                artifact: new URL(
+                  `.native/${platform}/${receipt.nativeSha256}.cwasm`,
+                  directory,
+                ),
+              });
+            },
+          },
+        ]),
+      ),
+    ),
+  );
+}

package/node.mjs

@@ -0,0 +1,332 @@
+// One helper process per instance. Revocation destroys its store and resources.
+// ref:DEC-host-sdk-direct-haskell
+import {spawn} from 'node:child_process';
+import {readFile} from 'node:fs/promises';
+import {createHash, randomUUID} from 'node:crypto';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+import {
+  HostError,
+  fail,
+  configure,
+  createBroker,
+  byteLength,
+  createResourceScope,
+  outcomeCode,
+  stringifyTransport,
+  parseTransport,
+  trustedJavaScript,
+} from './policy.mjs';
+export {HostError, trustedJavaScript};
+export {trustedDOM, trustedNativeFFI, trustedProcess} from './policy.mjs';
+const require = createRequire(import.meta.url);
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+const live = new Set();
+const cleanup = new FinalizationRegistry(stop => stop());
+process.once('exit', () =>
+{
+  for (const stop of live) stop();
+});
+
+/** Starts an isolated Wasmtime instance from the matching prebuilt npm platform package. */
+export async function createHost(options = {})
+{
+  if (
+    !['darwin', 'linux'].includes(process.platform) ||
+    !['arm64', 'x64'].includes(process.arch)
+  )
+    fail(
+      'unsupported',
+      'Node native execution supports macOS/Linux x64 and ARM64 only; use WSL on Windows',
+    );
+  if (
+    process.platform === 'linux' &&
+    !process.report.getReport().header.glibcVersionRuntime
+  )
+    fail(
+      'unsupported',
+      'Linux native execution requires a detectable glibc runtime; musl is unsupported',
+    );
+  const compilation = options.compilation ?? 'precompiled';
+  if (compilation !== 'precompiled')
+    fail(
+      'unsupported',
+      'Runtime compilation is unavailable; run WASM_PLATFORM_KIT_BUILD_FROM_SOURCE=1 npm rebuild to prepare native artifacts during installation',
+    );
+  const platform = `${process.platform}-${process.arch}`;
+  const approved = options.nativeArtifacts?.[platform];
+  // Snapshot embedding-owned registration before the first await. A guest
+  // manifest, including its hashes, is never an authority for native loading.
+  const native = approved && {
+    artifact: String(approved.artifact),
+    componentSha256: approved.componentSha256,
+    nativeSha256: approved.nativeSha256,
+    configuration: approved.configuration,
+    target: approved.target,
+  };
+  if (!native)
+    fail(
+      'unsupported',
+      `no embedding-approved native artifact for ${platform}; reinstall with scripts enabled or run npm rebuild`,
+    );
+  const resources = createResourceScope();
+  const configuration = configure(options);
+  const {limits, grants} = configuration;
+  const controller = new AbortController();
+  const broker = createBroker(configuration, {
+    signal: controller.signal,
+    storage: options.storage,
+  });
+  let binary;
+  try
+  {
+    binary = require.resolve(
+      `wasm-platform-kit-${platform}/bin/host-sdk-runtime`,
+    );
+  }
+  catch
+  {
+    fail(
+      'unsupported',
+      `no prebuilt runtime for ${process.platform}-${process.arch}; build platform packages before installation`,
+    );
+  }
+  if (!options.manifest)
+    fail('failed', 'an embedding-approved component manifest is required');
+  const manifestURL = new URL(options.manifest, import.meta.url);
+  const manifest = JSON.parse(await readFile(manifestURL, 'utf8'));
+  if (
+    manifest.sdk !== '0.2.0' ||
+    !manifest.contract?.interfaces[manifest.interface]
+  )
+    fail('unsupported', 'SDK 0.2.0 typed manifest required');
+  const resultType = type =>
+  {
+    if (typeof type !== 'number') return undefined;
+    const kind = manifest.contract.types[type].kind;
+    return kind.type !== undefined ? resultType(kind.type) : kind.result;
+  };
+  const component = new URL(manifest.component, manifestURL);
+  if (
+    native.componentSha256 !== manifest.sha256 ||
+    native.configuration !== 'host-sdk-0.2.0/wasmtime-50.0.1/fuel-v1' ||
+    !/^[a-f0-9]{64}$/.test(native.nativeSha256)
+  )
+    fail('failed', 'native artifact registration mismatch');
+  if (new URL(native.artifact).protocol !== 'file:')
+    fail('denied', 'native artifacts must be local files');
+  const providerIdentity = sha256(
+    Buffer.concat(
+      await Promise.all(
+        [
+          'policy.mjs',
+          'node.mjs',
+          'browser.mjs',
+          'worker.mjs',
+          'client.mjs',
+        ].map(name => readFile(new URL(name, import.meta.url))),
+      ),
+    ),
+  );
+  const runtimeIdentity = `wasmtime-50.0.1:${sha256(await readFile(binary))}`;
+  const child = spawn(binary, [], {
+    env: {},
+    cwd: '/',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  if (options.keepAlive === false)
+  {
+    child.unref();
+    child.stdin.unref();
+    child.stdout.unref();
+    child.stderr.unref();
+  }
+
+  const nativeGrants = Object.fromEntries(
+    [...grants].map(([name, grant]) => [
+      name,
+      {
+        kind: grant.kind,
+        ...(grant.kind === 'files'
+          ? {root: grant.root, read: !!grant.read, write: !!grant.write}
+          : {}),
+      },
+    ]),
+  );
+  let closed = false,
+    pending,
+    text = '',
+    stderr = '',
+    timer;
+  let queue = Promise.resolve();
+  const send = message =>
+  {
+    if (!closed) child.stdin.write(stringifyTransport(message) + '\n');
+  };
+  const cleanupToken = {};
+  const stop = (error = new HostError('cancelled', 'instance revoked')) =>
+  {
+    if (closed) return;
+    closed = true;
+    live.delete(stop);
+    cleanup.unregister(cleanupToken);
+    clearTimeout(timer);
+    controller.abort(error);
+    broker.dispose();
+    child.kill('SIGKILL');
+    pending?.reject(error);
+    pending = undefined;
+  };
+  live.add(stop);
+  const wait = () =>
+    new Promise((resolve, reject) =>
+    {
+      pending = {resolve, reject};
+      timer = setTimeout(
+        () => stop(new HostError('exhausted', 'execution deadline')),
+        limits.timeout,
+      );
+    });
+  child.stdout.setEncoding('utf8');
+  child.stderr.setEncoding('utf8');
+  child.on('error', error => stop(new HostError('failed', error.message)));
+  child.on('exit', () =>
+    stop(new HostError('failed', stderr || 'runtime exited')),
+  );
+  child.stdin.on('error', error =>
+    stop(new HostError('failed', error.message)),
+  );
+  child.stderr.on('data', bytes =>
+  {
+    stderr += bytes.toString();
+    if (stderr.length > 8192) stderr = stderr.slice(0, 8192);
+  });
+  child.stdout.on('data', bytes =>
+  {
+    text += bytes.toString();
+    if (byteLength(text) > limits.bytes * 6 + 8192)
+      return stop(new HostError('exhausted', 'transport output limit'));
+    let newline;
+    while ((newline = text.indexOf('\n')) >= 0)
+    {
+      const line = text.slice(0, newline);
+      text = text.slice(newline + 1);
+      let message;
+      try
+      {
+        message = parseTransport(line);
+      }
+      catch
+      {
+        return stop(new HostError('failed', 'invalid runtime message'));
+      }
+      if (message.hostRequest)
+      {
+        const {provider, request} = message.hostRequest;
+        broker.perform(provider, request).then(
+          value => send({value}),
+          error =>
+            send({
+              error: {
+                code:
+                  error.code ??
+                  (controller.signal.aborted ? 'cancelled' : 'failed'),
+                message: error.message,
+              },
+            }),
+        );
+        continue;
+      }
+      const active = pending;
+      pending = undefined;
+      clearTimeout(timer);
+      if (!active)
+        return stop(new HostError('failed', 'unexpected runtime response'));
+      if (message.error)
+      {
+        active.reject(new HostError(message.error.code, message.error.message));
+        stop();
+      }
+      else active.resolve(message);
+    }
+  });
+  const ready = wait();
+  send({
+    component: fileURLToPath(component),
+    compilation,
+    ...(compilation === 'precompiled'
+      ? {
+          nativeArtifact: fileURLToPath(native.artifact),
+          nativeRegistration: {
+            componentSha256: native.componentSha256,
+            nativeSha256: native.nativeSha256,
+            configuration: native.configuration,
+            target: native.target,
+          },
+        }
+      : {}),
+    sha256: manifest.sha256,
+    limits,
+    grants: nativeGrants,
+  });
+  const identity = await ready;
+  const host = Object.freeze({
+    identity: Object.freeze({
+      ...identity,
+      runtime: runtimeIdentity,
+      provider: providerIdentity,
+      instance: randomUUID(),
+      policy: sha256(JSON.stringify([...grants]) + JSON.stringify(limits)),
+      interface: manifest.interface,
+    }),
+    invoke(method, args = [], {signal} = {})
+    {
+      const run = async () =>
+      {
+        if (closed || signal?.aborted) fail('cancelled', 'instance revoked');
+        const encoded = resources.encode(args);
+        if (byteLength(encoded) > limits.bytes)
+          fail('exhausted', 'input byte limit');
+        const abort = () => stop();
+        signal?.addEventListener('abort', abort, {once: true});
+        try
+        {
+          const result = wait();
+          send({interface: manifest.interface, method, args: encoded});
+          const response = await result;
+          const value = response.value?.[0];
+          const resultSchema = resultType(
+            manifest.contract.interfaces[manifest.interface][method]?.result,
+          );
+          if (resultSchema && value?.tag === 'err')
+            throw new HostError(
+              outcomeCode(value.val?.code),
+              typeof value.val === 'string'
+                ? value.val
+                : (value.val?.message ?? 'component returned an error'),
+              resources.decode(value.val),
+            );
+          return resources.decode(
+            resultSchema && value?.tag === 'ok' ? value.val : value,
+          );
+        }
+        finally
+        {
+          signal?.removeEventListener('abort', abort);
+        }
+      };
+      const result = queue.then(run);
+      queue = result.catch(() =>
+      {});
+      return result;
+    },
+    drop(resource, controls)
+    {
+      return this.invoke('[resource-drop]', [resource], controls);
+    },
+    revoke: () => stop(),
+    close: () => stop(),
+  });
+  cleanup.register(host, stop, cleanupToken);
+  return host;
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "wasm-platform-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Capability-scoped WebAssembly components with typed Haskell guests",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "browser": "./browser.mjs",
+      "default": "./node.mjs"
+    },
+    "./browser": {
+      "types": "./index.d.ts",
+      "default": "./browser.mjs"
+    },
+    "./worker": "./worker.mjs",
+    "./package.json": "./package.json",
+    "./install": {
+      "types": "./install.d.ts",
+      "default": "./install.mjs"
+    },
+    "./native-registration": "./native-registration.mjs"
+  },
+  "files": [
+    "node.mjs",
+    "browser.mjs",
+    "worker.mjs",
+    "client.mjs",
+    "policy.mjs",
+    "index.d.ts",
+    "assets/wasi",
+    "README.md",
+    "LICENSE",
+    "install.mjs",
+    "install.d.ts",
+    "native-registration.mjs"
+  ],
+  "scripts": {
+    "build": "node tools/build.mjs",
+    "test": "node --test test/*.test.mjs",
+    "pack:local": "node tools/pack.mjs",
+    "format": "node tools/style.mjs",
+    "build:platform": "node tools/platform.mjs"
+  },
+  "devDependencies": {
+    "@bytecodealliance/jco": "1.41.0",
+    "@bytecodealliance/preview2-shim": "0.31.0",
+    "@playwright/test": "1.63.0",
+    "prettier": "3.9.10",
+    "prettier-plugin-brace-style": "0.10.4",
+    "typescript": "6.0.3"
+  },
+  "optionalDependencies": {
+    "wasm-platform-kit-darwin-arm64": "0.2.0",
+    "wasm-platform-kit-darwin-x64": "0.2.0",
+    "wasm-platform-kit-linux-arm64": "0.2.0",
+    "wasm-platform-kit-linux-x64": "0.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brain-fuel/wasm-platform-kit.git"
+  },
+  "homepage": "https://github.com/brain-fuel/wasm-platform-kit#readme"
+}