rpc-iframe 0.2.0

package/LICENSE

@@ -0,0 +1,38 @@
+MIT License
+
+Copyright (c) 2026 AdriAir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+ADDITIONAL DISCLAIMER:
+
+This software facilitates communication between web applications and iframes
+using the browser's postMessage API. Users of this software are solely
+responsible for:
+
+1. Validating and sanitizing all data exchanged between frames
+2. Properly configuring origin restrictions to prevent unauthorized access
+3. Implementing additional security measures appropriate to their use case
+4. Understanding and mitigating security risks inherent in cross-origin
+   communication
+
+The authors make no guarantees regarding the security, reliability, or
+fitness for any particular purpose of this software. This is experimental
+software and should not be used in production environments without thorough
+security review and testing.

package/README.md

@@ -0,0 +1,101 @@
+# RPC iFrame
+
+![npm](https://img.shields.io/npm/v/rpc-iframe)
+
+Type-safe RPC between iframes. Call methods across frames like they're local functions.
+
+```typescript
+// Parent
+const { remote } = await connectIframe<ChildAPI>(iframe, {
+    targetOrigin: "https://child.example.com",
+});
+
+const result = await remote.add(2, 3); // 5 — typed, async, done.
+```
+
+```typescript
+// Child
+expose(
+    {
+        async add(a: number, b: number) {
+            return a + b;
+        },
+    },
+    { allowedOrigin: "https://parent.example.com" },
+);
+```
+
+That's it. No glue code, no message parsing, no `postMessage` boilerplate.
+
+Works in both TypeScript and vanilla JavaScript. Types are optional.
+
+> **v0.2.0 — Experimental.** API may change before v1.0. Not recommended for production without thorough testing.
+
+## Use cases
+
+- Micro-frontends communicating across domains
+- Embedded widgets (payments, auth, analytics)
+- Secure sandboxed apps
+
+## Features
+
+- Typed RPC over `postMessage`
+- Promise-based async calls
+- Automatic handshake + origin validation
+- Functional and OOP APIs
+- Works cross-origin, no server, no bundler required
+- ESM + CJS builds
+
+## How it works
+
+The child exposes an API.
+The parent connects via a secure handshake.
+All method calls are proxied over `postMessage` as typed async RPC.
+
+> If using the `sandbox` attribute on your iframe, make sure to allow `allow-scripts` and `allow-same-origin`.
+
+## Why RPC-iFrame
+
+If you work with iframes, you know the pain: raw `postMessage`, manual serialization, no types, origin checks scattered everywhere, zero error context when something breaks.
+
+RPC-iFrame replaces all of that with a single abstraction: **typed RPC**. You define an interface, expose it from the child, and call it from the parent. The runtime handles handshakes, security, and cleanup.
+
+## Install
+
+```bash
+npm install rpc-iframe
+```
+
+## What's next
+
+Future versions will add:
+
+- Contract validation (fail-fast if the child doesn't expose what the parent expects)
+- API discovery (the child advertises its schema during handshake)
+- Dev diagnostics (structured logs for every connection and call)
+- Micro-frontend lifecycle helpers (lazy loading, reconnection, health checks)
+
+Check the full [Roadmap](docs/roadmap.md) for details.
+
+## Docs
+
+| Document                                   | What you'll find                                          |
+| ------------------------------------------ | --------------------------------------------------------- |
+| [Getting Started](docs/getting-started.md) | Installation, quick start, functional & OOP API usage     |
+| [API Reference](docs/api-reference.md)     | Full API surface, configuration options, TypeScript types |
+| [Architecture](docs/architecture.md)       | Internal design, protocol, transport, RPC flow diagram    |
+| [Security](docs/security.md)               | Origin validation, method exposure, nonce handshake       |
+| [Examples](docs/examples.md)               | Payments, micro-frontends, sandboxing, cross-domain data  |
+| [Compatibility](docs/compatibility.md)     | Browser support table, module formats (ESM/CJS)           |
+| [Roadmap](docs/roadmap.md)                 | v0.1 → v1.0 — every milestone and what it unlocks         |
+
+## Contributing
+
+Contributions are welcome. Open a PR or file an issue.
+
+**Repository:** [github.com/AdriAir/iFrameConnector](https://github.com/AdriAir/iFrameConnector)
+**Issues:** [github.com/AdriAir/iFrameConnector/issues](https://github.com/AdriAir/iFrameConnector/issues)
+
+## License
+
+MIT — Copyright (c) 2026 AdriAir. See [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,321 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  IframeConnection: () => IframeConnection,
+  IframeExposed: () => IframeExposed,
+  connectIframe: () => connectIframe,
+  expose: () => expose
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/protocol.ts
+var IFC_BRAND = "__ifc__";
+function isProtocolMessage(data) {
+  return typeof data === "object" && data !== null && data.__ifc === IFC_BRAND;
+}
+function createHandshakeRequest(nonce) {
+  return { __ifc: IFC_BRAND, type: "handshake-request", nonce };
+}
+function createHandshakeResponse(nonce) {
+  return { __ifc: IFC_BRAND, type: "handshake-response", nonce };
+}
+function createRequest(id, method, args) {
+  return { __ifc: IFC_BRAND, type: "request", id, method, args };
+}
+function createResponse(id, result) {
+  return { __ifc: IFC_BRAND, type: "response", id, result };
+}
+function createError(id, error) {
+  return { __ifc: IFC_BRAND, type: "error", id, error };
+}
+function generateId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `ifc-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+}
+
+// src/core/transport.ts
+var Transport = class {
+  /**
+   * @param target       Window to communicate with (iframe.contentWindow or window.parent).
+   * @param targetOrigin Expected origin of the remote side. '*' disables origin checks.
+   */
+  constructor(target, targetOrigin) {
+    this.callbacks = /* @__PURE__ */ new Set();
+    this.target = target;
+    this.targetOrigin = targetOrigin;
+    this.handleMessage = (event) => {
+      if (this.targetOrigin !== "*" && event.origin !== this.targetOrigin)
+        return;
+      if (!isProtocolMessage(event.data)) return;
+      for (const cb of this.callbacks) {
+        cb(event.data, event.origin);
+      }
+    };
+    window.addEventListener("message", this.handleMessage);
+  }
+  /** Post a protocol message to the remote window. */
+  send(message) {
+    this.target.postMessage(message, this.targetOrigin);
+  }
+  /** Subscribe to incoming protocol messages. Returns an unsubscribe function. */
+  onMessage(callback) {
+    this.callbacks.add(callback);
+    return () => {
+      this.callbacks.delete(callback);
+    };
+  }
+  /** Remove the event listener and clear all callbacks. */
+  destroy() {
+    window.removeEventListener("message", this.handleMessage);
+    this.callbacks.clear();
+  }
+};
+
+// src/nodes/parent.ts
+var IframeConnection = class _IframeConnection {
+  // ------------------------------------------------------------------
+  // Private constructor — use `connect()` or `connectIframe()` instead.
+  // ------------------------------------------------------------------
+  constructor(transport, callTimeout) {
+    this.pendingCalls = /* @__PURE__ */ new Map();
+    this.transport = transport;
+    this.callTimeout = callTimeout;
+    this.remote = this.createProxy();
+    this.unsubscribe = this.transport.onMessage(
+      (message) => {
+        this.handleMessage(message);
+      }
+    );
+  }
+  // ------------------------------------------------------------------
+  // Static factory — performs the handshake, then returns an instance.
+  // ------------------------------------------------------------------
+  /**
+   * Connect to a child iframe that has called `expose()`.
+   *
+   * @param iframe  The HTMLIFrameElement to communicate with.
+   * @param options Connection options (origin, timeouts).
+   * @returns       Promise resolving with an `IframeConnection` once the handshake succeeds.
+   */
+  static connect(iframe, options) {
+    const {
+      targetOrigin,
+      handshakeTimeout = 5e3,
+      callTimeout = 1e4
+    } = options;
+    return new Promise((resolve, reject) => {
+      const contentWindow = iframe.contentWindow;
+      if (!contentWindow) {
+        reject(
+          new Error(
+            "iframe.contentWindow is null. Is the iframe attached to the DOM?"
+          )
+        );
+        return;
+      }
+      const transport = new Transport(contentWindow, targetOrigin);
+      const nonce = generateId();
+      let handshakeComplete = false;
+      const handshakeTimer = setTimeout(() => {
+        if (!handshakeComplete) {
+          unsubscribe();
+          transport.destroy();
+          reject(
+            new Error(
+              `Handshake timed out after ${handshakeTimeout}ms.`
+            )
+          );
+        }
+      }, handshakeTimeout);
+      const unsubscribe = transport.onMessage(
+        (message) => {
+          if (message.type === "handshake-response" && message.nonce === nonce && !handshakeComplete) {
+            handshakeComplete = true;
+            clearTimeout(handshakeTimer);
+            unsubscribe();
+            resolve(
+              new _IframeConnection(transport, callTimeout)
+            );
+          }
+        }
+      );
+      iframe.addEventListener("load", () => {
+        transport.send(createHandshakeRequest(nonce));
+      });
+    });
+  }
+  // ------------------------------------------------------------------
+  // Message handling (post-handshake: responses & errors only)
+  // ------------------------------------------------------------------
+  handleMessage(message) {
+    switch (message.type) {
+      case "response": {
+        this.settlePendingCall(message.id)?.resolve(message.result);
+        break;
+      }
+      case "error": {
+        this.settlePendingCall(message.id)?.reject(
+          new Error(message.error)
+        );
+        break;
+      }
+    }
+  }
+  // ------------------------------------------------------------------
+  // Pending-call helpers
+  // ------------------------------------------------------------------
+  /**
+   * Extracts and cleans up a pending call by ID.
+   * Returns the call so the caller can resolve or reject it, or undefined
+   * if no call with that ID exists (e.g. already settled or timed out).
+   */
+  settlePendingCall(id) {
+    const pending = this.pendingCalls.get(id);
+    if (!pending) return void 0;
+    clearTimeout(pending.timer);
+    this.pendingCalls.delete(id);
+    return pending;
+  }
+  // ------------------------------------------------------------------
+  // Proxy creation
+  // ------------------------------------------------------------------
+  /**
+   * Builds the Proxy that translates property access into RPC calls.
+   * Each method call returns a Promise that resolves when the child responds.
+   */
+  createProxy() {
+    return new Proxy({}, {
+      get: (_target, prop) => {
+        if (typeof prop !== "string") return void 0;
+        return (...args) => new Promise((resolve, reject) => {
+          const id = generateId();
+          const timer = setTimeout(() => {
+            this.pendingCalls.delete(id);
+            reject(
+              new Error(
+                `Call to "${prop}" timed out after ${this.callTimeout}ms.`
+              )
+            );
+          }, this.callTimeout);
+          this.pendingCalls.set(id, { resolve, reject, timer });
+          this.transport.send(createRequest(id, prop, args));
+        });
+      }
+    });
+  }
+  // ------------------------------------------------------------------
+  // Cleanup
+  // ------------------------------------------------------------------
+  /** Tear down the connection: removes listeners, rejects pending calls. */
+  destroy() {
+    for (const [, pending] of this.pendingCalls) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Connection destroyed."));
+    }
+    this.pendingCalls.clear();
+    this.unsubscribe();
+    this.transport.destroy();
+  }
+};
+function connectIframe(iframe, options) {
+  return IframeConnection.connect(iframe, options);
+}
+
+// src/nodes/child.ts
+var IframeExposed = class {
+  constructor(api, options) {
+    this.api = api;
+    const { allowedOrigin } = options;
+    this.transport = new Transport(window.parent, allowedOrigin);
+    this.unsubscribe = this.transport.onMessage(
+      (message) => {
+        this.handleMessage(message);
+      }
+    );
+  }
+  // ------------------------------------------------------------------
+  // Message handling
+  // ------------------------------------------------------------------
+  handleMessage(message) {
+    switch (message.type) {
+      case "handshake-request": {
+        this.transport.send(createHandshakeResponse(message.nonce));
+        break;
+      }
+      case "request": {
+        this.dispatchRequest(message.id, message.method, message.args);
+        break;
+      }
+    }
+  }
+  // ------------------------------------------------------------------
+  // RPC dispatch
+  // ------------------------------------------------------------------
+  /**
+   * Validates and executes an RPC request, sending back the result or error.
+   *
+   * Extracted into its own method for clarity: the message handler stays
+   * focused on routing, while this method handles validation + execution.
+   */
+  async dispatchRequest(id, method, args) {
+    if (!Object.prototype.hasOwnProperty.call(this.api, method)) {
+      this.transport.send(
+        createError(id, `Method "${method}" is not exposed.`)
+      );
+      return;
+    }
+    const fn = this.api[method];
+    if (typeof fn !== "function") {
+      this.transport.send(
+        createError(id, `"${method}" is not a function.`)
+      );
+      return;
+    }
+    try {
+      const result = await fn.apply(this.api, args);
+      this.transport.send(createResponse(id, result));
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      this.transport.send(createError(id, errorMessage));
+    }
+  }
+  // ------------------------------------------------------------------
+  // Cleanup
+  // ------------------------------------------------------------------
+  /** Remove all listeners and stop responding to RPC calls. */
+  destroy() {
+    this.unsubscribe();
+    this.transport.destroy();
+  }
+};
+function expose(api, options) {
+  return new IframeExposed(api, options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IframeConnection,
+  IframeExposed,
+  connectIframe,
+  expose
+});

package/dist/index.d.cts

@@ -0,0 +1,248 @@
+/**
+ * types.ts - Public type definitions for iFrameConnector
+ *
+ * Defines user-facing type contracts: API shape constraints, configuration
+ * options for parent and child, and the remote proxy type.
+ *
+ * Key design decisions:
+ * - ApiMethods constrains all methods to return Promise<unknown>, enforcing
+ *   asynchronous RPC (postMessage is inherently async).
+ * - RemoteApi maps the child's API type 1:1 so the parent gets full
+ *   autocompletion and type safety on the proxy.
+ * - Origin options are mandatory (no default), making the secure path explicit.
+ */
+/**
+ * Constraint for methods that can be exposed via RPC.
+ * Every method must return a Promise — synchronous functions are not allowed
+ * because postMessage communication is inherently asynchronous.
+ *
+ * `any[]` is intentional: it lets consumers define specific parameter types
+ * in their own interfaces while keeping this base constraint flexible.
+ */
+type ApiMethods = Record<string, (...args: any[]) => Promise<unknown>>;
+/**
+ * Maps an API definition to its remote (proxy) representation.
+ * Preserves method signatures so the parent gets full type safety
+ * and autocompletion when calling methods through the proxy.
+ */
+type RemoteApi<T extends ApiMethods> = {
+    [K in keyof T]: T[K];
+};
+/** Options for the parent when connecting to a child iframe. */
+interface ConnectOptions {
+    /**
+     * Expected origin of the child iframe (e.g. 'https://child.example.com').
+     * Messages from any other origin are silently discarded.
+     * Use '*' to accept any origin (not recommended for production).
+     */
+    targetOrigin: string;
+    /** Max wait time (ms) for the handshake to complete. @default 5000 */
+    handshakeTimeout?: number;
+    /** Max wait time (ms) for each individual RPC call. @default 10000 */
+    callTimeout?: number;
+}
+/** Options for the child when exposing its API. */
+interface ExposeOptions {
+    /**
+     * Allowed parent origin (e.g. 'https://parent.example.com').
+     * Requests from any other origin are silently ignored.
+     * Use '*' to accept any origin (not recommended for production).
+     */
+    allowedOrigin: string;
+}
+
+/**
+ * parent.ts - Parent side of iFrameConnector
+ *
+ * Provides `IframeConnection` class and `connectIframe()` factory for
+ * establishing a connection to a child iframe that has called `expose()`.
+ *
+ * Connection flow:
+ *   1. `IframeConnection.connect()` sends a HandshakeRequest with a random
+ *      nonce to the child.
+ *   2. Waits for HandshakeResponse echoing the same nonce (with timeout).
+ *   3. Returns an `IframeConnection` instance whose `remote` Proxy turns
+ *      method calls into RPC requests resolved by the child's responses.
+ *
+ * Security:
+ * - The nonce prevents rogue iframes from faking readiness.
+ * - Origin validation is handled by Transport.
+ * - Each pending call has its own timeout to prevent memory leaks.
+ *
+ * OOP rationale:
+ * - Encapsulating transport, pending-call state, and the Proxy inside a class
+ *   eliminates loose closures and makes the lifecycle (connect → call → destroy)
+ *   explicit. The static factory `connect()` cleanly separates the async
+ *   handshake phase from the synchronous RPC phase.
+ */
+
+/** Object returned by `connectIframe` / `IframeConnection.connect`. */
+interface Connection<T extends ApiMethods> {
+    /** Proxy — call remote methods as if they were local. */
+    remote: RemoteApi<T>;
+    /** Tear down the connection: removes listeners, rejects pending calls. */
+    destroy: () => void;
+}
+/**
+ * Manages a parent-side connection to a child iframe.
+ *
+ * Use the static `connect()` factory (or the `connectIframe()` helper) to
+ * create an instance — the constructor is private because connection setup
+ * requires an async handshake.
+ *
+ * @example
+ * ```ts
+ * const conn = await IframeConnection.connect<ChildApi>(iframe, {
+ *   targetOrigin: 'https://child.example.com',
+ * });
+ * const result = await conn.remote.greet('World');
+ * conn.destroy();
+ * ```
+ */
+declare class IframeConnection<T extends ApiMethods> implements Connection<T> {
+    /** Proxy — call remote methods as if they were local. */
+    readonly remote: RemoteApi<T>;
+    private readonly transport;
+    private readonly pendingCalls;
+    private readonly callTimeout;
+    private readonly unsubscribe;
+    private constructor();
+    /**
+     * Connect to a child iframe that has called `expose()`.
+     *
+     * @param iframe  The HTMLIFrameElement to communicate with.
+     * @param options Connection options (origin, timeouts).
+     * @returns       Promise resolving with an `IframeConnection` once the handshake succeeds.
+     */
+    static connect<T extends ApiMethods>(iframe: HTMLIFrameElement, options: ConnectOptions): Promise<IframeConnection<T>>;
+    private handleMessage;
+    /**
+     * Extracts and cleans up a pending call by ID.
+     * Returns the call so the caller can resolve or reject it, or undefined
+     * if no call with that ID exists (e.g. already settled or timed out).
+     */
+    private settlePendingCall;
+    /**
+     * Builds the Proxy that translates property access into RPC calls.
+     * Each method call returns a Promise that resolves when the child responds.
+     */
+    private createProxy;
+    /** Tear down the connection: removes listeners, rejects pending calls. */
+    destroy(): void;
+}
+/**
+ * Connect to a child iframe that has called `expose()`.
+ *
+ * Thin wrapper around `IframeConnection.connect()` that preserves the
+ * original functional API.
+ *
+ * @param iframe  The HTMLIFrameElement to communicate with.
+ * @param options Connection options (origin, timeouts).
+ * @returns       Promise resolving with a `Connection` once the handshake succeeds.
+ *
+ * @example
+ * ```ts
+ * import { connectIframe } from 'rpc-iframe';
+ *
+ * interface ChildApi {
+ *   greet(name: string): Promise<string>;
+ *   add(a: number, b: number): Promise<number>;
+ * }
+ *
+ * const iframe = document.getElementById('my-iframe') as HTMLIFrameElement;
+ * const { remote, destroy } = await connectIframe<ChildApi>(iframe, {
+ *   targetOrigin: 'https://child.example.com',
+ * });
+ *
+ * const greeting = await remote.greet('World');
+ * console.log(greeting); // "Hello, World!"
+ * ```
+ */
+declare function connectIframe<T extends ApiMethods>(iframe: HTMLIFrameElement, options: ConnectOptions): Promise<Connection<T>>;
+
+/**
+ * child.ts - Child iframe side of iFrameConnector
+ *
+ * Provides `IframeExposed` class and `expose()` factory for registering
+ * callable methods for the parent frame.
+ *
+ * Flow:
+ *   1. Listen for HandshakeRequest from parent → respond with HandshakeResponse.
+ *   2. Listen for RPC requests → dispatch to the registered method, reply with
+ *      result or error.
+ *
+ * Security:
+ * - Only own-property methods on the `api` object can be invoked (blocks
+ *   prototype pollution attacks like calling `constructor` or `toString`).
+ * - Origin is validated at the Transport level.
+ * - Error stack traces are intentionally omitted from responses to avoid
+ *   leaking internal details across origins.
+ *
+ * OOP rationale:
+ * - Encapsulating the API reference, transport, and dispatch logic in a class
+ *   makes ownership of resources explicit and simplifies cleanup via `destroy()`.
+ */
+
+/** Handle returned by `expose()` / `IframeExposed` for cleanup. */
+interface ExposeHandle {
+    /** Remove all listeners and stop responding to RPC calls. */
+    destroy: () => void;
+}
+/**
+ * Manages the child-side of an iframe RPC connection.
+ *
+ * Registers an API object whose methods can be invoked by the parent frame.
+ * Handles the handshake response and dispatches incoming RPC requests.
+ *
+ * @example
+ * ```ts
+ * const handle = new IframeExposed({
+ *   async greet(name: string) { return `Hello, ${name}!`; },
+ *   async add(a: number, b: number) { return a + b; },
+ * }, { allowedOrigin: 'https://parent.example.com' });
+ *
+ * // Later:
+ * handle.destroy();
+ * ```
+ */
+declare class IframeExposed<T extends ApiMethods> implements ExposeHandle {
+    private readonly api;
+    private readonly transport;
+    private readonly unsubscribe;
+    constructor(api: T, options: ExposeOptions);
+    private handleMessage;
+    /**
+     * Validates and executes an RPC request, sending back the result or error.
+     *
+     * Extracted into its own method for clarity: the message handler stays
+     * focused on routing, while this method handles validation + execution.
+     */
+    private dispatchRequest;
+    /** Remove all listeners and stop responding to RPC calls. */
+    destroy(): void;
+}
+/**
+ * Expose an API object so the parent frame can call its methods via RPC.
+ *
+ * Thin wrapper around `new IframeExposed()` that preserves the original
+ * functional API.
+ *
+ * @param api     Object whose values are async functions.
+ * @param options Configuration — at minimum the allowed parent origin.
+ * @returns       Handle with a `destroy()` method for cleanup.
+ *
+ * @example
+ * ```ts
+ * import { expose } from 'iframeconnector';
+ *
+ * const api = {
+ *   async greet(name: string) { return `Hello, ${name}!`; },
+ *   async add(a: number, b: number) { return a + b; },
+ * };
+ *
+ * expose(api, { allowedOrigin: 'https://parent.example.com' });
+ * ```
+ */
+declare function expose<T extends ApiMethods>(api: T, options: ExposeOptions): ExposeHandle;
+
+export { type ApiMethods, type ConnectOptions, type Connection, type ExposeHandle, type ExposeOptions, IframeConnection, IframeExposed, type RemoteApi, connectIframe, expose };

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+/**
+ * types.ts - Public type definitions for iFrameConnector
+ *
+ * Defines user-facing type contracts: API shape constraints, configuration
+ * options for parent and child, and the remote proxy type.
+ *
+ * Key design decisions:
+ * - ApiMethods constrains all methods to return Promise<unknown>, enforcing
+ *   asynchronous RPC (postMessage is inherently async).
+ * - RemoteApi maps the child's API type 1:1 so the parent gets full
+ *   autocompletion and type safety on the proxy.
+ * - Origin options are mandatory (no default), making the secure path explicit.
+ */
+/**
+ * Constraint for methods that can be exposed via RPC.
+ * Every method must return a Promise — synchronous functions are not allowed
+ * because postMessage communication is inherently asynchronous.
+ *
+ * `any[]` is intentional: it lets consumers define specific parameter types
+ * in their own interfaces while keeping this base constraint flexible.
+ */
+type ApiMethods = Record<string, (...args: any[]) => Promise<unknown>>;
+/**
+ * Maps an API definition to its remote (proxy) representation.
+ * Preserves method signatures so the parent gets full type safety
+ * and autocompletion when calling methods through the proxy.
+ */
+type RemoteApi<T extends ApiMethods> = {
+    [K in keyof T]: T[K];
+};
+/** Options for the parent when connecting to a child iframe. */
+interface ConnectOptions {
+    /**
+     * Expected origin of the child iframe (e.g. 'https://child.example.com').
+     * Messages from any other origin are silently discarded.
+     * Use '*' to accept any origin (not recommended for production).
+     */
+    targetOrigin: string;
+    /** Max wait time (ms) for the handshake to complete. @default 5000 */
+    handshakeTimeout?: number;
+    /** Max wait time (ms) for each individual RPC call. @default 10000 */
+    callTimeout?: number;
+}
+/** Options for the child when exposing its API. */
+interface ExposeOptions {
+    /**
+     * Allowed parent origin (e.g. 'https://parent.example.com').
+     * Requests from any other origin are silently ignored.
+     * Use '*' to accept any origin (not recommended for production).
+     */
+    allowedOrigin: string;
+}
+
+/**
+ * parent.ts - Parent side of iFrameConnector
+ *
+ * Provides `IframeConnection` class and `connectIframe()` factory for
+ * establishing a connection to a child iframe that has called `expose()`.
+ *
+ * Connection flow:
+ *   1. `IframeConnection.connect()` sends a HandshakeRequest with a random
+ *      nonce to the child.
+ *   2. Waits for HandshakeResponse echoing the same nonce (with timeout).
+ *   3. Returns an `IframeConnection` instance whose `remote` Proxy turns
+ *      method calls into RPC requests resolved by the child's responses.
+ *
+ * Security:
+ * - The nonce prevents rogue iframes from faking readiness.
+ * - Origin validation is handled by Transport.
+ * - Each pending call has its own timeout to prevent memory leaks.
+ *
+ * OOP rationale:
+ * - Encapsulating transport, pending-call state, and the Proxy inside a class
+ *   eliminates loose closures and makes the lifecycle (connect → call → destroy)
+ *   explicit. The static factory `connect()` cleanly separates the async
+ *   handshake phase from the synchronous RPC phase.
+ */
+
+/** Object returned by `connectIframe` / `IframeConnection.connect`. */
+interface Connection<T extends ApiMethods> {
+    /** Proxy — call remote methods as if they were local. */
+    remote: RemoteApi<T>;
+    /** Tear down the connection: removes listeners, rejects pending calls. */
+    destroy: () => void;
+}
+/**
+ * Manages a parent-side connection to a child iframe.
+ *
+ * Use the static `connect()` factory (or the `connectIframe()` helper) to
+ * create an instance — the constructor is private because connection setup
+ * requires an async handshake.
+ *
+ * @example
+ * ```ts
+ * const conn = await IframeConnection.connect<ChildApi>(iframe, {
+ *   targetOrigin: 'https://child.example.com',
+ * });
+ * const result = await conn.remote.greet('World');
+ * conn.destroy();
+ * ```
+ */
+declare class IframeConnection<T extends ApiMethods> implements Connection<T> {
+    /** Proxy — call remote methods as if they were local. */
+    readonly remote: RemoteApi<T>;
+    private readonly transport;
+    private readonly pendingCalls;
+    private readonly callTimeout;
+    private readonly unsubscribe;
+    private constructor();
+    /**
+     * Connect to a child iframe that has called `expose()`.
+     *
+     * @param iframe  The HTMLIFrameElement to communicate with.
+     * @param options Connection options (origin, timeouts).
+     * @returns       Promise resolving with an `IframeConnection` once the handshake succeeds.
+     */
+    static connect<T extends ApiMethods>(iframe: HTMLIFrameElement, options: ConnectOptions): Promise<IframeConnection<T>>;
+    private handleMessage;
+    /**
+     * Extracts and cleans up a pending call by ID.
+     * Returns the call so the caller can resolve or reject it, or undefined
+     * if no call with that ID exists (e.g. already settled or timed out).
+     */
+    private settlePendingCall;
+    /**
+     * Builds the Proxy that translates property access into RPC calls.
+     * Each method call returns a Promise that resolves when the child responds.
+     */
+    private createProxy;
+    /** Tear down the connection: removes listeners, rejects pending calls. */
+    destroy(): void;
+}
+/**
+ * Connect to a child iframe that has called `expose()`.
+ *
+ * Thin wrapper around `IframeConnection.connect()` that preserves the
+ * original functional API.
+ *
+ * @param iframe  The HTMLIFrameElement to communicate with.
+ * @param options Connection options (origin, timeouts).
+ * @returns       Promise resolving with a `Connection` once the handshake succeeds.
+ *
+ * @example
+ * ```ts
+ * import { connectIframe } from 'rpc-iframe';
+ *
+ * interface ChildApi {
+ *   greet(name: string): Promise<string>;
+ *   add(a: number, b: number): Promise<number>;
+ * }
+ *
+ * const iframe = document.getElementById('my-iframe') as HTMLIFrameElement;
+ * const { remote, destroy } = await connectIframe<ChildApi>(iframe, {
+ *   targetOrigin: 'https://child.example.com',
+ * });
+ *
+ * const greeting = await remote.greet('World');
+ * console.log(greeting); // "Hello, World!"
+ * ```
+ */
+declare function connectIframe<T extends ApiMethods>(iframe: HTMLIFrameElement, options: ConnectOptions): Promise<Connection<T>>;
+
+/**
+ * child.ts - Child iframe side of iFrameConnector
+ *
+ * Provides `IframeExposed` class and `expose()` factory for registering
+ * callable methods for the parent frame.
+ *
+ * Flow:
+ *   1. Listen for HandshakeRequest from parent → respond with HandshakeResponse.
+ *   2. Listen for RPC requests → dispatch to the registered method, reply with
+ *      result or error.
+ *
+ * Security:
+ * - Only own-property methods on the `api` object can be invoked (blocks
+ *   prototype pollution attacks like calling `constructor` or `toString`).
+ * - Origin is validated at the Transport level.
+ * - Error stack traces are intentionally omitted from responses to avoid
+ *   leaking internal details across origins.
+ *
+ * OOP rationale:
+ * - Encapsulating the API reference, transport, and dispatch logic in a class
+ *   makes ownership of resources explicit and simplifies cleanup via `destroy()`.
+ */
+
+/** Handle returned by `expose()` / `IframeExposed` for cleanup. */
+interface ExposeHandle {
+    /** Remove all listeners and stop responding to RPC calls. */
+    destroy: () => void;
+}
+/**
+ * Manages the child-side of an iframe RPC connection.
+ *
+ * Registers an API object whose methods can be invoked by the parent frame.
+ * Handles the handshake response and dispatches incoming RPC requests.
+ *
+ * @example
+ * ```ts
+ * const handle = new IframeExposed({
+ *   async greet(name: string) { return `Hello, ${name}!`; },
+ *   async add(a: number, b: number) { return a + b; },
+ * }, { allowedOrigin: 'https://parent.example.com' });
+ *
+ * // Later:
+ * handle.destroy();
+ * ```
+ */
+declare class IframeExposed<T extends ApiMethods> implements ExposeHandle {
+    private readonly api;
+    private readonly transport;
+    private readonly unsubscribe;
+    constructor(api: T, options: ExposeOptions);
+    private handleMessage;
+    /**
+     * Validates and executes an RPC request, sending back the result or error.
+     *
+     * Extracted into its own method for clarity: the message handler stays
+     * focused on routing, while this method handles validation + execution.
+     */
+    private dispatchRequest;
+    /** Remove all listeners and stop responding to RPC calls. */
+    destroy(): void;
+}
+/**
+ * Expose an API object so the parent frame can call its methods via RPC.
+ *
+ * Thin wrapper around `new IframeExposed()` that preserves the original
+ * functional API.
+ *
+ * @param api     Object whose values are async functions.
+ * @param options Configuration — at minimum the allowed parent origin.
+ * @returns       Handle with a `destroy()` method for cleanup.
+ *
+ * @example
+ * ```ts
+ * import { expose } from 'iframeconnector';
+ *
+ * const api = {
+ *   async greet(name: string) { return `Hello, ${name}!`; },
+ *   async add(a: number, b: number) { return a + b; },
+ * };
+ *
+ * expose(api, { allowedOrigin: 'https://parent.example.com' });
+ * ```
+ */
+declare function expose<T extends ApiMethods>(api: T, options: ExposeOptions): ExposeHandle;
+
+export { type ApiMethods, type ConnectOptions, type Connection, type ExposeHandle, type ExposeOptions, IframeConnection, IframeExposed, type RemoteApi, connectIframe, expose };

package/dist/index.js

@@ -0,0 +1,291 @@
+// src/core/protocol.ts
+var IFC_BRAND = "__ifc__";
+function isProtocolMessage(data) {
+  return typeof data === "object" && data !== null && data.__ifc === IFC_BRAND;
+}
+function createHandshakeRequest(nonce) {
+  return { __ifc: IFC_BRAND, type: "handshake-request", nonce };
+}
+function createHandshakeResponse(nonce) {
+  return { __ifc: IFC_BRAND, type: "handshake-response", nonce };
+}
+function createRequest(id, method, args) {
+  return { __ifc: IFC_BRAND, type: "request", id, method, args };
+}
+function createResponse(id, result) {
+  return { __ifc: IFC_BRAND, type: "response", id, result };
+}
+function createError(id, error) {
+  return { __ifc: IFC_BRAND, type: "error", id, error };
+}
+function generateId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `ifc-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+}
+
+// src/core/transport.ts
+var Transport = class {
+  /**
+   * @param target       Window to communicate with (iframe.contentWindow or window.parent).
+   * @param targetOrigin Expected origin of the remote side. '*' disables origin checks.
+   */
+  constructor(target, targetOrigin) {
+    this.callbacks = /* @__PURE__ */ new Set();
+    this.target = target;
+    this.targetOrigin = targetOrigin;
+    this.handleMessage = (event) => {
+      if (this.targetOrigin !== "*" && event.origin !== this.targetOrigin)
+        return;
+      if (!isProtocolMessage(event.data)) return;
+      for (const cb of this.callbacks) {
+        cb(event.data, event.origin);
+      }
+    };
+    window.addEventListener("message", this.handleMessage);
+  }
+  /** Post a protocol message to the remote window. */
+  send(message) {
+    this.target.postMessage(message, this.targetOrigin);
+  }
+  /** Subscribe to incoming protocol messages. Returns an unsubscribe function. */
+  onMessage(callback) {
+    this.callbacks.add(callback);
+    return () => {
+      this.callbacks.delete(callback);
+    };
+  }
+  /** Remove the event listener and clear all callbacks. */
+  destroy() {
+    window.removeEventListener("message", this.handleMessage);
+    this.callbacks.clear();
+  }
+};
+
+// src/nodes/parent.ts
+var IframeConnection = class _IframeConnection {
+  // ------------------------------------------------------------------
+  // Private constructor — use `connect()` or `connectIframe()` instead.
+  // ------------------------------------------------------------------
+  constructor(transport, callTimeout) {
+    this.pendingCalls = /* @__PURE__ */ new Map();
+    this.transport = transport;
+    this.callTimeout = callTimeout;
+    this.remote = this.createProxy();
+    this.unsubscribe = this.transport.onMessage(
+      (message) => {
+        this.handleMessage(message);
+      }
+    );
+  }
+  // ------------------------------------------------------------------
+  // Static factory — performs the handshake, then returns an instance.
+  // ------------------------------------------------------------------
+  /**
+   * Connect to a child iframe that has called `expose()`.
+   *
+   * @param iframe  The HTMLIFrameElement to communicate with.
+   * @param options Connection options (origin, timeouts).
+   * @returns       Promise resolving with an `IframeConnection` once the handshake succeeds.
+   */
+  static connect(iframe, options) {
+    const {
+      targetOrigin,
+      handshakeTimeout = 5e3,
+      callTimeout = 1e4
+    } = options;
+    return new Promise((resolve, reject) => {
+      const contentWindow = iframe.contentWindow;
+      if (!contentWindow) {
+        reject(
+          new Error(
+            "iframe.contentWindow is null. Is the iframe attached to the DOM?"
+          )
+        );
+        return;
+      }
+      const transport = new Transport(contentWindow, targetOrigin);
+      const nonce = generateId();
+      let handshakeComplete = false;
+      const handshakeTimer = setTimeout(() => {
+        if (!handshakeComplete) {
+          unsubscribe();
+          transport.destroy();
+          reject(
+            new Error(
+              `Handshake timed out after ${handshakeTimeout}ms.`
+            )
+          );
+        }
+      }, handshakeTimeout);
+      const unsubscribe = transport.onMessage(
+        (message) => {
+          if (message.type === "handshake-response" && message.nonce === nonce && !handshakeComplete) {
+            handshakeComplete = true;
+            clearTimeout(handshakeTimer);
+            unsubscribe();
+            resolve(
+              new _IframeConnection(transport, callTimeout)
+            );
+          }
+        }
+      );
+      iframe.addEventListener("load", () => {
+        transport.send(createHandshakeRequest(nonce));
+      });
+    });
+  }
+  // ------------------------------------------------------------------
+  // Message handling (post-handshake: responses & errors only)
+  // ------------------------------------------------------------------
+  handleMessage(message) {
+    switch (message.type) {
+      case "response": {
+        this.settlePendingCall(message.id)?.resolve(message.result);
+        break;
+      }
+      case "error": {
+        this.settlePendingCall(message.id)?.reject(
+          new Error(message.error)
+        );
+        break;
+      }
+    }
+  }
+  // ------------------------------------------------------------------
+  // Pending-call helpers
+  // ------------------------------------------------------------------
+  /**
+   * Extracts and cleans up a pending call by ID.
+   * Returns the call so the caller can resolve or reject it, or undefined
+   * if no call with that ID exists (e.g. already settled or timed out).
+   */
+  settlePendingCall(id) {
+    const pending = this.pendingCalls.get(id);
+    if (!pending) return void 0;
+    clearTimeout(pending.timer);
+    this.pendingCalls.delete(id);
+    return pending;
+  }
+  // ------------------------------------------------------------------
+  // Proxy creation
+  // ------------------------------------------------------------------
+  /**
+   * Builds the Proxy that translates property access into RPC calls.
+   * Each method call returns a Promise that resolves when the child responds.
+   */
+  createProxy() {
+    return new Proxy({}, {
+      get: (_target, prop) => {
+        if (typeof prop !== "string") return void 0;
+        return (...args) => new Promise((resolve, reject) => {
+          const id = generateId();
+          const timer = setTimeout(() => {
+            this.pendingCalls.delete(id);
+            reject(
+              new Error(
+                `Call to "${prop}" timed out after ${this.callTimeout}ms.`
+              )
+            );
+          }, this.callTimeout);
+          this.pendingCalls.set(id, { resolve, reject, timer });
+          this.transport.send(createRequest(id, prop, args));
+        });
+      }
+    });
+  }
+  // ------------------------------------------------------------------
+  // Cleanup
+  // ------------------------------------------------------------------
+  /** Tear down the connection: removes listeners, rejects pending calls. */
+  destroy() {
+    for (const [, pending] of this.pendingCalls) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Connection destroyed."));
+    }
+    this.pendingCalls.clear();
+    this.unsubscribe();
+    this.transport.destroy();
+  }
+};
+function connectIframe(iframe, options) {
+  return IframeConnection.connect(iframe, options);
+}
+
+// src/nodes/child.ts
+var IframeExposed = class {
+  constructor(api, options) {
+    this.api = api;
+    const { allowedOrigin } = options;
+    this.transport = new Transport(window.parent, allowedOrigin);
+    this.unsubscribe = this.transport.onMessage(
+      (message) => {
+        this.handleMessage(message);
+      }
+    );
+  }
+  // ------------------------------------------------------------------
+  // Message handling
+  // ------------------------------------------------------------------
+  handleMessage(message) {
+    switch (message.type) {
+      case "handshake-request": {
+        this.transport.send(createHandshakeResponse(message.nonce));
+        break;
+      }
+      case "request": {
+        this.dispatchRequest(message.id, message.method, message.args);
+        break;
+      }
+    }
+  }
+  // ------------------------------------------------------------------
+  // RPC dispatch
+  // ------------------------------------------------------------------
+  /**
+   * Validates and executes an RPC request, sending back the result or error.
+   *
+   * Extracted into its own method for clarity: the message handler stays
+   * focused on routing, while this method handles validation + execution.
+   */
+  async dispatchRequest(id, method, args) {
+    if (!Object.prototype.hasOwnProperty.call(this.api, method)) {
+      this.transport.send(
+        createError(id, `Method "${method}" is not exposed.`)
+      );
+      return;
+    }
+    const fn = this.api[method];
+    if (typeof fn !== "function") {
+      this.transport.send(
+        createError(id, `"${method}" is not a function.`)
+      );
+      return;
+    }
+    try {
+      const result = await fn.apply(this.api, args);
+      this.transport.send(createResponse(id, result));
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      this.transport.send(createError(id, errorMessage));
+    }
+  }
+  // ------------------------------------------------------------------
+  // Cleanup
+  // ------------------------------------------------------------------
+  /** Remove all listeners and stop responding to RPC calls. */
+  destroy() {
+    this.unsubscribe();
+    this.transport.destroy();
+  }
+};
+function expose(api, options) {
+  return new IframeExposed(api, options);
+}
+export {
+  IframeConnection,
+  IframeExposed,
+  connectIframe,
+  expose
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+    "name": "rpc-iframe",
+    "version": "0.2.0",
+    "description": "Modern JS/TS library for RPC-style communication between parent and iframe",
+    "license": "MIT",
+    "author": "AdriAir",
+    "main": "dist/index.cjs",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "files": [
+        "dist"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "exports": {
+        ".": {
+            "types": {
+                "import": "./dist/index.d.ts",
+                "require": "./dist/index.d.cts"
+            },
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "engines": {
+        "node": ">=16"
+    },
+    "keywords": [
+        "iframe",
+        "rpc",
+        "postmessage",
+        "typescript",
+        "javascript",
+        "browser",
+        "cross-window",
+        "ipc",
+        "frontend"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format esm,cjs --dts",
+        "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+        "typecheck": "tsc --noEmit",
+        "clean": "rimraf dist",
+        "serve": "serve examples/",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:ui": "vitest --ui",
+        "test:coverage": "vitest run --coverage",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "format": "prettier --write .",
+        "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/AdriAir/iFrameConnector.git"
+    },
+    "bugs": {
+        "url": "https://github.com/AdriAir/iFrameConnector/issues"
+    },
+    "homepage": "https://github.com/AdriAir/iFrameConnector#readme",
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@vitest/coverage-v8": "^4.0.18",
+        "@vitest/ui": "^4.0.18",
+        "cpx": "^1.5.0",
+        "eslint": "^10.0.1",
+        "eslint-config-prettier": "^10.1.8",
+        "happy-dom": "^20.5.0",
+        "prettier": "^3.8.1",
+        "rimraf": "^6.1.2",
+        "serve": "^14.2.5",
+        "tsup": "^8.5.1",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.56.0",
+        "vitest": "^4.0.18"
+    }
+}