wasm-platform-kit 0.0.0-stage → 0.2.0

package/assets/wasi/random.js

@@ -0,0 +1,51 @@
+import { checkedU64AsNumber } from "./common.js";
+const MAX_BYTES = 65536;
+let insecureRandomValue1, insecureRandomValue2;
+export const insecure = {
+    getInsecureRandomBytes(len) {
+        return random.getRandomBytes(len);
+    },
+    getInsecureRandomU64() {
+        return random.getRandomU64();
+    },
+};
+let insecureSeedValue1, insecureSeedValue2;
+export const insecureSeed = {
+    insecureSeed() {
+        if (insecureSeedValue1 === undefined || insecureSeedValue2 === undefined) {
+            insecureSeedValue1 = random.getRandomU64();
+            insecureSeedValue2 = random.getRandomU64();
+        }
+        return [insecureSeedValue1, insecureSeedValue2];
+    },
+};
+export const random = {
+    getRandomBytes(len) {
+        const byteLength = checkedU64AsNumber(len, "random byte length");
+        const bytes = new Uint8Array(byteLength);
+        if (byteLength > MAX_BYTES) {
+            // this is the max bytes crypto.getRandomValues
+            // can do at once see https://developer.mozilla.org/en-US/docs/Web/API/window.crypto.getRandomValues
+            for (let generated = 0; generated < byteLength; generated += MAX_BYTES) {
+                // buffer.slice automatically checks if the end is past the end of
+                // the buffer so we don't have to here
+                crypto.getRandomValues(bytes.subarray(generated, generated + MAX_BYTES));
+            }
+        }
+        else {
+            crypto.getRandomValues(bytes);
+        }
+        return bytes;
+    },
+    getRandomU64() {
+        return crypto.getRandomValues(new BigUint64Array(1))[0];
+    },
+    // @ts-expect-error Not defined in WIT
+    insecureRandom() {
+        if (insecureRandomValue1 === undefined || insecureRandomValue2 === undefined) {
+            insecureRandomValue1 = random.getRandomU64();
+            insecureRandomValue2 = random.getRandomU64();
+        }
+        return [insecureRandomValue1, insecureRandomValue2];
+    },
+};

package/assets/wasi/sockets.d.ts

@@ -0,0 +1,9 @@
+import type { instanceNetwork as InstanceNetworkNamespace, ipNameLookup as IpNameLookupNamespace, network as NetworkNamespace, tcpCreateSocket as TcpCreateSocketNamespace, tcp as TcpNamespace, udpCreateSocket as UdpCreateSocketNamespace, udp as UdpNamespace } from "../../types/sockets.js";
+export { InMemoryTcpClient, InMemoryTcpSockets, InMemoryUdpClient, InMemoryUdpSockets, } from "./in-memory-sockets.js";
+export declare const instanceNetwork: typeof InstanceNetworkNamespace;
+export declare const network: typeof NetworkNamespace;
+export declare const ipNameLookup: typeof IpNameLookupNamespace;
+export declare const tcpCreateSocket: typeof TcpCreateSocketNamespace;
+export declare const tcp: typeof TcpNamespace;
+export declare const udpCreateSocket: typeof UdpCreateSocketNamespace;
+export declare const udp: typeof UdpNamespace;

package/assets/wasi/sockets.js

@@ -0,0 +1,85 @@
+export { InMemoryTcpClient, InMemoryTcpSockets, InMemoryUdpClient, InMemoryUdpSockets, } from "./in-memory-sockets.js";
+const unsupported = () => {
+    throw "not-supported";
+};
+class Network {
+}
+const defaultNetwork = new Network();
+export const instanceNetwork = {
+    instanceNetwork: () => defaultNetwork,
+};
+export const network = { Network };
+class ResolveAddressStream {
+    resolveNextAddress = unsupported;
+    subscribe = unsupported;
+}
+export const ipNameLookup = {
+    ResolveAddressStream,
+    resolveAddresses: unsupported,
+};
+class TcpSocket {
+    startBind = unsupported;
+    finishBind = unsupported;
+    startConnect = unsupported;
+    finishConnect = unsupported;
+    startListen = unsupported;
+    finishListen = unsupported;
+    accept = unsupported;
+    localAddress = unsupported;
+    remoteAddress = unsupported;
+    isListening = unsupported;
+    addressFamily = unsupported;
+    setListenBacklogSize = unsupported;
+    keepAliveEnabled = unsupported;
+    setKeepAliveEnabled = unsupported;
+    keepAliveIdleTime = unsupported;
+    setKeepAliveIdleTime = unsupported;
+    keepAliveInterval = unsupported;
+    setKeepAliveInterval = unsupported;
+    keepAliveCount = unsupported;
+    setKeepAliveCount = unsupported;
+    hopLimit = unsupported;
+    setHopLimit = unsupported;
+    receiveBufferSize = unsupported;
+    setReceiveBufferSize = unsupported;
+    sendBufferSize = unsupported;
+    setSendBufferSize = unsupported;
+    subscribe = unsupported;
+    shutdown = unsupported;
+}
+export const tcpCreateSocket = {
+    createTcpSocket: unsupported,
+};
+export const tcp = { TcpSocket };
+class IncomingDatagramStream {
+    receive = unsupported;
+    subscribe = unsupported;
+}
+class OutgoingDatagramStream {
+    checkSend = unsupported;
+    send = unsupported;
+    subscribe = unsupported;
+}
+class UdpSocket {
+    startBind = unsupported;
+    finishBind = unsupported;
+    stream = unsupported;
+    localAddress = unsupported;
+    remoteAddress = unsupported;
+    addressFamily = unsupported;
+    unicastHopLimit = unsupported;
+    setUnicastHopLimit = unsupported;
+    receiveBufferSize = unsupported;
+    setReceiveBufferSize = unsupported;
+    sendBufferSize = unsupported;
+    setSendBufferSize = unsupported;
+    subscribe = unsupported;
+}
+export const udpCreateSocket = {
+    createUdpSocket: unsupported,
+};
+export const udp = {
+    IncomingDatagramStream,
+    OutgoingDatagramStream,
+    UdpSocket,
+};

package/browser.mjs

@@ -0,0 +1,209 @@
+// Privileged handles and provider functions stay in the embedding page.
+// ref:DEC-host-sdk-direct-haskell
+import {
+  HostError,
+  fail,
+  configure,
+  createBroker,
+  byteLength,
+  createResourceScope,
+  trustedJavaScript,
+} from './policy.mjs';
+export {HostError, trustedJavaScript};
+export {trustedDOM, trustedNativeFFI, trustedProcess} from './policy.mjs';
+
+const hex = bytes =>
+  [...new Uint8Array(bytes)].map(x => x.toString(16).padStart(2, '0')).join('');
+/** Starts a registered component in a worker with grants retained by the page broker. */
+export async function createHost(options = {})
+{
+  const registration = options.registration;
+  if (
+    !registration ||
+    !Array.isArray(registration.manifests) ||
+    !registration.workerURL
+  )
+    fail('unsupported', 'host-generated browser registration required');
+  const trustedManifests = new Set(registration.manifests);
+  const resources = createResourceScope();
+  const configuration = configure(options),
+    {limits, grants} = configuration;
+  if (
+    !globalThis.isSecureContext ||
+    !globalThis.crypto?.subtle ||
+    typeof Worker === 'undefined'
+  )
+    fail('unsupported', 'secure context, workers and WebCrypto required');
+  if (
+    typeof WebAssembly.Suspending !== 'function' ||
+    typeof WebAssembly.promising !== 'function'
+  )
+    fail('unsupported', 'WebAssembly JSPI required; no fallback runtime');
+  if (!options.manifest)
+    fail('failed', 'an embedding-approved component manifest is required');
+  const manifestURL = new URL(options.manifest, import.meta.url);
+  const response = await fetch(manifestURL, {
+    credentials: 'omit',
+    redirect: 'error',
+  });
+  if (!response.ok) fail('failed', 'manifest unavailable');
+  const manifest = await response.json();
+  const manifestDigest = hex(
+    await crypto.subtle.digest(
+      'SHA-256',
+      new TextEncoder().encode(JSON.stringify(manifest)),
+    ),
+  );
+  if (!trustedManifests.has(manifestDigest))
+    fail('denied', 'component is not in the host-generated artifact registry');
+  if (options.deployment === 'isolated' && !globalThis.crossOriginIsolated)
+    fail('unsupported', 'isolated deployment requires COOP/COEP headers');
+  if (
+    options.deployment &&
+    !['standard', 'isolated'].includes(options.deployment)
+  )
+    fail('unsupported', 'unknown deployment profile');
+  if (manifest.version !== 1 || manifest.browser?.memory > limits.memory)
+    fail('unsupported', 'artifact exceeds browser memory policy');
+  const controller = new AbortController();
+  const broker = createBroker(configuration, {
+    signal: controller.signal,
+    storage: options.storage,
+  });
+  const worker = new Worker(registration.workerURL, {
+    type: 'module',
+  });
+  let closed = false,
+    pending,
+    timer,
+    queue = Promise.resolve();
+  const stop = (error = new HostError('cancelled', 'instance revoked')) =>
+  {
+    if (closed) return;
+    closed = true;
+    clearTimeout(timer);
+    controller.abort(error);
+    worker.terminate();
+    broker.dispose();
+    pending?.reject(error);
+    pending = undefined;
+  };
+  const wait = () =>
+    new Promise((resolve, reject) =>
+    {
+      pending = {resolve, reject};
+      timer = setTimeout(
+        () => stop(new HostError('exhausted', 'execution deadline')),
+        limits.timeout,
+      );
+    });
+  worker.onerror = event => stop(new HostError('failed', event.message));
+  worker.onmessage = event =>
+  {
+    const message = event.data;
+    if (message.hostRequest)
+    {
+      const {provider, request} = message.hostRequest;
+      broker.perform(provider, request).then(
+        value =>
+        {
+          if (!closed)
+            worker.postMessage({hostResponse: true, id: message.id, value});
+        },
+        error =>
+        {
+          if (!closed)
+            worker.postMessage({
+              hostResponse: true,
+              id: message.id,
+              error: {code: error.code ?? 'failed', message: error.message},
+            });
+        },
+      );
+      return;
+    }
+    const active = pending;
+    pending = undefined;
+    clearTimeout(timer);
+    if (!active)
+      return stop(new HostError('failed', 'unexpected worker response'));
+    if (message.error)
+    {
+      active.reject(
+        new HostError(
+          message.error.code,
+          message.error.message,
+          resources.decode(message.error.payload),
+        ),
+      );
+      // Guest-returned capability errors leave the component usable; traps do not.
+      if (message.fatal) stop();
+    }
+    else active.resolve(message);
+  };
+  const ready = wait();
+  worker.postMessage({
+    init: true,
+    manifestURL: manifestURL.href,
+    manifest,
+    limits,
+    providers: [...grants.keys()],
+  });
+  try
+  {
+    await ready;
+  }
+  catch (error)
+  {
+    stop(error);
+    throw error;
+  }
+  const policy = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(
+      JSON.stringify([...grants]) + JSON.stringify(limits),
+    ),
+  );
+  return Object.freeze({
+    identity: Object.freeze({
+      runtime: `jco-${manifest.generators.jco}`,
+      artifact: manifest.sha256,
+      provider: manifest.providers,
+      instance: crypto.randomUUID(),
+      policy: hex(policy),
+      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();
+          worker.postMessage({method, args: encoded});
+          return resources.decode((await result).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(),
+  });
+}

package/client.mjs

@@ -0,0 +1,138 @@
+// Typed façades use WIT metadata; application decisions never live in this module.
+// ref:DEC-host-sdk-typed-application-boundary
+import {HostError} from './policy.mjs';
+const camel = name =>
+  name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+const pascal = name =>
+{
+  const value = camel(name);
+  return value[0].toUpperCase() + value.slice(1);
+};
+
+/** Adds Promise-returning WIT operations and scoped resources to a generic host. */
+export function createClient(host, contract, interfaceName)
+{
+  const resultType = type =>
+  {
+    if (typeof type !== 'number') return undefined;
+    const kind = contract.types[type].kind;
+    return kind.type !== undefined ? resultType(kind.type) : kind.result;
+  };
+  const functions = contract.interfaces[interfaceName];
+  const wrappers = new WeakMap();
+  function transform(type, value, output)
+  {
+    if (type == null || typeof type === 'string') return value;
+    const {kind} = contract.types[type];
+    if (kind.type !== undefined) return transform(kind.type, value, output);
+    if (kind.handle)
+    {
+      const target = kind.handle.own ?? kind.handle.borrow;
+      if (!output)
+      {
+        const entry = wrappers.get(value);
+        if (!entry || entry.type !== target)
+          throw new HostError(
+            'denied',
+            'resource belongs to another client or type',
+          );
+        return entry.token;
+      }
+      const resource = {};
+      wrappers.set(resource, {type: target, token: value});
+      for (const fn of Object.values(functions))
+        if (fn.kind?.method === target)
+        {
+          const name = camel(fn.name.split('.')[1]);
+          if (name === 'dispose' || name === 'then')
+            throw new HostError(
+              'unsupported',
+              'resource method conflicts with lifecycle',
+            );
+          resource[name] = (...args) => call(fn, [resource, ...args]);
+        }
+      resource.dispose = controls => host.drop(value, controls);
+      return Object.freeze(resource);
+    }
+    if (kind.list !== undefined)
+    {
+      const items = Array.from(value, item =>
+        transform(kind.list, item, output),
+      );
+      return output && kind.list === 'u8' ? new Uint8Array(items) : items;
+    }
+    if (kind.record)
+      return Object.fromEntries(
+        kind.record.fields.map(field => [
+          output ? camel(field.name) : field.name,
+          transform(
+            field.type,
+            value[output ? field.name : camel(field.name)],
+            output,
+          ),
+        ]),
+      );
+    if (kind.option !== undefined)
+      return value == null ? null : transform(kind.option, value, output);
+    if (kind.variant)
+    {
+      const variant = kind.variant.cases.find(item => item.name === value?.tag);
+      if (!variant) throw new HostError('failed', 'invalid variant');
+      return {
+        tag: value.tag,
+        ...(variant.type == null
+          ? {}
+          : {val: transform(variant.type, value.val, output)}),
+      };
+    }
+    if (kind.result)
+    {
+      if (value?.tag !== 'ok' && value?.tag !== 'err')
+        throw new HostError('failed', 'invalid result');
+      return {
+        tag: value.tag,
+        val: transform(kind.result[value.tag], value.val, output),
+      };
+    }
+    if (kind.enum) return value;
+    throw new HostError('unsupported', 'unsupported façade type');
+  }
+  async function call(fn, values)
+  {
+    if (
+      values.length < fn.params.length ||
+      values.length > fn.params.length + 1
+    )
+      throw new HostError('failed', 'argument count mismatch');
+    const args = fn.params.map((param, i) =>
+      transform(param.type, values[i], false),
+    );
+    const result = resultType(fn.result);
+    try
+    {
+      const value = await host.invoke(fn.name, args, values[fn.params.length]);
+      return transform(result ? result.ok : fn.result, value, true);
+    }
+    catch (error)
+    {
+      if (result && Object.hasOwn(error, 'payload'))
+        error.payload = transform(result.err, error.payload, true);
+      throw error;
+    }
+  }
+  const client = {...host};
+  for (const fn of Object.values(functions))
+  {
+    if (fn.kind?.method !== undefined) continue;
+    const name = fn.name.startsWith('[constructor]')
+      ? 'new' + pascal(fn.name.slice(13))
+      : camel(fn.name.replace(/^\[static\]/, '').replace('.', '-'));
+    if (Object.hasOwn(client, name) || name === 'then')
+      throw new HostError(
+        'unsupported',
+        'export conflicts with client lifecycle',
+      );
+    client[name] = (...args) => call(fn, args);
+  }
+  return Object.freeze(client);
+}

package/index.d.ts

@@ -0,0 +1,199 @@
+/** Stable refusal and failure classifications shared with WIT. ref:DEC-host-sdk-direct-haskell */
+export type Status =
+  'denied' | 'unsupported' | 'cancelled' | 'exhausted' | 'failed';
+/** Reports an operation outcome separately from an exception message. */
+export class HostError extends Error
+{
+  /** Classifies the outcome for programmatic handling. */
+  readonly code: Status;
+  /** Original typed error value when a component returns result::err. */
+  readonly payload?: unknown;
+}
+/** Immutable resource budgets for one runtime instance. */
+export interface Limits
+{
+  /** Aggregate guest linear-memory budget in bytes; excludes trusted host heaps. */
+  memory: number;
+  /** Maximum request or response bytes, with bounded transport overhead. */
+  bytes: number;
+  /** Maximum imported capability calls during the instance lifetime. */
+  requests: number;
+  /** Wasmtime instruction fuel per invocation; browsers use the execution deadline. */
+  fuel: number;
+  /** Startup or invocation deadline in milliseconds; expiration terminates the instance. */
+  timeout: number;
+}
+/** Lets trusted provider implementations cooperate with revocation. */
+export interface ExecutionContext
+{
+  /** Aborts when the instance is revoked or an invocation is cancelled. */
+  signal: AbortSignal;
+}
+/** Authority supplied by the embedding application, never by guest declarations. */
+export type Grant =
+  | {
+      /** Selects the provider whose operations and scope are authorized. */
+      kind: 'files';
+      /** Node directory opened as a capability; never exposed as an ambient WASI preopen. */
+      root?: string;
+      /** Browser-owned directory handle; consent remains the embedding application responsibility. */
+      handle?: FileSystemDirectoryHandle;
+      /** Allows reads within this provider scope. */
+      read?: boolean;
+      /** Allows writes within this provider scope. */
+      write?: boolean;
+    }
+  | {
+      /** Selects the provider whose operations and scope are authorized. */
+      kind: 'network';
+      /** Explicitly permits HTTP in addition to the HTTPS default. */
+      allowHttp?: boolean;
+      /** Approved origin, path and operation combinations; redirects cannot widen them. */
+      destinations: {
+        /** Exact normalized URL origin, including an explicit non-default port. */
+        origin: string;
+        /** Exact URL pathname; defaults to the origin root. */
+        path?: string;
+        /** Also permits descendants under the path segment boundary. */
+        subpaths?: boolean;
+        /** Allowed HTTP methods for this destination. */
+        methods: ('GET' | 'POST')[];
+      }[];
+      /** Explicit application-supplied headers, including any mediated credentials. */
+      headers?: Record<string, string>;
+    }
+  | {
+      /** Selects the provider whose operations and scope are authorized. */
+      kind: 'storage';
+      /** Application/plugin storage namespace; no ambient storage lookup. */
+      namespace: string;
+      /** Maximum UTF-8 bytes of keys and values in the namespace. */
+      quota: number;
+      /** Allows reads within this provider scope. */
+      read?: boolean;
+      /** Allows writes within this provider scope. */
+      write?: boolean;
+    }
+  | {
+      /** Selects the provider whose operations and scope are authorized. */
+      kind: 'environment';
+      /** Explicit environment values; process and page environment are never inherited. */
+      values: Record<string, string>;
+    }
+  | {
+      /** Selects the provider whose operations and scope are authorized. */
+      kind: 'ui';
+      /** Embedding-selected element hosting an isolated text-rendering frame. */
+      surface: HTMLElement;
+    }
+  | {
+      /** Selects the provider whose operations and scope are authorized. */
+      kind: 'native';
+      /** Must return true before this native provider executes an input. */
+      validate(input: string): boolean;
+      /** Trusted application implementation; should cooperate with the cancellation signal. */
+      execute(
+        input: string,
+        context: ExecutionContext,
+      ): string | Promise<string>;
+    }
+  | TrustedGrant;
+/** Embedding-owned escape callback, rejected in the hostile profile. */
+export interface TrustedGrant
+{
+  /** Selects the provider whose operations and scope are authorized. */
+  readonly kind: 'trusted';
+  /** Trusted application implementation; should cooperate with the cancellation signal. */
+  readonly execute: (
+    request: unknown,
+    context: ExecutionContext,
+  ) => string | Promise<string>;
+}
+/** Wraps arbitrary JavaScript execution for the explicit trusted profile. */
+export function trustedJavaScript(
+  execute: TrustedGrant['execute'],
+): TrustedGrant;
+/** Wraps unrestricted DOM execution for the explicit trusted profile. */
+export function trustedDOM(execute: TrustedGrant['execute']): TrustedGrant;
+/** Wraps native FFI execution for the explicit trusted profile. */
+export function trustedNativeFFI(
+  execute: TrustedGrant['execute'],
+): TrustedGrant;
+/** Wraps unsandboxed process execution for the explicit trusted profile. */
+export function trustedProcess(execute: TrustedGrant['execute']): TrustedGrant;
+/** Trusted build output; never construct this authority from a guest manifest. */
+export interface NativeArtifactRegistration
+{
+  readonly artifact: URL | string;
+  readonly componentSha256: string;
+  readonly nativeSha256: string;
+  readonly configuration: string;
+  readonly target: string;
+}
+/** Selects an application-approved artifact and immutable per-instance grants. */
+export interface HostOptions
+{
+  /** Node loads trusted native code prepared during installation; runtime compilation is unavailable. */
+  compilation?: 'precompiled';
+  /** Node authority supplied by trusted embedding code, independent of guest declarations. */
+  nativeArtifacts?: Readonly<Record<string, NativeArtifactRegistration>>;
+  /** Node only: false allows an idle embedding process to exit and releases its helper. */
+  keepAlive?: boolean;
+  /** Required by browser callers; generated by the embedding application's build. */
+  registration?: {
+    readonly manifests: readonly string[];
+    readonly workerURL: URL | string;
+  };
+  /** Host-built component manifest URL; browsers additionally require registry membership. */
+  manifest: URL | string;
+  /** Defaults to hostile; trusted explicitly permits escape callbacks. */
+  profile?: 'hostile' | 'trusted';
+  /** Browser deployment requirements, separate from capability grants. */
+  deployment?: 'standard' | 'isolated';
+  /** Named providers granted by the embedding application. */
+  grants?: Record<string, Grant>;
+  /** Overrides to bounded runtime defaults. */
+  limits?: Partial<Limits>;
+  /** Optional application-owned store shared only through authorized namespaces. */
+  storage?: Map<string, Map<string, string>>;
+}
+/** Records exact artifact and runtime identity without implying proof or cache validity. */
+export interface Identity
+{
+  readonly compilation?: 'precompiled';
+  readonly configuration?: string;
+  readonly target?: string;
+  readonly nativeArtifact?: string | null;
+  /** Unique instance identifier; opaque callbacks and handles prevent general cache equivalence. */
+  readonly instance: string;
+  /** Runtime version and, on Node, the helper binary digest. */
+  readonly runtime: string;
+  /** SHA-256 digest of the original component. */
+  readonly artifact: string;
+  /** Build digest of the SDK provider and loader implementation. */
+  readonly provider: string;
+  /** Digest of serializable grants and limits; opaque callback identity is instance-scoped. */
+  readonly policy: string;
+  /** Versioned exported WIT interface. */
+  readonly interface: string;
+}
+/** Serializes component calls while keeping separate instances independent. */
+export interface HostInstance
+{
+  /** Integrity and policy identifiers for this invocation context. */
+  readonly identity: Identity;
+  /** Calls an exported method; aborting cancels and revokes the whole instance. */
+  invoke(
+    method: string,
+    args?: unknown[],
+    controls?: {signal?: AbortSignal},
+  ): Promise<unknown>;
+  /** Releases an owned exported resource; handles cannot cross instances. */
+  drop(resource: object, controls?: {signal?: AbortSignal}): Promise<void>;
+  /** Terminates the runtime and disposes broker resources. */
+  close(): void;
+  /** Terminates the runtime, rejecting pending and subsequent work as cancelled. */
+  revoke(): void;
+}
+/** Creates an instance or reports unsupported deployment without downgrading isolation. */
+export function createHost(options: HostOptions): Promise<HostInstance>;