feat(embed): add a versioned postMessage API for host pages (#1468)

* feat(embed): add a versioned postMessage API for host pages

URL parameters configure an embed once, at load. A host page that frames
GeoLibre had no way to keep talking to the map: every interaction meant
reloading the iframe with a new `?url=`, throwing away the analyst's
session, and nothing the user did inside the map was visible outside it.

Add an opt-in runtime protocol on top of the existing embed plumbing.
Host to app: `loadProject`, `setView`, `highlightFeature`, `openTool`
(the runtime twin of `?tool=`). App to host: `ready`, `ack`,
`projectLoaded`, `selectionChanged`, `viewChanged` (throttled),
`toolCompleted`, `serverFileWritten`. Every message is versioned
`{v, type, payload}`, and app messages carry `source: "geolibre"` so a
host can filter its own postMessage traffic.

The API is off by default. It activates only when the deployment names
the origins it trusts (`GEOLIBRE_EMBED_ORIGINS` on the Docker image,
`VITE_GEOLIBRE_EMBED_ORIGINS` at build time), so a public deployment can
never be driven by whoever frames it. The allowlist is enforced in both
directions, and setting it also narrows the existing Jupyter/`?embed=1`
project and scripting bridges to those origins.

Fixes #1462

* fix(embed): resolve highlight ids against the layer instead of trusting them

Explicit `featureId`/`featureIds` were passed through unchecked, so a
`highlightFeature` naming an id no feature carries — a typo, or any layer
whose features live in its MapLibre source rather than `layer.geojson` —
selected a phantom id, drew no highlight, and still answered `ack {ok:
true}`. Resolve ids against the layer's features under the same
`String(feature.id ?? index)` convention the map controller uses, and
reject a request that names features but resolves to none, leaving the
user's existing selection untouched. A request naming nothing is still
the documented "clear the highlight" form.

Also fix the docs claim that outbound messages are never addressed to
`*` (they are, before the handshake, when the `*` wildcard is
configured), type the null-geometry test fixtures as `Feature<null>[]`
(`Feature` defaults its geometry parameter to `Geometry`), and match the
surrounding assertion style in one test.

Author: giswqs

Dockerfile

@@ -27,10 +27,15 @@ ARG VITE_MAPILLARY_ACCESS_TOKEN=
 # Set to 1 (or true) to disable the first-launch welcome wizard for the whole
 # deployment; visitors land straight on the map.
 ARG VITE_WELCOME_DISABLED=
+# Comma-separated origins allowed to drive a framed app over the embed
+# postMessage API. Usually set at RUN time instead (-e GEOLIBRE_EMBED_ORIGINS=…),
+# which the entrypoint writes into the runtime config without a rebuild.
+ARG VITE_GEOLIBRE_EMBED_ORIGINS=
 ENV GEOLIBRE_APP_BASE=${GEOLIBRE_APP_BASE}
 ENV VITE_GEE_OAUTH_CLIENT_ID=${VITE_GEE_OAUTH_CLIENT_ID}
 ENV VITE_MAPILLARY_ACCESS_TOKEN=${VITE_MAPILLARY_ACCESS_TOKEN}
 ENV VITE_WELCOME_DISABLED=${VITE_WELCOME_DISABLED}
+ENV VITE_GEOLIBRE_EMBED_ORIGINS=${VITE_GEOLIBRE_EMBED_ORIGINS}
 
 RUN npm run build
 

apps/geolibre-desktop/src/components/layout/DesktopShell.tsx

@@ -114,6 +114,7 @@ import { KnowledgeCardConsentDialog } from "./KnowledgeCardConsentDialog";
 import { MapGrid } from "./MapGrid";
 import { RemoteCursorsOverlay } from "./RemoteCursorsOverlay";
 import { useCommandBridge } from "../../hooks/useCommandBridge";
+import { useEmbedApi } from "../../hooks/useEmbedApi";
 import { useJupyterRelay } from "../../hooks/useJupyterRelay";
 import { appendDiagnostic, useDiagnosticsSnapshot } from "../../lib/diagnostics";
 import { SectionErrorBoundary, SilentErrorBoundary } from "../common/error-boundaries";
@@ -748,6 +749,10 @@ export function DesktopShell({
   // Request/reply + event channel backing the Python scripting API (live
   // queries, processing, map events). Also inert when not embedded.
   useCommandBridge(mapControllerRef);
+  // Runtime postMessage API for a third-party host page that frames the app
+  // (fly to a record, highlight it, open a tool; selection/view/tool events back
+  // out). Off unless the deployment configured GEOLIBRE_EMBED_ORIGINS.
+  useEmbedApi(mapControllerRef);
   // Same scripting surface, reached over the desktop Jupyter server's relay, so
   // a kernel driven from an EXTERNAL client (VS Code's Jupyter extension) can
   // control the map too. Inert until that server is running.

apps/geolibre-desktop/src/hooks/embedHost.ts

@@ -4,6 +4,8 @@
 // (useCommandBridge) talk to the SAME host window and must apply the SAME trust
 // rules, so the detection and origin handshake live here once.
 
+import { EMBED_ORIGIN_WILDCARD, isEmbedOriginAllowed, readEmbedOrigins } from "../lib/embed-api";
+
 /**
  * Detects whether the app is running inside the GeoLibre Jupyter/embed host.
  *
@@ -21,7 +23,10 @@
  * broadcasts full project state to it. Because the legitimate hosts (the Jupyter
  * widget, Colab's proxy) have arbitrary, unknowable origins, an origin allowlist
  * is not viable here; instead the deployment constraint is: an `?embed=1`
- * export must only be served from a trusted context, never a public URL.
+ * export must only be served from a trusted context, never a public URL. A
+ * deployment that *can* name its hosts (a web build framed by a portal) should
+ * set `GEOLIBRE_EMBED_ORIGINS`, which both enables the embed API
+ * (`hooks/useEmbedApi.ts`) and narrows these bridges to those origins.
  *
  * @returns True when the postMessage bridges should be active.
  */
@@ -64,6 +69,11 @@ export interface EmbedHost {
   readonly handshakeComplete: boolean;
   /** Origin to scope outbound posts to (`"*"` until the host is identified). */
   targetOrigin(): string;
+  /**
+   * Origins a pre-handshake broadcast (the `ready` ping) may go to: the known
+   * host origin, else every allowlisted origin, else `["*"]`.
+   */
+  broadcastTargets(): string[];
   /**
    * Record an inbound message from the host: marks the handshake complete and
    * learns the host's origin. Returns true when the message actually came from
@@ -77,9 +87,17 @@ export interface EmbedHost {
  * always defined; when the app is the top-level document (the `?embed=1`
  * self-test) it is `window` itself, so the bridge naturally posts to and
  * receives from itself.
+ *
+ * When the deployment configured an embed-API origin allowlist
+ * (`GEOLIBRE_EMBED_ORIGINS`), it applies here too: a host whose origin is not
+ * listed never completes the handshake, so an operator who names their trusted
+ * hosts also narrows the `?embed=1` project/scripting bridges to them. With no
+ * allowlist configured nothing changes (the Jupyter widget's host origin is
+ * arbitrary and unknowable, so it cannot be listed in advance).
  */
 export function createEmbedHost(): EmbedHost {
   const host = window.parent;
+  const allowedOrigins = readEmbedOrigins();
   let hostOrigin: string | null = null;
   let handshakeComplete = false;
   return {
@@ -88,8 +106,18 @@ export function createEmbedHost(): EmbedHost {
       return handshakeComplete;
     },
     targetOrigin: () => hostOrigin ?? "*",
+    broadcastTargets: () => {
+      if (hostOrigin) return [hostOrigin];
+      if (allowedOrigins.length === 0 || allowedOrigins.includes(EMBED_ORIGIN_WILDCARD)) {
+        return [EMBED_ORIGIN_WILDCARD];
+      }
+      return allowedOrigins;
+    },
     note(event: MessageEvent): boolean {
       if (event.source !== host) return false;
+      if (allowedOrigins.length > 0 && !isEmbedOriginAllowed(event.origin, allowedOrigins)) {
+        return false;
+      }
       handshakeComplete = true;
       // "null" (opaque/file origins) stays "*".
       if (event.origin && event.origin !== "null") hostOrigin = event.origin;