chrome-in-iframe 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+# chrome-in-iframe
+
+[![npm version](https://img.shields.io/npm/v/chrome-in-iframe.svg)](https://www.npmjs.com/package/chrome-in-iframe)
+
+[中文文档](./README.zh-CN.md)
+
+Bridge Chrome extension APIs from a Chrome extension page into an embedded iframe.
+
+This is useful when an extension page such as `options.html`, `popup.html`, or another `chrome-extension://...` page embeds an iframe, but the iframe itself cannot directly access Chrome extension APIs.
+
+## Install
+
+```bash
+npm install chrome-in-iframe
+```
+
+## How It Works
+
+Use the package on both sides:
+
+- In the Chrome extension page, call `exposeChromeInIframe()` and pass the iframe element.
+- Inside the iframe, call `connectChromeInIframe()` and use the returned `chrome` proxy.
+
+Method calls, promises, plain objects, errors, and callback functions are forwarded through `postMessage`.
+
+## TypeScript Usage
+
+### Extension Page
+
+For example, in `options.html` or the script bundled for that page:
+
+```ts
+import { exposeChromeInIframe } from 'chrome-in-iframe';
+
+const iframe = document.querySelector<HTMLIFrameElement>('#app-frame');
+
+if (!iframe) {
+  throw new Error('iframe not found');
+}
+
+const bridge = exposeChromeInIframe({
+  iframe,
+  key: 'my-extension-bridge',
+});
+
+window.addEventListener('beforeunload', () => {
+  bridge.destroy();
+});
+```
+
+### Iframe Page
+
+```ts
+import { connectChromeInIframe } from 'chrome-in-iframe';
+
+const { chrome, get, destroy } = connectChromeInIframe({
+  key: 'my-extension-bridge',
+});
+
+const tabs = await chrome.tabs.query({
+  active: true,
+  currentWindow: true,
+});
+
+const extensionId = await get<string>('runtime.id');
+
+chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
+  console.log('tab updated', tabId, changeInfo);
+});
+
+window.addEventListener('beforeunload', () => {
+  destroy();
+});
+```
+
+If your TypeScript project does not already load Chrome types, add them in the iframe app:
+
+```bash
+npm install -D @types/chrome
+```
+
+```json
+{
+  "compilerOptions": {
+    "types": ["chrome"]
+  }
+}
+```
+
+## JavaScript Usage
+
+### Extension Page
+
+```js
+import { exposeChromeInIframe } from 'chrome-in-iframe';
+
+const iframe = document.querySelector('#app-frame');
+
+const bridge = exposeChromeInIframe({
+  iframe,
+  key: 'my-extension-bridge',
+});
+
+window.addEventListener('beforeunload', () => {
+  bridge.destroy();
+});
+```
+
+### Iframe Page
+
+```js
+import { connectChromeInIframe } from 'chrome-in-iframe';
+
+const { chrome, get, destroy } = connectChromeInIframe({
+  key: 'my-extension-bridge',
+});
+
+const tabs = await chrome.tabs.query({
+  active: true,
+  currentWindow: true,
+});
+
+const extensionId = await get('runtime.id');
+
+chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
+  console.log('tab updated', tabId, changeInfo);
+});
+
+window.addEventListener('beforeunload', () => {
+  destroy();
+});
+```
+
+## Security Options
+
+`targetOrigin` and `allowedOrigin` are optional. If omitted, messages are sent with `'*'` and incoming messages are only checked against the expected iframe or parent window source (via `MessageEvent.source`).
+
+> **Warning**: When both sides are Chrome extension pages under the same `chrome-extension://` origin, the default behavior is safe. However, if your iframe loads a **third-party page** or a page from a **different origin**, leaving `allowedOrigin` unset means **any window** can send forged `postMessage` messages and impersonate Chrome API calls. In that case, always set `allowedOrigin` to the expected origin.
+
+For production, pass origins when you know them.
+
+### Extension Page
+
+```ts
+exposeChromeInIframe({
+  iframe,
+  key: 'my-extension-bridge',
+  targetOrigin: 'https://your-iframe-app.example',
+  allowedOrigin: 'https://your-iframe-app.example',
+});
+```
+
+### Iframe Page
+
+```ts
+const { chrome } = connectChromeInIframe({
+  key: 'my-extension-bridge',
+  targetOrigin: 'chrome-extension://modkelfkcfjpgbfmnbnllalkiogfofhb',
+  allowedOrigin: 'chrome-extension://modkelfkcfjpgbfmnbnllalkiogfofhb',
+});
+```
+
+## Reading Properties
+
+Chrome API methods can be called directly:
+
+```ts
+const tabs = await chrome.tabs.query({ active: true });
+```
+
+Readable properties should be read through `get()` or `$get()`:
+
+```ts
+const extensionId = await get<string>('runtime.id');
+const platformOs = await chrome.runtime.$get<string>('PlatformOs');
+```
+
+## API
+
+### `exposeChromeInIframe(options)`
+
+Runs in the Chrome extension page.
+
+```ts
+const bridge = exposeChromeInIframe({
+  iframe,
+  key,
+  targetOrigin,
+  allowedOrigin,
+  chromeApi,
+});
+```
+
+Options:
+
+- `iframe`: the iframe element to bridge.
+- `key`: optional shared bridge key. Use the same key on both sides.
+- `targetOrigin`: optional origin used by `postMessage`.
+- `allowedOrigin`: optional origin, origin list, or predicate used to filter incoming messages.
+- `chromeApi`: optional custom Chrome-like object. Defaults to `globalThis.chrome`.
+
+Returns:
+
+- `proxy`: the bridged Chrome API proxy.
+- `get(path)`: read a property from the bridged Chrome API.
+- `destroy()`: remove message listeners and clear bridge state.
+
+### `connectChromeInIframe(options)`
+
+Runs inside the iframe.
+
+```ts
+const { chrome, get, destroy } = connectChromeInIframe({
+  key,
+  targetOrigin,
+  allowedOrigin,
+});
+```
+
+Returns:
+
+- `chrome`: a proxy for the extension page's Chrome API.
+- `proxy`: the same object as `chrome`.
+- `get(path)`: read a property from the bridged Chrome API.
+- `destroy()`: remove message listeners and clear bridge state.
+

package/README.zh-CN.md

@@ -0,0 +1,225 @@
+# chrome-in-iframe
+
+[![npm version](https://img.shields.io/npm/v/chrome-in-iframe.svg)](https://www.npmjs.com/package/chrome-in-iframe)
+
+[English](./README.md)
+
+将 Chrome 扩展页面的 Chrome 扩展 API 桥接到嵌入的 iframe 中。
+
+当扩展页面（如 `options.html`、`popup.html` 或其他 `chrome-extension://...` 页面）嵌入了 iframe，但 iframe 本身无法直接访问 Chrome 扩展 API 时，这个库非常有用。
+
+## 安装
+
+```bash
+npm install chrome-in-iframe
+```
+
+## 工作原理
+
+在两侧都使用该包：
+
+- 在 Chrome 扩展页面中，调用 `exposeChromeInIframe()` 并传入 iframe 元素。
+- 在 iframe 内部，调用 `connectChromeInIframe()` 并使用返回的 `chrome` 代理。
+
+方法调用、Promise、普通对象、错误和回调函数通过 `postMessage` 进行转发。
+
+## TypeScript 用法
+
+### 扩展页面
+
+例如在 `options.html` 或为该页面打包的脚本中：
+
+```ts
+import { exposeChromeInIframe } from 'chrome-in-iframe';
+
+const iframe = document.querySelector<HTMLIFrameElement>('#app-frame');
+
+if (!iframe) {
+  throw new Error('iframe not found');
+}
+
+const bridge = exposeChromeInIframe({
+  iframe,
+  key: 'my-extension-bridge',
+});
+
+window.addEventListener('beforeunload', () => {
+  bridge.destroy();
+});
+```
+
+### Iframe 页面
+
+```ts
+import { connectChromeInIframe } from 'chrome-in-iframe';
+
+const { chrome, get, destroy } = connectChromeInIframe({
+  key: 'my-extension-bridge',
+});
+
+const tabs = await chrome.tabs.query({
+  active: true,
+  currentWindow: true,
+});
+
+const extensionId = await get<string>('runtime.id');
+
+chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
+  console.log('tab updated', tabId, changeInfo);
+});
+
+window.addEventListener('beforeunload', () => {
+  destroy();
+});
+```
+
+如果你的 TypeScript 项目尚未加载 Chrome 类型，请在 iframe 应用中添加：
+
+```bash
+npm install -D @types/chrome
+```
+
+```json
+{
+  "compilerOptions": {
+    "types": ["chrome"]
+  }
+}
+```
+
+## JavaScript 用法
+
+### 扩展页面
+
+```js
+import { exposeChromeInIframe } from 'chrome-in-iframe';
+
+const iframe = document.querySelector('#app-frame');
+
+const bridge = exposeChromeInIframe({
+  iframe,
+  key: 'my-extension-bridge',
+});
+
+window.addEventListener('beforeunload', () => {
+  bridge.destroy();
+});
+```
+
+### Iframe 页面
+
+```js
+import { connectChromeInIframe } from 'chrome-in-iframe';
+
+const { chrome, get, destroy } = connectChromeInIframe({
+  key: 'my-extension-bridge',
+});
+
+const tabs = await chrome.tabs.query({
+  active: true,
+  currentWindow: true,
+});
+
+const extensionId = await get('runtime.id');
+
+chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
+  console.log('tab updated', tabId, changeInfo);
+});
+
+window.addEventListener('beforeunload', () => {
+  destroy();
+});
+```
+
+## 安全选项
+
+`targetOrigin` 和 `allowedOrigin` 是可选的。如果省略，消息将使用 `'*'` 发送，传入的消息仅通过 `MessageEvent.source` 与预期的 iframe 或父窗口进行校验。
+
+> **警告**：当两侧都是同一 `chrome-extension://` origin 下的 Chrome 扩展页面时，默认行为是安全的。但如果 iframe 加载的是**第三方页面**或来自**不同 origin** 的页面，不设置 `allowedOrigin` 意味着**任何窗口**都可以发送伪造的 `postMessage` 消息来冒充 Chrome API 调用。在这种情况下，务必将 `allowedOrigin` 设置为预期的 origin。
+
+在生产环境中，如果知道具体来源，建议传入 origin。
+
+### 扩展页面
+
+```ts
+exposeChromeInIframe({
+  iframe,
+  key: 'my-extension-bridge',
+  targetOrigin: 'https://your-iframe-app.example',
+  allowedOrigin: 'https://your-iframe-app.example',
+});
+```
+
+### Iframe 页面
+
+```ts
+const { chrome } = connectChromeInIframe({
+  key: 'my-extension-bridge',
+  targetOrigin: 'chrome-extension://modkelfkcfjpgbfmnbnllalkiogfofhb',
+  allowedOrigin: 'chrome-extension://modkelfkcfjpgbfmnbnllalkiogfofhb',
+});
+```
+
+## 读取属性
+
+Chrome API 方法可以直接调用：
+
+```ts
+const tabs = await chrome.tabs.query({ active: true });
+```
+
+可读属性应通过 `get()` 或 `$get()` 读取：
+
+```ts
+const extensionId = await get<string>('runtime.id');
+const platformOs = await chrome.runtime.$get<string>('PlatformOs');
+```
+
+## API
+
+### `exposeChromeInIframe(options)`
+
+在 Chrome 扩展页面中运行。
+
+```ts
+const bridge = exposeChromeInIframe({
+  iframe,
+  key,
+  targetOrigin,
+  allowedOrigin,
+  chromeApi,
+});
+```
+
+选项：
+
+- `iframe`：要桥接的 iframe 元素。
+- `key`：可选的共享桥接密钥。两侧使用相同的 key。
+- `targetOrigin`：可选，`postMessage` 使用的 origin。
+- `allowedOrigin`：可选，用于过滤传入消息的 origin、origin 列表或判断函数。
+- `chromeApi`：可选，自定义的 Chrome API 对象。默认为 `globalThis.chrome`。
+
+返回值：
+
+- `proxy`：桥接后的 Chrome API 代理。
+- `get(path)`：从桥接的 Chrome API 中读取属性。
+- `destroy()`：移除消息监听器并清除桥接状态。
+
+### `connectChromeInIframe(options)`
+
+在 iframe 内部运行。
+
+```ts
+const { chrome, get, destroy } = connectChromeInIframe({
+  key,
+  targetOrigin,
+  allowedOrigin,
+});
+```
+
+返回值：
+
+- `chrome`：扩展页面 Chrome API 的代理。
+- `proxy`：与 `chrome` 相同的对象。
+- `get(path)`：从桥接的 Chrome API 中读取属性。
+- `destroy()`：移除消息监听器并清除桥接状态。

package/dist/api.d.ts

@@ -0,0 +1,35 @@
+export type AllowedOrigin = string | string[] | ((origin: string) => boolean);
+export type PropertyPathPart = string | symbol | Array<string | symbol>;
+export type ChromeApi = typeof globalThis extends {
+    chrome: infer Api;
+} ? Api : unknown;
+export interface PropertyAccess {
+    $get<R = unknown>(...path: PropertyPathPart[]): Promise<R>;
+}
+export interface ConnectionOptions {
+    key?: string;
+    timeout?: number;
+    targetOrigin?: string;
+    allowedOrigin?: AllowedOrigin;
+}
+export interface SetupInMainWindowOptions<T = unknown> extends ConnectionOptions {
+    iframe: HTMLIFrameElement;
+    delegateTarget: T;
+}
+export type SetupInIframeOptions = ConnectionOptions;
+export interface ExposeChromeInIframeOptions<T = ChromeApi> extends ConnectionOptions {
+    iframe: HTMLIFrameElement;
+    chromeApi?: T;
+}
+export interface ConnectionHandle<T> {
+    proxy: T & PropertyAccess;
+    get: PropertyAccess['$get'];
+    destroy: () => void;
+}
+export interface ChromeIframeHandle<T = ChromeApi> extends ConnectionHandle<T> {
+    chrome: T & PropertyAccess;
+}
+export declare function setupInMainWindow<T>(options: SetupInMainWindowOptions<T>): ConnectionHandle<T>;
+export declare function setupInIframe<T>(options?: SetupInIframeOptions): ConnectionHandle<T>;
+export declare function exposeChromeInIframe<T = ChromeApi>(options: ExposeChromeInIframeOptions<T>): ConnectionHandle<T>;
+export declare function connectChromeInIframe<T = ChromeApi>(options?: SetupInIframeOptions): ChromeIframeHandle<T>;

package/dist/channel/channel.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessorRegistry } from '../processor/registry';
+import type { ClientContext, MessageChannel, MessagePoster } from './types';
+export declare function createMessageChannel(poster: MessagePoster, key: string, context: ClientContext, processorRegistry: ProcessorRegistry): MessageChannel;

package/dist/channel/deserializer.d.ts

@@ -0,0 +1,2 @@
+import type { Callable, CallbackCacheOptions, MessageValue } from './types';
+export declare function deserialize(arg: MessageValue, generateCallback: (id: string, args: MessageValue[], options?: CallbackCacheOptions) => MessageValue, getRemoteCallback?: (id: string, invoke: (args: MessageValue[]) => void, options?: CallbackCacheOptions) => Callable, options?: CallbackCacheOptions): MessageValue;

package/dist/channel/listener.d.ts

@@ -0,0 +1,3 @@
+import type { MessageValue, PathKey } from './types';
+export declare function isListenerRegistrationPath(path: PathKey[]): boolean;
+export declare function isLikelyListenerPath(path: PathKey[], value?: MessageValue): boolean;

package/dist/channel/path.d.ts

@@ -0,0 +1,10 @@
+import type { PathKey } from './types';
+type SerializedSymbolPathKey = {
+    $type: 'symbol';
+    value: string;
+};
+export type SerializedPathKey = string | SerializedSymbolPathKey;
+export declare function serializePath(path: PathKey[]): SerializedPathKey[];
+export declare function deserializePath(path: SerializedPathKey[]): PathKey[];
+export declare function isSerializedPath(value: unknown): value is SerializedPathKey[];
+export {};

package/dist/channel/sender.d.ts

@@ -0,0 +1,2 @@
+import type { MessagePoster, MessageSender } from './types';
+export declare function createMessageSender(poster: MessagePoster, key: string): MessageSender;

package/dist/channel/serializer.d.ts

@@ -0,0 +1,2 @@
+import type { Callable, CallbackCacheOptions, MessageValue } from './types';
+export declare function serialize(arg: MessageValue, registerFunction: (fn: Callable, options?: CallbackCacheOptions) => string, options?: CallbackCacheOptions): MessageValue;

package/dist/channel/types.d.ts

@@ -0,0 +1,93 @@
+import type { LRUCache } from 'lru-cache';
+export type PathKey = string | symbol;
+export type MessageValue = unknown;
+export type Callable = (...args: MessageValue[]) => MessageValue;
+export type RequestId = string;
+export type SerializedError = {
+    message: string;
+    stack?: string;
+};
+export type ListenerCallback = (event: {
+    data: string;
+}) => void;
+export interface Messages {
+    invokeRequest: {
+        id: RequestId;
+        path: PathKey[];
+        args: MessageValue[];
+    };
+    invokeResponse: {
+        id: RequestId;
+        data?: MessageValue;
+        error?: SerializedError;
+    };
+    accessPropertyRequest: {
+        id: RequestId;
+        path: PathKey[];
+    };
+    accessPropertyResponse: {
+        id: RequestId;
+        data?: MessageValue;
+        error?: SerializedError;
+    };
+    invokeFunctionByIdRequest: {
+        id: string;
+        callId: RequestId;
+        args: MessageValue[];
+    };
+    invokeFunctionByIdResponse: {
+        id: RequestId;
+        data?: MessageValue;
+        error?: SerializedError;
+    };
+}
+export type MessageType = keyof Messages;
+export type MessageBody<K extends MessageType = MessageType> = {
+    type: K;
+    key: string;
+    data: Messages[K];
+};
+export interface MessagePoster {
+    postMessage(message: string): void;
+    addEventListener(name: 'message', callback: ListenerCallback): void;
+    removeEventListener(name: 'message', callback: ListenerCallback): void;
+}
+export interface PromiseCallbacks {
+    resolve: (value: MessageValue) => void;
+    reject: (reason: MessageValue) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+export interface ClientContext {
+    getDelegateTarget(): MessageValue;
+    getMessageChannel(): MessageChannel;
+    getFunctionCache(): LRUCache<string, Callable>;
+    getPersistentFunctionCache(): Map<string, Callable>;
+    registerFunction(fn: Callable, options?: CallbackCacheOptions): string;
+    getRemoteCallback(id: string, invoke: (args: MessageValue[]) => MessageValue, options?: CallbackCacheOptions): Callable;
+    getAndRemovePendingPromise(id: RequestId): PromiseCallbacks | undefined;
+    invoke(path: PathKey[], args: MessageValue[]): Promise<MessageValue>;
+    accessProperty(path: PathKey[]): Promise<MessageValue>;
+    invokeFunctionById(id: string, args: MessageValue[], options?: CallbackCacheOptions): Promise<MessageValue>;
+    registerPendingPromise(id: RequestId, callbacks: PromiseCallbacks): void;
+    destroy(): void;
+}
+export interface CallbackCacheOptions {
+    persistent?: boolean;
+}
+export interface MessageChannel {
+    getSender(): MessageSender;
+    getContext(): ClientContext;
+    getPoster(): MessagePoster;
+    getKey(): string;
+    destroy(): void;
+}
+export interface MessageSender {
+    sendMessage<K extends MessageType>(type: K, data: Messages[K]): void;
+}
+export interface RequestHandler<K extends MessageType = MessageType> {
+    (data: Messages[K], ctx: ClientContext): void;
+}
+export type ProxyNode = {
+    parent?: ProxyNode;
+    key: PathKey;
+};

package/dist/channel/utils.d.ts

@@ -0,0 +1,5 @@
+import type { SerializedError } from './types';
+export declare const WELL_KNOWN_SYMBOLS: Record<string, symbol>;
+export declare function getWellKnownSymbolName(value: symbol): string | undefined;
+export declare function getWellKnownSymbol(name: string): symbol | undefined;
+export declare function serializeThrownError(err: unknown): SerializedError;

package/dist/client/context.d.ts

@@ -0,0 +1,6 @@
+import type { ClientContext, MessageChannel, MessageValue } from '../channel/types';
+export interface ClientContextOptions {
+    delegateTarget?: MessageValue;
+    timeout?: number;
+}
+export declare function createClientContext(getMessageChannel: () => MessageChannel, options?: ClientContextOptions): ClientContext;

package/dist/client/endpoint.d.ts

@@ -0,0 +1,12 @@
+import type { MessagePoster } from '../channel/types';
+import { type ClientContextOptions } from './context';
+export interface EndpointOptions {
+    poster: MessagePoster;
+    key?: string;
+    contextOptions?: ClientContextOptions;
+}
+export interface Endpoint<TProxy = unknown> {
+    proxy: TProxy;
+    destroy: () => void;
+}
+export declare function createEndpoint<TProxy = unknown>(options: EndpointOptions): Endpoint<TProxy>;

package/dist/client/proxy.d.ts

@@ -0,0 +1,3 @@
+import type { MessageValue, PathKey, ProxyNode } from '../channel/types';
+export declare function resolvePath(node: ProxyNode): PathKey[];
+export declare function createClientProxy<TProxy = unknown>(invoke: (path: PathKey[], args: MessageValue[]) => Promise<MessageValue>, accessProperty?: (path: PathKey[]) => Promise<MessageValue>): TProxy;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { connectChromeInIframe, exposeChromeInIframe, setupInIframe, setupInMainWindow } from './api';
+export type { AllowedOrigin, PropertyAccess, PropertyPathPart, ConnectionHandle, ChromeIframeHandle, ExposeChromeInIframeOptions, SetupInIframeOptions, SetupInMainWindowOptions, ConnectionOptions, } from './api';
+export type { Messages, MessageType, MessageBody, MessagePoster, ClientContext, MessageChannel, MessageSender, ProxyNode, ListenerCallback, SerializedError, } from './channel/types';