chrome-in-iframe 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 2.1.0
+
+Security & robustness hardening. Runtime backwards-compatible.
+
+### Security
+
+- `readProperty` denylist extended with `__defineGetter__` / `__defineSetter__` / `__lookupGetter__` / `__lookupSetter__`.
+- `serialize` / `deserialize` enforce a 200-level depth cap; deeper payloads throw.
+- Envelope validators cap path length (64), args count (1024), `type` (64 chars), and id fields (200 chars).
+- `releaseCallbacks` now checks ID ownership against the sender — targeted callbacks can only be released by their owner.
+- Incoming `postMessage` data exceeding `MAX_MESSAGE_LENGTH` (1 000 000 chars) is dropped before `JSON.parse` to guard against oversized payloads.
+- `releaseCallbacks` IDs are validated as message IDs (`isMessageId`) instead of only `typeof === 'string'`.
+- Auto-derived `targetOrigin` is frozen on first **successful** resolution (`freezeResolvedOrigin`). When the derivation falls back to `'*'`, the next call retries the resolution instead of permanently caching `'*'`, fixing the common "create iframe before setting `src`" pattern.
+- When `targetOrigin` falls back to `'*'`, the default `allowedOrigin` no longer accepts any origin. It now tightens to `event.origin === window.location.origin`, blocking cross-origin scripts from injecting messages through the `'*'` escape hatch.
+- `handleDestroyEndpoint` now validates `data.instanceId === senderInstanceId` and rejects forged destroy notifications; `isDestroyEndpoint` at the envelope layer validates `instanceId` with `isMessageId`.
+- Response handlers (`invokeResponse` / `accessPropertyResponse` / `invokeFunctionByIdResponse`) now validate `meta.senderInstanceId === pending.expectedRemote`. Mismatched responses are silently dropped **without** consuming the pending entry, so the real remote's response can still land. Closes a sender-spoofing vector where another endpoint sharing the channel key could race-answer pending requests. `invoke` and `accessProperty` now also lock `expectedRemote = targetInstanceId` in `sendRequest`, matching `invokeFunctionById`.
+
+### Bug fixes
+
+- `handleDestroyEndpoint` actively rejects pending requests targeted at the destroyed remote — and all broadcast pendings when the last known remote disappears — instead of letting them hang to timeout.
+- `handleRemoteDestroy` scrubs `callbackOwners` of the gone remote.
+- `destroy()` clears `callbackOwners` and `knownRemotes` along with the other caches.
+- `destroy()` now invokes the `onReject` hook before rejecting each pending request, matching the `rejectPending` / `handleRemoteDestroy` paths. Previously persistent callbacks registered via `addListener` would leak references when the transport closed before the response arrived.
+- All `onReject` / `onResolve` hooks are wrapped via `safeOnReject` / `safeInvokeResolve`: a throwing hook no longer swallows the outer `reject` / `resolve`, and the error is logged via `warn`.
+- Broadcast-registered callbacks (`BROADCAST_OWNER`) now carry per-remote refcounting. A release from one remote no longer collaterally evicts the callback for other remotes still holding it — fixes the "any host can knock out everyone" failure mode when multiple hosts share a key.
+- `sender.sendMessage` uses `!== undefined` for `targetInstanceId`; empty string is no longer silently treated as broadcast.
+- Shared `windowDispatcher` wraps each subscriber's `deliver` in try/catch so one throwing endpoint can't affect others.
+- `ERROR_FACTORIES` restores `AggregateError` and `DOMException` when available; failing to set `error.name` falls back to `Object.defineProperty`.
+- Replaced the fragile `message.includes('contentWindow…')` matching with a `TRANSPORT_DETACHED` Symbol sentinel.
+- `invoke` / `accessProperty` now validate the path via `serializePath` *before* creating the pending entry; a serialization failure no longer leaves a dangling pending promise.
+- Response-path error rebuild upgraded from `new Error(message) + stack` to reusing the deserializer's `rebuildErrorFromSerialized`, so the original `name` (e.g. `TypeError`, `RangeError`) is preserved across the bridge.
+- `serializeError` now filters own properties by `isEnumerable`, consistent with the plain-object path. Prevents subclasses / `DOMException` from leaking internal non-enumerable own props on some browsers.
+- Multiple hosts sharing the same key: the client now binds to a single remote via the connect handshake and targets that remote for all subsequent calls, instead of broadcasting to every host.
+- `dropLocalCallback` honors `persistentRefcount`: a remote releasing a callback id now only decrements the refcount; the local persistent entry is torn down only when refcount reaches 0. Fixes "N local `addListener(fn)` calls + one remote release wipes out all N registrations".
+- The three request processors (`handleInvokeRequest`, `handleAccessPropertyRequest`, `handleCallbackInvoke`) early-return on `ctx.isDestroyed()`. Combined with reordering `endpoint.destroy()` to call `channel.destroy()` (remove the listener) before `context.destroy(true)` (drain state), eliminates post-destroy message handling that could otherwise register new callbacks into a freshly-cleared cache and leak.
+- `invoke` / `invokeFunctionById` failure paths (`serialize` throw / `postMessage` throw) now release both persistent and non-persistent registered callback ids. Previously non-persistent ids lingered in `functionCache` until the 5-min LRU TTL; `invokeFunctionById` performed no cleanup at all on failure.
+- `handleConnectRequest` now uses the new `noteFreshConnect`: when a previously-unseen sender announces itself, the bound remote is replaced. Fixes iframe-reload scenarios where the main-window endpoint's `boundRemoteInstanceId` stayed pinned to the old, dead instance — subsequent invokes were filtered out by channel-layer targeting and could only fail by timeout.
+
+### Performance
+
+- `MAX_RELEASE_IDS` lowered to 10 000; batches over 1 000 are sliced via `queueMicrotask`.
+- Multiple endpoints on the same `window` now share a single DOM `message` listener via a module-level dispatcher.
+- `destroy()` de-duplicates collected `releaseCallbacks` ids with a `Set`.
+- `functionIds` outer map is now a `WeakMap`, so callbacks aren't pinned after eviction.
+- `releaseCallbacks` is now chunked on the *sender* side (`RELEASE_CALLBACKS_CHUNK_SIZE` = 10 000). The receiver processes each chunk at face value instead of re-splitting, reducing redundant work.
+- Client proxy caches child proxies per key (`stringChildren` / `symbolChildren`). Repeated calls like `chrome.tabs.query` / `chrome.runtime.sendMessage` on the same path no longer allocate fresh `Proxy` + handler closures every time.
+- Plain-object serialize / deserialize switched to direct assignment; only `__proto__` keeps `Object.defineProperty` to preserve its "data, not prototype" semantics while preventing prototype pollution. 5-10× faster on V8's plain-object hot path.
+- Serializer type-dispatch order reordered: `Array.isArray` + plain-object short-circuit first (the common cases), then the `instanceof Error/Date/RegExp/Map/Set` chain.
+- `callbackOwners` value type widened from `BROADCAST_OWNER | Set<string>` to `BROADCAST_OWNER | string | Set<string>`. Single-remote scenarios now store a bare string instead of a `Set`, saving ~40 bytes per callback (≈ 40 KB at 1 000 active callbacks).
+- Removed the defensive `Array.from(subs)` clone in the `windowDispatcher` deliver loop; Set iterators behave correctly with add/delete on the current entry.
+
+### Refactor / internal
+
+- Symbol token encode/decode (`encodeSymbolToken` / `decodeSymbolToken`) centralized in `channel/utils.ts`; `channel/path.ts`, `serializer.ts`, and `deserializer.ts` no longer keep their own copies.
+- New `processor/helpers.ts` extracts `createScopedRemoteCallback`, `createGenerateCallback`, `createResponseHandler`, plus `safeInvokeReject` / `safeInvokeResolve`.
+- The three response handlers (`handleAccessPropertyResponse` / `handleInvokeResponse` / `handleCallbackInvokeResponse`) collapsed onto the shared `createResponseHandler` template, eliminating three copies that had been drifting in error-handling detail.
+- `setupInMainWindow` and `setupInIframe` now share an internal `setupConnection(options, sides)` helper; they differ only in target-origin resolution, postMessage destination, and `getExpectedSource`.
+- `setOwnProperty` consolidated into `channel/utils.ts`; `serializer.ts` and `deserializer.ts` no longer define their own.
+- `destroy()` now reuses `notifyReleaseCallbacks` for chunked release-send instead of duplicating the cursor loop.
+- New `createResponder(ctx, target, responseType, id)` factory in `processor/helpers.ts` returns `{ respondError, respondThrown, respondSuccess }`, with built-in serialize-failure fallback to error response. ~70 lines of `sendXxxSuccess` / `sendXxxErrorMessage` boilerplate across the three processors collapse into direct responder calls.
+- The three message-type switches in `channel/channel.ts` (`isValidMessagePayload`, `deserializeMessageData`, `sendProcessorError`) collapse onto a single `MESSAGE_SPECS: { [K in MessageType]: MessageSpec<K> }` table. Per-type validator, path pre-deserialize hook, and error-response routing live in one row; adding a new message type now means adding one entry instead of touching three switches.
+
+### API additions
+
+- `ConnectionHandle.isDestroyed()` / `Endpoint.isDestroyed()`.
+- `ConnectionOptions.strictOrigin` — throws on origin auto-derivation failure instead of falling back to `'*'`.
+- `timeout: Infinity` disables the timeout entirely.
+- Exports `TRANSPORT_DETACHED`, `isTransportDetachedError(err)`, and the `TransportDetachedError` type.
+
+### Internal interface widening (type-only)
+
+- `ClientContext` gained `serializeForRemote`, `noteRemoteSeen`, `bindRemote`, `disableRemoteTargetWait`; `invokeFunctionById` and `dropLocalCallback` gained optional ownership params.
+- `ClientContext.getAndRemovePendingPromise` gained an optional `senderInstanceId` parameter for sender validation.
+- `ClientContext` gained `noteFreshConnect(remoteInstanceId)` for iframe-reload-aware rebinding.
+- `Messages` gained `connectRequest` / `connectResponse` message types.
+- `PromiseCallbacks.timer` widened to `… | null`; added optional `expectedRemote`.
+
+### Package metadata
+
+- `build` script now runs `node scripts/fix-dts-extensions.mjs` after `rollup -c` to correct `.d.ts` import extensions.
+
+### Tests
+
+- 20 new regression tests covering the above; suite grew 146 → 166.
+
+## 2.0.2
+
+### Package metadata
+
+- Added a CommonJS entry at `dist/index.cjs`, exposed through `main` and
+  the `exports.require` condition. `require('chrome-in-iframe')` now returns
+  the same named runtime exports as the ESM entry.
+- The CommonJS bundle resolves dependencies with browser conditions so it
+  does not pull in Node-only modules such as `node:crypto` when bundled for
+  Chrome extension pages or iframes.
+- `exports.default` now points to the ESM entry so bundlers that fall
+  through to `default` get the browser-friendly bundle.
+
 ## 2.0.1
 
 ### Bug fixes

package/CHANGELOG.zh-CN.md

@@ -1,12 +1,109 @@
 # 更新日志
 
+## 2.1.0
+
+安全与稳健性加固。运行时完全向后兼容。
+
+### 安全
+
+- `readProperty` 危险属性黑名单扩充 `__defineGetter__` / `__defineSetter__` / `__lookupGetter__` / `__lookupSetter__`。
+- `serialize` / `deserialize` 加入 200 层深度上限，超出抛 `TypeError`。
+- envelope 校验加入路径段数（64）、参数数量（1024）、type 长度（64）、id 长度（200）上限。
+- `releaseCallbacks` 按 sender 校验 ID 归属 —— targeted callback 只允许 owner remote 释放。
+- 传入的 `postMessage` 数据超过 `MAX_MESSAGE_LENGTH`（1 000 000 字符）时在 `JSON.parse` 前直接丢弃，防御超大载荷。
+- `releaseCallbacks` 的 ID 字段现在使用 `isMessageId` 校验，不再仅做 `typeof === 'string'` 检查。
+- 自动推导的 `targetOrigin` 首次成功解析后被冻结（`freezeResolvedOrigin`）；若解析回退到 `'*'`，下次调用会重试，避免「iframe 创建早于 `src` 赋值」的常见模式被永久卡在 `'*'`。
+- 当 `targetOrigin` 已经回退到 `'*'` 时，自动派生的 `allowedOrigin` 不再退化为「接受任意 origin」，而是收紧为 `event.origin === window.location.origin`，阻止跨域脚本经由 `'*'` 注入消息。
+- `handleDestroyEndpoint` 现在校验 `data.instanceId === senderInstanceId`，拒绝伪造的销毁指令；`isDestroyEndpoint` 在 envelope 层使用 `isMessageId` 校验 `instanceId`。
+- 响应处理器（`invokeResponse` / `accessPropertyResponse` / `invokeFunctionByIdResponse`）现在校验 `meta.senderInstanceId === pending.expectedRemote`：不匹配的响应会被静默丢弃且**不消费** pending 条目，真实远端的响应仍能继续命中。封堵了「共享同一 key 的其他 endpoint 伪造响应抢答」这一攻击面。`invoke` 与 `accessProperty` 现在也会在 `sendRequest` 中锁定 `expectedRemote = targetInstanceId`，与 `invokeFunctionById` 行为一致。
+
+### Bug 修复
+
+- `handleDestroyEndpoint` 主动 reject 本端 pending（等该 remote 响应的；以及最后一个 known remote 消失时所有 broadcast pending），不再卡到 timeout。
+- `handleRemoteDestroy` 同时清理 `callbackOwners` 中该 remote 的痕迹。
+- `destroy()` 一并清理 `callbackOwners` 和 `knownRemotes`。
+- `destroy()` reject 每个 pending 之前现在会调用 `onReject` 钩子，与 `rejectPending` / `handleRemoteDestroy` 路径一致；此前 addListener 路径上的 persistent callback 在 transport 提前关闭时不会被释放。
+- 所有 `onReject` / `onResolve` 钩子统一通过 `safeOnReject` / `safeInvokeResolve` 包装：钩子内部抛错不再吞掉外层 `reject`/`resolve`，错误以 `warn` 记录。
+- broadcast 注册的 callback（`BROADCAST_OWNER`）现在带 per-remote 引用计数：一个 remote 释放该 ID 不再连带清除其它 remote 仍持有的引用，避免「多 host 共用 key 时，任一 host 单方释放就让全员失效」。
+- `sender.sendMessage` 中 `targetInstanceId` 改用 `!== undefined`，避免空字符串被当 broadcast。
+- 共享 `windowDispatcher` 对订阅者的 `deliver` 加 try/catch 隔离，单个订阅者抛错不影响其它。
+- `ERROR_FACTORIES` 增补 `AggregateError` 和 `DOMException`；`error.name` 写入失败用 `Object.defineProperty` 兜底。
+- 用 `TRANSPORT_DETACHED` Symbol sentinel 取代脆弱的 `message.includes('contentWindow…')` 字符串匹配。
+- `invoke` / `accessProperty` 在创建 pending 条目前先通过 `serializePath` 校验路径；序列化失败不再残留悬挂的 pending promise。
+- response 路径的错误重建从「`new Error(message) + stack`」升级为复用 `deserialize` 的 `rebuildErrorFromSerialized`，保留 `name`（`TypeError` / `RangeError` 等）。
+- `serializeError` 现在按 `isEnumerable` 过滤 own 属性，与 plain-object 序列化保持一致，避免子类 / DOMException 在某些浏览器上把内部 non-enumerable own props 也带出去。
+- 多个 host 共享同一 key 时，client 通过 connect 握手绑定单一 remote，后续所有调用精确路由到该 remote，不再广播给所有 host。
+- `dropLocalCallback` 现在会先递减 `persistentRefcount`，归零后才真正销毁 `persistentFunctionCache` 条目。修复「本地多次 `addListener(fn)` 后，远端任一 release 让所有注册同时失效」的问题。
+- 三个 request processor（`handleInvokeRequest` / `handleAccessPropertyRequest` / `handleCallbackInvoke`）在入口处补上 `ctx.isDestroyed()` 守卫；同时 `endpoint.destroy()` 的顺序调整为「先 `channel.destroy()` 摘掉 listener，再 `context.destroy(true)` 清空状态」。两者配合后，destroy 之后到达的消息会被直接忽略，不会再把新 callback 注册进已清空的 cache 造成泄漏。
+- `invoke` / `invokeFunctionById` 的失败路径（`serialize` 抛错 / `postMessage` 抛错）现在会同时释放 persistent 与非 persistent 的已注册 callback。此前非 persistent 的 id 会一直占着 `functionCache`，要等到 LRU TTL（5 min）才回收；`invokeFunctionById` 失败时则根本不做清理。
+- `handleConnectRequest` 改用新增的 `noteFreshConnect`：当一个从未见过的 sender 发来 `connectRequest` 时直接替换 `boundRemoteInstanceId`。修复 iframe reload 场景——主窗口 endpoint 不会再继续把 invoke 发往已失效的旧 instanceId，只能干等到超时。
+
+### 性能
+
+- `MAX_RELEASE_IDS` 降到 10 000；超过 1 000 条改用 `queueMicrotask` 切片处理。
+- 同一 `window` 上多 endpoint 共享一个 DOM `message` listener（module-level dispatcher）。
+- `destroy()` 收集 release id 用 `Set` 去重。
+- `functionIds` 外层改用 `WeakMap`，callback 不再被强引用。
+- `releaseCallbacks` 在发送端按 `RELEASE_CALLBACKS_CHUNK_SIZE`（10 000）切片发送，接收端直接处理各分片，减少重复拆分工作。
+- client proxy 子节点按 key 缓存（`stringChildren` / `symbolChildren`）：重复调用 `chrome.tabs.query` / `chrome.runtime.sendMessage` 等同一路径不再每次新建 `Proxy` + handler 闭包。
+- plain-object 序列化 / 反序列化改用直接赋值，仅对 `__proto__` 这一危险 key 保留 `Object.defineProperty`（避免原型污染同时不丢失 `__proto__` 作为 own data 的语义）。在 V8 上 plain-object 分支提速 5-10 倍。
+- `serializer` 类型派发顺序优化：先 `Array.isArray` + plain-object 短路（最常见情形），再走 `instanceof Error/Date/RegExp/Map/Set` 链。
+- `callbackOwners` value 由「`BROADCAST_OWNER | Set<string>`」改为「`BROADCAST_OWNER | string | Set<string>`」三态：单 remote 场景只存字符串引用，省去 `Set` 实例（每条节省 ~40 字节，1000 个活跃 callback ≈ 40KB）。
+- 移除 `windowDispatcher` 派发循环中的防御性 `Array.from(subs)` 拷贝；Set 迭代器对 add/delete 当前项行为良好。
+
+### 重构 / 内部
+
+- 符号 token 编解码（`encodeSymbolToken` / `decodeSymbolToken`）集中到 `channel/utils.ts`；`channel/path.ts`、`serializer.ts`、`deserializer.ts` 不再各自维护一份。
+- 新增 `processor/helpers.ts`：抽出 `createScopedRemoteCallback`、`createGenerateCallback`、`createResponseHandler` 模板，以及 `safeInvokeReject` / `safeInvokeResolve`。
+- 三个 response handler（`handleAccessPropertyResponse` / `handleInvokeResponse` / `handleCallbackInvokeResponse`）合并为 `createResponseHandler` 同一模板，避免三份拷贝独立演化。
+- `setupInMainWindow` 与 `setupInIframe` 共享内部 `setupConnection(options, sides)` helper，二者只在「目标 origin 解析、postMessage 目标、expectedSource」三处不同。
+- `setOwnProperty` 单一来源（`channel/utils.ts`），`serializer.ts` 与 `deserializer.ts` 不再各自定义。
+- `destroy()` 复用 `notifyReleaseCallbacks` 完成分片发送，去掉了那段重复的 cursor 循环。
+- 新增 `createResponder(ctx, target, responseType, id)` 工厂（`processor/helpers.ts`），返回 `{ respondError, respondThrown, respondSuccess }`，并内置「序列化失败时自动降级为 error 响应」的兜底。三个 processor 里近 70 行 `sendXxxSuccess` / `sendXxxErrorMessage` 模板全部改为直接调用 responder。
+- `channel/channel.ts` 中原本散落的三个 switch（`isValidMessagePayload` / `deserializeMessageData` / `sendProcessorError`）合并为一张 `MESSAGE_SPECS: { [K in MessageType]: MessageSpec<K> }` 表：每条消息的 validator、path 预反序列化、错误响应路由都集中在一处。今后新增消息类型只需添加一行 spec entry，不必再同步三处分支。
+
+### API 新增
+
+- `ConnectionHandle.isDestroyed()` / `Endpoint.isDestroyed()`。
+- `ConnectionOptions.strictOrigin` —— origin 推导失败时抛错而非降级到 `'*'`。
+- `timeout: Infinity` 表示禁用超时。
+- 导出 `TRANSPORT_DETACHED` symbol、`isTransportDetachedError(err)` 类型守卫、`TransportDetachedError` 类型。
+
+### 内部接口扩展（仅类型层面）
+
+- `ClientContext` 新增 `serializeForRemote`、`noteRemoteSeen`、`bindRemote`、`disableRemoteTargetWait`；`invokeFunctionById` / `dropLocalCallback` 增加可选 owner 参数。
+- `ClientContext.getAndRemovePendingPromise` 新增可选的 `senderInstanceId` 参数，用于 sender 校验。
+- `ClientContext` 新增 `noteFreshConnect(remoteInstanceId)`，用于在 iframe reload 场景下替换已陈旧的 `boundRemoteInstanceId`。
+- `Messages` 新增 `connectRequest` / `connectResponse` 消息类型。
+- `PromiseCallbacks.timer` 类型放宽为 `… | null`；新增可选 `expectedRemote`。
+
+### 打包配置
+
+- `build` 脚本在 `rollup -c` 之后新增 `node scripts/fix-dts-extensions.mjs` 步骤，修正 `.d.ts` 文件中的 import 扩展名。
+
+### 测试
+
+- 新增 20 条针对上述修复的回归测试；总数 146 → 166，全部通过。
+
+## 2.0.2
+
+### 打包配置
+
+- 新增 CommonJS 入口 `dist/index.cjs`，并通过 `main` 和 `exports.require`
+  暴露。`require('chrome-in-iframe')` 现在会返回与 ESM 入口一致的运行时
+  命名导出。
+- CommonJS bundle 会按浏览器条件解析依赖，因此打包到 Chrome 扩展页面或
+  iframe 时不会引入 `node:crypto` 等仅 Node 可用的模块。
+- `exports.default` 现在指向 ESM 入口，确保回退到 `default` 条件的
+  打包器拿到浏览器友好的产物。
+
 ## 2.0.1
 
 ### Bug 修复
 
 - `handleReleaseCallbacks` 现在会同时清理接收方 `remoteCallbacksByOwner` /
   `persistentRemoteCallbacksByOwner` 中对应的条目。此前只清理接收方自身
-  的 `functionCache` / `persistentFunctionCache`,导致每次
+  的 `functionCache` / `persistentFunctionCache`，导致每次
   `chrome.*.onX.addListener(handler)` 在宿主端留下的包裹函数永远不会被
   释放 —— 在长期运行的 service worker 中频繁增删监听器会造成真实泄漏。
 - 调整 `removeListener` 的客户端发送顺序：先发送 `invokeRequest`，再发送
@@ -23,8 +120,8 @@
   `'undefined' is not a function`。
 - 中间路径解到 null / undefined 时的错误信息现在准确报告父值类型，并附
   上已访问的路径前缀。
-- `isAllowedOrigin` 区分 `undefined`(不限制)与 `''`(空白名单)。空字符串
-  不再被当作"放行所有 origin"。
+- `isAllowedOrigin` 区分 `undefined`（不限制）与 `''`（空白名单）。空字符串
+  不再被当作「放行所有 origin」。
 - 未传 `allowedOrigin` 时，传入的 `postMessage` 现在会默认按
   `targetOrigin` 推导出的同一个具体 origin 过滤。这样默认桥接配置不会
   接收来自意外 origin 的消息，同时仍保留自动推导失败时回退到 `'*'` 的
@@ -67,10 +164,10 @@
 - `handleReleaseCallbacks` 现在通过新增的 `ctx.dropLocalCallback(id)`
   彻底清理 `functionIds` 和 `persistentRefcount`，而不是只清理外层
   两个缓存。
-- `accessPropertyRequest` / `invokeRequest` 的"无 delegate target"
+- `accessPropertyRequest` / `invokeRequest` 的「无 delegate target」
   判断改为显式 `=== undefined || === null`，不再用 `!target`。这样
   `0` / `false`（例如以数字为根的自定义 RPC target）不会被误报为
-  "未配置 delegate target"。
+  「未配置 delegate target」。
 - `isMessageEnvelope` 在原有的非字符串校验之外，还会拒绝
   `senderInstanceId` / `type` 为空字符串的消息。
 - Error payload 的额外字段现在通过 own-property 定义恢复，而不是直接赋值。
@@ -119,7 +216,7 @@
 - 将所有静默 `catch` 块（仅注释 / 空 `return`）替换为 `warn()` 调用，此前被吞掉的错误现在会在控制台输出。涉及区域：源推导（`deriveOriginFromIframe`、`deriveParentOrigin`、`parseOrigin`）、消息分发（`createMessageChannel`）、反序列化（`deserializeError`、`deserializeWrappedObject`、`resolveObjectKey`）以及客户端生命周期（`notifyReleaseCallbacks`、`destroy`）。
 - 将现有的裸 `console.warn` 调用迁移至集中的 `warn()` 工具。
 
-### 包元数据
+### 打包配置
 
 - `exports` map 新增顶层 `types` / `import` / `default` 条件以及
   `"./package.json"` 子路径，修复 webpack 5 严格 exports 等工具链下的
@@ -185,7 +282,7 @@
 
 - 本包**仅支持 ESM**。没有 CommonJS 入口。`require('chrome-in-iframe')` 将无法工作 — 请在 ESM 项目中使用或配置打包器将其作为 ESM 外部依赖处理。
 
-### 包元数据
+### 打包配置
 
 - 添加了 `engines`、`sideEffects: false`。
 - `prepublishOnly` 依次运行 `typecheck`、`test` 和 `build`。

package/README.md

@@ -10,17 +10,17 @@ This is useful when an extension page such as `options.html`, `popup.html`, or a
 
 ## Module Format
 
-**This package is ESM-only.** It ships a single ECMAScript module and exposes no CommonJS entry point. Use it from an ESM project (Vite, Rollup, webpack 5+, Parcel 2+, modern bundlers, or native `<script type="module">`).
+This package ships both ESM and CommonJS entry points. Modern bundlers and native module code should use the ESM entry automatically; CommonJS consumers can use `require()`.
 
-`require('chrome-in-iframe')` will not work.
+```ts
+import { connectChromeInIframe, exposeChromeInIframe } from 'chrome-in-iframe';
+```
 
-```json
-{
-  "type": "module"
-}
+```js
+const { connectChromeInIframe, exposeChromeInIframe } = require('chrome-in-iframe');
 ```
 
-If your tooling still emits CommonJS, configure it to leave `chrome-in-iframe` as an ESM external, or migrate the consuming project to ESM.
+The CommonJS build is generated with browser-oriented dependency resolution so it can still be bundled for Chrome extension pages and iframes.
 
 ## Install
 
@@ -147,9 +147,11 @@ window.addEventListener('beforeunload', () => {
 
 ## Security Options
 
-`targetOrigin` and `allowedOrigin` are optional. When `targetOrigin` is not supplied, the library resolves it from `iframe.src` / `contentWindow.location.origin` (on the extension side) or from `document.referrer` / `location.ancestorOrigins` (on the iframe side); it only falls back to `'*'` when none of those are available. Incoming messages are checked against both the expected window source and, by default, the same origin resolved for `targetOrigin`.
+`targetOrigin` and `allowedOrigin` are optional. When `targetOrigin` is not supplied, the library resolves it from `iframe.src` / `contentWindow.location.origin` (on the extension side) or from `document.referrer` / `location.ancestorOrigins` (on the iframe side); it only falls back to `'*'` when none of those are available. Incoming messages are checked against both the expected window source and, by default, the same origin resolved for `targetOrigin`. When `targetOrigin` falls back to `'*'`, the default `allowedOrigin` tightens to `event.origin === window.location.origin` (same-origin only) instead of accepting any origin.
+
+> **Note**: The `'*'` fallback only affects the outgoing `postMessage` `targetOrigin` (which can be observed by anyone listening). It does **not** let arbitrary-origin messages in. Even so, prefer passing explicit `targetOrigin` and `allowedOrigin` for third-party iframes, navigable iframes, or any cross-origin page, so the message can be locked to a known destination.
 
-> **Warning**: If origin auto-detection cannot resolve a concrete origin and falls back to `'*'`, incoming messages from the expected window source are allowed from any origin. For third-party iframes, navigable iframes, or any page from a different origin, pass explicit `targetOrigin` and `allowedOrigin`.
+> **Note**: The auto-derived `targetOrigin` is cached (`freezeResolvedOrigin`) once it resolves to a concrete origin. A fallback to `'*'` is **not** cached — the next call retries the resolution, so the common "create the iframe element first, then assign `src`" pattern doesn't end up permanently stuck on `'*'`.
 
 For production, pass origins when you know them.
 
@@ -267,7 +269,7 @@ 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`. Falls back to a value resolved from `iframe.src`.
-- `allowedOrigin`: optional origin, origin list, or predicate used to filter incoming messages. Defaults to the resolved `targetOrigin` when it is a concrete origin.
+- `allowedOrigin`: optional origin, origin list, or predicate used to filter incoming messages. By default: uses the resolved `targetOrigin` when it is a concrete origin; when it falls back to `'*'`, tightens to same-origin only (`event.origin === window.location.origin`).
 - `chromeApi`: optional custom Chrome-like object. Defaults to `globalThis.chrome`.
 - `timeout`: optional per-call timeout in ms (default `30000`).
 - `functionCacheMax` / `functionCacheTtl`: tune the LRU that stores non-persistent callbacks the local side has sent.

package/README.zh-CN.md

@@ -10,17 +10,17 @@
 
 ## 模块格式
 
-**本包只提供 ESM。** 发布产物是单个 ECMAScript 模块，没有 CommonJS 入口。请在 ESM 项目中使用（Vite、Rollup、webpack 5+、Parcel 2+、其他现代打包器，或浏览器原生 `<script type="module">`）。
+本包同时提供 ESM 和 CommonJS 入口。现代打包器和原生模块代码会自动使用 ESM 入口；CommonJS 消费方可以使用 `require()`。
 
-`require('chrome-in-iframe')` 无法工作。
+```ts
+import { connectChromeInIframe, exposeChromeInIframe } from 'chrome-in-iframe';
+```
 
-```json
-{
-  "type": "module"
-}
+```js
+const { connectChromeInIframe, exposeChromeInIframe } = require('chrome-in-iframe');
 ```
 
-如果你的构建工具仍然产出 CommonJS，请将 `chrome-in-iframe` 配置为 ESM external，或将消费方项目迁移到 ESM。
+CommonJS 构建会按浏览器条件解析依赖，因此仍可被打包到 Chrome 扩展页面和 iframe 中使用。
 
 ## 安装
 
@@ -147,11 +147,13 @@ window.addEventListener('beforeunload', () => {
 
 ## 安全选项
 
-`targetOrigin` 和 `allowedOrigin` 是可选的。当不传 `targetOrigin` 时，库会自动从 `iframe.src` / `contentWindow.location.origin`（扩展侧）或 `document.referrer` / `location.ancestorOrigins`（iframe 侧）推导出 origin；只有在以上来源都不可用时才回退到 `'*'`。传入的消息默认同时校验预期的 window source，以及为 `targetOrigin` 推导出的同一个 origin。
+`targetOrigin` 和 `allowedOrigin` 是可选的。当不传 `targetOrigin` 时,库会自动从 `iframe.src` / `contentWindow.location.origin`(扩展侧)或 `document.referrer` / `location.ancestorOrigins`(iframe 侧)推导出 origin;只有在以上来源都不可用时才回退到 `'*'`。传入的消息默认同时校验预期的 window source,以及为 `targetOrigin` 推导出的同一个 origin;当 `targetOrigin` 解析失败回退到 `'*'` 时,`allowedOrigin` 默认收紧为 `event.origin === window.location.origin`(同源限制),而不是接受任意 origin。
+
+> **提示**:`'*'` 回退仅影响 `postMessage` 出去的 `targetOrigin`(可能被中间人窥探),不会让任意 origin 的消息打进来。对于第三方 iframe、可能被导航的 iframe,或任何不同 origin 的页面,仍建议显式传入 `targetOrigin` 和 `allowedOrigin`,以便消息可以发往明确的目标 origin。
 
-> **警告**：如果自动推导无法得到具体 origin 并回退到 `'*'`，来自预期 window source 的传入消息会允许任意 origin。对于第三方 iframe、可能被导航的 iframe，或任何不同 origin 的页面，请显式传入 `targetOrigin` 和 `allowedOrigin`。
+> **注意**:`targetOrigin` 的自动推导结果会被冻结(`freezeResolvedOrigin`),首次成功解析后不会再变;但首次解析回退到 `'*'` 时不冻结,下次调用会重试,以兼容「先 `createElement('iframe')` 再设 `src`」这种常见模式。
 
-在生产环境中，如果知道具体来源，建议显式传入 origin。
+在生产环境中,如果知道具体来源,建议显式传入 origin。
 
 ### 扩展页面
 
@@ -267,7 +269,7 @@ const bridge = exposeChromeInIframe({
 - `iframe`：要桥接的 iframe 元素。
 - `key`：可选的共享桥接 key。两侧使用相同的 key。
 - `targetOrigin`：可选，`postMessage` 使用的 origin。不传时由 `iframe.src` 推导。
-- `allowedOrigin`：可选，用于过滤传入消息；可以是 origin、origin 列表或判断函数。默认使用解析后的 `targetOrigin`（当它是具体 origin 时）。
+- `allowedOrigin`:可选,用于过滤传入消息;可以是 origin、origin 列表或判断函数。默认情况下:解析后的 `targetOrigin` 是具体 origin 时,使用它;若回退到 `'*'`,则收紧为同源限制(`event.origin === window.location.origin`)。
 - `chromeApi`：可选，自定义的 Chrome API 对象。默认为 `globalThis.chrome`。
 - `timeout`：可选，单次调用的超时时长（毫秒，默认 `30000`）。
 - `functionCacheMax` / `functionCacheTtl`：调整本端发出的非持久 callback 的 LRU 缓存。

package/dist/api.d.ts

@@ -11,6 +11,7 @@ export interface ConnectionOptions {
     timeout?: number;
     targetOrigin?: string;
     allowedOrigin?: AllowedOrigin;
+    strictOrigin?: boolean;
     functionCacheMax?: number;
     functionCacheTtl?: number;
     remoteCallbackCacheMax?: number;
@@ -29,6 +30,7 @@ export interface ConnectionHandle<T> {
     proxy: T & PropertyAccess;
     get: PropertyAccess['$get'];
     destroy: () => void;
+    isDestroyed: () => boolean;
 }
 export interface ChromeIframeHandle<T = ChromeApi> extends ConnectionHandle<T> {
     chrome: T & PropertyAccess;

package/dist/channel/channel.d.ts

@@ -1,3 +1,7 @@
-import type { ProcessorRegistry } from '../processor/registry';
-import type { ClientContext, MessageChannel, MessagePoster } from './types';
+import type { ProcessorRegistry } from '../processor/registry.js';
+import type { ClientContext, MessageChannel, MessagePoster } from './types.js';
+export declare const MAX_PATH_LENGTH = 64;
+export declare const MAX_INVOKE_ARGS = 1024;
+export declare const MAX_MESSAGE_LENGTH = 1000000;
+export declare const MAX_RELEASE_IDS = 10000;
 export declare function createMessageChannel(poster: MessagePoster, key: string, instanceId: string, context: ClientContext, processorRegistry: ProcessorRegistry): MessageChannel;

package/dist/channel/deserializer.d.ts

@@ -1,4 +1,10 @@
-import type { Callable, CallbackCacheOptions, MessageValue } from './types';
+import type { Callable, CallbackCacheOptions, MessageValue } from './types.js';
 export type GenerateCallbackFn = (id: string, args: MessageValue[], options?: CallbackCacheOptions) => MessageValue;
 export type GetRemoteCallbackFn = (id: string, invoke: (args: MessageValue[]) => MessageValue, options?: CallbackCacheOptions) => Callable;
+export declare const MAX_DESERIALIZE_DEPTH = 200;
 export declare function deserialize(arg: MessageValue, generateCallback: GenerateCallbackFn, getRemoteCallback?: GetRemoteCallbackFn): MessageValue;
+export declare function rebuildErrorFromSerialized(serialized: {
+    message: string;
+    name?: string;
+    stack?: string;
+}): Error;

package/dist/channel/listener.d.ts

@@ -1,4 +1,4 @@
-import type { PathKey } from './types';
+import type { PathKey } from './types.js';
 export declare function isListenerRegistrationPath(path: PathKey[]): boolean;
 export declare function isListenerRemovalPath(path: PathKey[]): boolean;
 export declare function isLikelyListenerPath(path: PathKey[]): boolean;

package/dist/channel/path.d.ts

@@ -1,4 +1,4 @@
-import type { PathKey } from './types';
+import type { PathKey } from './types.js';
 type SerializedSymbolPathKey = {
     $type: 'symbol';
     value: string;

package/dist/channel/sender.d.ts

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

package/dist/channel/serializer.d.ts

@@ -1,4 +1,7 @@
-import type { Callable, CallbackCacheOptions, MessageValue } from './types';
+import type { Callable, CallbackCacheOptions, MessageValue } from './types.js';
+import { setOwnProperty } from './utils.js';
 export declare const TYPE_KEY = "$cii$";
+export declare const MAX_SERIALIZE_DEPTH = 200;
 export type RegisterFunctionFn = (fn: Callable, thisArg: MessageValue, options?: CallbackCacheOptions) => string;
 export declare function serialize(arg: MessageValue, registerFunction: RegisterFunctionFn, options?: CallbackCacheOptions): MessageValue;
+export { setOwnProperty };

package/dist/channel/types.d.ts

@@ -7,10 +7,22 @@ export type SerializedError = {
     message: string;
     stack?: string;
 };
+export declare const TRANSPORT_DETACHED: unique symbol;
+export interface TransportDetachedError extends Error {
+    [TRANSPORT_DETACHED]: true;
+}
+export declare function isTransportDetachedError(err: unknown): err is TransportDetachedError;
+export declare function createTransportDetachedError(message: string): TransportDetachedError;
 export type ListenerCallback = (event: {
     data: string;
 }) => void;
 export interface Messages {
+    connectRequest: {
+        instanceId: string;
+    };
+    connectResponse: {
+        instanceId: string;
+    };
     invokeRequest: {
         id: RequestId;
         path: PathKey[];
@@ -63,9 +75,10 @@ export interface MessagePoster {
 export interface PromiseCallbacks {
     resolve: (value: MessageValue) => void;
     reject: (reason: MessageValue) => void;
-    timer: ReturnType<typeof setTimeout>;
+    timer: ReturnType<typeof setTimeout> | null;
     onResolve?: () => void;
     onReject?: () => void;
+    expectedRemote?: string;
 }
 export interface ClientContext {
     getDelegateTarget(): MessageValue;
@@ -74,20 +87,26 @@ export interface ClientContext {
     getFunctionCache(): LRUCache<string, CallbackEntry>;
     getPersistentFunctionCache(): Map<string, CallbackEntry>;
     registerFunction(fn: Callable, thisArg: MessageValue, options?: CallbackCacheOptions): string;
+    serializeForRemote(value: MessageValue, target: 'broadcast' | string, options?: CallbackCacheOptions): MessageValue;
     getRemoteCallback(id: string, invoke: (args: MessageValue[]) => MessageValue, options: CallbackCacheOptions | undefined, remoteInstanceId: string): Callable;
-    getAndRemovePendingPromise(id: RequestId): PromiseCallbacks | undefined;
+    getAndRemovePendingPromise(id: RequestId, senderInstanceId?: string): PromiseCallbacks | undefined;
     invoke(path: PathKey[], args: MessageValue[]): Promise<MessageValue>;
     accessProperty(path: PathKey[]): Promise<MessageValue>;
-    invokeFunctionById(id: string, args: MessageValue[], options?: CallbackCacheOptions): Promise<MessageValue>;
+    invokeFunctionById(id: string, args: MessageValue[], options?: CallbackCacheOptions, remoteInstanceId?: string): Promise<MessageValue>;
     handleRemoteDestroy(instanceId: string): void;
+    bindRemote(remoteInstanceId: string): void;
+    noteFreshConnect(remoteInstanceId: string): void;
+    disableRemoteTargetWait(): void;
+    noteRemoteSeen(remoteInstanceId: string): void;
     releaseRemoteCallbacks(remoteInstanceId: string, ids: readonly string[]): void;
-    dropLocalCallback(id: string): void;
+    dropLocalCallback(id: string, requesterInstanceId?: string): void;
     bindMethod(fn: Callable, owner: MessageValue): Callable;
     /** @internal Exposed for tests; do not use in application code. */
     getRemoteCallbackCounts(remoteInstanceId: string): {
         lru: number;
         persistent: number;
     };
+    isDestroyed(): boolean;
     destroy(notifyRemote?: boolean): void;
 }
 export interface CallbackCacheOptions {

package/dist/channel/utils.d.ts

@@ -1,6 +1,9 @@
-import type { SerializedError } from './types';
+import type { MessageValue, SerializedError } from './types.js';
 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 encodeSymbolToken(value: symbol, context?: string): string;
+export declare function decodeSymbolToken(value: string, context?: string): symbol;
+export declare function setOwnProperty(target: Record<PropertyKey, MessageValue>, key: PropertyKey, value: MessageValue): void;
 export declare function serializeThrownError(err: unknown): SerializedError;
 export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;

package/dist/client/context.d.ts

@@ -1,4 +1,4 @@
-import type { ClientContext, MessageChannel, MessageValue } from '../channel/types';
+import type { ClientContext, MessageChannel, MessageValue } from '../channel/types.js';
 export interface ClientContextOptions {
     delegateTarget?: MessageValue;
     timeout?: number;

package/dist/client/endpoint.d.ts

@@ -1,5 +1,5 @@
-import type { ClientContext, MessagePoster } from '../channel/types';
-import { type ClientContextOptions } from './context';
+import type { ClientContext, MessagePoster } from '../channel/types.js';
+import { type ClientContextOptions } from './context.js';
 export interface EndpointOptions {
     poster: MessagePoster;
     key?: string;
@@ -8,6 +8,7 @@ export interface EndpointOptions {
 export interface Endpoint<TProxy = unknown> {
     proxy: TProxy;
     destroy: () => void;
+    isDestroyed: () => boolean;
     /** @internal Exposed for tests; do not use in application code. */
     getContext: () => ClientContext;
 }

package/dist/client/proxy.d.ts

@@ -1,3 +1,3 @@
-import type { MessageValue, PathKey, ProxyNode } from '../channel/types';
+import type { MessageValue, PathKey, ProxyNode } from '../channel/types.js';
 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;