chrome-in-iframe 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,267 @@
 # 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
+
+- `handleReleaseCallbacks` now also evicts the corresponding entries from the
+  receiver's `remoteCallbacksByOwner` / `persistentRemoteCallbacksByOwner`
+  maps. Previously only the receiver's own `functionCache` /
+  `persistentFunctionCache` were touched, so the host kept the wrapper
+  function for every `chrome.*.onX.addListener(handler)` indefinitely — a
+  real leak in long-lived service workers with frequent listener churn.
+- Reordered the `removeListener` flow on the sender side: the
+  `invokeRequest` is now dispatched before the `releaseCallbacks` so the
+  receiver can still resolve the cached wrapper, call
+  `chrome.*.removeListener(W)` correctly, and only afterwards drop it.
+- The error response handlers (`invokeResponse`, `accessPropertyResponse`,
+  `invokeFunctionByIdResponse`) no longer clobber the local Error's stack
+  with `undefined` when the remote payload has no `stack` field.
+- A function reused as a listener for several events (e.g. both
+  `tabs.onActivated.addListener(handler)` and
+  `tabs.onUpdated.addListener(handler)`) is now reference-counted on the
+  sender side. Removing one registration no longer evicts the shared id, so
+  the other listener keeps working.
+- `handleInvokeRequest` rejects empty-path invocations with a clear error
+  instead of bottoming out at `'undefined' is not a function`.
+- Mid-path read errors now report the actual parent value (`null` /
+  `undefined`) plus the full traversed prefix, instead of stringifying the
+  previous path segment.
+- `isAllowedOrigin` distinguishes `undefined` (no restriction) from `''`
+  (empty allow-list); the empty string is no longer treated as
+  "allow everything".
+- When `allowedOrigin` is omitted, incoming `postMessage` events are now
+  filtered against the same concrete origin resolved for `targetOrigin`.
+  This keeps the default bridge configuration from accepting messages
+  from an unexpected origin while still preserving the documented `'*'`
+  fallback when origin auto-detection cannot resolve one.
+- `invoke` / `accessProperty` / `invokeFunctionById` now clear the pending
+  Map entry and timer when `serialize` / `sendMessage` throws synchronously.
+  Previously the entry lingered until the timeout fired.
+- `timeout` is clamped to the default when given a non-finite or
+  non-positive value, so accidental `timeout: 0` no longer rejects every
+  call instantly.
+- Listener registration/removal is now transactional. Failed
+  `addListener` calls roll back local persistent callback state and ask the
+  peer to release any wrapper it created; failed `removeListener` calls no
+  longer invalidate a callback that the remote side still has registered.
+- Remote method and callback results now treat any thenable as async instead
+  of relying on `instanceof Promise`, so cross-realm Promises and custom
+  thenables resolve/reject correctly.
+- `destroy()` no longer warns when the only failure is an already-detached
+  iframe whose `contentWindow` is unavailable during shutdown.
+- Nested function arguments inside `addListener` payloads are now
+  release-tracked. Previously only top-level function arguments were
+  collected for cleanup, so a call like
+  `addListener({ filter, handler })` left `handler` pinned in the
+  persistent cache even after the matching `removeListener`.
+- The `setTimeout` branch in `invoke` / `accessProperty` /
+  `invokeFunctionById` now triggers the pending entry's `onReject`
+  before rejecting. A timed-out `addListener` no longer leaks its
+  persistent registration.
+- `hasListener` is no longer classified as a listener-registration path.
+  Its argument used to be pinned as persistent indefinitely, because
+  `hasListener` has no `removeListener` counterpart that would refcount
+  it back down.
+- Sender-side function ids are now keyed by `(fn, thisArg)` rather than
+  just `fn`. The same function reused under different owners (e.g. one
+  method shared across two parent objects) no longer overwrites the
+  first registration's `thisArg`.
+- `accessPropertyRequest` now rejects intermediate-`null` /
+  `undefined` traversal with the same diagnostic format as
+  `invokeRequest` (`Cannot read property 'X' of null (at 'a.b')`),
+  instead of silently returning the partial value. Leaf
+  `null` / `undefined` still resolves normally.
+- Endpoint `destroy(notifyRemote=true)` now sends a `releaseCallbacks`
+  for every remote callback this endpoint is still holding before
+  emitting `destroyEndpoint`. This evicts the peer's persistent-flagged
+  methods that paths like `$get('runtime.onMessage')` had pinned on its
+  side — fixing a leak in long-lived hosts whose clients open and close.
+- `handleReleaseCallbacks` now fully cleans `functionIds` and
+  `persistentRefcount` via the new `ctx.dropLocalCallback(id)`, not just
+  the two outer caches.
+- `accessPropertyRequest` / `invokeRequest` no-delegate-target checks
+  now use explicit `=== undefined || === null` instead of `!target`, so
+  a delegate that is `0` / `false` (e.g. a numeric-rooted custom RPC
+  target) is no longer misreported as missing.
+- `isMessageEnvelope` rejects messages whose `senderInstanceId` or
+  `type` is the empty string, in addition to the previous non-string
+  check.
+- Error payload extras are now restored with own-property definitions
+  rather than direct assignment, so fields such as `__proto__` remain data
+  and cannot mutate the deserialized Error object's prototype.
+
+### Performance / resource
+
+- The `message` listener now does a cheap pre-filter (string check + `'{'`
+  start + `"key":<jsonStringifyOfKey>` substring) before `JSON.parse`, so
+  unrelated `window.postMessage` traffic from other libraries is rejected
+  without parsing. The match string handles JSON-escaped key values, so
+  keys containing `"` or `\` route correctly.
+- Well-known symbol reverse lookup is now O(1) via a `Map<symbol, string>`
+  built once at module load.
+- The deep payload validators run only after `handler` lookup succeeds; the
+  cheap envelope check (type/key/senderInstanceId shape) runs first.
+- `createWindowPoster.addEventListener` is idempotent for the same callback:
+  re-registering with the same listener instance unregisters the previous
+  DOM listener first, preventing accidental window-listener leaks.
+- `handleReleaseCallbacks` caps the batch at 100 000 ids, warning and
+  truncating instead of silently dropping the whole batch on overflow.
+- `endpoint.destroy()` is idempotent — extra calls are no-ops, so an
+  accidental double-destroy from cleanup hooks no longer pokes the
+  underlying poster twice.
+- `createWindowPoster`'s listener map is keyed by `(name, callback)`
+  rather than just `callback`. The same callback registered against
+  different event names no longer overwrites each other.
+- `bindMethod`'s WeakMap cache is now owned by each `ClientContext`
+  rather than being module-global. Multiple endpoints in the same
+  process no longer share bound-method state.
+
+### API
+
+- New: `setLogger(logger | null)` and the `Logger` type are exported from
+  the package entry. Pass `null` to silence all library warnings, or pass
+  your own function to route them through a custom sink (e.g. Sentry).
+
+### Removed (internal type surface)
+
+- The following members were removed from interfaces that are re-exported
+  for advanced use. They had no internal or external callers; removing them
+  is technically a type-level breaking change for anyone who imported and
+  asserted against these shapes, but the runtime behavior is unchanged:
+  - `ClientContext.registerPendingPromise`
+  - `MessageChannel.getContext`, `getPoster`, `getKey`, `getInstanceId`
+
+### Logging
+
+- Extracted a unified `warn()` utility (`src/log.ts`) with a `[chrome-in-iframe]` prefix and scope tag for all internal warnings.
+- Replaced all silent `catch` blocks (comment-only / bare `return`) with `warn()` calls so previously swallowed errors are now visible in the console. Affected areas: origin derivation (`deriveOriginFromIframe`, `deriveParentOrigin`, `parseOrigin`), message dispatch (`createMessageChannel`), deserialization (`deserializeError`, `deserializeWrappedObject`, `resolveObjectKey`), and client lifecycle (`notifyReleaseCallbacks`, `destroy`).
+- Migrated existing ad-hoc `console.warn` calls to use the centralized `warn()` utility.
+
+### Package metadata
+
+- `exports` map now exposes top-level `types` / `import` / `default`
+  conditions and `"./package.json"` for tooling that wants to read the
+  manifest. Fixes resolution under stricter bundlers (webpack 5 strict
+  exports) without changing the canonical entry.
+- Removed the `clean` and `test:watch` scripts. `build` now runs `rollup -c`
+  directly without a preceding `clean` step.
+
+### Tests
+
+- New `test/chrome-api.test.ts` with 53 tests covering all 12 Chrome MV3 API
+  patterns through the bridge: Promise async methods (various return types),
+  synchronous methods proxied as async, Port objects, event listeners
+  (addListener/removeListener/hasListener, multi-arg callbacks, sendResponse),
+  nested namespaces, optional leading parameters, static properties via `$get`,
+  complex data round-trips, CRUD registration, multi-client event isolation,
+  error propagation, and timeout behavior.
+- 8 new regression tests in `test/bridge.test.ts` covering each of the
+  newly fixed defects: nested-callback release on `removeListener`,
+  persistent rollback on `addListener` timeout, non-persistent
+  `hasListener` argument, mid-path null/undefined diagnostics through
+  `$get`, distinct `(fn, thisArg)` entries for the same function, host
+  persistent-cache cleanup on client `destroy()`, idempotent
+  `endpoint.destroy()`, and empty-`senderInstanceId` envelope rejection.
+
 ## 2.0.0
 
 Breaking changes — both peers of the bridge must run the same major version.

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,233 @@
 # 更新日志
 
+## 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`，导致每次
+  `chrome.*.onX.addListener(handler)` 在宿主端留下的包裹函数永远不会被
+  释放 —— 在长期运行的 service worker 中频繁增删监听器会造成真实泄漏。
+- 调整 `removeListener` 的客户端发送顺序：先发送 `invokeRequest`，再发送
+  `releaseCallbacks`。这样接收方可以先用缓存中的包裹函数调用
+  `chrome.*.removeListener(W)`，然后再清理缓存。
+- 错误响应处理（`invokeResponse` / `accessPropertyResponse` /
+  `invokeFunctionByIdResponse`）不再在远端 payload 没有 `stack` 字段时
+  用 `undefined` 覆盖本地 `Error` 的 stack。
+- 同一个函数被注册为多个事件的监听器（如同时绑定
+  `tabs.onActivated.addListener(handler)` 和
+  `tabs.onUpdated.addListener(handler)`）时，客户端现在按 callback id
+  做引用计数。移除其中一处不再让另一处失效。
+- `handleInvokeRequest` 在 path 为空时直接返回明确的错误，而不是落到
+  `'undefined' is not a function`。
+- 中间路径解到 null / undefined 时的错误信息现在准确报告父值类型，并附
+  上已访问的路径前缀。
+- `isAllowedOrigin` 区分 `undefined`（不限制）与 `''`（空白名单）。空字符串
+  不再被当作「放行所有 origin」。
+- 未传 `allowedOrigin` 时，传入的 `postMessage` 现在会默认按
+  `targetOrigin` 推导出的同一个具体 origin 过滤。这样默认桥接配置不会
+  接收来自意外 origin 的消息，同时仍保留自动推导失败时回退到 `'*'` 的
+  既有行为。
+- `invoke` / `accessProperty` / `invokeFunctionById` 在 `serialize` /
+  `sendMessage` 同步抛错时会清掉 pending 条目和 timer，不再等到 timeout
+  才回收。
+- 非有限或非正的 `timeout` 值会回落到默认值，避免 `timeout: 0` 导致每
+  次调用瞬间被拒。
+- 监听器注册/移除现在是事务式的。失败的 `addListener` 会回滚本地持久
+  callback 状态，并通知对端释放已创建的包裹函数；失败的
+  `removeListener` 不再让仍注册在远端的 callback 失效。
+- 远端方法和 callback 返回值现在按 thenable 判断异步，不再依赖
+  `instanceof Promise`，因此跨 realm Promise 和自定义 thenable 可以正确
+  resolve/reject。
+- `destroy()` 在关闭阶段如果只是因为 iframe 已分离、`contentWindow`
+  不可用而通知失败，不再输出 warning。
+- `addListener` 参数中嵌套对象内的回调函数现在也参与释放计数。此前
+  只有顶层函数参数会被收集到回滚清单中，所以
+  `addListener({ filter, handler })` 这种调用即使后续 `removeListener`，
+  `handler` 也会一直留在持久缓存里。
+- `invoke` / `accessProperty` / `invokeFunctionById` 的 `setTimeout`
+  分支现在会在 reject 之前触发挂起项的 `onReject`。`addListener`
+  调用超时不再造成持久注册泄漏。
+- `hasListener` 不再被识别为监听器注册路径。其参数此前会被永久标记
+  为 persistent —— 因为 `hasListener` 没有对应的 `removeListener`
+  可以把引用计数减回去。
+- 客户端的函数 id 现在以 `(fn, thisArg)` 为联合键，而不是仅以 `fn`
+  为键。同一函数被复用到不同 owner 上（例如同一方法挂在两个父对象
+  上）不再覆盖前一次注册的 `thisArg`。
+- `accessPropertyRequest` 中间节点解到 null / undefined 时，现在
+  和 `invokeRequest` 一样抛出 `Cannot read property 'X' of null
+  (at 'a.b')` 的诊断错误，不再静默返回中间值。叶子节点为
+  null / undefined 仍正常返回。
+- 端点 `destroy(notifyRemote=true)` 现在会在发送 `destroyEndpoint`
+  之前，先发送一条 `releaseCallbacks`，列出本端当前持有的所有远端
+  callback id。这样对端就可以释放被 `$get('runtime.onMessage')`
+  这类路径标记为 persistent 的方法 —— 修复了长期运行宿主里客户端
+  反复 open/close 时的累积泄漏。
+- `handleReleaseCallbacks` 现在通过新增的 `ctx.dropLocalCallback(id)`
+  彻底清理 `functionIds` 和 `persistentRefcount`，而不是只清理外层
+  两个缓存。
+- `accessPropertyRequest` / `invokeRequest` 的「无 delegate target」
+  判断改为显式 `=== undefined || === null`，不再用 `!target`。这样
+  `0` / `false`（例如以数字为根的自定义 RPC target）不会被误报为
+  「未配置 delegate target」。
+- `isMessageEnvelope` 在原有的非字符串校验之外，还会拒绝
+  `senderInstanceId` / `type` 为空字符串的消息。
+- Error payload 的额外字段现在通过 own-property 定义恢复，而不是直接赋值。
+  因此 `__proto__` 等字段会被保留为普通数据，不会改变反序列化后 Error
+  对象的原型。
+
+### 性能 / 资源
+
+- `message` 监听器在 `JSON.parse` 之前先做廉价过滤（字符串检查 + `'{'`
+  起始 + `"key":<JSON.stringify(key)>` 子串）。其它库通过
+  `window.postMessage` 发出的无关消息不再被解析。匹配串经过 JSON 转义，
+  含 `"` 或 `\` 的 key 也能正确路由。
+- 知名 Symbol 反向查找改为模块加载时一次性建立的 `Map<symbol, string>`，
+  O(1) 替代之前的 O(n)。
+- envelope（type / key / senderInstanceId 形状）的廉价校验先做；深层
+  payload 校验延后到 handler 命中之后再执行。
+- `createWindowPoster.addEventListener` 对同一 callback 幂等：再次注册
+  会先卸掉旧的 DOM listener，避免 window-listener 泄漏。
+- `handleReleaseCallbacks` 将单批上限改为 100 000 个 id，超过时截断
+  并输出警告，而不是直接丢弃整批。
+- `endpoint.destroy()` 改为幂等——重复调用直接 no-op，避免清理钩子
+  里不小心的 double-destroy 让底层 poster 被处理两次。
+- `createWindowPoster` 的 listener map 改为以 `(name, callback)` 为
+  联合键，不再仅以 `callback` 为键。同一 callback 注册到不同事件名
+  时不会再相互覆盖。
+- `bindMethod` 的 WeakMap 缓存改由每个 `ClientContext` 各自持有，
+  不再是模块级全局。同一进程中多个端点不再共享绑定方法状态。
+
+### API
+
+- 新增：从包入口导出 `setLogger(logger | null)` 和 `Logger` 类型。传
+  `null` 可彻底静默库内警告，也可传入自定义函数把日志路由到 Sentry 等
+  外部 sink。
+
+### 移除（内部类型层面）
+
+- 以下接口成员被移除。它们在源码和测试中都没有调用方，从未被实际使
+  用；运行时行为完全不变，仅在严格断言这些接口形状的下游代码看来属
+  于类型层面的破坏性变更：
+  - `ClientContext.registerPendingPromise`
+  - `MessageChannel.getContext` / `getPoster` / `getKey` / `getInstanceId`
+
+### 日志
+
+- 提取统一的 `warn()` 工具函数（`src/log.ts`），所有内部警告均带有 `[chrome-in-iframe]` 前缀和 scope 标签。
+- 将所有静默 `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 等工具链下的
+  解析问题。规范入口未变。
+- 移除 `clean` 和 `test:watch` 脚本，`build` 直接运行 `rollup -c`，不再前置清理步骤。
+
+### 测试
+
+- 新增 `test/chrome-api.test.ts`，包含 53 个测试用例，覆盖全部 12 种 Chrome MV3 API 调用模式的桥接测试：Promise 异步方法（各种返回类型）、同步方法代理、Port 对象、事件监听器（addListener/removeListener/hasListener、多参数回调、sendResponse）、嵌套命名空间、可选前导参数、$get 静态属性、复杂数据往返、CRUD 注册模式、多客户端事件隔离、错误传播、超时行为。
+- 在 `test/bridge.test.ts` 末尾新增 8 个针对上述新修复点的回归测试：`removeListener` 时嵌套回调被释放、`addListener` 超时回滚持久注册、`hasListener` 参数不被标记为 persistent、通过 `$get` 时中间路径 null/undefined 的诊断错误、同一函数不同 owner 产生不同 entry、客户端 `destroy()` 触发宿主端持久缓存清零、`endpoint.destroy()` 幂等、空 `senderInstanceId` 信封被拒收。
+
 ## 2.0.0
 
 破坏性变更 — 桥接的两端必须运行相同的主版本号。
@@ -8,7 +236,7 @@
 
 - 将魔法字符串前缀（`$undefined$`、`$function$id` 等）替换为对象标签（`{ $cii$: 'undef' }`、`{ $cii$: 'fn', id }` 等）。与保留标记冲突的普通字符串现在可以正确地往返传输。
 - 新增对 `Date`、`RegExp`、`Map`、`Set`、`BigInt`、`NaN`、`Infinity`、`-Infinity` 和 `-0` 的序列化支持。
-- 自有键包含保留标记 `$cii$` 或包含 Symbol 类型键的普通对象会被包装为条目列表，从而无歧义地往返传输。使用 `Reflect.ownKeys` 以保留自有 Symbol 键。非全局的 `Symbol(...)` 键会被静默跳过（`Symbol.for(...)` 和知名 Symbol 仍然可以正常传输），因此带有私有品牌 Symbol 的用户对象不再导致序列化抛出异常。
+- 自有键包含保留标记 `$cii$` 或包含 Symbol 类型键的普通对象会被包装为条目列表，从而无歧义地往返传输。使用 `Reflect.ownKeys` 以保留自有 Symbol 键。非全局的 `Symbol(...)` 键会被静默跳过（`Symbol.for(...)` 和知名 Symbol 仍然可以正常传输），因此带有私有 brand Symbol 的用户对象不再导致序列化抛出异常。
 - `Error` 序列化保留 `name`（因此 `TypeError` 传输后仍为 `TypeError`）、`cause`（递归）、`stack` 以及额外的自有可枚举字符串键属性（如自定义 `code` 字段）。
 - 标签载荷会进行校验；格式错误的 `date` / `regexp` / `bigint` / `fn` 载荷会抛出带有描述信息的 `TypeError`，而不是产生 `Invalid Date` 或静默返回 undefined。当条目包含无法解析的键时，`deserializeWrappedObject` 会向控制台输出警告，而非静默丢弃。
 
@@ -54,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 additionally checked against the expected window source.
+`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.
 
-> **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** that can reach this page can send forged `postMessage` messages and impersonate Chrome API calls. In that case, always set `allowedOrigin` to the expected 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.
+
+> **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.
+- `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.
@@ -302,3 +304,19 @@ Returns:
 - `proxy`: the same object as `chrome`.
 - `get(path)`: read a property from the bridged Chrome API. See [Path Forms](#path-forms).
 - `destroy()`: remove message listeners, clear bridge state, and notify the remote peer.
+
+### `setLogger(logger)`
+
+Customize or silence library warnings. All internal warnings carry a `[chrome-in-iframe]` prefix and a scope tag.
+
+```ts
+import { setLogger } from 'chrome-in-iframe';
+
+// Silence all warnings
+setLogger(null);
+
+// Route warnings to a custom sink (e.g. Sentry)
+setLogger((scope, ...args) => {
+  captureMessage(`[chrome-in-iframe] ${scope}`, { extra: { args } });
+});
+```