@greensecurity/javascript-sdk 0.46.0-beta.5 → 0.46.0-beta.7

package/src/apps/review.ts

@@ -0,0 +1,253 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md (C18).
+ *
+ * The automated review every catalog submission goes through, as data the server and the CLI
+ * share: which permissions count as sensitive, how long a `purpose` and a `justification` must be,
+ * and which CSP hosts are never accepted. The server reads the JSON these are written to
+ * (`shared/app-platform/review-rules.json` and `csp-denylist.json`); `src/__tests__/apps` keeps the
+ * files in step. Deliberately dependency-free (no zod), like `url.ts`.
+ */
+
+/**
+ * The thresholds and lists the review applies to a submission's added permissions.
+ *
+ * - `purpose_min_chars`: the shortest `purpose` accepted for an added permission, after trimming.
+ * - `justification_min_chars`: the shortest `justification` accepted for an added sensitive
+ *   permission, after trimming.
+ * - `read_only_actions`: the permission actions that only read. Every other action (`add`, `edit`,
+ *   `delete`, `write`, and any added later) writes, and a permission that writes is sensitive.
+ * - `pii_resources`: the resources whose records identify people or describe them (names, contact
+ *   details, credentials, background checks, visits, payment details). Reading one is sensitive.
+ */
+export const REVIEW_RULES = Object.freeze({
+  purpose_min_chars: 30,
+  justification_min_chars: 40,
+  read_only_actions: Object.freeze(["view", "search"] as const),
+  pii_resources: Object.freeze([
+    "background_checks",
+    "communications",
+    "company_managers",
+    "contacts",
+    "credentials",
+    "criminal_history",
+    "events",
+    "invoices",
+    "mobile_devices",
+    "payment_profiles",
+    "users",
+    "vendor_credentials",
+    "vendor_scans",
+    "vendor_transactions",
+    "vendors",
+    "visitor_checkins",
+    "visitors",
+    "watchlist_entries",
+  ] as const),
+} as const);
+
+const READ_ONLY_ACTIONS: ReadonlySet<string> = new Set(REVIEW_RULES.read_only_actions);
+const PII_RESOURCES: ReadonlySet<string> = new Set(REVIEW_RULES.pii_resources);
+
+/**
+ * Whether a `resource.action` permission is sensitive: it writes (any action that is not read-only)
+ * or it reads a resource about people. A sensitive permission added by a submission needs a
+ * `justification` as well as a `purpose`, and holds the submission for a Green Security admin.
+ */
+export function isSensitivePermission(permission: string): boolean {
+  const dot = permission.indexOf(".");
+  if (dot <= 0 || dot === permission.length - 1) return true;
+
+  const resource = permission.slice(0, dot);
+  const action = permission.slice(dot + 1);
+  return !READ_ONLY_ACTIONS.has(action) || PII_RESOURCES.has(resource);
+}
+
+/** Why a host is on the denylist. */
+export type CspDenylistCategory = "tunnel" | "pastebin" | "url_shortener" | "raw_code_host" | "dynamic_dns";
+
+export interface CspDenylistEntry {
+  /** A registrable domain or host. It matches itself and every name under it. */
+  domain: string;
+  category: CspDenylistCategory;
+}
+
+function entries(category: CspDenylistCategory, domains: readonly string[]): CspDenylistEntry[] {
+  return domains.map((domain) => ({ domain, category }));
+}
+
+/**
+ * Hosts a submission may never add to `connect_src` or `image_src`, nor serve its bundle from. Each
+ * lets anybody publish content, or point a name at any address, without owning a domain, so an app
+ * that could reach one could reach anything:
+ *
+ * - `tunnel`: expose a local server under a shared domain;
+ * - `pastebin`: host arbitrary text, including code and exfiltrated data;
+ * - `url_shortener`: redirect to a destination the review never saw;
+ * - `raw_code_host`: serve files straight out of anybody's repository or gist;
+ * - `dynamic_dns`: hand out names under a shared domain, including the wildcard DNS services that
+ *   resolve a name such as `10.0.0.1.nip.io` to the IP address inside it.
+ */
+export const CSP_DENYLIST: readonly CspDenylistEntry[] = Object.freeze([
+  ...entries("tunnel", [
+    "trycloudflare.com",
+    "ngrok.io",
+    "ngrok.app",
+    "ngrok.dev",
+    "ngrok-free.app",
+    "ngrok-free.dev",
+    "loca.lt",
+    "localtunnel.me",
+    "localhost.run",
+    "lhr.life",
+    "serveo.net",
+    "serveousercontent.com",
+    "pagekite.me",
+    "tunnelto.dev",
+    "bore.pub",
+    "loclx.io",
+    "localxpose.io",
+    "pinggy.io",
+    "pinggy.link",
+    "devtunnels.ms",
+    "tunnelmole.net",
+    "localtonet.com",
+    "zrok.io",
+    "sharedwithexpose.com",
+  ]),
+  ...entries("pastebin", [
+    "pastebin.com",
+    "paste.ee",
+    "hastebin.com",
+    "rentry.co",
+    "dpaste.com",
+    "dpaste.org",
+    "paste.rs",
+    "termbin.com",
+    "controlc.com",
+    "justpaste.it",
+    "privatebin.net",
+    "pastes.dev",
+    "ix.io",
+    "sprunge.us",
+  ]),
+  ...entries("url_shortener", [
+    "bit.ly",
+    "tinyurl.com",
+    "t.co",
+    "goo.gl",
+    "ow.ly",
+    "is.gd",
+    "v.gd",
+    "buff.ly",
+    "rebrand.ly",
+    "cutt.ly",
+    "shorturl.at",
+    "rb.gy",
+    "tiny.cc",
+    "t.ly",
+    "bl.ink",
+  ]),
+  ...entries("raw_code_host", [
+    "raw.githubusercontent.com",
+    "gist.githubusercontent.com",
+    "gist.github.com",
+    "raw.githack.com",
+    "rawcdn.githack.com",
+    "cdn.statically.io",
+  ]),
+  ...entries("dynamic_dns", [
+    "duckdns.org",
+    "no-ip.com",
+    "no-ip.org",
+    "ddns.net",
+    "hopto.org",
+    "zapto.org",
+    "sytes.net",
+    "dynu.com",
+    "dynu.net",
+    "dyndns.org",
+    "dynalias.com",
+    "changeip.com",
+    "afraid.org",
+    "mooo.com",
+    "dedyn.io",
+    "nsupdate.info",
+    "ydns.eu",
+    "dynv6.net",
+    "nip.io",
+    "sslip.io",
+    "xip.io",
+    "traefik.me",
+    "localtest.me",
+  ]),
+]);
+
+/**
+ * The denylist entry a host falls under, or `undefined` when it is on none: the host is the entry's
+ * domain or a name under it (`abc.trycloudflare.com`). Case and a trailing dot are ignored.
+ */
+export function cspDenylistEntry(host: string): CspDenylistEntry | undefined {
+  const name = host.toLowerCase().replace(/\.$/, "");
+  return CSP_DENYLIST.find((entry) => name === entry.domain || name.endsWith(`.${entry.domain}`));
+}
+
+/** One problem the review would find with an added permission, as the catalog reports it. */
+export interface PermissionReviewIssue {
+  code: "purpose_too_short" | "purpose_is_permission_name" | "purpose_repeated" | "justification_required"
+    | "justification_too_short" | "justification_repeats_purpose";
+  path: string;
+  message: string;
+}
+
+/** Lower case, with every run of non-alphanumerics collapsed to one space: how two texts are compared. */
+function normalizedText(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+/**
+ * The justification rules the review applies to the permissions a submission adds, so the CLI can
+ * report them before upload. `added` names the permissions that are new since the last accepted
+ * version; the rest are not checked. Every entry's `purpose` counts when looking for repeats.
+ */
+export function permissionReviewIssues(
+  permissions: ReadonlyArray<{ permission: string; purpose: string; justification?: string | undefined }>,
+  added: ReadonlySet<string>,
+): PermissionReviewIssue[] {
+  const issues: PermissionReviewIssue[] = [];
+  const purposeCounts = new Map<string, number>();
+  for (const entry of permissions) {
+    const key = normalizedText(entry.purpose);
+    purposeCounts.set(key, (purposeCounts.get(key) ?? 0) + 1);
+  }
+
+  permissions.forEach((entry, index) => {
+    if (!added.has(entry.permission)) return;
+
+    const path = `permissions.${index}`;
+    const purpose = normalizedText(entry.purpose);
+    const [resource = "", action = ""] = entry.permission.split(".");
+    if (entry.purpose.trim().length < REVIEW_RULES.purpose_min_chars) {
+      issues.push({ code: "purpose_too_short", path: `${path}.purpose`, message: `must be at least ${REVIEW_RULES.purpose_min_chars} characters and say what the app does with ${entry.permission}` });
+    }
+    if ([normalizedText(entry.permission), normalizedText(resource), normalizedText(`${action} ${resource}`)].includes(purpose)) {
+      issues.push({ code: "purpose_is_permission_name", path: `${path}.purpose`, message: "must explain what the app does with the permission, not repeat its name" });
+    }
+    if ((purposeCounts.get(purpose) ?? 0) > 1) {
+      issues.push({ code: "purpose_repeated", path: `${path}.purpose`, message: "must be written for this permission; another permission has the same purpose" });
+    }
+
+    if (!isSensitivePermission(entry.permission)) return;
+
+    const justification = entry.justification?.trim() ?? "";
+    if (justification.length === 0) {
+      issues.push({ code: "justification_required", path: `${path}.justification`, message: `${entry.permission} is sensitive and needs a justification explaining why the app cannot work without it` });
+    } else if (justification.length < REVIEW_RULES.justification_min_chars) {
+      issues.push({ code: "justification_too_short", path: `${path}.justification`, message: `must be at least ${REVIEW_RULES.justification_min_chars} characters` });
+    } else if (normalizedText(justification) === purpose) {
+      issues.push({ code: "justification_repeats_purpose", path: `${path}.justification`, message: "must say why the permission is needed, not repeat its purpose" });
+    }
+  });
+
+  return issues;
+}

package/src/apps/route.ts

@@ -0,0 +1,44 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md.
+ *
+ * Apps never navigate by path. They name a destination and the host maps it to its own routes,
+ * which keeps host URLs free to change and stops an app from steering users to arbitrary pages.
+ */
+
+import { isSurfaceId, type SurfaceId } from "./surfaces.js";
+
+/** Values the destination view receives as `environment.queryParams`. Strings only. */
+export type EnvParams = Record<string, string>;
+
+export type RouteDescriptor =
+  /** The screen a surface lives on, optionally for one record (detail surfaces). */
+  | { type: "surface"; surfaceId: SurfaceId; objectId?: number; envParams?: EnvParams }
+  /** The calling app's own settings page (the `settings` surface). */
+  | { type: "appSettings"; envParams?: EnvParams };
+
+export function isRouteDescriptor(value: unknown): value is RouteDescriptor {
+  if (typeof value !== "object" || value === null || !("type" in value)) return false;
+
+  const v = value as Record<string, unknown>;
+  if (v["envParams"] !== undefined && !isEnvParams(v["envParams"])) return false;
+
+  switch (v["type"]) {
+    case "surface":
+      // Only catalog surfaces: the host has no route for anything else. Safe integers only, so a
+      // record id is never silently rounded on its way through JSON. `settings` is reachable only
+      // as `appSettings`, which always means the calling app: as a plain surface its `objectId`
+      // would name another app's settings page.
+      return isSurfaceId(v["surfaceId"]) && v["surfaceId"] !== "settings" &&
+        (v["objectId"] === undefined || (Number.isSafeInteger(v["objectId"]) && (v["objectId"] as number) > 0));
+    case "appSettings":
+      return true;
+    default:
+      return false;
+  }
+}
+
+function isEnvParams(value: unknown): value is EnvParams {
+  return typeof value === "object" && value !== null && !Array.isArray(value) &&
+    Object.values(value).every((v) => typeof v === "string");
+}

package/src/apps/runtime/console.ts

@@ -0,0 +1,118 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * Dev sessions only (`context.environment.devSessionId`): mirrors the worker's `console.*`
+ * calls to the host so `apps-cli dev` can print them. `HostApi` has no log method, so the
+ * runtime posts C0's `BootstrapToHost` `log` envelope on the worker channel, next to (not
+ * inside) the thread traffic. The bootstrap is expected to forward it to the host as-is; see
+ * `transport.ts` for the channel assumptions.
+ *
+ * Forwarded lines leave the sandbox, so credentials are redacted from them first: the current
+ * access tokens of every mounted view (passed in by the runtime), anything token-shaped
+ * (`gsu_…`, `gsi_…`, `gsd_…`, `gsdr_…`), and the value of any `Bearer` credential. The worker's
+ * own console still gets the original arguments.
+ */
+
+import type { BootstrapToHost } from "../protocol.js";
+
+export type LogEnvelope = Extract<BootstrapToHost, { kind: "log" }>;
+export type LogLevel = LogEnvelope["level"];
+
+/** Longest message forwarded; well under C0's `MAX_ENVELOPE_CHARS`. */
+export const MAX_LOG_MESSAGE_CHARS = 8_000;
+
+/** What a credential is replaced with in a forwarded line. */
+export const REDACTED = "[redacted]";
+
+/** Green Security token prefixes (`gsu_`, `gsi_`, `gsd_`, `gsdr_`, …) and what follows them. */
+const TOKEN_SHAPED = /\bgs[a-z]{1,4}_[A-Za-z0-9._~+/=-]+/g;
+/** The credential after `Bearer`, as it appears in an Authorization header. */
+const BEARER = /\b(Bearer\s+)[^\s"',;]+/gi;
+/** Shorter strings are not treated as secrets, so a blank or tiny token cannot blank the log. */
+const MIN_SECRET_LENGTH = 8;
+
+export interface ForwardConsoleOptions {
+  /** Current secrets (the mounted views' access tokens), read on every forwarded line. */
+  secrets?: () => Iterable<string>;
+}
+
+/** Removes credentials from a line about to leave the sandbox. */
+export function redactLogMessage(message: string, secrets: Iterable<string> = []): string {
+  let text = message;
+  for (const secret of secrets) {
+    if (typeof secret === "string" && secret.length >= MIN_SECRET_LENGTH) text = text.split(secret).join(REDACTED);
+  }
+  return text.replace(BEARER, `$1${REDACTED}`).replace(TOKEN_SHAPED, REDACTED);
+}
+
+const METHODS: ReadonlyArray<[method: "debug" | "info" | "log" | "warn" | "error", level: LogLevel]> = [
+  ["debug", "debug"],
+  ["info", "info"],
+  ["log", "info"],
+  ["warn", "warn"],
+  ["error", "error"],
+];
+
+let restore: (() => void) | undefined;
+
+/**
+ * Patches `console` once; later calls replace the sink. Returns a function that restores the
+ * original methods.
+ */
+export function forwardConsole(
+  post: (envelope: LogEnvelope) => void,
+  target: Console = console,
+  options: ForwardConsoleOptions = {},
+): () => void {
+  restore?.();
+
+  const originals = new Map<string, (...args: unknown[]) => void>();
+  let forwarding = false;
+
+  for (const [method, level] of METHODS) {
+    const original = target[method].bind(target) as (...args: unknown[]) => void;
+    originals.set(method, target[method] as (...args: unknown[]) => void);
+
+    target[method] = (...args: unknown[]) => {
+      original(...args);
+      if (forwarding) return; // a failing `post` that logs must not recurse
+      forwarding = true;
+      try {
+        post({ kind: "log", level, message: formatLogArgs(args, options.secrets?.() ?? []) });
+      } catch {
+        // Logging must never break the app.
+      } finally {
+        forwarding = false;
+      }
+    };
+  }
+
+  const undo = () => {
+    for (const [method, original] of originals) {
+      (target as unknown as Record<string, unknown>)[method] = original;
+    }
+    if (restore === undo) restore = undefined;
+  };
+  restore = undo;
+  return undo;
+}
+
+/** Formats `console` arguments into one redacted line, truncated to {@link MAX_LOG_MESSAGE_CHARS}. */
+export function formatLogArgs(args: readonly unknown[], secrets: Iterable<string> = []): string {
+  // Redacted before truncating, so a cut can never leave the start of a credential behind.
+  const text = redactLogMessage(args.map(formatValue).join(" "), secrets);
+  return text.length > MAX_LOG_MESSAGE_CHARS ? `${text.slice(0, MAX_LOG_MESSAGE_CHARS - 1)}…` : text;
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return value.stack ?? `${value.name}: ${value.message}`;
+  if (typeof value === "function") return `[function ${value.name || "anonymous"}]`;
+  if (typeof value === "bigint" || typeof value === "symbol") return value.toString();
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/apps/runtime/elements.ts

@@ -0,0 +1,100 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * One remote custom element per entry of the C0 component catalog, built from the catalog
+ * itself so the SDK and the host renderer cannot drift apart:
+ *  - every declared prop becomes a remote property (sent to the host as a property update);
+ *  - every declared event becomes a remote event listener named by `EventSpec.event`
+ *    (`press`, `change`, `shownchange`, `save`, ...). The host calls the listener with the
+ *    event's `detail` as its only argument;
+ *  - every declared slot becomes a remote slot. Slotted content arrives at the host as a
+ *    `remote-fragment` child whose `slot` attribute names the slot.
+ */
+
+import { polyfillInstalled } from "./polyfill.js";
+import {
+  createRemoteElement,
+  RemoteFragmentElement,
+  RemoteRootElement,
+  type RemoteElementConstructor,
+  type RemoteElementPropertyDefinition,
+} from "@remote-dom/core/elements";
+import { COMPONENTS, type ComponentName, type ComponentSpec, type PropSpec } from "../components.js";
+
+export const REMOTE_ROOT_TAG = "remote-root";
+export const REMOTE_FRAGMENT_TAG = "remote-fragment";
+
+/** Loose constructor type shared by every catalog element. */
+export type CatalogElementConstructor = RemoteElementConstructor<
+  Record<string, unknown>,
+  Record<string, never>,
+  Record<string, unknown>,
+  Record<string, unknown>
+>;
+
+function propertyType(spec: PropSpec): NonNullable<RemoteElementPropertyDefinition["type"]> {
+  switch (spec.type) {
+    case "string":
+    case "enum":
+    case "imageSrc":
+      return String;
+    case "number":
+      return Number;
+    case "boolean":
+      return Boolean;
+    // `href` is a RouteDescriptor or a string; `json` is a plain object. Both travel as-is.
+    case "href":
+    case "json":
+      return Object;
+  }
+}
+
+function buildElement(spec: ComponentSpec): CatalogElementConstructor {
+  const properties: Record<string, RemoteElementPropertyDefinition> = {};
+  for (const [name, propSpec] of Object.entries(spec.props)) {
+    properties[name] = { type: propertyType(propSpec) };
+  }
+
+  return createRemoteElement<
+    Record<string, unknown>,
+    Record<string, never>,
+    Record<string, unknown>,
+    Record<string, unknown>
+  >({
+    properties,
+    events: Object.values(spec.events).map((e) => e.event),
+    slots: [...spec.slots],
+  });
+}
+
+const CATALOG = COMPONENTS as Readonly<Record<ComponentName, ComponentSpec>>;
+
+/** The element class for each catalog component, keyed by component name. */
+export const ELEMENTS: Readonly<Record<ComponentName, CatalogElementConstructor>> = Object.fromEntries(
+  (Object.keys(CATALOG) as ComponentName[]).map((name) => [name, buildElement(CATALOG[name])]),
+) as Record<ComponentName, CatalogElementConstructor>;
+
+let defined = false;
+
+/**
+ * Registers `remote-root`, `remote-fragment` and every catalog tag with the polyfilled
+ * `customElements` registry. Idempotent, and tolerant of a tag another copy of the SDK already
+ * registered (a second registration would throw).
+ */
+export function defineRemoteElements(): void {
+  if (defined) return;
+  if (!polyfillInstalled()) throw new Error("The remote-dom polyfill is not installed");
+
+  defineOnce(REMOTE_ROOT_TAG, RemoteRootElement);
+  // Its published typings lose the HTMLElement base (an extensionless import); it is one.
+  defineOnce(REMOTE_FRAGMENT_TAG, RemoteFragmentElement as unknown as CustomElementConstructor);
+  for (const name of Object.keys(ELEMENTS) as ComponentName[]) {
+    defineOnce(CATALOG[name].tagName, ELEMENTS[name]);
+  }
+  defined = true;
+}
+
+function defineOnce(tagName: string, ctor: CustomElementConstructor): void {
+  if (!customElements.get(tagName)) customElements.define(tagName, ctor);
+}

package/src/apps/runtime/index.ts

@@ -0,0 +1,84 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * Import as `@greensecurity/javascript-sdk/apps/runtime`.
+ *
+ * ```ts
+ * import { defineApp } from "@greensecurity/javascript-sdk/apps/runtime";
+ * defineApp({ views: { VendorPanel, AppSettings } });
+ * ```
+ */
+
+import { polyfillInstalled } from "./polyfill.js";
+import type { SandboxExports } from "../protocol.js";
+import { createSandboxExports, type AppDefinition, type SandboxRuntime, type SandboxRuntimeOptions } from "./sandbox.js";
+import { exposeSandbox, isWorkerGlobalScope, type ExposedSandbox, type MessageEndpoint, RuntimeChannel } from "./transport.js";
+
+export { createSandboxExports, MUTATION_BATCH_MS, type AppDefinition, type SandboxRuntime, type SandboxRuntimeOptions } from "./sandbox.js";
+export { ExtensionContextProvider, type ExtensionContextProviderProps } from "./provider.js";
+export {
+  exposeSandbox,
+  isWorkerGlobalScope,
+  PORT_HANDOFF_KIND,
+  RuntimeChannel,
+  type ExposedSandbox,
+  type MessageEndpoint,
+  type PortHandoffMessage,
+} from "./transport.js";
+export {
+  forwardConsole,
+  formatLogArgs,
+  MAX_LOG_MESSAGE_CHARS,
+  REDACTED,
+  redactLogMessage,
+  type ForwardConsoleOptions,
+  type LogEnvelope,
+  type LogLevel,
+} from "./console.js";
+export { defineRemoteElements, ELEMENTS, REMOTE_FRAGMENT_TAG, REMOTE_ROOT_TAG } from "./elements.js";
+export { TokenStore, type TokenKind, type TokenSource } from "./session.js";
+
+export interface DefineAppOptions extends Omit<SandboxRuntimeOptions, "postLog"> {
+  /**
+   * Where to serve `SandboxExports`. Defaults to the worker's global scope when running in a
+   * Web Worker; outside one (tests, SSR) nothing is exposed unless you pass an endpoint.
+   */
+  endpoint?: MessageEndpoint | RuntimeChannel;
+}
+
+export interface DefinedApp {
+  /** The `SandboxExports` implementation, also callable directly (tests use this). */
+  exports: SandboxRuntime;
+  /**
+   * Present when the exports are served over a thread; resolves once the thread is answering.
+   * Messages that arrive before then are held, not dropped.
+   */
+  exposed?: Promise<ExposedSandbox>;
+}
+
+/**
+ * Registers your views and starts serving them to the host. Call it once, at the top level of
+ * your bundle's entry file. The bundle should not `export` anything: the host loads it as a
+ * worker script.
+ */
+export function defineApp(definition: AppDefinition, options: DefineAppOptions = {}): DefinedApp {
+  if (!polyfillInstalled()) throw new Error("The remote-dom polyfill failed to install");
+
+  const { endpoint, ...runtimeOptions } = options;
+  let channel: RuntimeChannel | undefined;
+  if (endpoint instanceof RuntimeChannel) channel = endpoint;
+  else if (endpoint) channel = new RuntimeChannel(endpoint);
+  else if (isWorkerGlobalScope()) channel = new RuntimeChannel(globalThis as unknown as MessageEndpoint);
+
+  const exports = createSandboxExports(definition, {
+    ...runtimeOptions,
+    ...(channel ? { postLog: (envelope) => channel.postLog(envelope) } : {}),
+  });
+
+  if (!channel) return { exports };
+  const exposed = exposeSandbox(exports satisfies SandboxExports, { endpoint: channel });
+  // Nothing in a worker entry awaits this, so report a failed load instead of an unhandled rejection.
+  exposed.catch((error: unknown) => console.error("[green-app] could not start the host connection:", error));
+  return { exports, exposed };
+}

package/src/apps/runtime/polyfill.ts

@@ -0,0 +1,25 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * Installs the DOM polyfill an app's worker needs before anything touches `HTMLElement`.
+ * Order matters: `@remote-dom/core/polyfill` creates `window`, `document`, `HTMLElement` and
+ * `customElements`, then `installReactDomShims` adds what react-dom probes for
+ * (`HTMLIFrameElement`, `location`, `navigator`, `Element#style`).
+ *
+ * Every module in this kit that imports `@remote-dom/core/elements` imports this module first,
+ * and uses `remoteWindow` so bundlers cannot drop the import: the SDK package is
+ * `sideEffects: false`, so a bare `import "./polyfill.js"` would be tree-shaken away.
+ */
+
+import { window as remoteWindow } from "@remote-dom/core/polyfill";
+import { installReactDomShims } from "./react-dom-shims.js";
+
+installReactDomShims(remoteWindow);
+
+export { remoteWindow };
+
+/** True once the polyfilled `window` is in place. Referencing it keeps this module in bundles. */
+export function polyfillInstalled(): boolean {
+  return typeof remoteWindow === "object" && remoteWindow !== null;
+}